Module index

Core types, guards, and utilities.

Bridges the gap between TypeScript's static type system and untrusted runtime data. Every guard returns a boolean and narrows its argument on success, so validation and type inference collapse into a single call at API boundaries, deserialisation sites, and other trust-crossing points. Companion utilities work along the same lines, deferring values to first use, lifting total mappers over missing arguments, and reporting failures where a statement isn't allowed.

Built-in Guards

Guards for language-level values and host objects. isDefined pairs with the Defined type operator, stripping undefined from the type of the checked value while retaining null.

isDefined("value"); // true
isDefined(null); // true (only undefined is rejected)
values.filter(isDefined); // (string | undefined)[] narrowed to string[]
isPrimitive("value"); // true (any non-object value)
isIdentifier("myVar"); // true (valid ECMAScript identifier)
isSymbol(Symbol("key")); // true
isFunction(() => {}); // true
isError(new Error()); // true
isRegExp(/pattern/); // true
isDate(new Date()); // true
isPromise(Promise.resolve()); // true
isIterable([1, 2, 3]); // true
isAsyncIterable(asyncGenerator()); // true

JSON Guards

Complete coverage of the JSON data model: the recursive Value type, its Scalar leaves, and structural guards for arrays and objects. isArray and isObject validate shape in depth through element predicates or tuple/template descriptors; object templates are closed by default, with the key wildcard turning them open.

isNull(null); // true
isBoolean(true); // true
isNumber(42); // true
isString("hello"); // true
isScalar(42); // true (boolean, number, or string)
isValue({ a: [1, 2], b: "test" }); // true (recursive JSON value)

isArray([1, 2, 3]); // true
isArray([1, 2, 3], isNumber); // with element predicate
isArray(["hello", 42], [isString, isNumber]); // with tuple template
isArray([], []); // empty array check

isObject({ a: 1 }); // true
isObject({ a: 1 }, isNumber); // with entry predicate
isObject({ a: 1 }, { a: isNumber }); // with closed template
isObject({ a: 1 }, { a: isNumber, [key]: isAny }); // with open template
isObject({ a: 1 }, { a: isNumber, b: v => isOptional(v, isString) }); // with optional field
isObject({ kind: "circle" }, { kind: v => isLiteral(v, ["circle", "square"]) }); // with literal field
isObject({ value: 42 }, { value: v => isUnion(v, [isString, isNumber]) }); // with union field
isObject({}, {}); // empty object check

Composable Guards

Higher-order guards that combine simpler ones into arbitrary type expressions: isLiteral for literal and enum-like sets, isOptional for T | undefined, isUnion for A | B, and isIntersection for A & B. isAny acts as a wildcard that always succeeds, typically used as a placeholder inside templates.

isAny("test"); // true (wildcard, always succeeds)
isLiteral("foo", "foo"); // true
isLiteral("foo", ["foo", "bar", "baz"]); // true (matches any)
isOptional(undefined, isString); // true
isOptional("hello", isString); // true
isUnion("test", [isString, isNumber]); // true (matches isString)
isUnion(42, [isString, isNumber]); // true (matches isNumber)
isIntersection({ a: 1 }, [isObject, v => isObject(v, { a: isNumber })]); // true (satisfies all)

Deferred Values

isLazy admits values supplied either eagerly or as no-arg factories; isEager is its dual, rejecting factories and accepting only plain values. Paired with the Lazy / Eager type operators. lazy defers a reference behind a memoising accessor that computes it at most once on first use; eager is its converse, resolving a reference to its value on every call.

isLazy(() => 42, isNumber); // true (no-arg function)
isLazy(42, isNumber); // true (plain value)
isEager(42, isNumber); // true (plain value)
isEager(() => 42, isNumber); // false (no-arg function rejected)

lazy(() => 42)(); // 42 (computed once, then memoised)
eager(() => 42); // 42 (resolved on every call)

Functional Idioms

given binds a value to a mapper of its own, so a computation reads as a scoped expression rather than as a temporary variable followed by a statement; a missing value short-circuits to undefined without calling the mapper, and the result type follows suit, staying defined for a value that can't be undefined in the first place.

given(8080)(port => `localhost:${port}`); // "localhost:8080"
given(ports.get(name))(port => `localhost:${port}`); // string or undefined (the mapper is not called)

Error Reporting

assert validates a value against an arbitrary predicate, returning it unchanged on success and throwing a TypeError otherwise, with a message derived from the predicate name or computed from the offending value; validation doesn't narrow, so values are returned at their declared type, whatever type the predicate tests for.

error throws where a statement isn't allowed, turning a failure into an expression: Error causes are thrown as they are, anything else wrapped in a generic Error reporting its string representation.

assert(input, isString); // returns input, or throws TypeError("expected string")
assert(data, isNumber, "count must be numeric"); // with a fixed message
assert(value, v => v > 0, v => `expected positive port <${v}>`); // with a computed message

const port = ports.get(name) ?? error("missing required port");
const result = await task().catch(reason => error(reason)); // rethrow a reason of unknown type

Variables

key: Wildcard symbol for open template validation in isObject.

Type Aliases

Nullable: Nullable value.
Defined: Defined value.
Primitive: ECMAScript primitive value.
Identifier: ECMAScript Identifier.
Value: Immutable JSON value.
Scalar: Immutable JSON scalar.
Array: Immutable JSON array.
Object: Immutable JSON object.
Guard: A type guard function.
Union: Extracts the union of guarded types from an array of type guards.
Intersection: Extracts the intersection of guarded types from an array of type guards.
Lazy: A value or a function returning a value.
Eager: The eager counterpart of a Lazy reference.

Functions

isDefined: Checks if a value is Defined.
isPrimitive: Checks if a value is a Primitive.
isIdentifier: Checks if a value is a valid Identifier.
isSymbol: Checks if a value is a symbol.
isFunction: Checks if a value is a function.
isError: Checks if a value is an Error instance.
isRegExp: Checks if a value is a RegExp instance.
isDate: Checks if a value is a Date instance.
isPromise: Checks if a value is a promise.
isIterable: Checks if a value is iterable.
isAsyncIterable: Checks if a value is async iterable.
isValue: Checks if a value is a valid JSON value.
isNull: Checks if a value is null.
isScalar: Checks if a value is a JSON scalar.
isBoolean: Checks if a value is a boolean.
isNumber: Checks if a value is a finite number.
isString: Checks if a value is a string.
isArray: Checks if a value is an array.
isObject: Checks if a value is a plain object.
isAny: Wildcard type guard that always succeeds.
isLiteral: Checks if a value matches one of the specified literal values.
isOptional: Checks if a value is either undefined or satisfies a type guard.
isUnion: Checks if a value satisfies any of the provided type guards.
isIntersection: Checks if a value satisfies all the provided type guards.
isLazy: Checks if a value is a Lazy reference.
isEager: Checks if a value is an Eager reference.
lazy: Defers a value to first use.
eager: Resolves a Lazy reference to its value.
given: Applies a mapper to a value, short-circuiting an undefined one.
assert: Validates a value against a predicate and returns it.
error: Throws an error in expression contexts.