An assertion function is the implementation of a runtime check that is able to identify the type of unknown input. When the conditions of the assertion functions are passed, TypeScript’s compiler will then assume that the input is of the type claimed by the signature of the assertion function.
Assertion Function
The TypeScript code below examines an input of type unknown. If the assertUser function does not produce an error, TypeScript’s compiler will assume that the input is of type User as specified in the signature of the assertion function with asserts input is User:
if (!hasAge) { thrownewError('User does not have an age.'); }
if (!hasName) { thrownewError('User does not have a name.'); } }
thrownewError('Input is not an object'); }
functionprintAge(input: unknown) { // My `input` is unknown here assertUser(input); // After passing the assertion function, my `input` is typed console.log(input.age); }
// Error: User does not have an age. printAge({name: 'Benny'});
Benefits
Assertion functions are useful in situations where the type of a value is uncertain, especially when the value originates from external sources such as user input or third-party libraries.
Unlike type assertions, which are only used by the compiler to check the type of a value, assertion functions generate JavaScript code that performs the check at runtime.
Assertion functions can check that the input meets certain criteria, and if it doesn’t, they can raise an error, preventing the rest of the code from executing in an undefined state.
Disadvantages
Because the checks of an assertion function are created by the user, it is possible for them to contain errors or omitted conditions.
Incorrect Assertion Function
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
typeUser = { age: number; name: string; }
// This assertion function is insufficient and only checks whether the input existsF functionassertUser(input: unknown): asserts input is User { if (!input) { thrownewError('Input is not a User.'); } }
const user = 1337; assertUser(user); // We have convinced TypeScript's compiler that our `number` is of type `User` console.log(user.name);
Assertion Functions in Node.js
If your code is running in a Node.js environment and you have installed @types/node, you can make use of Node’s built-in module assert:node to do assertions on your variables:
1 2 3 4 5 6 7 8 9
import assert from'node:assert';
functiongetShortenedText(text?: string): string { assert.ok(text, 'expected text to be defined'); // Thanks to the "assert" from above, TypeScript knows that "text" is defined: return text.slice(0, 5); }