Boundary validation
Validating inputs at API, configuration, or boundary layers before typed code consumes them.
TypeScript · Function
assertion functions
Assertion functions combine runtime validation with compile-time narrowing. If the function returns successfully, TypeScript treats an asserted condition or type predicate as established in the rest of the relevant control-flow scope.
- Since
- 3.7
How it works
An assertion function communicates a runtime invariant through its return type. A signature using asserts condition tells TypeScript the condition is true after successful return, while asserts value is Type narrows a named parameter or property to the specified type; the implementation must enforce that claim, usually by throwing when validation fails.
Syntax
function assert(condition: unknown, msg?: string): asserts condition;
function assertIsString(value: unknown): asserts value is string;Parameters
| Name | Type | Description |
|---|---|---|
value / condition | unknown or a declared parameter type | The condition, value, or property whose runtime invariant the function checks. |
msg | string | undefined | An optional diagnostic supplied by the implementation when the assertion fails. |
Returns
An assertion signature: either asserts condition or asserts parameterName is Type; the function normally throws when the asserted condition is false.
Key points
- Assertion functions are runtime checks that fail early when assumptions about values are violated.
- A bare
asserts valuesignature tells TypeScript that the value is truthy after the function returns. - Successful assertion calls participate in control-flow analysis, so later expressions receive narrower types.
- A type-predicate assertion can narrow a parameter to a selected subset of a union.
- Assertion functions and type guards are related mechanisms, but assertions refine control flow after a successful call.
Example: Narrowing with a type assertion
function assertIsString(value: unknown): asserts value is string {
if (typeof value !== "string") throw new Error("Expected a string");
}
function shout(value: unknown): string {
assertIsString(value);
return value.toUpperCase();
}
console.log(shout("hello"));The assertion throws for non-strings; after it returns, TypeScript narrows value to string.
When to use it
Removing uncertainty
Checking that a nullable or broadly typed value satisfies a required invariant before property access or computation.
Union refinement
Progressively narrowing a discriminated union or numeric literal union through multiple successful checks.
Interview questions
QWhat does an asserts condition return type communicate?
asserts condition means that, if the function returns normally, TypeScript treats the supplied condition as true for the remaining scope. The function generally throws when the condition is false.
Follow-up: How does asserts value is string differ? It narrows a named value to string after successful return, rather than asserting an arbitrary boolean condition.
QHow can an assertion function narrow a value to a specific type?
An assertion signature can narrow a value based on a type predicate, such as asserts value is string. After the call, control-flow analysis uses that predicate to refine the value’s type.
Follow-up: Can it narrow a union repeatedly? Yes; successive assertion functions can reduce the remaining possible members of a union.
QHow are assertion functions different from type guards?
Assertion functions are related to type guards, but they affect control flow after the function continues rather than producing a boolean result used directly in a conditional. Their runtime implementation must establish the promised invariant, commonly by throwing on failure.
Follow-up: What happens if the implementation’s check is wrong? TypeScript can still apply the declared narrowing, so incorrect assertions can make later code unsound at runtime.
Related
Type GuardsNarrowingControl flow analysisType predicates