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."

For Donny, the only source of sustainability is sponsorship from companies. "Honestly, I'm still not sure if open-source is sustainable without companies like Vercel."

But despite the possibility his work might not be rewarded, Donny persists. The project is "too essential for the web development ecosystem".

It takes its toll. "Although it's quite fun, it's super exhausting. [...] I stopped working on it several times."

But community contributions help. Donny is working on 

 alone, apart from "some short-time contributors". Financial backers help morale, too. The best place to contribute is 

To me, the project seems precarious. It's an enormous amount to ask from a single developer, even one with extraordinary abilities like Donny. TypeScript's velocity means the project is a long-term commitment.

Financial contributions could help keep the project sustainable. But a 

 seems more likely - where the users of the project don't contribute back to its development.

 is pre-alpha. Donny is working his way towards reducing erroneous errors, and getting feature-complete with TypeScript.

Personally, I can think of few projects more deserving of your support. You can:

: Let's start with the basics - what is stc? What problem is it trying to solve?

 stands for a Speedy TypeScript Type Checker. The goal is to improve DX by reducing build time and iteration time.

, is very slow because it's written in TypeScript - which does not support parallel processing.

: Why did you decide to start working on 

: I started it because I wanted to improve 

. It was actually a subproject of swc at the start.

I think there is no one else on the planet who can and will do it. I mean, it requires way too much effort. Many people do not have enough energy to investigate such long-term projects. But I have. I have seen my effort rewarding me back thanks to swc.

I open-sourced it recently because I thought I will be able to be rewarded via sponsorship in the future if there's enough company using it for everyday development.

Until recently, I couldn't think open-sourcing will compensate me back. Thanks to Vercel, I concluded I can.

: Right - were you hired at Vercel because of your work on swc?

: Yes, Vercel wanted to make Next.js fast, and swc was a perfect fit for them. They needed extensibility.

: But without Vercel, your work on swc might not have been rewarded? What do you think this says about the sustainability of open source?

: I could be rewarded by Deno, but I don't think it's the point. I think it was possible I couldn't get rewarded enough. And it means a Tragedy of the Commons for open-source. I'm sort of a lucky case. Many open-source maintainers are using enormous amounts of their own time without enough reward.

Honestly, I'm still not sure if open-source is sustainable without companies like Vercel.

: So despite that, you've put a lot of effort into 

 already (thank you). You're willing to keep pushing even though it might not be rewarded?

: I can't be 100% sure, but I think so. But I don't think I would develop 

Rather, I would develop it as BUSL or closed source.

: Let's talk more about the technical details of the project. What have you found challenging so far? I'd heard that you switched languages a couple of times.

: The most challenging thing is the absence of the specification. I had to infer everything just from test cases.

The second thing is the velocity of tsc. It's way too fast, and I was unsure if I could follow it up. So I decided to use semi-automated translation and selected Golang.

But it was too boring, and more importantly, my programming ability has improved enough to follow tsc only by myself.

? Are you planning to support everything tsc can currently support, or only a subset?

: The former, but not exactly 100%. I don't like some design decisions of tsc, mainly about diagnostics. Error messages of tsc are too hard to understand, in my opinion.

: Definitely agree about the errors being hard to read. But you're planning to support advanced features like generics, conditional types, overloads etc?

: Yes, all typing and type inference should match 100%. All three features you mentioned are already implemented

: How is progress going? What are you using to measure your progress?

: I'm using stats of the conformance test suite from tsc:

This is the current stat. I'm focusing on reducing 

: Are you able to estimate when it might be 'complete'? I.e. when required_error and extra_error go to 0? Or would you plan to release an alpha earlier than that?

: I'm not sure about the time when it is complete, but I'll release alpha with a language server when the extra_error goes to 0 I hope I can finish within... about 6 months, but I can't be sure. I mean alpha by 'finish'

: Do you have any help on the project? Or so far, is it just you?

: Currently, it's only me, although there are some short-time contributors.

: What's the best way that the community can support you right now?

: As always, contributing developer time is the best. But honestly, I don't think it's possible, considering the difficulty of the project. And the second best contribution is a financial contribution, which helps me use almost all my free time for 

: Where's the best spot to give a financial contribution?

 right now to be working on the project? Doing something so difficult in your spare time must be extremely draining.

Yeah, honestly, it's quite exhausting. But today, I'm quite motivated thanks to 

. Although it's quite fun, it's super exhausting.

: It's great when the community gets involved. Do you think there's a danger that exhaustion could prevent the project from being completed?

: Yes, actually I stopped working on it several times.

: So it's a project which is exhausting, extremely complicated, possibly never-ending and could be without reward. Why do you keep going?

This is too essential for the web development ecosystem

I think I may get rewarded sometime in future

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

Donny (kdy1 on GitHub) is rewriting TypeScript in Rust hoping to speed up tsc which is slow due to its TypeScript base. In this interview, he explains some of the financial and technical challenges they face with this open-source project.

Rewriting TypeScript in Rust? You'd have to be...

Let's imagine you're creating a function which sums up an array of objects. Here's one, taken from the Excalidraw codebase:

Let's look at the type definition. This function takes in:

For each member of the array, it then adds 

 together. So, you end up with the sum of all of the members of the array.

 function is the key. Let's strip it out to take a look at it:

 represents the function that extracts the number from the object. The powerful thing about the 

 function is that you can discard most of these type declarations:

The big mistake I see a lot of beginner devs making is declaring a function like 

This keyword basically stands for 'any function'. It means that 

 is supposed to be, or what our mapper function is supposed to return.

' - there's always a more specific option available.

Sometimes, you'll want to express 'any function' in TypeScript. For this, let's look at some of TypeScript's built-in types, 

Instead of using Function to express types there are several more specific alternatives we could use instead to better describe functions.

TypeScript Articles by Matt Pocock

Structure of a TypeScript Error

Mental Model for TypeScript Generics

When should you use Zod?

Writing string.replace in TypeScript

Rewriting TypeScript in Rust? You'd have to be...

Don't use Function type in TypeScript