Assertion Functions (asserts x is T)

## Two shapes for the same idea A user-defined guard is a function whose signature tells the checker something it cannot work out on its own — that a value with a wide type is really a narrower one. TypeScript offers two signatures for this, and interviewers use the contrast to see whether a candidate reasons about control flow or just memorises syntax. ```ts type User = { id: string }; function isUser(value: unknown): value is User { return typeof value === "object" && value !== null && "id" in value; } function assertIsUser(value: unknown): asserts value is User { if (!isUser(value)) throw new TypeError("not a User"); } ``` ## What the compiler does with each The predicate form returns a genuine `boolean` at runtime. Its declared type, `value is User`, tells the checker: wherever this boolean is `true`, treat the argument as `User`; wherever it is `false`, remove `User` from the argument's type. Narrowing is therefore *scoped to the test*. ```ts function withPredicate(value: unknown): string { if (isUser(value)) { return value.id; // narrowed only inside this branch } return "anonymous"; // here it is still unknown } ``` The assertion form returns nothing. Its signature says the call throws or the claim holds, so the checker applies the narrowing to the *continuation* of the flow: ```ts function withAssertion(value: unknown): string { assertIsUser(value); return value.id; // narrowed for the rest of the path } ``` That difference cascades into everything else. The predicate gives you two typed paths; the assertion gives you one, because the other path left the function. The predicate produces a value you can store, negate, or pass on; the assertion produces nothing testable — `if (assertIsUser(x))` is a compile error, TS1345, because a `void` expression cannot be tested for truthiness. ## Composability Because the predicate is an ordinary boolean-returning function, it can be handed to anything that expects a boolean callback, and the compiler carries the narrowing claim through. An assertion function cannot be used that way: it returns nothing, and its effect is expressed through control flow at a direct call site rather than through a value. If you need a guard that other code can call as a plain function and act on, it must be the predicate. ## One signature, one shape A function's signature carries either `value is User` or `asserts value is User`, never both. In practice teams write the predicate as the single source of shape-checking truth and let the assertion delegate to it, exactly as `assertIsUser` does above. That gives two call styles over one implementation and keeps the two guards from drifting apart. ## Choosing between them Ask what the failing case *is*. If a non-`User` is a normal state your caller has an answer for — render a placeholder, skip the item, take a different branch — the predicate is right, because you want both paths typed and you want a value you can compose with. If a non-`User` means the caller was handed something it was never supposed to receive, the assertion is right. The call reads as a precondition, the rest of the function is written against the narrow type without an extra level of nesting, and you avoid the awkward pattern of testing a predicate only to throw in the `else`. A readability signal that shows up in real reviews: a function whose body is one long `if (isUser(value)) { ...forty lines... } else { throw ... }` is usually asking to be an assertion call on line one. ## Consequences to keep straight Both forms are compile-time only. Types are erased, so neither signature emits a check; the runtime behaviour comes entirely from the code you wrote in the body — a `return` of a boolean expression in one case, a `throw` in the other. Both narrow references the checker can track, including property paths: `assertIsUser(payload.user)` narrows `payload.user` on the following lines, until something the compiler can see reassigns it. And neither gives you narrowing in a `catch`. Wrapping an assertion call in `try`/`catch` does not produce the predicate's `else` branch — inside the `catch` the checker assumes the `try` block may have failed anywhere, so the original binding is back to its declared type.