Compiler Performance and Diagnostics

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

Diagnostics

Numbers and timings that tsc prints about its own work.

Instantiation

Filling in a generic type with real types, such as turning Array<T> into Array<string>. Each costs a little time.

Trace

A recording of what the checker did and when, written by --generateTrace.

TS2589

The error 'Type instantiation is excessively deep and possibly infinite': a recursive type that never reaches its end.

skipLibCheck

Do not type-check .d.ts files. Faster, and hides errors in other people's declarations.

Checker (7.0)

A worker thread that type-checks part of a project. --checkers sets how many.

ignoreDeprecations

A 6.0 setting that silences deprecation errors. It has no effect in 7.0, where the options are gone.

Bridge release

A version whose main job is to prepare for the next one. TypeScript 6.0 is the bridge to 7.0.

1. 1

   Find the limit

   In the first example, change Count<2000> to smaller values (Count<500>, Count<999>, Count<1000>) and note when the error appears: in TypeScript 7.0.2 Count<999> is clean and Count<1000> fails. The exact limit is an internal detail that can change between versions, so never design around it.

2. 2

   Read the counters

   In any project of yours run tsc --noEmit --extendedDiagnostics. Write down Files, Types, Instantiations and Check time. Then add skipLibCheck: true and run again: which numbers change?

3. 3

   Read the upgrade errors

   Take the old config in the walkthrough, and for each of the three options write the replacement you would choose (target: your oldest engine, es2015 or later; moduleResolution: bundler or nodenext; esModuleInterop: leave it out, it is always on). Then run both compilers on it.

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

1. 1

   The problem this solves: as a project grows, checking can become slow, and guessing at the cause wastes time. This topic gives you tools to measure where the time goes and a safe path for upgrading the compiler itself. Type checking has a cost that grows with the number of files read, the number of types created and the number of instantiations (each time a generic type like Array<T> is filled in with a real type). Most projects are dominated by reading library .d.ts files and by a few expensive types. **--extendedDiagnostics** prints counters for all of that plus the time spent in each stage: parsing, binding (connecting names to declarations), checking and emitting. Always measure before you change anything.

2. 2

   In practice the numbers to watch are Files (are you accidentally including node_modules sources or whole @types folders?), Types and Instantiations (a sudden jump after a change points to one expensive type), and Check time (almost always the biggest). TypeScript 7.0 prints a shorter list than 6.0, because it has a different internal design, so compare numbers within one version, never across them.

3. 3

   **--generateTrace <dir>** writes a performance trace: trace.json (a timeline you can open in Chrome's chrome://tracing or in Perfetto) and types_*.json (a list of types the checker created). In TypeScript 7.0 you get one types_N.json per checker. The timeline shows which file and which check took long, and the types list shows the huge unions or deeply nested generics behind it. TypeScript's own performance guide describes how to read it.

4. 4

   Things that make types slow, from most to least common: giant unions (thousands of members, where each comparison walks all of them); deeply recursive conditional or mapped types; intersections of large object types repeated everywhere (interface ... extends is cheaper because the result is cached by name); and inferred return types of huge exported functions that the checker has to compute again in every file that uses them. The cure is usually to name an expensive type with a type alias or interface and to annotate exported return types, so work is done once.

5. 5

   There is also a built-in safety limit. When instantiation goes too deep the compiler gives up with **TS2589: Type instantiation is excessively deep and possibly infinite**. It is not a crash: it is the checker telling you a recursive type does not stop soon enough. The live examples below hit it with a counter built from a recursive type. Fixes: add a base case, recurse less deeply, split the work, or rewrite so the recursive call is the last thing in the branch (a tail-recursive conditional type), which lets the compiler loop instead of nesting and allows far more steps than plain nesting does. The counter below is already written that way, so it hits the 1000-step limit: Count<999> is fine and Count<1000> fails.

6. 6

   **skipLibCheck** tells tsc not to type-check any .d.ts file. A broken declaration inside a package you installed then stops being your error, and the check is faster. It is in the tsc --init file because the types in a library file are the library authors' concern, not yours. The price: a mistake in your own hand-written .d.ts (Topic 11.3) is hidden too, and you give up detecting two libraries whose types disagree with each other. Keep it on in apps; for a library you publish, check your own declarations once in CI with it off.

7. 7

   TypeScript 7.0 changes the numbers more than any tuning: the compiler was ported to Go, so it runs as native code on several threads. The announcement reports about a ten times speed-up (VS Code's repository: 125.7 s down to 10.6 s). Type-checking results are the same as 6.0. Parallelism is controlled by --checkers (checker workers per project), --builders (projects built in parallel, Topic 12.4) and --singleThreaded (turn it all off, handy for comparing or for tiny CI machines). The numbers on your project will differ from the headline: it depends on project size, core count and disk.

8. 8

   Upgrading is a two-step path. From 5.x go to 6.0 first: it still runs on JavaScript, accepts old options with warnings, and has new defaults (strict: true, types: [], module: esnext, rootDir = the tsconfig folder). Fix every deprecation it reports. Then move to 7.0, where the deprecated options are removed (TS5108, TS5102). "ignoreDeprecations": "6.0" silences the warnings in 6.0 only; it is a deadline, not a solution. Tools that use the compiler's programmatic API (typescript-eslint, framework language tools) can't use 7.0 until it gets an API, so they use 6.0 through @typescript/typescript6 (its executable is tsc6), side by side with 7.0 for tsc.

• ↔

  Aggressive type-level programming gives precise APIs but costs checking time and can hit TS2589. A simpler, slightly less precise type is often the better engineering trade.

• ↔

  Staying on 6.0 keeps every tool that uses the compiler API working; moving to 7.0 gives a large speed-up now. Many teams run 7.0 for tsc and 6.0 for the tools, until the 7.x API lands.

• I can use --extendedDiagnostics and say which numbers matter.

• I can produce a trace with --generateTrace and know what the files in it are.

• I can explain TS2589 and name three ways to avoid it.

• I can explain skipLibCheck and what it hides.

• I can describe the 5.x to 6.0 to 7.0 upgrade and the role of ignoreDeprecations.

• I know that 7.0 checks types like 6.0 but runs natively, and that API-based tools stay on 6.0.