As a frontend developer, your job isn't just pixel-pushing. Most of the complexity in frontend comes from handling all the various states your app can be in.

It might be loading data, waiting for a form to be filled in, or sending a telemetry event - or all three at the same time.

If you aren't handling your states properly, you're likely to come unstuck. And 

Let's imagine you're building a simple data loader. You might choose to use a type like this to represent its state:

 to understand what kind of UI we should display on the screen.

Except - this type lets us declare all sorts of shapes which should be impossible:

Here, we're in a success state - which should let us access our data. But it doesn't exist!

An here, we're in a loading state - but there's still an error in our data object!

This is because we've chosen to represent our state using what I call a 'bag of optionals' - an object full of optional properties.

Optional properties are best used when a value might or might not be present. In this case, that isn't right.

The more accurate way to represent this is using a discriminated union.

Let's start by changing our state to be a union of object, each containing a status.

Now that we've got our scaffolding, we can start adding elements to each branch of the union. Let's re-add our error and data types.

Now, our examples from above will start erroring.

 type now properly represents all the possible states of the feature. That's a big step forward, but we're not done yet.

Let's imagine we're inside a component in our codebase. We've received our piece of state, and we're looking to use it to render some JSX.

 here, but this could be any frontend framework.

The first instinct of many developers will be to destructure the elements of 

For many devs, this is going to be tricky to figure out. Both 

 the union yet! We don't know which state we're in, so the only properties available are the ones which all the members of the union share. Namely, 

Once we've checked which branch of the union we're in, we can safely destructure 

, not a bug. By ensuring you can only access data when the status equals 

, you're encouraged to think of your app in terms of its states, and only access data in the states it's available.

When you start thinking of your app in terms of discriminated states, a lot of things get easier.

Instead of a big optional bag of data, you'll start understanding the connections between data and UI.

Not only that, but you'll be able to think about props in a whole new way.

What if you need to display a component in two slightly different ways? Use a discriminated union:

 will only be required when the variant passed in is 

Discriminated Unions make frontend development easier by representing the different application states and helping to make connections between data and UI.


Discriminated Unions are a Frontend Dev's Best Friend

TypeScript's satisfies operator has been out for a while, but it still seems to be a source of confusion that could use some clearing up.

Think of satisfies as another way to assign types to values.

Before we look closer, let's do a review of how to assign types.

First, there's the humble "colon annotation" (we'll go with this slightly medical-sounding name since this concept isn't really given a name in the TS docs).

The : says "this variable is always this type":

When you use a colon annotation, you're declaring that the variable is that type.

That means that the thing you assign to the variable must be that type:

It’s possible to give a variable a type that’s wider than the one you initially assign.

This is useful when you want to have a default which might later be reassigned.

But colon annotations come with an edge-case downside.

When you use a colon, the type BEATS the value.

In other words, if you declare a wider type than you want, you're stuck with the wider type.

For example, in this snippet you don't get autocomplete on the routes object: 

This is the problem satisfies was designed to solve.

This means it infers the narrowest possible type, not the wider type you specify:

 also protects you from specifying the wrong thing inside your config object.

Another way you can assign types to variables is the ‘

’ annotations lets you lie to TypeScript.

In this example, you wouldn’t see an error in your IDE but it will break at runtime:

There are some limits to the lies– you can add properties to objects, but you can’t convert between basic types.

For instance, you can’t force TypeScript to convert a string into a number…

…unless you use the monstrous ‘as-as’:

, where it is used to convert an object to a known type that hasn’t been constructed yet:

 as your default way to annotate variables, that’s almost certainly wrong!

The code below might look safe, but as soon as you add another property to the 

 will be out of date, and it will not show you an error!

There’s one last way to give a type to a variable:

TypeScript does an amazing job at inferring types for your variables.

In fact most of the time, you won’t need to type your variables at all:

To recap, we’ve got FOUR ways of assigning a type to a variable:

With different ways to do similar things, it can get a bit confusing about when to use what.

But most of the time, when you want to assign a type to a variable you probably want the type to be wider.

The rule of thumb is that you should only use satisfies in two specific situations:

You want the EXACT type of the variable, not the WIDER type.

The type is complex enough that you want to make sure you didn’t mess it up

 includes dozens of challenges in this vein that will help you solidify your mental model for type assignments and transformations!

Using the satisfies keyword is one of four ways to make type assignments in TypeScript. But when should you use it?

Using the satisfies keyword is one of four ways to make type assignments in TypeScript. In this article we'll look at examples of when each method should be used.

Clarifying the `satisfies` Operator

Understanding TypeScript errors can be extremely tough. They have a reputation for having complicated wording, and can be extraordinarily long. Let's take this example:

Here's the code that's causing this error:

You might be able to see immediately what's causing the error - but let's keep the suspense a little longer. If you can understand 

 TypeScript throws this strange-looking error, you'll feel much more confident when the next one comes along.

What's happening here is that we're saying that 

You'll notice that the error is split up into several indented sections:

This structure mirrors the structure of the code. Since we're comparing a function (

Why isn't my function assignable, TypeScript? Well, it's the return signature.

Great, that means I know that the return types are incompatible, not the parameters. So, what about the return type is incompatible?

There we go! We've finally got at the root of the problem. To fix it, we'd need to change 

TypeScript errors mirror the structure of the code that's being compared

. The more complex the structure, the more complex the error.

In the example above, we can see that the actual red line is some distance away from the cause:

TypeScript had to produce a long error to explain the entire structure between the error's 

 its cause. We can reduce the complexity of the error by changing the way we assign the type:

Now, we're asking TypeScript to only check the 

 of the function, not the entire function. That means it's comparing an object to an object.

Objects are less complex than functions (they can't be overloaded), so TypeScript can actually dispense with a long error and show only the line that matters:

So, if you're looking to improve your TypeScript errors - aim to always compare 

. This means you should prefer typing return types and parameters over giving a type to the function itself.

Understand why TypeScript throws complicated errors by learning how to read them.

Understand why TypeScript throws complicated errors by learning how to read them. Errors mirror the structure of the code being compared and can be simplified by changing the way types are assigned.

Structure of a TypeScript Error

The TypeScript docs are mostly excellent. The 

 is a shining example of what good docs look like. They're precise, well-maintained, well laid-out, and complete.

However, if there's one section could us a rewrite, it would be the section on 

. This section assumes too much knowledge, teaches things in the wrong order, and misses out key information. The generics section of the TypeScript docs leaves you feeling that generics are complicated and mysterious.

Look at generics first on the type level. Imagine you have a type like this:

, expressed in a type alias. This can't be altered later, so it behaves similarly to a 

, meaning that whenever you use it, you'll need to pass in an argument:

. Now, its equivalent in JavaScript would be:

Since it's now a function, let's name it something more function-like:

 is currently unused, so as an example return an object from our type 'function':

 type function to create types, by passing it arguments:

 this pattern is called 'type helpers'. Type helpers are really useful on the type level to create new types to help DRY up your code.

Now you know how to handle generics on the type level, what about generic functions?

This function won't return whatever you pass in - it'll actually always return 

 on the type level. This is annoying, because it ruins your autocomplete on the thing you pass in:

Imagine you wanted to create this on the type level. You'd create a type helper called 

You can use a very similar syntax to annotate our function:

This is now a generic function. This means that when you call it, the type argument of 

A generic function is a type helper layered on top of a normal function

This means that when you call the function, you're also passing a type to the 'type helper'.

Build up that function again, piece by piece to make it clearer starting from your JavaScript-only function again:

Get the structure of the 'type helper' set up first. You'll need to infer an 

If you try and call this now, it'll infer what it returns as 

told the type helper which arguments to infer from

, you perform a mapping between the runtime argument - 

This is the right way to think about generics - as a type helper laid over your function, with a mapping between them.

Generics get a lot more complex from here - multiple generics, generic constraints, generics hidden deep within other types - but this mental model stays the same.

Learn how to use TypeScript generics to improve code readability, type safety, and reduce repetitive code.

Learn how to use TypeScript generics on the type level and with functions to improve code readability, type safety, and reduce repetitive code. Use "type helpers" to create new types and generic functions to pass in and return specific types.

Mental Model for TypeScript Generics

You're an engineer. You're building something. The thing you're building probably has 

 is the input. It's the thing that tells the program what to do. It's totally unknown at runtime - it might not even exist.

If you're building a public-facing API, you might have inputs that are exposed to public ports on the web:

Search parameters you've added to the request: 

All of these are unknown at runtime, because if these API's are exposed to the world anyone can ping them. If they aren't validated, many might even be vectors for attack.

 the data entering your app. For those cases, you should use Zod.

 usually contains two useless arguments, then the dynamic one you want to extract. For more complex cases, you'll want to use 

 - but for simple scripts this works great.

The nice thing about using Zod here is that 

For your public API, you can create Zod schemas to ensure that the request body and headers are correct.

 here so that we don't throw an error - instead, we return 

 and pass back the error. Zod throws really nice, readable errors, so we can be sure the user knows what went wrong.

Thanks to Zod, you can be sure that the unknown inputs in your app are validated and safe. If I were building an app with 

Forms - login forms, CRUD forms... All great use cases for Zod

 - users can manipulate this, or it might be out of date.

 inputs to your application. But there are other types of inputs which you 'sort of' trust.

The example that comes to mind is third-party services. If your app relies on calling a third-party API which you don't control, should you validate that API with Zod?

If that API changes its shape, that might cause subtle bugs in your application. I've been through this plenty of times as an engineer: assuming for hours that my code is wrong before realising that the API returned something I didn't expect.

Validating that data with Zod will still cause an error in your app - but that error will be thrown 

, right when the data enters your app. This makes it 

In that case, why not validate? If bundle size is a concern, 

 which is a little too large for some apps. Validation is also, inevitably, slightly slower than 

 validating. So if critical-path performance is a concern, you might want to skip Zod.

However, in most apps I've built in my career, robustness is the key concern. 'Impossible data' - or data you don't expect - has been probably the most frequent cause of bugs throughout my dev life. So I'll be validating any input that's remotely untrustworthy.

API's controlled by other teams in your organization (this is debatable, but depending on the culture I'd consider Zod as an option)

Let's take the final case. Imagine you're building a fullstack app, using a popular framework like Remix, Next.js, SvelteKit or Nuxt.

You want to load some data from the frontend. You ping an API endpoint (which, since it's public-facing, is likely already validated with Zod). You get some data back. Should you validate that data with Zod 

This is a tricky one. We completely control the API endpoint - we're in charge of deploying to it, and it's deployed in sync with the frontend. However - it's still possible that the following sequence happens:

A user starts a browser session on our page (without refreshing). Let's say it's a finance app, with charts that refresh every 10 seconds by pinging the API.

While they're browsing, we redeploy our app, with some breaking changes to the backend.

The user still hasn't refreshed the page, but now the backend they're pinging is out of date. The page starts breaking.

This kind of 'version drift' between frontend and backend is more common than you think, especially given how often some teams deploy. If we had Zod on the frontend, we'd be able to error as soon as any kind of version drift happened and prompt the user to refresh the page.

However, in these situations I usually opt for 

 using Zod. With version drift, the app is usually just a browser refresh away from a better experience. Since nothing security-sensitive is exposed to frontend code, the blast radius of a bug is relatively small.

This is up for debate, though - you may want to check all the data coming into your app to error whenever a version drift happens.

, I usually don't validate them with Zod.

If you want to learn more about using Zod, check out my free, 

Use Zod to validate unknown inputs in your app, whether it's a CLI or a public API, to ensure that data entering your app is safe.

Use Zod to validate unknown inputs in your app, whether it's a CLI or a public API, to ensure that data entering your app is safe. Zod can also be used for 'sort of' trusted inputs, like third-party services, to ensure that the data returned is what you expect.

When should you use Zod?

Since 4.1, TypeScript has had the power to manipulate and transform strings using template literal syntax. Take the example below:

You can use unions inside template literal types to expand into larger unions:

 represents any two strings with a space between:

 as type variables which can be used if it matches the string passed in. The 

 returns the last name, meaning you can use 

What about more advanced use cases? What if we wanted to replace the space in the name with a dash?

Very nice - we just change the result to 

. Now, our type variables seem a bit misnamed. Let's switch:

Now it's more generic. But not quite generic enough - let's make this type helper be able to handle replacing 

Except, there are a couple of bugs. For instance, that 

What is the correct behaviour? We want to just return whatever string got passed in:

. If there's more than one instance of the 

This feels like a tricky bug to fix - until we consider how 

${infer TPrefix}${TToReplace}${infer TSuffix}

This means that the rest of the work needs to be performed on 

. Again, this feels intractable - until we realise that you can call types 

Whenever you're doing recursion, you need to make sure you don't end up in an infinite loop. So let's track what 

StringReplace<"Matt Pocock III", " ", "-">

). We found the end of our recursive loop!

Thanks for following along on this deep dive of conditional types, template literals and 

, and build up all the knowledge with step-by-step exercises.

TypeScript's template literal syntax enables powerful string manipulation and transformation using unions, infer, and recursion.

TypeScript's template literal syntax allows developers to manipulate and transform strings in a powerful way. This can be extended using unions, infer, and recursion to handle more complex tasks.

Writing string.replace in TypeScript

 on GitHub) has been walking a long, lonely road. The author of 

, has his eyes on another goal: rewriting TypeScript in Rust.

 is his attempt. It's a drop-in replacement for 

 supporting "all typing and type inference", including all the complexity of generics, conditional types and template literals.

In Donny's words, "the official TypeScript type checker, 

, is very slow". This means in VSCode, the red lines and warnings take a long time to update on large projects.

 is itself "written in TypeScript - which does not support parallel processing". Rewriting 

 in a native language, like Rust, could speed it up immensely.

But there's a problem. Rewriting a library like TypeScript is extremely challenging. First, "absence of [a] specification" for TypeScript's behaviour. Donny's had to infer TypeScript's behaviour mostly test cases alone.

The pure size of TypeScript is daunting. It's had ten years to iterate, grow and add features. A glance at TypeScript's 

TypeScript's velocity is extraordinary. In Donny's words, it's "way too fast". It's one of the most active open-source projects in the world. For a single developer to keep up with a huge team seems impossible.

But Donny is confident. "I think there is no one else on the planet who can and will do it. [...] Many people do not have enough energy to investigate such long-term projects."

But the real killer is the state of open source. Donny doesn't know if his work will be rewarded. But he's seen it happen before. His work on swc landed him a job at Vercel.

 fast, and swc was a perfect fit for them". Vercel are now the long-term stewards of swc - which is now an integral part of their bundler, 

Donny sees problems with the sustainability of open source. "I'm sort of a lucky case. Many open-source maintainers are using enormous amounts of their own time without enough reward."

Donny (kdy1 on GitHub) is rewriting TypeScript in Rust hoping to speed up tsc which is slow due to its TypeScript base.

TypeScript Articles by Matt Pocock