- Published on
- -10 min read
Intermediate Typescript: Literals and Unions
Table of Contents
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
ts
letnum : number = 1; // can be any numberletstr : string = 'hi'; // can be any stringletbool : boolean = true; // can be true or falseletarr : number[] = [10]; // can be an array of any length with numbersletobj : {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
ts
constnumLiteral = 1 asconst ; // this can only be the number 1, no other numberconststrLiteral = 'literal' asconst ; // can only be the string 'literal'constboolLiteral = true asconst ; // can only be trueconstarrLiteral = [10] asconst ; // can only be an array with a single element of 10constobjLiteral = {key : 'value' } asconst ; // 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
...
ts
functionprintId (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.
ts
typeMethodType = 'GET' | 'PUT' | 'POST' | 'DELETE';functionmakeHttpCall (url : string,method :MethodType ) {console .log (`Im hitting ${url } with ${method }`);}consturl = 'johns.codes';makeHttpCall (url , 'GET'); // 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 , 'GeT'); // 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'.makeHttpCall (url , 'POG'); // not allowed
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
ts
functionhandleAny (url : string,method : unknown) {if (typeofmethod === 'string') {// in this block method is now a string typeif (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 arrayconstValidMethods = ['GET', 'PUT', 'POST', 'DELETE'] asconst ;typeMethodType = typeofValidMethods [number]; // resulting type is the same as beforefunctionisValidMethod (method : unknown):method isMethodType {// need the `as any` since valid methods is more strongly typedreturn typeofmethod === 'string' &&ValidMethods .includes (method as any);}functionhandleAny (url : string,method : unknown) {if (isValidMethod (method )) {// method is now a MethodTypemakeHttpCall (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
ts
interfaceLoginEvent {// the user's emailuser : string;wasSuccessful : boolean;}interfacePostCreatedEvent {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
ts
interfaceLoginEvent {type : 'login';user : string;wasSuccessful : boolean;}interfacePostCreatedEvent {type : 'postCreated';name : string;body : string;createdAt :Date ;}typeApiEvent =LoginEvent |PostCreatedEvent ;typeEventTypes =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
ts
functionlogEvent (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.
ts
functionlogEvent (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 newError (`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
ts
functionassertUnreachable (type : never): never {throw newError (`Invalid event type: ${type }`);}functionlogEvent (event :ApiEvent ) {consttype =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 handledassertUnreachable (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!