@rcompat/assert · rcompat

Runtime type assertions and invariants.

What is @rcompat/assert?#

A cross-runtime module for runtime type checking and validation that works consistently across Node, Deno, and Bun. Provides type assertions with helpful error messages.

Installation#

bash

npm install @rcompat/assert

bash

pnpm add @rcompat/assert

bash

yarn add @rcompat/assert

bash

bun add @rcompat/assert

Usage#

Basic assertions#

Validates a value against a type and throws with a helpful message if validation fails.

import assert from "@rcompat/assert";

// primitives
assert.bigint(x);
assert.boolean(x);
assert.function(x);
assert.number(x);
assert.string(x);
assert.symbol(x);
assert.undefined(x);

// conditions
assert.array(x);
assert.date(x);
assert.dict(x);    // plain object (not array, Date, class instance, etc.)
assert.error(x);
assert.false(x);
assert.finite(x);
assert.int(x);
assert.map(x);
assert.nan(x);
assert.newable(x);
assert.null(x);
assert.nullish(x);
assert.object(x);  // any non-null object
assert.promise(x);
assert.regexp(x);
assert.safeint(x);
assert.set(x);
assert.true(x);
assert.uint(x);    // unsigned (non-negative) integer
assert.url(x);

// other
assert.defined(x);
assert.instance(x, MyClass);
assert.uuid(x);    // valid UUIDv4 string (lowercase, crypto.randomUUID format)

Custom error messages#

import assert from "@rcompat/assert";

assert.string(input, new TypeError("Expected a string for username"));
assert.number(input, new TypeError("Invalid count"));

Error codes#

Error-code values are available on the default aggregate. The corresponding Code type can be imported separately because type imports are removed at runtime.

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

const code: Code = assert.Code.invalid_string;

Instance checks#

import assert from "@rcompat/assert";

class Animal {}
class Dog extends Animal {}

const dog = new Dog();

assert.instance(dog, Animal);  // passes
assert.instance(dog, Dog);     // passes
assert.instance(dog, Map);     // throws

maybe#

Optional/nullable assertions. Returns without throwing for null or undefined, but validates non-nullish values.

import assert from "@rcompat/assert";

// returns without error for nullish
assert.maybe.string(undefined);  // ok
assert.maybe.number(null);       // ok

// validates non-nullish values
assert.maybe.string("hello");    // ok
assert.maybe.string(42);         // throws - 42 is not a string

every#

Ensures ALL values in an array satisfy a type condition.

import assert from "@rcompat/assert";

assert.every.string(["a", "b", "c"]);  // ok - all strings
assert.every.number([1, 2, 3]);        // ok - all numbers
assert.every.number([1, "2", 3]);      // throws - "2" is not a number

assert.every.instance([dog1, dog2], Animal);  // ok - all Animal instances

API Reference#

Primitives#

Method	Description
`assert.bigint(x)`	Assert value is a bigint
`assert.boolean(x)`	Assert value is a boolean
`assert.function(x)`	Assert value is a function
`assert.number(x)`	Assert value is a number
`assert.string(x)`	Assert value is a string
`assert.symbol(x)`	Assert value is a symbol
`assert.undefined(x)`	Assert value is undefined

Conditions#

Method	Description
`assert.array(x)`	Assert value is an array
`assert.date(x)`	Assert value is a `Date`
`assert.dict(x)`	Assert value is a plain object
`assert.error(x)`	Assert value is an `Error`
`assert.false(x)`	Assert value is exactly `false`
`assert.finite(x)`	Assert value is a finite number
`assert.int(x)`	Assert value is an integer
`assert.map(x)`	Assert value is a `Map`
`assert.nan(x)`	Assert value is `NaN`
`assert.newable(x)`	Assert value is constructable
`assert.null(x)`	Assert value is exactly `null`
`assert.nullish(x)`	Assert value is `null` or `undefined`
`assert.object(x)`	Assert value is a non-null object
`assert.promise(x)`	Assert value is a `Promise`
`assert.regexp(x)`	Assert value is a `RegExp`
`assert.safeint(x)`	Assert value is a safe integer
`assert.set(x)`	Assert value is a `Set`
`assert.true(x)`	Assert value is exactly `true`
`assert.uint(x)`	Assert value is an unsigned integer
`assert.url(x)`	Assert value is a `URL`

Other#

Method	Description
`assert.defined(x)`	Assert value is not undefined
`assert.instance(x, Ctor)`	Assert value is instance of Ctor
`assert.uuid(x)`	Assert value is a valid UUIDv4

maybe#

All assertions are available under assert.maybe.* for optional values:

assert.maybe.string(x);
assert.maybe.number(x);
assert.maybe.instance(x, MyClass);
// ... etc

every#

All assertions are available under assert.every.* for array validation:

assert.every.string(xs);
assert.every.number(xs);
assert.every.instance(xs, MyClass);
// ... etc

Examples#

Validating function inputs#

import assert from "@rcompat/assert";

function createUser(data) {
  assert.dict(data);
  assert.string(data.name);
  assert.uint(data.age);
  assert.maybe.string(data.nickname);

  return { ...data };
}

Parsing configuration#

import assert from "@rcompat/assert";

function parseConfig(config) {
  assert.dict(config);
  assert.uint(config.port);
  assert.string(config.host);
  assert.maybe.boolean(config.debug);

  return {
    port: config.port,
    host: config.host,
    debug: config.debug ?? false,
  };
}

Validating arrays#

import assert from "@rcompat/assert";

function processIds(ids) {
  assert.array(ids);
  assert.every.uuid(ids);

  return ids.map(id => lookup(id));
}

Cross-Runtime Compatibility#

Runtime	Supported
Node.js	✓
Deno	✓
Bun	✓

No configuration required — just import and use.

License#

MIT

Contributing#

See CONTRIBUTING.md in the repository root.