@evolu/common 8.5.0 → 8.6.0

package/dist/src/Task.js

@@ -51,8 +51,6 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
 /**
- * ## Intro
- *
  * JavaScript-native structured concurrency.
  *
  * Structured concurrency organizes running tasks into a tree. Every child
@@ -86,6 +84,8 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  *
  * ```ts
  * import {
+ *   assertOk,
+ *   assertType,
  *   createRun,
  *   err,
  *   ok,
@@ -128,8 +128,8 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  * });
  *
  * const result = await run(getUser(user.id));
- * expectTypeOf(result).toEqualTypeOf<Result<User, UserNotFoundError>>();
- * expectOk(result, user);
+ * assertType<Result<User, UserNotFoundError>, typeof result>();
+ * assertOk(result, user);
  * ```
  *
  * In composition roots, prefer the lifecycle API from the matching Evolu
@@ -172,6 +172,8 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  *
  * ```ts
  * import {
+ *   assertOk,
+ *   assertType,
  *   createRun,
  *   err,
  *   ok,
@@ -230,13 +232,14 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  *
  * await using run = createRun();
  * const result = await run(getUserWithProfile("user-1"));
- * expectTypeOf(result).toEqualTypeOf<
+ * assertType<
  *   Result<
  *     { readonly user: User; readonly profile: Profile },
  *     UserNotFoundError | ProfileNotFoundError
- *   >
+ *   >,
+ *   typeof result
  * >();
- * expectOk(result, {
+ * assertOk(result, {
  *   user: { id: "user-1", profileId: "profile-1" },
  *   profile: { id: "profile-1" },
  * });
@@ -255,6 +258,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  *
  * ```ts
  * import {
+ *   assertType,
  *   exponential,
  *   fetch,
  *   jitter,
@@ -275,8 +279,9 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  *     jitter("100%")(maxDelay("20s")(take(2)(exponential("100ms")))),
  *   );
  *
- * expectTypeOf(fetchWithRetry).returns.toEqualTypeOf<
- *   Task<string, RetryTaskError<FetchError | TimeoutError>>
+ * assertType<
+ *   Task<string, RetryTaskError<FetchError | TimeoutError>>,
+ *   ReturnType<typeof fetchWithRetry>
  * >();
  * ```
  *
@@ -285,7 +290,15 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  * Run composed Tasks with a `concurrency` option and {@link all}:
  *
  * ```ts
- * import { all, createRun, ok, sleep, type Task } from "@evolu/common";
+ * import {
+ *   assertEqual,
+ *   assertOk,
+ *   all,
+ *   createRun,
+ *   ok,
+ *   sleep,
+ *   type Task,
+ * } from "@evolu/common";
  *
  * await using run = createRun();
  *
@@ -308,8 +321,8 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  *
  * // At most 2 concurrent requests.
  * const result = await run(all(urls, fetchUrl, { concurrency: 2 }));
- * expectOk(result, urls);
- * expect(maxActiveRequests).toBe(2);
+ * assertOk(result, urls);
+ * assertEqual(maxActiveRequests, 2);
  * ```
  *
  * Task helpers compose Tasks; concurrency primitives are stateful objects that
@@ -341,7 +354,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  * resources, or services shared by all code running inside a Run.
  *
  * ```ts
- * import { createRun, ok, type Task } from "@evolu/common";
+ * import { assertOk, createRun, ok, type Task } from "@evolu/common";
  *
  * interface GreetingFormatter {
  *   readonly format: (name: string) => string;
@@ -366,10 +379,10 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  * await using run = createRun({ greetingFormatter: formal });
  *
  * // Root dependencies are inherited.
- * expectOk(await run(greet("Ada")), "Hello, Ada");
+ * assertOk(await run(greet("Ada")), "Hello, Ada");
  *
  * // Child-specific dependencies replace the root's custom dependencies.
- * expectOk(
+ * assertOk(
  *   await run(greet("Ada"), { greetingFormatter: casual }),
  *   "Hi, Ada",
  * );
@@ -420,7 +433,15 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  * `undefined` should represent valid absence, not failure.
  *
  * ```ts
- * import { createRun, ok, type Task, type Typed } from "@evolu/common";
+ * import {
+ *   assertEqual,
+ *   assertFalse,
+ *   assertTrue,
+ *   createRun,
+ *   ok,
+ *   type Task,
+ *   type Typed,
+ * } from "@evolu/common";
  *
  * interface Socket extends AsyncDisposable {
  *   readonly send: (message: string) => string;
@@ -434,8 +455,9 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  * const openSocket: Task<Socket, ConnectionFailedError> = () =>
  *   ok({
  *     send: (message) => message,
- *     [Symbol.asyncDispose]: async () => {
+ *     [Symbol.asyncDispose]: () => {
  *       socketDisposed = true;
+ *       return Promise.resolve();
  *     },
  *   });
  *
@@ -467,11 +489,11 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  *
  * await using run = createRun();
  * const result = await run(createConnection);
- * assert(result.ok);
- * expect(socketDisposed).toBe(false);
- * expect(result.value.send("hello")).toBe("hello");
+ * assertTrue(result.ok);
+ * assertFalse(socketDisposed);
+ * assertEqual(result.value.send("hello"), "hello");
  * await result.value[Symbol.asyncDispose]();
- * expect(socketDisposed).toBe(true);
+ * assertTrue(socketDisposed);
  * ```
  *
  * Use {@link Run.ok} with `await using` when a Task whose error type is `never`
@@ -628,7 +650,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  * each iteration reuses the same stack frame:
  *
  * ```ts
- * import { createRun, ok, type Task } from "@evolu/common";
+ * import { assertOk, createRun, ok, type Task } from "@evolu/common";
  *
  * interface TreeNode {
  *   readonly value: string;
@@ -652,7 +674,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  *   };
  *
  * await using run = createRun();
- * expectOk(
+ * assertOk(
  *   await run(
  *     visitTree({
  *       value: "root",
@@ -843,7 +865,7 @@ export const createRunDefaultDeps = () => {
  * ### Example
  *
  * ```ts
- * import { createRun, ok, type Task } from "@evolu/common";
+ * import { assertOk, createRun, ok, type Task } from "@evolu/common";
  *
  * interface ConfigDep {
  *   readonly config: { readonly apiUrl: string };
@@ -855,7 +877,7 @@ export const createRunDefaultDeps = () => {
  * await using run = createRun({
  *   config: { apiUrl: "https://api.example.com" },
  * });
- * expectOk(await run(loadApiUrl), "https://api.example.com");
+ * assertOk(await run(loadApiUrl), "https://api.example.com");
  * ```
  *
  * @group Run
@@ -1371,14 +1393,23 @@ const mapInput = (input, fn) => Array.isArray(input)
  * ### Example
  *
  * ```ts
- * import { callback, createRun, ok, type Task } from "@evolu/common";
+ * import {
+ *   assertEqual,
+ *   assertOk,
+ *   callback,
+ *   createRun,
+ *   ok,
+ *   type Task,
+ * } from "@evolu/common";
  *
  * const listeners = new Set<(message: string) => void>();
  * const subscribe = (
  *   listener: (message: string) => void,
  * ): (() => void) => {
  *   listeners.add(listener);
- *   return () => listeners.delete(listener);
+ *   return () => {
+ *     listeners.delete(listener);
+ *   };
  * };
  * const nextMessage: Task<string> = callback(({ resolve }) =>
  *   subscribe((message) => resolve(ok(message))),
@@ -1386,11 +1417,11 @@ const mapInput = (input, fn) => Array.isArray(input)
  *
  * await using run = createRun();
  * const fiber = run(nextMessage);
- * expect(listeners.size).toBe(1);
+ * assertEqual(listeners.size, 1);
  * for (const listener of listeners) listener("ready");
- * expectOk(await fiber, "ready");
+ * assertOk(await fiber, "ready");
  * // The callback cleanup unsubscribes after settlement.
- * expect(listeners.size).toBe(0);
+ * assertEqual(listeners.size, 0);
  * ```
  *
  * @group Interop
@@ -1414,10 +1445,10 @@ export const callback = (fn) => (run) => {
  * ### Example
  *
  * ```ts
- * import { createRun, sleep } from "@evolu/common";
+ * import { assertOk, createRun, sleep } from "@evolu/common";
  *
  * await using run = createRun();
- * expectOk(await run(sleep("1ms")), undefined);
+ * assertOk(await run(sleep("1ms")), undefined);
  * ```
  *
  * @group Timing
@@ -1439,6 +1470,8 @@ export const sleep = (duration) => callback(({ run: { deps }, resolve }) => {
  *
  * ```ts
  * import {
+ *   assertErr,
+ *   assertType,
  *   createRun,
  *   timeout,
  *   timeoutError,
@@ -1450,8 +1483,8 @@ export const sleep = (duration) => callback(({ run: { deps }, resolve }) => {
  * await using run = createRun();
  *
  * const result = await run(timeout(waitForAbort, "1ms"));
- * expectTypeOf(result).toEqualTypeOf<Result<never, TimeoutError>>();
- * expectErr(result, timeoutError);
+ * assertType<Result<never, TimeoutError>, typeof result>();
+ * assertErr(result, timeoutError);
  * ```
  *
  * @group Timing
@@ -1498,6 +1531,8 @@ export const timeoutError = { type: "TimeoutError" };
  *
  * ```ts
  * import {
+ *   assertErr,
+ *   assertType,
  *   createRun,
  *   err,
  *   recurs,
@@ -1517,10 +1552,11 @@ export const timeoutError = { type: "TimeoutError" };
  *
  * await using run = createRun();
  * const result = await run(fetchWithRetry);
- * expectTypeOf(result).toEqualTypeOf<
- *   Result<string, RetryTaskError<ServiceUnavailableError>>
+ * assertType<
+ *   Result<string, RetryTaskError<ServiceUnavailableError>>,
+ *   typeof result
  * >();
- * expectErr(result, {
+ * assertErr(result, {
  *   type: "RetryError",
  *   attempts: 3,
  *   lastError: { type: "ServiceUnavailable" },
@@ -1531,6 +1567,7 @@ export const timeoutError = { type: "TimeoutError" };
  *
  * ```ts
  * import {
+ *   assertErr,
  *   createRun,
  *   err,
  *   recurs,
@@ -1553,7 +1590,8 @@ export const timeoutError = { type: "TimeoutError" };
  * });
  *
  * await using run = createRun();
- * expectErr(await run(fetchWithRetry), {
+ * const result = await run(fetchWithRetry);
+ * assertErr(result, {
  *   type: "RetryError",
  *   attempts: 1,
  *   lastError: { type: "PermanentFailure" },
@@ -1609,7 +1647,15 @@ export const retry = (task, schedule, { shouldRetry = constTrue, onRetry, } = {}
  * ### Repeating successes
  *
  * ```ts
- * import { createRun, ok, recurs, repeat, type Task } from "@evolu/common";
+ * import {
+ *   assertEqual,
+ *   assertOk,
+ *   createRun,
+ *   ok,
+ *   recurs,
+ *   repeat,
+ *   type Task,
+ * } from "@evolu/common";
  *
  * let attempts = 0;
  * const checkStatus: Task<string> = () => {
@@ -1620,14 +1666,16 @@ export const retry = (task, schedule, { shouldRetry = constTrue, onRetry, } = {}
  * const poll = repeat(checkStatus, recurs(3));
  *
  * await using run = createRun();
- * expectOk(await run(poll), "pending");
- * expect(attempts).toBe(4);
+ * assertOk(await run(poll), "pending");
+ * assertEqual(attempts, 4);
  * ```
  *
  * ### Stopping with Done
  *
  * ```ts
  * import {
+ *   assertErr,
+ *   assertEqual,
  *   createRun,
  *   done,
  *   err,
@@ -1650,8 +1698,8 @@ export const retry = (task, schedule, { shouldRetry = constTrue, onRetry, } = {}
  *
  * await using run = createRun();
  * const result = await run(repeat(processQueue, spaced("1ms")));
- * expectErr(result, done());
- * expect(queue).toEqual([]);
+ * assertErr(result, done());
+ * assertEqual(queue, []);
  * ```
  *
  * @group Repetition
@@ -1697,6 +1745,9 @@ export const repeat = (task, schedule, { shouldRepeat = constTrue, onRepeat } =
  *
  * ```ts
  * import {
+ *   assertOk,
+ *   assertType,
+ *   assertTrue,
  *   any,
  *   createRun,
  *   err,
@@ -1720,11 +1771,9 @@ export const repeat = (task, schedule, { shouldRepeat = constTrue, onRepeat } =
  * await using run = createRun();
  * const result = await run(any([unavailable, fallback]));
  *
- * expectTypeOf(result).toEqualTypeOf<
- *   Result<string, ServiceUnavailableError>
- * >();
- * expectOk(result, "fallback");
- * expect(fallbackStarted).toBe(true);
+ * assertType<Result<string, ServiceUnavailableError>, typeof result>();
+ * assertOk(result, "fallback");
+ * assertTrue(fallbackStarted);
  * ```
  *
  * @group Racing
@@ -1775,6 +1824,7 @@ export const any = (tasks, options) => async (run) => {
  *
  * ```ts
  * import {
+ *   assertOk,
  *   createRun,
  *   isNonEmptyArray,
  *   ok,
@@ -1786,7 +1836,7 @@ export const any = (tasks, options) => async (run) => {
  * await using run = createRun();
  * if (isNonEmptyArray(tasks)) {
  *   const result = await run(race(tasks));
- *   expectOk(result, "first");
+ *   assertOk(result, "first");
  * }
  * ```
  *
@@ -1794,6 +1844,9 @@ export const any = (tasks, options) => async (run) => {
  *
  * ```ts
  * import {
+ *   assertFalse,
+ *   assertOk,
+ *   assertType,
  *   createRun,
  *   ok,
  *   race,
@@ -1815,9 +1868,9 @@ export const any = (tasks, options) => async (run) => {
  * // Input order does not matter: the first settled Result wins, and the
  * // still-running loser is aborted.
  * const result = await run(race([slow, fast]));
- * expectTypeOf(result).toEqualTypeOf<Result<string>>();
- * expectOk(result, "fast");
- * expect(slowCompleted).toBe(false);
+ * assertType<Result<string>, typeof result>();
+ * assertOk(result, "fast");
+ * assertFalse(slowCompleted);
  * ```
  *
  * @group Racing
@@ -1848,6 +1901,8 @@ export const race = (tasks) => async (run) => {
  *
  * ```ts
  * import {
+ *   assertFalse,
+ *   assertOk,
  *   createRun,
  *   err,
  *   firstN,
@@ -1878,8 +1933,8 @@ export const race = (tasks) => async (run) => {
  *
  * // Errs do not count. After two Ok values settle, the slow Task is aborted.
  * const result = await run(firstN(tasks, 2, { concurrency: 4 }));
- * expectOk(result, ["fast-1", "fast-2"]);
- * expect(slowCompleted).toBe(false);
+ * assertOk(result, ["fast-1", "fast-2"]);
+ * assertFalse(slowCompleted);
  * ```
  *
  * @group Racing
@@ -1910,6 +1965,8 @@ export const firstN = (tasks, count, options) => async (run) => {
  *
  * ```ts
  * import {
+ *   assertFalse,
+ *   assertOk,
  *   createRun,
  *   err,
  *   firstNSettled,
@@ -1935,11 +1992,11 @@ export const firstN = (tasks, count, options) => async (run) => {
  *
  * // Err and Ok both count, and Results use settlement order.
  * const result = await run(firstNSettled(tasks, 2, { concurrency: 3 }));
- * expectOk(result, [
+ * assertOk(result, [
  *   { ok: false, error: { type: "ServiceUnavailable" } },
  *   { ok: true, value: "fast" },
  * ]);
- * expect(slowCompleted).toBe(false);
+ * assertFalse(slowCompleted);
  * ```
  *
  * @group Racing
@@ -1984,6 +2041,9 @@ export const firstNSettled = (tasks, count, options) => async (run) => {
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertFalse,
+ *   assertOk,
  *   createRun,
  *   each,
  *   err,
@@ -2019,9 +2079,9 @@ export const firstNSettled = (tasks, count, options) => async (run) => {
  *   ),
  * );
  *
- * expectOk(result, undefined);
- * expect(first).toEqual(["fast", 2]);
- * expect(slowCompleted).toBe(false);
+ * assertOk(result, undefined);
+ * assertEqual(first, ["fast", 2]);
+ * assertFalse(slowCompleted);
  * ```
  *
  * `onResult` is a synchronous scheduling decision, not a place to do work. It
@@ -2118,13 +2178,19 @@ export const each = (tasks, onResult, options = {}) => async (run) => {
  * ### Example
  *
  * ```ts
- * import { createRun, ok, prioritized, type Task } from "@evolu/common";
+ * import {
+ *   assertOk,
+ *   createRun,
+ *   ok,
+ *   prioritized,
+ *   type Task,
+ * } from "@evolu/common";
  *
  * const rebuildSearchIndex: Task<string> = () => ok("indexed");
  * const backgroundIndexing = prioritized("background", rebuildSearchIndex);
  *
  * await using run = createRun();
- * expectOk(await run(backgroundIndexing), "indexed");
+ * assertOk(await run(backgroundIndexing), "indexed");
  * ```
  *
  * @group Scheduling
@@ -2144,7 +2210,13 @@ export const prioritized = (priority, task) => withTaskMeta({ priority })(task);
  * ### Example
  *
  * ```ts
- * import { createRun, ok, yieldNow, type Task } from "@evolu/common";
+ * import {
+ *   assertOk,
+ *   createRun,
+ *   ok,
+ *   yieldNow,
+ *   type Task,
+ * } from "@evolu/common";
  *
  * const sumTo =
  *   (count: number): Task<number> =>
@@ -2160,7 +2232,7 @@ export const prioritized = (priority, task) => withTaskMeta({ priority })(task);
  *   };
  *
  * await using run = createRun();
- * expectOk(await run(sumTo(1001)), 500500);
+ * assertOk(await run(sumTo(1001)), 500500);
  * ```
  *
  * @group Scheduling
@@ -2197,6 +2269,10 @@ export const yieldNow = async (run) => {
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertFalse,
+ *   assertType,
+ *   assertTrue,
  *   AbortError,
  *   createRun,
  *   ok,
@@ -2213,23 +2289,22 @@ export const yieldNow = async (run) => {
  * const serverStarted = Promise.withResolvers<void>();
  * let serverStopped = false;
  * const startServer: Task<Server, never, ServerDep> = (run) => {
- *   expect(run.deps.port).toBe(3000);
+ *   assertEqual(run.deps.port, 3000);
  *   serverStarted.resolve();
  *   return ok({
- *     [Symbol.asyncDispose]: async () => {
+ *     [Symbol.asyncDispose]: () => {
  *       serverStopped = true;
+ *       return Promise.resolve();
  *     },
  *   });
  * };
  *
  * const serve = (): Task<never, never, ServerDep> => async (run) => {
- *   await using server = await run.ok(startServer);
+ *   await using _ = await run.ok(startServer);
  *   return await run(waitForAbort);
  * };
  *
- * expectTypeOf(serve).returns.toEqualTypeOf<
- *   Task<never, never, ServerDep>
- * >();
+ * assertType<Task<never, never, ServerDep>, ReturnType<typeof serve>>();
  *
  * await using run = createRun();
  * const fiber = run.abortable(serve(), { port: 3000 });
@@ -2237,9 +2312,9 @@ export const yieldNow = async (run) => {
  * fiber.abort();
  *
  * const result = await fiber;
- * assert(!result.ok);
- * expect(AbortError.is(result.error)).toBe(true);
- * expect(serverStopped).toBe(true);
+ * assertFalse(result.ok);
+ * assertTrue(AbortError.is(result.error));
+ * assertTrue(serverStopped);
  * ```
  *
  * @group Abortability
@@ -2303,6 +2378,9 @@ export const waitForAbort = async (run) => {
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertFalse,
+ *   assertTrue,
  *   createRun,
  *   daemon,
  *   ok,
@@ -2323,18 +2401,24 @@ export const waitForAbort = async (run) => {
  * {
  *   await using run = createRun();
  *   const result = await run(timeout(daemon(taskNotUsingAbort), "1ms"));
- *   assert(!result.ok);
- *   expect(result.error.type).toBe("TimeoutError");
- *   expect(finished).toBe(false);
+ *   assertFalse(result.ok);
+ *   assertEqual(result.error.type, "TimeoutError");
+ *   assertFalse(finished);
  *   finishTask();
  * }
- * expect(finished).toBe(true);
+ * assertTrue(finished);
  * ```
  *
  * Promise-returning functions should be called inside the Task, not before it.
  *
  * ```ts
- * import { createRun, ok, type Result, type Task } from "@evolu/common";
+ * import {
+ *   assertOk,
+ *   createRun,
+ *   ok,
+ *   type Result,
+ *   type Task,
+ * } from "@evolu/common";
  *
  * type ResultValue = string;
  * const createPromiseReturningResult = (): Promise<Result<ResultValue>> =>
@@ -2343,14 +2427,20 @@ export const waitForAbort = async (run) => {
  * const task: Task<ResultValue> = () => createPromiseReturningResult();
  *
  * await using run = createRun();
- * expectOk(await run(task), "value");
+ * assertOk(await run(task), "value");
  * ```
  *
  * Do not reuse an already-running Promise. It started outside the Task, so the
  * Run cannot own its lifetime or request abort before it begins.
  *
  * ```ts
- * import { ok, type Result, type Task } from "@evolu/common";
+ * import {
+ *   assertType,
+ *   assertTrue,
+ *   ok,
+ *   type Result,
+ *   type Task,
+ * } from "@evolu/common";
  *
  * type ResultValue = string;
  * let promiseStarted = false;
@@ -2365,8 +2455,8 @@ export const waitForAbort = async (run) => {
  * const promise = createPromiseReturningResult();
  * const task: Task<ResultValue> = () => promise;
  *
- * expect(promiseStarted).toBe(true);
- * expectTypeOf(task).toEqualTypeOf<Task<ResultValue>>();
+ * assertTrue(promiseStarted);
+ * assertType<Task<ResultValue>, typeof task>();
  * ```
  *
  * @group Lifetime
@@ -2413,14 +2503,21 @@ export const daemon = (task) => async (run) => {
  * ### Example
  *
  * ```ts
- * import { createRun, ok, unabortable, type Task } from "@evolu/common";
+ * import {
+ *   assertFalse,
+ *   assertOk,
+ *   createRun,
+ *   ok,
+ *   unabortable,
+ *   type Task,
+ * } from "@evolu/common";
  *
  * const commitStarted = Promise.withResolvers<void>();
  * const finishCommit = Promise.withResolvers<void>();
  * const commit: Task<string> = unabortable(async (run) => {
  *   commitStarted.resolve();
  *   await finishCommit.promise;
- *   expect(run.signal.aborted).toBe(false);
+ *   assertFalse(run.signal.aborted);
  *   return ok("committed");
  * });
  *
@@ -2430,7 +2527,7 @@ export const daemon = (task) => async (run) => {
  * fiber.abort();
  * finishCommit.resolve();
  *
- * expectOk(await fiber, "committed");
+ * assertOk(await fiber, "committed");
  * ```
  *
  * @group Abortability
@@ -2460,6 +2557,9 @@ export const unabortable = /*#__PURE__*/ withTaskMeta({
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertFalse,
+ *   assertTrue,
  *   AbortError,
  *   createRun,
  *   ok,
@@ -2476,17 +2576,17 @@ export const unabortable = /*#__PURE__*/ withTaskMeta({
  * const operationStarted = Promise.withResolvers<void>();
  * const operate =
  *   (resource: Resource): Task<never> =>
- *   async (run) => {
- *     expect(resource.id).toBe("resource-1");
+ *   (run) => {
+ *     assertEqual(resource.id, "resource-1");
  *     operationStarted.resolve();
- *     return await run(waitForAbort);
+ *     return run(waitForAbort);
  *   };
  * let released = false;
  * const release =
  *   (_resource: Resource): Task<void> =>
  *   (run) => {
  *     // Release inherits the mask even after abort was requested.
- *     expect(run.signal.aborted).toBe(false);
+ *     assertFalse(run.signal.aborted);
  *     released = true;
  *     return ok();
  *   };
@@ -2510,9 +2610,9 @@ export const unabortable = /*#__PURE__*/ withTaskMeta({
  * await operationStarted.promise;
  * fiber.abort();
  * const result = await fiber;
- * assert(!result.ok);
- * expect(AbortError.is(result.error)).toBe(true);
- * expect(released).toBe(true);
+ * assertFalse(result.ok);
+ * assertTrue(AbortError.is(result.error));
+ * assertTrue(released);
  * ```
  *
  * @group Abortability
@@ -2555,6 +2655,8 @@ export const unabortableMask = (fn) => unabortable((run) => {
  *
  * ```ts
  * import {
+ *   assertErr,
+ *   assertTrue,
  *   acquireUseRelease,
  *   createRun,
  *   err,
@@ -2594,9 +2696,9 @@ export const unabortableMask = (fn) => unabortable((run) => {
  * );
  *
  * await using run = createRun();
- * expectErr(await run(queryUser), { type: "UserUnavailable" });
+ * assertErr(await run(queryUser), { type: "UserUnavailable" });
  * // Release still runs when use returns a domain error.
- * expect(connectionClosed).toBe(true);
+ * assertTrue(connectionClosed);
  * ```
  *
  * @group Lifetime
@@ -2620,6 +2722,10 @@ export const acquireUseRelease = (acquire, use, release) => unabortableMask((res
  *
  * ```ts
  * import {
+ *   assertFalse,
+ *   assertOk,
+ *   assertType,
+ *   assertTrue,
  *   createDeferred,
  *   createRun,
  *   ok,
@@ -2630,22 +2736,28 @@ export const acquireUseRelease = (acquire, use, release) => unabortableMask((res
  * const deferred = createDeferred<string>();
  *
  * const fiber = run(deferred.task);
- * expect(deferred.resolve(ok("ready"))).toBe(true);
+ * assertTrue(deferred.resolve(ok("ready")));
  *
  * const result = await fiber;
- * expectTypeOf(result).toEqualTypeOf<Result<string>>();
- * expectOk(result, "ready");
+ * assertType<Result<string>, typeof result>();
+ * assertOk(result, "ready");
  *
  * // A Deferred is one-shot: later resolutions are ignored, and future
  * // waiters receive the original Result.
- * expect(deferred.resolve(ok("late"))).toBe(false);
- * expectOk(await run(deferred.task), "ready");
+ * assertFalse(deferred.resolve(ok("late")));
+ * assertOk(await run(deferred.task), "ready");
  * ```
  *
  * ### Aborting a waiter
  *
  * ```ts
- * import { AbortError, createDeferred, createRun } from "@evolu/common";
+ * import {
+ *   assertFalse,
+ *   assertTrue,
+ *   AbortError,
+ *   createDeferred,
+ *   createRun,
+ * } from "@evolu/common";
  *
  * await using run = createRun();
  * const deferred = createDeferred<string>();
@@ -2654,8 +2766,8 @@ export const acquireUseRelease = (acquire, use, release) => unabortableMask((res
  * fiber.abort({ type: "NoLongerNeeded" });
  *
  * const result = await fiber;
- * assert(!result.ok);
- * expect(AbortError.is(result.error)).toBe(true);
+ * assertFalse(result.ok);
+ * assertTrue(AbortError.is(result.error));
  * ```
  *
  * @group Concurrency primitives
@@ -2691,7 +2803,15 @@ export const createDeferred = () => {
  * ### Example
  *
  * ```ts
- * import { createGate, createRun, ok, type Task } from "@evolu/common";
+ * import {
+ *   assertEqual,
+ *   assertOk,
+ *   assertTrue,
+ *   createGate,
+ *   createRun,
+ *   ok,
+ *   type Task,
+ * } from "@evolu/common";
  *
  * await using run = createRun();
  * const networkGate = createGate();
@@ -2707,13 +2827,13 @@ export const createDeferred = () => {
  *
  * const first = run(syncOnce("first"));
  * const second = run(syncOnce("second"));
- * expect(uploadedItems).toEqual([]);
+ * assertEqual(uploadedItems, []);
  *
  * networkGate.open();
- * expectOk(await first, undefined);
- * expectOk(await second, undefined);
- * expect(uploadedItems).toEqual(["first", "second"]);
- * expect(networkGate.isOpen()).toBe(true);
+ * assertOk(await first, undefined);
+ * assertOk(await second, undefined);
+ * assertEqual(uploadedItems, ["first", "second"]);
+ * assertTrue(networkGate.isOpen());
  * ```
  *
  * @group Concurrency primitives
@@ -2756,6 +2876,7 @@ export const createGate = ({ isOpen = false, } = {}) => {
  *
  * ```ts
  * import {
+ *   assertEqual,
  *   createRun,
  *   createSemaphore,
  *   getOk,
@@ -2787,8 +2908,8 @@ export const createGate = ({ isOpen = false, } = {}) => {
  * ]);
  *
  * const savedUsers = results.map(getOk);
- * expect(savedUsers).toEqual(["saved:1", "saved:2", "saved:3"]);
- * expect(maxActiveSaves).toBe(2);
+ * assertEqual(savedUsers, ["saved:1", "saved:2", "saved:3"]);
+ * assertEqual(maxActiveSaves, 2);
  * ```
  *
  * @group Concurrency primitives
@@ -2910,6 +3031,8 @@ export const createSemaphore = (initialPermits, { policy = "fifo", } = {}) => {
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertOk,
  *   createMutex,
  *   createRun,
  *   ok,
@@ -2932,9 +3055,9 @@ export const createSemaphore = (initialPermits, { policy = "fifo", } = {}) => {
  *   run(deposit(2)),
  *   run(deposit(3)),
  * ]);
- * expectOk(first, undefined);
- * expectOk(second, undefined);
- * expect(balance).toBe(5);
+ * assertOk(first, undefined);
+ * assertOk(second, undefined);
+ * assertEqual(balance, 5);
  * ```
  *
  * @group Concurrency primitives
@@ -2991,14 +3114,14 @@ export function createMutexByKey({ lookup = identity, } = {}) {
  * ### Example
  *
  * ```ts
- * import { createMutexRef, createRun, ok } from "@evolu/common";
+ * import { assertOk, createMutexRef, createRun, ok } from "@evolu/common";
  *
  * const counter = createMutexRef(0);
  * const increment = counter.updateAndGet((value) => () => ok(value + 1));
  *
  * await using run = createRun();
- * expectOk(await run(increment), 1);
- * expectOk(await run(counter.get), 1);
+ * assertOk(await run(increment), 1);
+ * assertOk(await run(counter.get), 1);
  * ```
  *
  * @group Concurrency primitives