Inference, widening and narrowing

Inference and widening

1let a = "draft" // string2const b = "draft" // "draft"3const c = { status: "draft" } // { status: string }4const d = { status: "draft" } as const // { readonly status: "draft" }5const e = [1, "x"] // (string | number)[]

The rule behind these: the checker infers the type the value could later hold. A let can be reassigned and an object property can be overwritten, so the literal "draft" is widened to string. A const binding can't change, so it keeps the literal type. as const says that nothing in the expression will change: properties become readonly and keep their literal types, and arrays become readonly tuples.

Contextual typing works in the other direction. In [1, 2, 3].map((n) => n * 2), nobody wrote that n is a number: the checker knows what map passes to its callback.

Narrowing

A union type says a value may be one of several things. Each check you write tells the checker which one it has, from that point on:

1type Shape = { kind: "circle"; r: number } | { kind: "square"; side: number }2 3function describe(input: string | number | Shape | null) {4  if (input === null) return "nothing" // equality5  if (typeof input === "string") return input.toUpperCase() // typeof6  if (typeof input === "number") return input.toFixed(2)7  if ("r" in input) return `circle ${input.r}` // in8  return `square ${input.side}` // only one possibility left9}

None of this is magic: each check is ordinary JavaScript that runs, and the checker follows the control flow (returns, else branches, assignments) to know which checks have passed at each line. Narrowing can only work with what exists at runtime, which is why it uses typeof, in and property values rather than type names.

When a check is too complex to follow, write a type predicate:

1type Item = { id: string; price: number }2 3function isItem(x: unknown): x is Item {4  return typeof x === "object" && x !== null && "id" in x && "price" in x5}

The checker trusts the x is Item claim without verifying the body, so a careless predicate is just a cast in disguise. Since TypeScript 5.5 it can infer simple predicates by itself, for example in values.filter((v) => v !== undefined).

satisfies: check without widening

1type Config = Record<string, string | number>2 3const annotated: Config = { port: 8080, host: "localhost" }4const checked = { port: 8080, host: "localhost" } satisfies Config5 6checked.port.toFixed(0) // fine: still known to be a number7annotated.port // type is string | number, and the key may not exist at all

An annotation replaces the inferred type; satisfies only checks against it. Use it for configuration objects and lookup tables, where you want both the check and the precise keys and values.