Published on
-

# Intermediate Typescript: Literals and Unions

At my job we have spent a lot of time converting a node backend and angular frontend to Typescript. Before Typescript when working in our codebase I found myself having to read a lot of code, API schemas, and tests just to see what fields actually existed. So during the transition I tried my hardest to make the types I made as descriptive as they could be. Converting to Typescript and making big interfaces/types with many optional fields does not buy you much other than typo prevention and basic autocomplete.

This post assumes you have a basic understanding of Javascript/Typescript.

# Literal types

You are most likely familiar with the basic types like

tslet num: number = 1; // can be any numberlet str: string = 'hi'; // can be any stringlet bool: boolean = true; // can be true or falselet arr: number[] = [10]; // can be an array of any length with numberslet obj: { key: string } = { key: 'value' }; // the key field can be any string

These types are fine for many cases and I still default most types to be these until I understand the code more.

Literal Types on the other hand are a much stronger restriction on what the allowed values are

tsconst numLiteral = 1 as const; // this can only be the number 1, no other numberconst strLiteral = 'literal' as const; // can only be the string 'literal'const boolLiteral = true as const; // can only be trueconst arrLiteral = [10] as const; // can only be an array with a single element of 10const objLiteral = { key: 'value' } as const; // can only be this specific object mapping

These types on their own are not that useful but when combined with unions and conditional types they can make your types very powerful.

# Unions

Union Types allow you to say a type is either foo or bar or number or string...

tsfunction printId(id: number | string) {  console.log('Your ID is: ' + id);}

This function will allow you to pass in a string or number, this is fine since both can be added to a string for display.

When combined with literals you can make types very strongly defined.

tstype MethodType = 'GET' | 'PUT' | 'POST' | 'DELETE'; function makeHttpCall(url: string, method: MethodType) {  console.log(Im hitting ${url} with${method});}const url = 'johns.codes';makeHttpCall(url, 'GET'); // allowedmakeHttpCall(url, 'GeT'); // not allowedArgument of type '"GeT"' is not assignable to parameter of type 'MethodType'.2345Argument of type '"GeT"' is not assignable to parameter of type 'MethodType'.makeHttpCall(url, 'POG'); // not allowedArgument of type '"POG"' is not assignable to parameter of type 'MethodType'.2345Argument of type '"POG"' is not assignable to parameter of type 'MethodType'.

This helps greatly for new users of this function to see what the valid method fields are without having to look at external documentation, your editor will provide autocomplete on the method field, and you get a compile error if you try to use an arbitrary string as the method parameter.

## Restricting Unions

Literals allow for strongly typed APIs, but how do you properly narrow a general type to a more specific type? Typescript allows this in a few ways

tsfunction handleAny(url: string, method: unknown) {  if (typeof method === 'string') {    // in this block method is now a string type    if (method == 'GET') {      // method is now the literal "GET"      makeHttpCall(url, method);    }    if (method == 'PUT') {      // method is now the literal "PUT"      makeHttpCall(url, method);    }  }}

This manual checking is fine but if you have a more complex type or a union with many possible values this gets unwieldy quite fast. The next best approach is a type predicate

ts// First define valid methods as a const arrayconst ValidMethods = ['GET', 'PUT', 'POST', 'DELETE'] as const;type MethodType = typeof ValidMethods[number]; // resulting type is the same as before function isValidMethod(method: unknown): method is MethodType {  // need the as any since valid methods is more strongly typed  return typeof method === 'string' && ValidMethods.includes(method as any);} function handleAny(url: string, method: unknown) {  if (isValidMethod(method)) {    // method is now a MethodType    makeHttpCall(url, method);  }}

The type predicate isValidMethod is just a function that returns a boolean, when true Typescript knows the input parameter method is a MethodType and can be used as such. Type predicates are a good simple way to encode any runtime checks into the type system.

## Discriminated unions

Now unions of basic literals are quite powerful, but unions can be even more powerful when you make unions of objects. Say in your app you track different events. The events could look like the following

tsinterface LoginEvent {  // the user's email  user: string;  wasSuccessful: boolean;} interface PostCreatedEvent {  name: string;  body: string;  createdAt: Date;}// and many others

Once you have typed out all the different events, and you want to group them together to a single event type you might think a simple union like type ApiEvent = LoginEvent | PostCreatedEvent | ... would be good but when you want to narrow this type down you would have to end up with a lot of if ('user' in event) {..} checks or many custom type predicate functions.

To avoid that issue you can define the event types as a Discriminated union. All this is, is a union type where all types in the union have a field whose value is unique in all the union's types. We can redefine the above types as follows

tsinterface LoginEvent {  type: 'login';  user: string;  wasSuccessful: boolean;} interface PostCreatedEvent {  type: 'postCreated';  name: string;  body: string;  createdAt: Date;} type ApiEvent = LoginEvent | PostCreatedEvent;type EventTypes = ApiEvent['type']; // this resolves to 'login' | 'postCreated'

In this example you could name the key type whatever you want, as long as every type has that field the union type will allow you to access the key. Now to narrow this type down you could do the following

tsfunction logEvent(event: ApiEvent) {  if (event.type === 'login') {    console.log(user: ${event.user}, wasSuccessful:${event.wasSuccessful});  } else if (event.type === 'postCreated') {    console.log(post ${event.name} was created at${event.createdAt});  }}

This style of checking the discriminating field in if statement is fine but is a little verbose to me. I find that a switch statement makes it more readable and less verbose.

tsfunction logEvent(event: ApiEvent) {  switch (event.type) {    case 'login':      console.log(user: ${event.user}, wasSuccessful:${event.wasSuccessful});      break;    case 'postCreated':      console.log(post ${event.name} was created at${event.createdAt});      break;    default:      throw new Error(invalid event type: ${(event as { type: string }).type}); }} There is one issue with this approach, in the future when we add a new event type it would fall through to default case, and we wouldn't know about it until runtime. However, using Typescript's never type we can force a compile error when we don't handle all cases tsfunction assertUnreachable(type: never): never { throw new Error(Invalid event type:${type});} function logEvent(event: ApiEvent) {  const type = event.type;  switch (type) {    case 'login':      console.log(user: ${event.user}, wasSuccessful:${event.wasSuccessful});      break;    case 'postCreated':      console.log(post ${event.name} was created at${event.createdAt});      break;    default:      // event.type is never here since this default case would never be hit since all possible cases are handled      assertUnreachable(type);  }}

Now in the future if we added an event with a type field of NewEvent it would fall through to the default case, since its type is not never (it would be NewEvent) we would get a compile error on the call to assertUnreachable.

# Wrap up

While these features I covered can help you a lot (these are almost all I used during the initial typescript migration), there are many other really cool typescript features, like generics, mapped types and conditional types. I hope to cover them all in a Part 2 so check back soon!