Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt

Use this file to discover all available pages before exploring further.

An assertion function is a specialized type guard that leverages TypeScript’s control flow analysis to narrow types by throwing an error if a specified condition is false. Unlike standard type predicates that return a boolean, an assertion function guarantees to the compiler that if the function returns normally (without throwing an exception), the asserted condition holds true for the remainder of the current scope. TypeScript supports two distinct syntactic forms for assertion functions:

​
1. Asserting a Condition

This form narrows the type based on the truthy evaluation of a parameter. The return type signature uses the asserts keyword followed by the parameter name. 
function assert(condition: unknown, message?: string): asserts condition {
    if (!condition) {
        throw new Error(message ?? "Assertion failed");
    }
}

​
2. Asserting a Type

This form acts similarly to a user-defined type guard (value is Type), but operates via control flow termination rather than a boolean return. The signature uses asserts [parameter] is [Type]. 
function assertIsString(value: unknown): asserts value is string {
    if (typeof value !== "string") {
        throw new TypeError("Value must be a string");
    }
}

​
Compiler Mechanics and Rules

  • Control Flow Integration: When the TypeScript compiler encounters an assertion function call, it applies the assertion to the subsequent control flow graph. If assertIsString(x) is called, the compiler narrows the type of x to string for all code paths following the call, knowing that any non-string value would have terminated execution via the thrown error.
  • Explicit Signatures Required: TypeScript will never infer an asserts signature. It must be explicitly annotated on the function declaration.
  • Return Type Constraints: The return type of an assertion function is implicitly void. The TypeScript compiler strictly enforces this at compile time; attempting to return a value from a function annotated with asserts will yield a standard type mismatch error, such as Type 'string' is not assignable to type 'void'.
  • Parameter Binding: The asserts keyword must reference a specific parameter from the function’s own parameter list. You cannot assert a condition on a variable outside the function’s immediate scope.
  • Arrow Functions: Assertion signatures can be applied to arrow functions, but the type must be explicitly declared, requiring an explicit return type annotation.
// Arrow function syntax requiring explicit return annotation
const assertIsNumber = (val: unknown): asserts val is number => {
    if (typeof val !== "number") throw new Error("Not a number");
};

​
Method Assertions

Assertion functions can also be implemented as class methods. In this context, the assertion can narrow the type of the class instance itself using asserts this is Type. 
class DataWrapper {
    value: string | null = null;

    assertHasData(): asserts this is this & { value: string } {
        if (this.value === null) {
            throw new Error("Data is uninitialized");
        }
    }
}
Master TypeScript with Deep Grasping Methodology!Learn More