JS stdlib — assert API

Member signatures use schematic object.member(...) API notation. Exported type declarations are valid TypeScript.

Runtime assertions that return their validated input.

Each method throws its optional custom Error, or a coded default error, when validation fails. Successful calls return a narrowed value rather than using TypeScript's asserts return type.

import assert from "@rcompat/assert";
import type { Code } from "@rcompat/assert";

assert.bigint#

Requires a bigint value.

assert.bigint(x: unknown, error?: Error): bigint;

Example

assert.bigint(1n); // passes
assert.bigint(1); // throws

assert.boolean#

Requires a boolean value.

assert.boolean(x: unknown, error?: Error): boolean;

Example

assert.boolean(false); // passes
assert.boolean(0); // throws

assert.function#

Requires a callable value.

assert.function(x: unknown, error?: Error): UnknownFunction;

Example

assert.function(() => undefined); // passes
assert.function({}); // throws

assert.number#

Requires a number value, including NaN.

assert.number(x: unknown, error?: Error): number;

Example

assert.number(NaN); // passes
assert.number("1"); // throws

assert.string#

Requires a string value.

assert.string(x: unknown, error?: Error): string;

Example

assert.string(""); // passes
assert.string(1); // throws

assert.symbol#

Requires a symbol value.

assert.symbol(x: unknown, error?: Error): symbol;

Example

assert.symbol(Symbol("id")); // passes
assert.symbol("id"); // throws

assert.undefined#

Requires an undefined value.

assert.undefined(x: unknown, error?: Error): undefined;

Example

assert.undefined(undefined); // passes
assert.undefined(null); // throws

assert.array#

Requires an array value.

assert.array(x: unknown, error?: Error): unknown[];

Example

assert.array([]); // passes
assert.array({}); // throws

assert.date#

Requires a Date value.

assert.date(x: unknown, error?: Error): Date;

Example

assert.date(new Date()); // passes
assert.date(Date.now()); // throws

assert.dict#

Requires a plain object while preserving a narrower input type.

assert.dict<T>(x: T, error?: Error): T extends Dict ? T : Dict;

Example

assert.dict({ name: "Ada" }); // passes
assert.dict([]); // throws

assert.error#

Requires an Error value.

assert.error(x: unknown, error?: Error): Error;

Example

assert.error(new Error("failed")); // passes
assert.error("failed"); // throws

assert.false#

Requires the literal value false.

assert.false(x: unknown, error?: Error): false;

Example

assert.false(false); // passes
assert.false(true); // throws

assert.finite#

Requires a finite number or bigint.

assert.finite(x: unknown, error?: Error): bigint | number;

Example

assert.finite(42); // passes
assert.finite(Infinity); // throws

assert.int#

Requires an integer number or bigint.

assert.int(x: unknown, error?: Error): bigint | number;

Example

assert.int(-1n); // passes
assert.int(1.5); // throws

assert.map#

Requires a Map value.

assert.map(x: unknown, error?: Error): Map<unknown, unknown>;

Example

assert.map(new Map()); // passes
assert.map({}); // throws

assert.nan#

Requires the number value NaN.

assert.nan(x: unknown, error?: Error): number;

Example

assert.nan(NaN); // passes
assert.nan(0); // throws

assert.newable#

Requires a value constructible with new.

assert.newable(x: unknown, error?: Error): Newable;

Example

assert.newable(Date); // passes
assert.newable(() => undefined); // throws

assert.null#

Requires the value null.

assert.null(x: unknown, error?: Error): null;

Example

assert.null(null); // passes
assert.null(undefined); // throws

assert.nullish#

Requires null or undefined.

assert.nullish(x: unknown, error?: Error): Nullish;

Example

assert.nullish(undefined); // passes
assert.nullish(0); // throws

assert.object#

Requires a non-null object.

assert.object(x: unknown, error?: Error): object;

Example

assert.object({}); // passes
assert.object(null); // throws

assert.promise#

Requires a Promise value.

assert.promise(x: unknown, error?: Error): Promise<unknown>;

Example

assert.promise(Promise.resolve()); // passes
assert.promise({}); // throws

assert.regexp#

Requires a regular expression.

assert.regexp(x: unknown, error?: Error): RegExp;

Example

assert.regexp(/rcompat/); // passes
assert.regexp("rcompat"); // throws

assert.safeint#

Requires a number for which Number.isSafeInteger returns true.

Safe integers are whole numbers from Number.MIN_SAFE_INTEGER (-(2 ** 53 - 1)) through Number.MAX_SAFE_INTEGER (2 ** 53 - 1), inclusive. NaN, infinities, fractional numbers, numeric strings, and bigint values are not safe integer numbers.

assert.safeint(x: unknown, error?: Error): number;

Example

assert.safeint(Number.MAX_SAFE_INTEGER); // passes
assert.safeint(Number.MAX_SAFE_INTEGER + 1); // throws

assert.set#

Requires a Set value.

assert.set(x: unknown, error?: Error): Set<unknown>;

Example

assert.set(new Set()); // passes
assert.set([]); // throws

assert.true#

Requires the literal value true.

assert.true(x: unknown, error?: Error): true;

Example

assert.true(true); // passes
assert.true(false); // throws

assert.uint#

Requires a non-negative integer number or bigint.

assert.uint(x: unknown, error?: Error): bigint | number;

Example

assert.uint(0); // passes
assert.uint(-1); // throws

assert.url#

Requires a URL value.

assert.url(x: unknown, error?: Error): URL;

Example

assert.url(new URL("https://example.com")); // passes
assert.url("https://example.com"); // throws

assert.empty#

Requires an empty string, collection, or object.

assert.empty<T>(x: T, error?: Error): T;

Example

assert.empty(""); // passes
assert.empty("value"); // throws

assert.nonempty#

Requires a nonempty value.

assert.nonempty<T>(x: T, error?: Error): T;

Example

assert.nonempty("value"); // passes
assert.nonempty(""); // throws

assert.shape#

Requires a plain object matching a property type descriptor.

A descriptor value ending in ? permits the property to be absent or undefined. Properties not named by the descriptor are ignored.

assert.shape<T>(x: unknown, descriptor: ShapeDescriptor, error?: Error): T;

Example

type User = { name: string; age?: number };
const input: unknown = { name: "Ada" };

const user = assert.shape<User>(input, {
  name: "string",
  age: "number?",
}); // passes
assert.shape(input, { name: "number" }); // throws

assert.defined#

Requires a value other than undefined.

assert.defined<T>(x: T, error?: Error): Exclude<T, undefined>;

Example

assert.defined(null); // passes
assert.defined(undefined); // throws

assert.instance#

Requires an instance of the given constructor.

assert.instance<T extends Newable>(
    x: unknown,
    N: T,
    error?: Error,
  ): InstanceType<T>;

Example

assert.instance(new Date(), Date); // passes
assert.instance({}, Date); // throws

assert.uuid#

Requires a lowercase UUIDv4 string.

assert.uuid(x: unknown, error?: Error): string;

Example

assert.uuid("3b12f1df-5232-4e3c-8bf2-32c1e3b7c1a3"); // passes
assert.uuid("not-a-uuid"); // throws

assert.Code#

Error-code values keyed by the corresponding Code string.

assert.Code: { [K in Code]: K };

assert.every#

Modifier namespace that applies an assertion to every value in an array.

Supports every top-level assertion except shape. Call the corresponding method on assert.every; for example, assert.every.number(values) applies assert.number to each value. Each method returns the original array after all elements pass validation and throws when an element fails. The instance method also accepts the constructor and optional custom error used by assert.instance.

Example

assert.every.number([1, 2, 3]); // passes
assert.every.number([1, "2"]); // throws

Call forms

assert.every.<check>(values) for every top-level check except shape
assert.every.instance(values, Constructor, error?) for instances

assert.maybe#

Modifier namespace that permits null and undefined values.

Supports every top-level assertion. Call the corresponding method on assert.maybe; for example, assert.maybe.number(value) returns null or undefined unchanged and applies assert.number to any other value. The instance and shape methods also accept the additional arguments and optional custom error used by their top-level counterparts.

Example

assert.maybe.safeint(null); // passes
assert.maybe.safeint("8080"); // throws

Call forms

assert.maybe.<check>(value) for every top-level check
assert.maybe.instance(value, Constructor, error?) for instances
assert.maybe.shape(value, descriptor, error?) for object shapes

Types#

Code#

An error code emitted by a built-in assertion.

type Code =
  | "invalid_bigint"
  | "invalid_boolean"
  | "invalid_function"
  | "invalid_number"
  | "invalid_string"
  | "invalid_symbol"
  | "invalid_undefined"
  | "invalid_defined"
  | "invalid_array"
  | "invalid_date"
  | "invalid_dict"
  | "invalid_error"
  | "invalid_false"
  | "invalid_finite"
  | "invalid_int"
  | "invalid_map"
  | "invalid_nan"
  | "invalid_newable"
  | "invalid_null"
  | "invalid_nullish"
  | "invalid_object"
  | "invalid_promise"
  | "invalid_regexp"
  | "invalid_safeint"
  | "invalid_set"
  | "invalid_true"
  | "invalid_uint"
  | "invalid_url"
  | "invalid_uuid"
  | "invalid_empty"
  | "invalid_nonempty"
  | "invalid_instance"
  | "invalid_shape_dict"
  | "invalid_shape_property";

ShapeDescriptor#

A map from property names to required or ?-suffixed optional types.

type ShapeDescriptor = Dict<
  `${"bigint" | "boolean" | "function" | "number" | "object" | "string" | "symbol"}${"?" | ""}`
>;