Type System Fundamentals & Type Inference
TypeScript's type system has two modes of operation: explicit annotation (the developer states the type) and inference (TypeScript derives the type from the value or context). Most of the time, inference is sufficient and annotation is noise. Understanding where each belongs is the first practical TypeScript skill.
The primitive types (string, number, boolean, null, undefined, symbol, bigint) and the escape hatches (any, unknown, never) form the foundation. any disables type checking. unknown is the safe alternative — it accepts any value but forces narrowing before use. never represents unreachable code and drives exhaustiveness checking.
Union types (string | number) and intersection types (A & B) let the type system express "one of these" and "all of these" respectively. Literal types ('success' | 'error') turn string/number/boolean values into types, enabling discriminated unions and exhaustiveness checking.
Design Thinking
Inference eliminates annotation noise
TypeScript infers the type of const x = 42 as number, const arr = [1, 2, 3] as number[], and function return types from the return expression. Annotating these manually adds maintenance burden without safety benefit. The boundary where annotation matters: function parameters (inference cannot reach across call sites), public API return types (explicit contract), and variable declarations that will be assigned later.
any vs unknown: the difference matters
any is a bidirectional escape: a value typed as any can be assigned to any type and can have any operation performed on it without error. unknown is one-directional: any value can be assigned to unknown, but unknown cannot be used until narrowed. This makes unknown safe for representing genuinely unknown input (JSON responses, error catch clauses) while any is safe for nothing.
never as correctness proof
A function that throws always returns never. A switch statement that handles all cases of a union has a default branch that is unreachable — TypeScript types that branch as never. Assigning the value to a variable typed never causes a compile error if a new union member is added without updating the switch. This pattern is called exhaustiveness checking.
Best Practices
MUST prefer unknown over any for values of genuinely unknown type. any disables all type checking for the value and everything derived from it — a property access on an any value returns any, spreading the unsafety silently through the codebase. unknown forces explicit narrowing before use, preserving the type safety guarantee. Use unknown in error catch clauses, for deserialized JSON, and for any value whose shape is not known at the call site.
MUST use never exhaustiveness checks in switch statements and discriminated union handlers. When a switch statement handles a discriminated union, the default branch should assign the value to a never-typed variable. If a new member is added to the union without updating the switch, the assignment fails to compile. This pattern makes the switch a compile-time contract: adding a variant without handling it is a build error, not a silent runtime fallthrough.
SHOULD let TypeScript infer types for local variables, array/object literals, and function return types where the return expression makes the type obvious. Explicit annotations at inference sites add line noise and create a second source of truth that can drift from the actual type. Reserve explicit annotations for function parameters, public API return types, and variables that are declared before assignment.
SHOULD use literal types and union types to model domain values rather than widening to string or number. A status field typed as 'pending' | 'fulfilled' | 'rejected' is more precise than string and enables exhaustiveness checking wherever the field is switched on. Widening to string discards the constraint and removes the compile-time guarantee that all states are handled.
Related FEEs
- FEE-1700 — TypeScript Overview
- FEE-1702 — Generics
- FEE-1704 — Narrowing & Type Guards
References
- TypeScript Handbook: Everyday Types — https://www.typescriptlang.org/docs/handbook/2/everyday-types.html
- TypeScript Handbook: Narrowing — https://www.typescriptlang.org/docs/handbook/2/narrowing.html
- TypeScript Handbook: More on Functions — https://www.typescriptlang.org/docs/handbook/2/functions.html