Assignment and Declared-Type Narrowing

## Two inferences from the same initializer When TypeScript infers a variable's type from its initializer, it first asks whether the binding can ever hold a different value. ```ts const greeting = "hi"; // type: "hi" let message = "hi"; // type: string ``` A `const` binding can never be reassigned, so the compiler is free to keep the most precise type it can name: the *string literal type* `"hi"`, a type whose only member is the string `hi`. A `let` binding can be reassigned. If the compiler kept `"hi"` there, every later `message = "bye"` would be an error and the variable would be unusable, so the literal is **widened** to its base primitive type, `string`. The rule is uniform across primitives: ```ts const n1 = 42; // 42 let n2 = 42; // number const b1 = true; // true let b2 = true; // boolean ``` ## Widening happens at the mutable location The literal types produced by inference are widening literal types: they collapse to the base type wherever they land in a mutable slot. That is why widening also reaches into object literals, whose properties are mutable by default: ```ts const config = { mode: "fast" }; // { mode: string } config.mode = "slow"; // allowed — the property is string ``` And why copying a `const` into a `let` loses the literal: ```ts const a = "hi"; // "hi" let b = a; // string ``` ## Why the difference is visible in real code The distinction shows up the moment a value flows into a parameter that expects a union of literals: ```ts declare function setMode(mode: "fast" | "slow"): void; const fixed = "fast"; setMode(fixed); // OK — fixed is "fast" let current = "fast"; setMode(current); // Error: Argument of type 'string' is not // assignable to parameter of type '"fast" | "slow"'. ``` The error message is the giveaway: the compiler is not complaining about the *value*, which is perfectly valid, but about the widened *type* of the variable that carries it. Nothing about the runtime differs; the two calls emit identical JavaScript. ## Keeping precision on a mutable binding The fix is to give the mutable binding a declared type instead of relying on inference: ```ts let current: "fast" | "slow" = "fast"; setMode(current); // OK current = "slow"; // OK — inside the declared type // current = "turbo"; // Error — outside the declared type ``` The annotation does two jobs at once. It caps what the variable may ever hold — the declared type is the ceiling for every future assignment — and it lets control-flow analysis track which member of the union the variable currently holds, so a `switch` or comparison on `current` still narrows. For object literals the equivalent tool is a declared type on the variable (`const config: { mode: "fast" | "slow" } = { mode: "fast" }`), or a const assertion, which is its own topic. ## Common traps - **`const` is not deep.** `const` freezes the *binding*, not the object. A `const` object's properties still widen and are still writable; only the variable cannot be re-pointed. - **An annotation on a `const` throws precision away.** `const mode: string = "fast"` gives `string`, not `"fast"` — the declared type always wins over inference. - **Widening is not a runtime behaviour.** Types are erased; `let` and `const` differ at runtime only in JavaScript's own binding and scoping rules, which are a separate subject. Everything above is purely what the checker sees. ## The mental model Inference gives you the most useful type, not the narrowest possible one, and "useful" depends on mutability. Immutable binding, precise type; mutable binding, room to move. When you want a mutable binding to *also* be precise, you must say so with an annotation — the compiler will not guess a restriction you did not write.