DEV Community: Danny Jones

Intro to string literal types

Danny Jones — Sat, 16 May 2020 18:55:11 +0000

Are you using string literal types? They're by far my most favorite feature in TypeScript. In their simplest form, they're used as a set of self-documenting props. In advanced cases, exhaustiveness type checking gives you confidence knowing that you'll receive compile errors when making updates without properly handling all cases.

If you're new to TypeScript and not yet using string literal types, then let's go over three reasons why you'll want to start using them:

Self documenting props
Pairing with Record<K, T>
Exhaustiveness checking

Self documenting props

I need a helper function that returns a number when given input of small, medium, or large. This is a pretty common pattern when creating React components and could be used for something as simple as supporting different sizes of buttons. How would I do this without string literal types?

Note: This is probably the worst possible way to handle this. Don't do this! 🤠

const getPx = (size: string): number => {
  if (size === "large") {
    return 20
  } else if (size === "medium") {
    return 16;
  } else {
    return 12;
  }
};

From looking at this, it's pretty clear what props are supported, but I need to look at the code to understand it. What if this is moved to a library? Would I need to go to the readme or to the source code to remind myself which props are supported? This is a quick way to guarantee that nobody uses this helper function.

Converting this to use a string literal type does two things:

Defines a clear set of accepted properties. If you're using an IDE with IntelliSense then you'll see supported props as you type.
Compile time error when using unsupported props:

type Sizes = "small" | "medium" | "large";
const getPx = (size: Sizes): number => {
  if (size === "large") {
    return 20
  } else if (size === "medium") {
    return 16;
  } else {
    return 12;
  }
};

getPx("xlarge")
// Argument of type '"xlarge"' is not assignable to parameter of type 'Sizes'

Pairing with Record<K, T>

Pairing string literal types with the Record<K, T> utility type is a slick pattern to use when you want to cleanup your code.

Let's apply this pattern to getPx:

type Sizes = "small" | "medium" | "large";
const sizes: Record<Sizes, number> = {
  small: 12,
  medium: 16,
  large: 20
}
const getPx = (size: Sizes): number => {
 return sizes[size]
};

That's a lot cleaner! Not only is it easier to add new sizes, but you'll also receive an error if you update Sizes without updating the sizes object.

// Add a new size without updating `sizes`
type Sizes = "small" | "medium" | "large" | "xlarge";
// Property 'xlarge' is missing in type '{ small: number; medium: number; large: number; }' but required in type 'Record<Sizes, number>'

Exhaustiveness checking

Another lesser known feature of string literal types is that you can benefit from what's known as exhaustiveness type checking when using switch statements. This means that TypeScript follows the flow of your code to determine if all cases are covered. If your code is too complex to work with the Record<K, T> pattern, then using exhaustiveness checking is a way to remove brittleness from your code.

This can be demonstrated most easily by converting this reducer to TypeScript

type ActionType = "decrement" | "increment";
type Action = { type: ActionType };
type State = { count: number };
const initialState: State = { count: 0 };

function reducer(state: State, action: Action): State  {
  switch (action.type) {
    case "increment":
      return { count: state.count + 1 };
    case "decrement":
      return { count: state.count - 1 };
  }
}

The key part of making this work is to remove the default case from the switch statement. By removing the default case, you'll run into a compile error when updating ActionType without updating the switch statement to handle the new case:

// Add "reset" to `ActionType'
type ActionType = "decrement" | "increment" | "reset";
// Function lacks ending return statement and return type does not include 'undefined'

Conclusion

String literal types solve a handful of problems that help developers write clean, maintainable, and scalable code.

Move fast with GraphQL, Rails, and TypeScript

Danny Jones — Wed, 06 May 2020 22:55:48 +0000

Here at OneHQ, we've had great success using GraphQL with Rails and TypeScript. I wanted to take the time to show off a couple techniques that we use to enable developers to move fast ~~and break things~~:

Dynamically create GraphQL types in Ruby
Commit the GraphQL schema to version control
Auto-generate GraphQL types in TypeScript

Dynamically create GraphQL types in Ruby

Our database schemas are continuously evolving, and we didn't want the overhead of having to keep our tables, models, and GraphQL types in sync. ActiveRecord gets around this by using meta-programming to dynamically analyze the database to generate methods. Why couldn't we do the same with GraphQL?

We could and we did! Thus was born hq-graphql. hq-graphql is a wrapper around graphql-ruby that does all of the necessary magic to integrate with ActiveRecord. Instead of creating a bajillion types with a bazillion fields...

class AdvisorType < ::GraphQL::Object
  field :id, ID, null: false
  field :created_at, ISO8601DateTime, null: false
  field :name, String, null: false
  # <bazillion fields go here (use your imagination)>
  # <bazillion fields go here (use your imagination)>
  # <bazillion fields go here (use your imagination)>
end

We can now simply reference the model to dynamically create fields.

class AdvisorType < ::HQ::GraphQL::Object
  with_model "Advisor"
end

Commit the GraphQL schema to version control

Once we began creating types dynamically, I feared that devs would add/remove columns from our schema without realizing that it affected GraphQL. Too much magic can be bad, especially if there isn't feedback for when something changes.

For this reason, we dump and commit the GraphQL IDL (Interface Definition Language) to a file named schema.graphql whenever the schema changes. Checking in the schema to version control helps both the developer and code reviewer identify breaking changes before they hit production.

To make things even easier, we created a test that compares the current schema with what's committed so that they can't forget to check it in! This ensures that our CI process fails whenever a dev forgets to update the schema file.

Auto-generate GraphQL types in TypeScript

Another fear of mine was that we would update the schema and forget to update the front-end!^{(I'm afraid of a lot)} Of course you could write tests to circumvent this (and we do), but what if we could auto-generate our GraphQL types in TypeScript instead of creating them by hand? This would give us another layer of protection and allow for us to easily correct any disparities when something does change.

Good news! This was the easiest of all our problems as there's already a tool out there that does this. Apollo Codegen.

Point codegen to the code that uses GraphQL and run it! It pulls out any GraphQL queries and uses introspection to dynamically generate your types. If the GraphQL queries in your client don't align with your back-end, then it throws an error and lets you know what's wrong

$ apollo client:codegen src/graphql/types/index.ts --endpoint=http://[::1]:8080/graphql --target=typescript --includes='src/graphql/**/**/*.{ts,tsx}' --tagName=gql --addTypename --outputFlat
  ⠏ Loading Apollo Project
    Generating query files
.../src/graphql/application/useApplications.ts: Cannot query field "names" on type "Application". Did you mean "name"?
ToolError: Validation of GraphQL query document failed

Conclusion

Using meta-programming to generate types has saved us countless hours at OneHQ by allowing us to focus on what really matters. But beware!!! Using meta-programming without checks and balances in your code review process could lead to a broken app.