TypeScript · Const

asserts

asserts defines assertion signatures that narrow types after a function returns successfully. It supports asserting a condition or declaring that a parameter has a specific type.

Since: 3.7

How it works

asserts marks a function as an assertion function. If the function returns normally, TypeScript uses either the asserted condition or a parameter is Type predicate to narrow types in the remaining control-flow scope; the implementation must enforce the claim at runtime.

Syntax

function assert(condition: any, msg?: string): asserts condition
function assertIsString(val: any): asserts val is string

Returns

An assertion signature narrows the checked condition or named value after the function returns normally.

Key points

Assertion signatures model runtime checks that stop execution when an expected condition is not met.
The condition form narrows control flow after a successful assertion call.
A condition assertion uses asserts condition in the return-type position.
A type assertion uses asserts parameter is Type to narrow a particular value.
Assertion signatures and type predicates express related narrowing relationships, but assertions continue execution only after validation succeeds.
Generic assertions can use NonNullable<T> to narrow away both null and undefined.

Common mistakes

An assertion signature can claim a parameter has a type without TypeScript verifying the implementation, so the function must throw or otherwise reject invalid values itself.
With asserts condition, the condition is considered true only after the function returns; an unsound assertion can make later code incorrectly unreachable or over-narrowed.

Example: Narrowing with an assertion function

function assertIsString(value: unknown): asserts value is string {
  if (typeof value !== "string") {
    throw new TypeError("Expected a string");
  }
}

function shout(value: unknown) {
  assertIsString(value);
  return value.toUpperCase();
}

console.log(shout("hello"));

The assertion validates the runtime value and lets TypeScript treat it as a string after the call.

When to use it

Validate external input

A boundary receives unknown data and must reject invalid values before typed code uses it.

Enforce non-null values

A generic value may be absent during lookup but must be present before processing.

Encode control-flow invariants

An invariant must hold for the rest of a function after a check.

Interview questions

QWhat does asserts do?

An assertion signature tells TypeScript what is guaranteed when a function returns normally. asserts condition narrows the condition itself, while asserts value is Type narrows a named parameter or property.

Follow-up: How does this differ from a type predicate? A type predicate returns a boolean for the caller to branch on; an assertion function generally throws on failure and narrows after the call continues.

QHow does asserts condition affect control flow?

For asserts condition, the condition passed to the function is treated as true for the rest of the containing scope if the function returns. The typical implementation throws when the condition is false.

Follow-up: What happens if the implementation fails to throw? The compiler still trusts the signature, so invalid states can be accepted and subsequent narrowing can be unsound.

QWhen would you use asserts value is Type?

asserts value is string states that the named value is a string after successful return. This resembles a type predicate, but it changes control flow through the assertion call instead of returning a boolean that must be tested.

Follow-up: Can the asserted type be generic? Yes; the documentation demonstrates asserts val is NonNullable<T> to remove null and undefined from a generic value.

type predicates
type guards
NonNullable
narrowing
assertion signatures

Source: Documentation - TypeScript 3.7. Checked 2026-10-15.