Assertion functions

Two signature shapes, both asserts

Before reaching for if (!x) throw or scattering ! across a file, ask yourself whether the false case is a bug or a legitimate variant. If it is a bug, an assertion function expresses that intent — and the compiler enforces it for the rest of the scope.

TypeScript 3.7 introduced assertion signatures: a void-returning function whose return type is asserts …. There are two forms.

// Form 1 — asserts a condition is true
function assert(condition: unknown, msg?: string): asserts condition {
  if (!condition) throw new Error(msg ?? "Assertion failed");
}

// Form 2 — asserts a value has a specific type
function assertIsString(x: unknown): asserts x is string {
  if (typeof x !== "string") throw new TypeError("not a string");
}

The contract is a promise to the compiler: if this function returns normally, the assertion held. The only way to “not return normally” is to throw. So after the call, the compiler can assume the narrowed fact for every subsequent statement in the scope — because if the fact were false, control would never have reached them.

function load(raw: unknown) {
  assertIsString(raw);
  raw;
  // ^? string   — narrowed for the rest of the scope, no branch needed
  return raw.toUpperCase();
}

Predicate vs assertion: branch-narrowing vs scope-narrowing

This is the senior distinction. A type predicate (x is T) returns a boolean and narrows only inside the branch where the boolean is truthy. An assertion function (asserts x is T) returns void and narrows the rest of the scope after the call, because the false case has already thrown.

// Predicate: narrows inside the if-branch only
function isStr(x: unknown): x is string {
  return typeof x === "string";
}
function a(x: unknown) {
  if (isStr(x)) {
    x; // ^? string  (only here)
  }
  x;   // ^? unknown (back to wide outside the branch)
}

// Assertion: narrows everything after the call
function b(x: unknown) {
  assertIsString(x);
  x; // ^? string  (for the whole remaining scope)
}

Choose a predicate when you want to handle both cases; choose an assertion when the false case is a bug you want to fail loudly on.

The annotation is mandatory — and unchecked

An assertion signature is never inferred. If you omit the explicit : asserts … return type, TypeScript types the function as returning void and the call narrows nothing — silently.

// Missing the asserts annotation:
function assertNum(x: unknown) {     // inferred return: void
  if (typeof x !== "number") throw new Error();
}
function c(x: unknown) {
  assertNum(x);
  x; // ^? unknown   — NOT narrowed; the assert effect was lost silently
}

There is no error here — just a missing narrowing, which is the dangerous kind of bug. Worse, the body is not checked against the claim. TypeScript trusts the signature; it does not verify that the function actually throws when the assertion is false.

function brokenAssert(x: unknown): asserts x is string {
  // forgot to throw! does nothing
}
function d(x: unknown) {
  brokenAssert(x);
  x.toUpperCase(); // x is `string` to the compiler, but at runtime x may be anything → crash
}

This is the central unsoundness: an assertion function is a load-bearing claim the type checker takes on faith. The body must genuinely throw on the false case, or you have lied to the compiler. Keep assertion functions tiny and obviously-throwing, and let validation libraries (Zod et al.) generate them so the throw can’t drift from the type.

Assertions and definite assignment

Assertion functions also interact with definite-assignment analysis. A common pattern is asserting that a value is assigned before use, which lets the compiler treat a let as definitely-assigned afterward — but note this only works through the asserts mechanism, not by ordinary control flow, so the same “must actually throw” discipline applies. Used soundly, assertDefined(config) replaces a forest of ! non-null assertions with one auditable choke point.