Skip to content
Tutorials Center
My learning

Topics

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.

TypeScript
function assert(condition: unknown, message: string): asserts condition {
  if (!condition) throw new Error(message);
}

Try it

TypeScript asserts condition

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.

TypeScript asserts x is T

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.

TypeScript Assertion functions need an explicit type

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

TypeScript
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 typed never.

Usage notes

  • Explicit type required for the callee. Declare assertion functions with the function keyword, or give an arrow function stored in a const a 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 assert module is typed with assertion signatures, so assert(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 finally is 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.