TypeScript Reference ยท Narrowing and Type Guards
Assertion functions in TypeScript
Reference for TypeScript assertion functions: asserts x is T and asserts condition signatures, how they narrow after the call, explicit typing rules and examples.
An assertion function checks a condition and throws if it fails. Its return type tells TypeScript that, if the call returns normally, a fact is true for the rest of the scope. There are two forms: asserts condition (the argument is truthy) and asserts x is T (the parameter has type T).
Unlike a type guard you do not wrap the call in an if. The statements after the call are narrowed, which makes assertion functions a good fit for validation at the top of a function.
function assert(condition: unknown, message: string): asserts condition { if (!condition) throw new Error(message); }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Syntax
function f(arg: unknown): asserts arg is T { ... } function f(arg: unknown): asserts arg { ... }
| Form | Meaning after a normal return |
|---|---|
asserts arg is T |
arg has type T. |
asserts arg |
arg is truthy, so null, undefined, false, 0 and "" are removed. |
asserts this is T |
In a method, the receiver is T. |
Edge cases:
- Every name in the return type must be a parameter of the function.
- If the function being called was not declared with an explicit type annotation, the compiler reports TS2775 ("Assertions require every name in the call target to be declared with an explicit type annotation.") and does not narrow, so a follow-up error such as TS18047 appears. The last example shows both.
- The return type of an assertion function is effectively
void; a function that never returns normally should be typednever.
Usage notes
- Explicit type required for the callee. Declare assertion functions with the
functionkeyword, or give an arrow function stored in aconsta full type annotation. The compiler needs to know the function is an assertion before it analyses the call. - TypeScript does not check the body against the signature, so make the check match what you promise.
- Good for invariants. Use them for preconditions, parsed configuration and test helpers. Node's
assertmodule is typed with assertion signatures, soassert(x)narrows too. - Not for expected failures. Throwing is for programmer errors and invalid input you cannot continue from. If failure is a normal outcome, return a boolean guard or a result type.
- Control flow. Code after the call is narrowed, and code in a
finallyis not. Inside loops, the narrowing holds only until the variable is reassigned. - Difference from
as. A type assertion (x as T) checks nothing at run time. An assertion function really performs the check. - No effect on callbacks. Narrowing established by the assertion does not extend into a callback if the variable might change later.