Unions & Narrowing

Annotate the function's return type explicitly and omit the fallback branch. A missing case leaves the end point reachable, and under strictNullChecks the compiler reports that the function lacks an ending return statement. noImplicitReturns gives the same protection.

Inference widens the object's kind property to string, and string is not assignable to the literal type 'circle'. Fix it by annotating the variable as Shape, adding as const, or using satisfies Shape.

An assertion call only works when every name in the call target has a written-out type, and this const's type is inferred from its arrow initializer. Fix it by annotating the binding with a function type, or by using a function declaration.

On TypeScript 5.5 and later the compiler infers a type predicate for that arrow and the result is string[]; on earlier versions it stays (string | undefined)[]. Passing a function declared with a value is string return type always gives string[].

Narrowing an element access requires the key to be a stable literal, so the checker can treat both obj[key] occurrences as the same slot. A const key has a literal type; a let key widens to string and is mutable, so the two accesses are not matched.

Stop encoding absence as a falsy in-band value. Model the missing state as null or an optional property so the checker can see it, normalise the API's "" at the boundary, and require presence checks like x != null instead of truthiness, which narrows types and never values.

TypeScript's type system is structural, so two classes with identical members are interchangeable types. Narrowing keeps every union member compatible with the target, which is both of them. Giving one class a private or #private field makes them incompatible and restores the narrowing.

Control-flow analysis only invalidates a narrowing at assignments it can see on the path being analysed. A call to reset() is opaque to it, so the narrowing survives the call even though the value no longer holds. Copy the checked value into a local const to make the read safe.

No complaint: the checker invalidates narrowing only on assignments it can see in the same body, so calls and awaits leave it intact. That is deliberately unsound — snapshot the value into a const before awaiting, or re-check after it.

getElementById is typed to return an element or null precisely because the element may be missing; the ! told the checker to drop the null case and emits no check of its own. Replace the assertion with an explicit test that throws a descriptive error at startup.

Types are erased at compile time, so the exhaustiveness proof covers only the code — not the data. A value whose tag is outside the declared union reached the dispatch, almost always through an unvalidated payload or an as assertion at a boundary.

Yes, it can run. Types are erased, so the emitted switch has no idea the default is supposed to be impossible, and a payload with an unrecognised tag lands there. Write it defensively: log the actual tag and fail loudly.

Declare it with the bare assertion form: function invariant(condition: unknown, message?: string): asserts condition. After the call the compiler applies whatever narrowing the condition expression would have produced inside an if, so the id binding becomes string.

Nothing decides T except the caller's annotation, and the body compiles only because the DOM lib types Response.json() as Promise<any>. The signature is a disguised cast. Return Promise<unknown> and force a guard, or take a validating parser that infers T.

Predicate bodies are never checked against the asserted type, so a guard silently keeps promising a shape it no longer verifies. The durable fix is one source of truth: derive the static type from a runtime schema so the check cannot fall behind the type.

Judge each assertion by where the knowledge lives. It is acceptable when the invariant is established visibly nearby and cheap for a reviewer to confirm; it is unacceptable on data crossing a trust boundary, where validation belongs once at the edge instead.

A variable declared with no annotation and no initializer gets an evolving type rather than a fixed any: TypeScript infers it at each use from the assignments that reach that point. After value = 1, reads of value see number.

A method returning this is Foo is a type predicate on the receiver: when it returns true, the object you called it on is narrowed to Foo for the rest of the branch. Reach for it when the object owns the state being checked.

Rely on inferred narrowing where the check and its use are visible together inside one function, and make the narrow type the declared type wherever data crosses a module or API boundary, so the guarantee lives in a signature rather than in a body someone can edit.

Treat the errors as a signal that mutable state is read late. Narrow once at the boundary into immutable locals, pass narrowed values into callbacks as arguments, and model state as replaced discriminated unions rather than optional fields flipped in place.

Pick one conventional, required field name that carries no data of its own, give it readable string-literal values that are unique within the union, and treat those values as a published contract: renaming one is a breaking change for every producer and consumer.

Decide whether the union is closed or open, and say so in the contract. A closed union makes every addition a breaking change consumers must handle; an open union asks consumers to keep a real fallback branch and gives up compile-time exhaustiveness.