CHAPTER 04 · LANGUAGE

The TypeScript Type System

Coming from Java or C#, TS types look familiar, but the underlying philosophy differs: they describe the shape of data, not class lineage; and they exist only while you write code, leaving no trace at runtime. Grasp those two points and you know what types can and cannot protect you from.

Opening: all green, still crashed in production

Where the answer lies: that record came from an external API, and the code says const link = await res.json() as Link. as means "compiler, trust me". The compiler did — but the actual runtime data had no tags field. TS types are your declaration of the data's shape. The compiler checks your code against the declaration; it never checks real data against the declaration. So every piece of data entering from outside the program must be validated once at runtime.

Structural typing: shape, not ancestry

In Java, compatibility depends on declarations: class Dog implements Animal lets a Dog be used as an Animal. That's nominal typing. TypeScript uses structural typing: if the shape fits, it's compatible, no declaration needed.

It's a lot like Go's interfaces (implicit implementation), just extended to every type, plain objects included.

Building blocks

type or interface? For describing object shapes they're almost interchangeable. interface can be re-declared and merged automatically and sometimes gives friendlier errors; type can express anything, including unions and tuples. In practice: pick one as a team convention. Many projects default to type and use interface for public object shapes meant to be extended. It's style, not correctness.

Unions and narrowing Deep

Union types are TS's most expressive feature and where it differs most from Java's type system. If a value's type is string | null, you can't call .length directly — you must first prove it isn't null. That proof is called narrowing: the compiler follows your if, return, typeof, in checks and gives the same variable different types at different points in the code.

Discriminated unions: modeling multi-state data

Each LinkNote bookmark has a status: pending, done or failed. Each status has different fields: only done has a summary, only failed has an error. A Java programmer's first instinct is usually one big class with every field nullable:

The discriminated-union approach: one shape per state, told apart by a shared literal field (the discriminant). Illegal states simply can't be represented:

This pattern is everywhere in TS: request state (loading / success / error), LLM streaming message parts (text / tool-call / tool-result), Redux actions, event types… Whenever you see a type: "..." or kind: "..." field, think of it.

Exhaustiveness checks: let the compiler tell you what you missed

If someone later adds a fourth status archived to Bookmark, every switch that forgot it fails to compile. This is the type system at its most valuable: turning "changed it here, forgot it there" bugs into compile errors. When agents make sweeping changes, that protection matters more than ever.

Type inference: write fewer types, in the right places

TS inference is strong. Most local variables need no annotation. A practical rule:

• Always annotate: function parameters; return types of exported public functions (as a contract); entry points of external data.
• Let it infer: local variables, callback parameters, return values of simple functions.

Two keywords that help inference:

The typeof STATUSES line shows an important habit: derive types from a single source of truth instead of writing them by hand in two places that can drift apart.

Generics

Generics let a function or type stay general over "some type to be decided" while keeping type information. Same concept as Java generics, but in TS they're used heavily for inference:

Utility types: deriving new types from existing ones Use

You'll see much fancier "type gymnastics" in library declarations (conditional, mapped and template literal types). Aware Knowing they exist is enough: reading the errors matters more than writing them. Hand complex type-writing to the agent, but require type tests or usage examples.

Type erasure and boundary validation Deep

Back to the opening question. Since types don't exist at runtime, data in your program falls into two categories:

Zod: define once, get both a validator and a type

Zod is the de facto standard for runtime validation in TS (Valibot and ArkType are alternatives; most implement the shared Standard Schema interface, so frameworks accept them generically). Its core value: you write one schema and the TypeScript type is derived from it, so the two can never disagree.

You'll see the same Zod schema reused in many places: form validation, API input validation, env var validation, DB result validation — and, very importantly, constraining LLM structured output (Chapter 11).

Escape hatches: when they're OK and when they're red flags

About enum

People from Java/C# naturally reach for enum. In modern TS, prefer unions of string literals or as const objects: they're pure types that erase cleanly (Node's type stripping doesn't support enum, because enums generate runtime code), and they map naturally onto string values in JSON and databases.

Reading type errors

TS errors can run to dozens of lines. Three tips:

1. Read from the bottom up. The last line is usually the most specific mismatch ("property X is missing in type Y").
2. Hover both sides. Look at the "expected" type and the "actual" type separately; the difference is the answer.
3. Ask the agent to explain, not to fix. First ask "what inconsistency in my data model does this error reveal?"; once you understand, decide whether to change the type or the code. Saying "fix this error" often gets you an as.

Self-check