Proposal for an Error.assert() method.
Author:
- @threepointone (Sunil Pai, PartyKit)
Today, it is very common to write a utility function like this:
function assert(condition, message) {
if (condition === false || condition == null) {
throw new Error(
message != null ? `Assertion failed: ${message}` : `Assertion failed`
);
}
}And use it it like so:
function add(a, b) {
assert(typeof a === "number", "a must be a number");
assert(typeof b === "number", "b must be a number");
return a + b;
}Additionally, this is useful in a typed language like typescript, where you can use it to assert type invariants and narrow the type of a variable:
function assert(value: boolean, message?: string): asserts value;
function assert<T>(
value: T | null | undefined,
message?: string
): asserts value is T;
function assert(value: unknown, message?: string): void {
if (value === false || value == null) {
throw new Error(
message != null ? `Assertion failed: ${message}` : "Assertion failed"
);
}
}
function add(a: number | void, b: number | void): number {
assert(typeof a === "number", "a must be a number");
assert(typeof b === "number", "b must be a number");
return a + b; // a and b are now narrowed to number
}There are a number of existing libraries that provide this functionality:
- assert
- tiny-invariant
- invariant
- Runtimes like node.js provide it as part of their standard library (as the
assertmodule).
This proposal removes the userland implementation, and replaces it with a built-in method, Error.assert().