@evolu/common 8.7.0 → 8.9.0

package/dist/src/Assert.d.ts

@@ -1,219 +1,364 @@
 /**
- * Runtime assertions for invariants and value checks.
+ * 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 {@link assert} requires a message explaining the invariant, and
+ * specialized assertions provide focused diagnostics and narrowing. The API
+ * deliberately favors strict and predictable contracts: one {@link assertEqual}
+ * covers primitives and structural Data comparisons, {@link assertEqualBytes}
+ * compares bytes across array representations, and {@link 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.
+ * {@link assertOk} and {@link assertErr} provide convenient Result narrowing,
+ * while {@link assertType} provides runtime Type assertions and compile-time
+ * type equality similar to Vitest's `expectTypeOf` without requiring a test
+ * runner. {@link assertThrows} and {@link 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 {@link Type}
+ * declaration's `fromUnknown` so invalid input is represented by a typed
+ * {@link 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.
  *
  * @module
  */
 import type { NonEmptyArray, NonEmptyReadonlyArray } from "./Array.ts";
 import { type Eq } from "./Eq.ts";
 import type { Err, InferErr, InferOk, Ok, Result } from "./Result.ts";
-import type { IsData } from "./Type.ts";
-import type { CompileTimeError } from "./Types.ts";
+import type { ValueWithLength } from "./Types.ts";
 /**
- * Ensures a condition is true, throwing an error with the provided message if
- * not.
+ * Asserts that a condition is truthy.
  *
- * Prevents invalid states from propagating through the system by halting
- * execution when a condition fails, improving reliability and debuggability.
+ * Throws an `AssertionError` with the provided message if the condition is
+ * falsy, preventing invalid state from propagating and making the failure
+ * easier to diagnose.
  *
- * Do not use this instead of {@link Type}. Assertions are intended when a
- * condition is logically guaranteed to be true but TypeScript cannot prove it,
- * or for catching and signaling developer mistakes eagerly.
+ * Use `assert` only when a more specific assertion, such as {@link assertTrue}
+ * or {@link assertEqual}, does not apply. For that reason, `assert` requires a
+ * custom message explaining the expected condition.
+ *
+ * Options provide structured diagnostics for custom assertions. Pass an
+ * underlying failure as `cause` when it explains why the asserted condition
+ * failed, and pass the custom assertion as `stackStartFn` to omit its
+ * implementation from the stack trace.
  *
  * ### Example
  *
  * ```ts
- * import { assert, assertEqual, assertErr, trySync } from "@evolu/common";
+ * import { assert, assertEqual, assertType } from "@evolu/common";
  *
- * assert(true, "Expected true.");
- * const result = trySync(() => assert(false, "Expected true."));
- * assertErr(result);
- * assert(result.error instanceof Error, "Expected an Error.");
- * assertEqual(result.error.message, "Expected true.");
+ * const value: unknown = "Evolu";
+ * assert(typeof value === "string", "Expected a string.");
+ *
+ * assertType<typeof value, string>();
+ * assertEqual(value, "Evolu");
  * ```
+ *
+ * @group Assertions
  */
-export declare const assert: (condition: unknown, message: string) => asserts condition;
+export declare const assert: (condition: unknown, message: string, options?: {
+    readonly actual?: unknown;
+    readonly expected?: unknown;
+    readonly operator?: string;
+    readonly diff?: "full" | undefined;
+    readonly cause?: unknown;
+    readonly stackStartFn?: (...args: Array<never>) => unknown;
+}) => asserts condition;
 /**
- * Asserts that two values are the same according to {@link eqStrict}.
+ * Asserts that a value is exactly `true`.
  *
- * `eqStrict` uses SameValue equality: it considers `NaN` the same as itself,
- * distinguishes `0` from `-0`, and compares objects by reference identity.
+ * Boolean conditions preserve their control-flow narrowing, including named
+ * type guards. Unknown values narrow to the literal `true`. Unlike
+ * {@link assert}, this checks an exact boolean value instead of truthiness and
+ * does not require a custom message.
  *
  * ### Example
  *
  * ```ts
- * import { assertSame, assertType } from "@evolu/common";
+ * import { assertTrue, assertType } from "@evolu/common";
  *
  * interface User {
  *   readonly name: string;
  * }
  *
- * const user: User = { name: "Ada" };
- * const value: unknown = user;
+ * const isUser = (value: unknown): value is User =>
+ *   typeof value === "object" &&
+ *   value !== null &&
+ *   "name" in value &&
+ *   typeof value.name === "string";
  *
- * assertSame(value, user);
- * assertType<User, typeof value>();
+ * const value: unknown = { name: "Ada" };
+ * assertTrue(isUser(value));
+ * assertType<typeof value, User>();
+ *
+ * const condition: unknown = true;
+ * assertTrue(condition);
+ * assertType<typeof condition, true>();
  * ```
+ *
+ * @group Assertions
  */
-export declare const assertSame: <Expected>(actual: unknown, expected: Expected) => asserts actual is Expected;
+export declare function assertTrue(condition: boolean): asserts condition;
+export declare function assertTrue(value: unknown): asserts value is true;
 /**
- * Asserts that a value is exactly `true` and narrows it to `true`.
+ * Asserts that a value is exactly `false` and narrows it to `false`.
  *
- * Unlike {@link assert}, this checks an exact boolean value instead of
- * truthiness and does not require a custom message.
+ * Unlike {@link assert}, this checks an exact boolean value instead of falsiness
+ * and does not require a custom message.
  *
  * ### Example
  *
  * ```ts
- * import { assertTrue, assertType } from "@evolu/common";
+ * import { assertFalse, assertType } from "@evolu/common";
  *
- * const value: unknown = true;
- * assertTrue(value);
- * assertType<true, typeof value>();
+ * const value: unknown = false;
+ * assertFalse(value);
+ * assertType<typeof value, false>();
  * ```
+ *
+ * @group Assertions
  */
-export declare const assertTrue: (value: unknown) => asserts value is true;
+export declare const assertFalse: (value: unknown) => asserts value is false;
 /**
- * Asserts that a value is exactly `false` and narrows it to `false`.
+ * Asserts that a condition becomes true after exactly the specified number of
+ * microtasks.
  *
- * Unlike {@link assert}, this checks an exact boolean value instead of falsiness
- * and does not require a custom message.
+ * Use this in tests that intentionally specify async scheduling behavior.
+ * Application code must not depend on exact microtask counts. Maintainers
+ * should review count changes because they indicate that an async pipeline
+ * changed.
  *
  * ### Example
  *
  * ```ts
- * import { assertFalse, assertType } from "@evolu/common";
+ * import { assertConditionAfterMicrotasks } from "@evolu/common";
  *
- * const value: unknown = false;
- * assertFalse(value);
- * assertType<false, typeof value>();
+ * let ready = false;
+ * queueMicrotask(() => {
+ *   ready = true;
+ * });
+ *
+ * await assertConditionAfterMicrotasks(() => ready, 1);
  * ```
+ *
+ * @group Assertions
  */
-export declare const assertFalse: (value: unknown) => asserts value is false;
+export declare function assertConditionAfterMicrotasks(condition: () => boolean, expectedMicrotaskCount: number): Promise<void>;
 /**
- * Asserts that two {@link Data} values are equal according to {@link eqData}.
+ * Asserts that a Promise continuation runs after exactly the specified number
+ * of microtasks.
  *
- * Use this for concise value checks in platform-independent examples. Use
- * {@link assert} with a descriptive message for application invariants.
+ * Both fulfillment and rejection count as running the continuation. Use this in
+ * tests that intentionally specify async scheduling behavior. Application code
+ * must not depend on exact microtask counts. Maintainers should review count
+ * changes because they indicate that an async pipeline changed.
  *
  * ### Example
  *
  * ```ts
- * import { assertEqual } from "@evolu/common";
+ * import { assertContinuationAfterMicrotasks } from "@evolu/common";
  *
- * const actual = new Map([["roles", new Set(["admin", "author"])]]);
- * const expected = new Map([["roles", new Set(["author", "admin"])]]);
+ * await assertContinuationAfterMicrotasks(Promise.resolve("ready"), 1);
+ * ```
  *
- * assertEqual(actual, expected);
+ * @group Assertions
+ */
+export declare const assertContinuationAfterMicrotasks: (promise: Promise<unknown>, expectedMicrotaskCount: number) => Promise<void>;
+/**
+ * Asserts that a function throws the expected value.
+ *
+ * Expected values use {@link assertEqual} semantics. To perform several or
+ * specialized assertions, pass an assertion function that receives the thrown
+ * value and returns nothing. Returning a predicate result fails. Use
+ * {@link assertThrowsSame} for SameValue or reference identity and
+ * {@link assertThrowsInstanceOf} for a runtime type.
+ *
+ * Because JavaScript permits throwing functions, a function second argument is
+ * always treated as an assertion function. Use `assertThrowsSame` to assert
+ * that a particular function was thrown.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertThrows } from "@evolu/common";
+ *
+ * assertThrows(
+ *   () => {
+ *     // oxlint-disable-next-line eslint/no-throw-literal, typescript/only-throw-error -- Exercise arbitrary thrown values.
+ *     throw { type: "ExpectedFailure", value: 42 };
+ *   },
+ *   { type: "ExpectedFailure", value: 42 },
+ * );
  * ```
+ *
+ * @group Assertions
  */
-export declare function assertEqual<Actual, Expected>(actual: Actual, expected: Expected, ...dataError: AssertEqualError<Actual | Expected>): void;
-type AssertEqualError<Value> = IsData<Value> extends true ? [] : [
-    error: CompileTimeError<"assertEqual", "Actual and expected values must consist only of Data.">
-];
+export declare function assertThrows(run: () => unknown, assertThrown: (thrown: unknown) => void): void;
+export declare function assertThrows(run: () => unknown, expected: unknown): void;
 /**
- * Asserts that a {@link Result} is an {@link Ok}, optionally compares its value,
- * and narrows the Result.
+ * Asserts that a function throws the same value using `Object.is`.
  *
- * With only a Result, this checks the variant without inspecting the value.
- * When an expected value is provided, it uses {@link eqData}; its Data type is
- * inferred independently, so an unbranded literal can compare a branded
- * primitive or collection. Pass a custom {@link Eq} when either value is outside
- * {@link Data} or needs domain-specific equality.
+ * Use this to verify that a thrown value was propagated unchanged. For value
+ * comparisons, use {@link assertThrows}.
  *
  * ### Example
  *
  * ```ts
- * import {
- *   assertEqual,
- *   assertOk,
- *   assertType,
- *   ok,
- *   type Ok,
- *   type Result,
- *   type Typed,
- * } from "@evolu/common";
+ * import { assertThrowsSame } from "@evolu/common";
  *
- * interface User {
- *   readonly id: string;
- * }
+ * const expected = new Error("Unavailable.");
+ * assertThrowsSame(() => {
+ *   throw expected;
+ * }, expected);
+ * ```
  *
- * interface UserNotFoundError extends Typed<"UserNotFound"> {}
+ * @group Assertions
+ */
+export declare const assertThrowsSame: (run: () => unknown, expected: unknown) => void;
+/**
+ * Asserts that a function throws an instance of a constructor.
  *
- * const result: Result<User, UserNotFoundError> = ok({ id: "user-1" });
+ * Returns the narrowed instance so additional properties can be asserted
+ * without running the function again.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertEqual, assertThrowsInstanceOf } from "@evolu/common";
+ *
+ * const error = assertThrowsInstanceOf(() => {
+ *   throw new TypeError("Expected a string.");
+ * }, TypeError);
+ * assertEqual(error.message, "Expected a string.");
+ * ```
+ *
+ * @group Assertions
+ */
+export declare const assertThrowsInstanceOf: <T extends {
+    readonly name: string;
+} & (abstract new (...args: Array<never>) => unknown)>(run: () => unknown, constructor: T) => InstanceType<T>;
+/**
+ * Asserts that a promise rejects with the expected value.
+ *
+ * Expected values use {@link assertEqual} semantics. To perform several or
+ * specialized assertions, pass an assertion function that receives the
+ * rejection reason and returns nothing. Returning a predicate result fails. Use
+ * {@link assertRejectsSame} for SameValue or reference identity and
+ * {@link assertRejectsInstanceOf} for a runtime type.
  *
- * assertOk(result);
- * assertType<Ok<User>, typeof result>();
- * assertEqual(result.value.id, "user-1");
+ * Because JavaScript permits rejecting with functions, a function second
+ * argument is always treated as an assertion function. Use `assertRejectsSame`
+ * to assert that a particular function was rejected.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertRejects } from "@evolu/common";
+ *
+ * const expected = new Error("Unavailable.");
+ * await assertRejects(Promise.reject(expected), expected);
  * ```
+ *
+ * @group Assertions
  */
-export declare function assertOk<R extends Result<unknown, unknown>>(result: R): asserts result is Extract<R, Ok<unknown>>;
-export declare function assertOk<R extends Result<unknown, unknown>>(result: R, expectedValue: InferOk<R>, eq: Eq<InferOk<R>>): asserts result is Extract<R, Ok<unknown>>;
-export declare function assertOk<R extends Result<unknown, unknown>, ExpectedValue>(result: R, ...comparison: [expectedValue: ExpectedValue] & (IsData<InferOk<R> | ExpectedValue> extends true ? unknown : {
-    readonly [Error in CompileTimeError<"assertOk", "Result value and expected value must consist only of Data when no custom Eq is provided.">]: never;
-})): asserts result is Extract<R, Ok<unknown>>;
+export declare function assertRejects(promise: PromiseLike<unknown>, assertRejected: (reason: unknown) => void): Promise<void>;
+export declare function assertRejects(promise: PromiseLike<unknown>, expected: unknown): Promise<void>;
 /**
- * Asserts that a {@link Result} is an {@link Err}, optionally compares its error,
- * and narrows the Result.
+ * Asserts that a promise rejects with the same value using `Object.is`.
  *
- * With only a Result, this checks the variant without inspecting the error.
- * When an expected error is provided, it uses {@link eqData}; its Data type is
- * inferred independently, so an unbranded literal can compare a branded
- * primitive or collection. Pass a custom {@link Eq} when either value is outside
- * {@link Data} or needs domain-specific equality.
+ * Use this to verify that a rejection reason was propagated unchanged. For
+ * value comparisons, use {@link assertRejects}.
  *
  * ### Example
  *
  * ```ts
- * import {
- *   assertEqual,
- *   assertErr,
- *   assertType,
- *   err,
- *   type Err,
- *   type Result,
- *   type Typed,
- * } from "@evolu/common";
+ * import { assertRejectsSame } from "@evolu/common";
  *
- * interface UserNotFoundError extends Typed<"UserNotFound"> {
- *   readonly id: string;
- * }
+ * const expected = new Error("Unavailable.");
+ * await assertRejectsSame(Promise.reject(expected), expected);
+ * ```
  *
- * const result: Result<string, UserNotFoundError> = err({
- *   type: "UserNotFound",
- *   id: "user-1",
- * });
+ * @group Assertions
+ */
+export declare const assertRejectsSame: (promise: PromiseLike<unknown>, expected: unknown) => Promise<void>;
+/**
+ * Asserts that a promise rejects with an instance of a constructor.
  *
- * assertErr(result);
- * assertType<Err<UserNotFoundError>, typeof result>();
- * assertEqual(result.error.id, "user-1");
+ * Returns the narrowed instance so additional properties can be asserted.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertEqual, assertRejectsInstanceOf } from "@evolu/common";
+ *
+ * const error = await assertRejectsInstanceOf(
+ *   Promise.reject(new TypeError("Unavailable.")),
+ *   TypeError,
+ * );
+ * assertEqual(error.message, "Unavailable.");
  * ```
+ *
+ * @group Assertions
  */
-export declare function assertErr<R extends Result<unknown, unknown>>(result: R): asserts result is Extract<R, Err<unknown>>;
-export declare function assertErr<R extends Result<unknown, unknown>>(result: R, expectedError: InferErr<R>, eq: Eq<InferErr<R>>): asserts result is Extract<R, Err<unknown>>;
-export declare function assertErr<R extends Result<unknown, unknown>, ExpectedError>(result: R, ...comparison: [expectedError: ExpectedError] & (IsData<InferErr<R> | ExpectedError> extends true ? unknown : {
-    readonly [Error in CompileTimeError<"assertErr", "Result error and expected error must consist only of Data when no custom Eq is provided.">]: never;
-})): asserts result is Extract<R, Err<unknown>>;
+export declare const assertRejectsInstanceOf: <T extends {
+    readonly name: string;
+} & (abstract new (...args: Array<never>) => unknown)>(promise: PromiseLike<unknown>, constructor: T) => Promise<InstanceType<T>>;
+/**
+ * Asserts that a value is an instance of a constructor and narrows it.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertInstanceOf, assertType } from "@evolu/common";
+ *
+ * const value: unknown = new TypeError("Invalid value.");
+ * assertInstanceOf(value, TypeError);
+ * assertType<typeof value, TypeError>();
+ * ```
+ *
+ * @group Assertions
+ */
+export declare const assertInstanceOf: <Constructor extends {
+    readonly name: string;
+} & (abstract new (...args: Array<never>) => unknown)>(value: unknown, constructor: Constructor) => asserts value is InstanceType<Constructor>;
 /**
  * Asserts that a value is non-nullable.
  *
  * Following TypeScript's {@link NonNullable}, non-nullable here means neither
- * null nor undefined. Use this when a value is logically guaranteed to be
- * non-nullable but TypeScript cannot prove it.
+ * null nor undefined.
+ *
+ * @group Assertions
  */
 export declare const assertNonNullable: <T>(value: T, message?: string) => asserts value is NonNullable<T>;
 /**
  * Asserts that a value is not null while preserving undefined.
  *
- * Use this when a value is logically guaranteed not to be null but TypeScript
- * cannot prove it.
- *
  * ### Example
  *
  * ```ts
  * import {
- *   assert,
  *   assertEqual,
  *   assertErr,
+ *   assertInstanceOf,
  *   assertNotNull,
  *   assertType,
  *   trySync,
@@ -221,28 +366,29 @@ export declare const assertNonNullable: <T>(value: T, message?: string) => asser
  *
  * const value = undefined as string | null | undefined;
  * assertNotNull(value);
- * assertType<string | undefined, typeof value>();
+ *
+ * assertType<typeof value, string | undefined>();
  * assertEqual(value, undefined);
+ *
  * const result = trySync(() => assertNotNull(null));
  * assertErr(result);
- * assert(result.error instanceof Error, "Expected an Error.");
+ * assertInstanceOf(result.error, Error);
  * assertEqual(result.error.message, "Expected value not to be null.");
  * ```
+ *
+ * @group Assertions
  */
 export declare const assertNotNull: <T>(value: T, message?: string) => asserts value is T & ({} | undefined);
 /**
  * Asserts that a value is not undefined while preserving null.
  *
- * Use this when a value is logically guaranteed not to be undefined but
- * TypeScript cannot prove it.
- *
  * ### Example
  *
  * ```ts
  * import {
- *   assert,
  *   assertEqual,
  *   assertErr,
+ *   assertInstanceOf,
  *   assertNotUndefined,
  *   assertType,
  *   trySync,
@@ -250,20 +396,37 @@ export declare const assertNotNull: <T>(value: T, message?: string) => asserts v
  *
  * const value = null as string | null | undefined;
  * assertNotUndefined(value);
- * assertType<string | null, typeof value>();
+ * assertType<typeof value, string | null>();
  * assertEqual(value, null);
  * const result = trySync(() => assertNotUndefined(undefined));
  * assertErr(result);
- * assert(result.error instanceof Error, "Expected an Error.");
+ * assertInstanceOf(result.error, Error);
  * assertEqual(result.error.message, "Expected value not to be undefined.");
  * ```
+ *
+ * @group Assertions
  */
 export declare const assertNotUndefined: <T>(value: T, message?: string) => asserts value is T & ({} | null);
 /**
- * Asserts that an array is non-empty.
+ * Asserts that a value has the expected length and narrows its length.
  *
- * Use this when an array is logically guaranteed to be non-empty but TypeScript
- * cannot prove it.
+ * ### Example
+ *
+ * ```ts
+ * import { assertLength, assertType } from "@evolu/common";
+ *
+ * const values: ReadonlyArray<string> = ["Ada", "Grace"];
+ * assertLength(values, 2);
+ * assertType<typeof values.length, 2>();
+ * ```
+ *
+ * @group Assertions
+ */
+export declare const assertLength: <Value extends ValueWithLength, const Length extends number>(value: Value, expectedLength: Length) => asserts value is Value & {
+    readonly length: Length;
+};
+/**
+ * Asserts that an array is non-empty.
  *
  * ### Example
  *
@@ -279,19 +442,18 @@ export declare const assertNotUndefined: <T>(value: T, message?: string) => asse
  *
  * const values = [1, 2, 3];
  * assertNonEmptyArray(values);
- * assertType<NonEmptyArray<number>, typeof values>();
+ * assertType<typeof values, NonEmptyArray<number>>();
  * assertEqual(values[0], 1);
  * const result = trySync(() => assertNonEmptyArray([]));
  * assertErr(result);
  * ```
+ *
+ * @group Assertions
  */
 export declare const assertNonEmptyArray: <T>(arr: Array<T>, message?: string) => asserts arr is NonEmptyArray<T>;
 /**
  * Asserts that a readonly array is non-empty.
  *
- * Use this when a readonly array is logically guaranteed to be non-empty but
- * TypeScript cannot prove it.
- *
  * ### Example
  *
  * ```ts
@@ -306,11 +468,13 @@ export declare const assertNonEmptyArray: <T>(arr: Array<T>, message?: string) =
  *
  * const values: ReadonlyArray<number> = [1, 2, 3];
  * assertNonEmptyReadonlyArray(values);
- * assertType<NonEmptyReadonlyArray<number>, typeof values>();
+ * assertType<typeof values, NonEmptyReadonlyArray<number>>();
  * assertEqual(values[0], 1);
  * const result = trySync(() => assertNonEmptyReadonlyArray([]));
  * assertErr(result);
  * ```
+ *
+ * @group Assertions
  */
 export declare const assertNonEmptyReadonlyArray: <T>(arr: ReadonlyArray<T>, message?: string) => asserts arr is NonEmptyReadonlyArray<T>;
 /**
@@ -322,29 +486,222 @@ export declare const assertNonEmptyReadonlyArray: <T>(arr: ReadonlyArray<T>, mes
  *
  * ```ts
  * import {
- *   assert,
  *   assertEqual,
  *   assertErr,
+ *   assertInstanceOf,
  *   assertNotDisposed,
  *   trySync,
  * } from "@evolu/common";
  *
- * await using disposer = new globalThis.AsyncDisposableStack();
+ * await using disposer = new AsyncDisposableStack();
  * assertNotDisposed(disposer);
  * await disposer.disposeAsync();
  * const result = trySync(() => assertNotDisposed(disposer));
  * assertErr(result);
- * assert(result.error instanceof Error, "Expected an Error.");
+ * assertInstanceOf(result.error, Error);
  * assertEqual(result.error.message, "Cannot use a disposed object.");
  * ```
  *
  * This is the JavaScript equivalent of the .NET `ObjectDisposedException`
  * pattern: once a helper has been disposed, calling its synchronous methods is
- * a programmer error and should throw immediately instead of continuing with
- * invalid state.
+ * a bug and should throw immediately instead of continuing with invalid state.
+ *
+ * @group Assertions
  */
 export declare const assertNotDisposed: (value: DisposableStack | AsyncDisposableStack | {
     readonly disposed: boolean;
 }) => void;
-export {};
+/**
+ * Asserts that two values are the same using `Object.is`.
+ *
+ * Use this when exact sameness is the contract, such as asserting reference
+ * identity or narrowing the actual value to the expected value's type, as shown
+ * below. For value comparisons, use {@link assertEqual}.
+ *
+ * Uses the same equality semantics as `assert.strictEqual` from
+ * `node:assert/strict`, but is platform-agnostic. See {@link eqSameValue} for
+ * the equality semantics.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertSame, assertType } from "@evolu/common";
+ *
+ * interface User {
+ *   readonly name: string;
+ * }
+ *
+ * const user: User = { name: "Ada" };
+ * const value: unknown = user;
+ *
+ * assertSame(value, user);
+ * // `assertSame` narrows `value` from `unknown` to `User`.
+ * assertType<typeof value, User>();
+ * ```
+ *
+ * @group Assertions
+ */
+export declare const assertSame: <Expected>(actual: unknown, expected: Expected) => asserts actual is Expected;
+/**
+ * Asserts that two values are not the same using `Object.is`.
+ *
+ * The opposite of {@link assertSame}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertNotSame } from "@evolu/common";
+ *
+ * const first = { name: "Ada" };
+ * const second = { name: "Ada" };
+ *
+ * assertNotSame(first, second);
+ * assertNotSame(0, -0);
+ * ```
+ *
+ * @group Assertions
+ */
+export declare const assertNotSame: (actual: unknown, expected: unknown) => void;
+/**
+ * Asserts that two values are equal.
+ *
+ * Use this for value comparisons of both primitive and deeply structured
+ * values. Use {@link assertSame} when exact sameness or narrowing is required.
+ *
+ * Like `assert.deepEqual` from `node:assert/strict`, it performs deep
+ * structural comparison, but uses deliberately smaller, platform-agnostic
+ * equality logic based on {@link eqData}. More complex comparison logic is
+ * difficult to reason about and rarely needed. Other values are opaque and
+ * compare equal only by identity. If broader comparison semantics are needed in
+ * Node.js, use the native assertion instead.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertEqual } from "@evolu/common";
+ *
+ * assertEqual(21 * 2, 42);
+ *
+ * const actual: unknown = new Map([
+ *   ["roles", new Set(["admin", "author"])],
+ * ]);
+ * const expected = new Map([["roles", new Set(["author", "admin"])]]);
+ *
+ * assertEqual(actual, expected);
+ * ```
+ *
+ * @group Assertions
+ */
+export declare function assertEqual(actual: unknown, expected: unknown): void;
+/**
+ * Asserts that a `Uint8Array` contains the expected bytes.
+ *
+ * Uses {@link eqArrayNumber}, so the runtime representations may differ. For
+ * example, a `Uint8Array` can be compared directly with a regular array.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertEqualBytes } from "@evolu/common";
+ *
+ * const bytes = new Uint8Array([1, 5, 39, 254]);
+ *
+ * assertEqualBytes(bytes, [1, 5, 39, 254]);
+ * ```
+ *
+ * @group Assertions
+ */
+export declare const assertEqualBytes: (actual: Uint8Array, expected: ArrayLike<number>) => void;
+/**
+ * Asserts that two values are not equal.
+ *
+ * The opposite of {@link assertEqual}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertNotEqual } from "@evolu/common";
+ *
+ * assertNotEqual({ name: "Ada" }, { name: "Grace" });
+ * assertNotEqual([1, 2], [2, 1]);
+ * ```
+ *
+ * @group Assertions
+ */
+export declare function assertNotEqual(actual: unknown, expected: unknown): void;
+/**
+ * Asserts that a {@link Result} is an {@link Ok} and narrows it, optionally
+ * comparing its value.
+ *
+ * When an expected value is provided, it is compared using {@link assertEqual}
+ * semantics by default. Pass a custom {@link Eq} for different equality
+ * semantics.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertOk,
+ *   assertType,
+ *   ok,
+ *   type Ok,
+ *   type Result,
+ *   type Typed,
+ * } from "@evolu/common";
+ *
+ * interface User {
+ *   readonly id: string;
+ * }
+ *
+ * interface UserNotFoundError extends Typed<"UserNotFound"> {}
+ *
+ * const result: Result<User, UserNotFoundError> = ok({ id: "user-1" });
+ *
+ * assertOk(result, { id: "user-1" });
+ * assertType<typeof result, Ok<User>>();
+ * ```
+ *
+ * @group Assertions
+ */
+export declare function assertOk<R extends Result<unknown, unknown>>(result: R): asserts result is Extract<R, Ok<unknown>>;
+export declare function assertOk<R extends Result<unknown, unknown>>(result: R, expectedValue: InferOk<R>, eq: Eq<InferOk<R>>): asserts result is Extract<R, Ok<unknown>>;
+export declare function assertOk<R extends Result<unknown, unknown>>(result: R, expectedValue: unknown): asserts result is Extract<R, Ok<unknown>>;
+/**
+ * Asserts that a {@link Result} is an {@link Err} and narrows it, optionally
+ * comparing its error.
+ *
+ * When an expected error is provided, it is compared using {@link assertEqual}
+ * semantics by default. Pass a custom {@link Eq} for different equality
+ * semantics.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertErr,
+ *   assertType,
+ *   err,
+ *   type Err,
+ *   type Result,
+ *   type Typed,
+ * } from "@evolu/common";
+ *
+ * interface UserNotFoundError extends Typed<"UserNotFound"> {
+ *   readonly id: string;
+ * }
+ *
+ * const result: Result<string, UserNotFoundError> = err({
+ *   type: "UserNotFound",
+ *   id: "user-1",
+ * });
+ *
+ * assertErr(result, { type: "UserNotFound", id: "user-1" });
+ * assertType<typeof result, Err<UserNotFoundError>>();
+ * ```
+ *
+ * @group Assertions
+ */
+export declare function assertErr<R extends Result<unknown, unknown>>(result: R): asserts result is Extract<R, Err<unknown>>;
+export declare function assertErr<R extends Result<unknown, unknown>>(result: R, expectedError: InferErr<R>, eq: Eq<InferErr<R>>): asserts result is Extract<R, Err<unknown>>;
+export declare function assertErr<R extends Result<unknown, unknown>>(result: R, expectedError: unknown): asserts result is Extract<R, Err<unknown>>;
 //# sourceMappingURL=Assert.d.ts.map