API reference › @evolu/common › Assert

Platform-agnostic assertions for invariants, examples, and tests.

An assertion documents a condition required for the program to be correct. Ideally, the type system should enforce it so incorrect code cannot compile, but that is not always possible (not even in Rust). A runtime assertion failure therefore indicates a bug that must be fixed. Throwing at the point of violation prevents invalid state from propagating and makes the defect easier to diagnose.

Evolu provides its own assertions so the same concise API works for production invariants, executable examples, and tests on every platform. The general assert requires a message explaining the invariant, and specialized assertions provide focused diagnostics and narrowing. The API deliberately favors strict and predictable contracts: one assertEqual covers primitives and structural Data comparisons, assertEqualBytes compares bytes across array representations, and assertSame is reserved for SameValue or reference identity. Generic partial structural assertions such as assertMatches are omitted so unmentioned state cannot hide regressions. If a complete expected value is too large to keep inline, use a fixture or a focused domain helper that keeps the contract explicit. assertOk and assertErr provide convenient Result narrowing, while assertType provides runtime Type assertions and compile-time type equality similar to Vitest's expectTypeOf without requiring a test runner. assertThrows and assertRejects verify thrown and rejected values without matcher semantics. Together, these assertions keep documentation examples concise and directly copyable.

In Node.js, failures use the native AssertionError for structured diagnostics and diffs. Other platforms use a compatible fallback. You should not need to import Node.js assertions unless Evolu does not provide an equivalent or a test requires exact Node.js semantics.

Do not use assertions to validate external input. Use a Type declaration's fromUnknown so invalid input is represented by a typed Result.

TODO(next major): Add a separate production build that replaces full assertion messages with numeric error codes and a decoder, following React's approach, to reduce the core bundle size since Evolu has many assertions.

Assertions

Name	Description
assert	Asserts that a condition is truthy.
assertFalse	Asserts that a value is exactly false and narrows it to false.
assertInstanceOf	Asserts that a value is an instance of a constructor and narrows it.
assertLength	Asserts that a value has the expected length and narrows its length.
assertNonEmptyArray	Asserts that an array is non-empty.
assertNonEmptyReadonlyArray	Asserts that a readonly array is non-empty.
assertNonNullable	Asserts that a value is non-nullable.
assertNotNull	Asserts that a value is not null while preserving undefined.
assertNotUndefined	Asserts that a value is not undefined while preserving null.
assertSame	Asserts that two values are the same using Object.is.
assertConditionAfterMicrotasks	Asserts that a condition becomes true after exactly the specified number of microtasks.
assertContinuationAfterMicrotasks	Asserts that a Promise continuation runs after exactly the specified number of microtasks.
assertEqual	Asserts that two values are equal.
assertEqualBytes	Asserts that a Uint8Array contains the expected bytes.
assertErr	Asserts that a Result is an Err and narrows it, optionally comparing its error.
assertNotDisposed	Guards synchronous methods on objects that may be called after disposal.
assertNotEqual	Asserts that two values are not equal.
assertNotSame	Asserts that two values are not the same using Object.is.
assertOk	Asserts that a Result is an Ok and narrows it, optionally comparing its value.
assertRejects	Asserts that a promise rejects with the expected value.
assertRejectsInstanceOf	Asserts that a promise rejects with an instance of a constructor.
assertRejectsSame	Asserts that a promise rejects with the same value using Object.is.
assertThrows	Asserts that a function throws the expected value.
assertThrowsInstanceOf	Asserts that a function throws an instance of a constructor.
assertThrowsSame	Asserts that a function throws the same value using Object.is.
assertTrue	Asserts that a value is exactly true.