@evolu/common 8.4.0 → 8.5.0

package/dist/src/Task.js

@@ -55,36 +55,34 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  *
  * JavaScript-native structured concurrency.
  *
- * Structured concurrency makes ownership of asynchronous work explicit.
- * Operations form a tree where every child belongs to a parent. A parent waits
- * for its children before it completes, and abort follows the tree: aborting a
- * parent requests abort of all its descendants. Races and fail-fast operations
- * also abort their remaining sibling branches.
+ * Structured concurrency organizes running tasks into a tree. Every child
+ * belongs to a parent, a parent waits for its children before it completes, and
+ * abort propagates from parents to descendants. Races and fail-fast control
+ * flow abort siblings that are no longer needed.
  *
  * With plain {@link AbortController} code, these guarantees depend on call-site
- * discipline: someone must remember the `finally` that aborts started work and
- * the await that waits for cleanup. {@link Run} makes both structural:
- * `run(task)` registers every child before it starts, and the parent settles
+ * discipline: someone must remember the `finally` that aborts started tasks and
+ * the await that waits for cleanup. Evolu makes both structural: `run(task)`
+ * registers every child before it starts, and the parent {@link Run} settles
  * only after child cleanup finishes.
  *
- * Evolu models structured concurrency with ordinary JavaScript:
+ * Evolu implements structured concurrency with:
  *
- * - A {@link Task} describes an asynchronous operation and its dependencies.
+ * - A {@link Task} is a function passed to Run that returns an {@link Awaitable}
+ *   {@link Result} and declares its dependencies.
  * - A {@link Run} starts Tasks and owns their lifetimes.
  * - A {@link Fiber} is the Promise-backed handle returned when a Run starts a
  *   Task.
  * - An {@link AbortableFiber} adds explicit abort and async disposal.
  *
- * The runtime core is deliberately small: ordinary functions, a callable Run
- * with closed-over state, Promise-backed Fibers, {@link AbortSignal}
- * propagation, and JavaScript resource management. Together, these primitives
- * provide abort, cleanup, defect handling, dependency injection, monitoring,
- * concurrency, and resource bracketing.
+ * Together, these APIs provide abort, cleanup, defect handling, dependency
+ * injection, monitoring, and resource management.
  *
- * Tasks return domain success or failure as {@link Result}. Abort is control
- * flow represented by {@link AbortError}. If a Task throws or rejects with
- * anything else, that is a defect: the root Run reports it and shuts down its
- * tree so code does not continue in a potentially invalid state.
+ * Tasks return a {@link Result} containing either success or a domain error.
+ * Abort is control flow represented by {@link AbortError}. If a Task throws or
+ * rejects with anything else, that is a defect: the root Run reports it and
+ * shuts down its tree so code does not continue in a potentially invalid
+ * state.
  *
  * ```ts
  * import {
@@ -253,7 +251,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  *
  * {@link fetch} with a body mode already returns a plain value, so resilience is
  * ordinary Task composition. Combine {@link timeout} and {@link retry} to bound
- * each attempt and retry recoverable domain failures:
+ * each attempt and retry recoverable domain errors:
  *
  * ```ts
  * import {
@@ -476,9 +474,9 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  * expect(socketDisposed).toBe(true);
  * ```
  *
- * Use {@link Run.ok} with `await using` when an infallible Task returns a
- * disposable value. Use {@link acquireUseRelease} when acquisition and release
- * are separate operations rather than a disposable value.
+ * Use {@link Run.ok} with `await using` when a Task whose error type is `never`
+ * returns a disposable value. Use {@link acquireUseRelease} when acquisition and
+ * release are separate steps rather than a disposable value.
  *
  * ## Awaitable
  *
@@ -491,7 +489,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  *
  * A Task is an async ownership boundary, not a general unit of program
  * decomposition. Calling `run(task)` always creates a child Run by design. Use
- * ordinary promises when an async operation does not need its own Run.
+ * a plain async function when it does not need its own Run.
  *
  * A unified sync/async effect API is technically possible. It can detect
  * Promise-like values with {@link isPromiseLike}, dispose synchronous resources
@@ -509,7 +507,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  * code performs effects with the result. For example, a pure function can
  * accept a {@link RandomNumber} value instead of depending on {@link Random}.
  *
- * Large CPU-bound operations, such as parsing large JSON, sorting millions of
+ * Large CPU-bound computations, such as parsing large JSON, sorting millions of
  * items, or complex cryptography, belong in a worker. Model the asynchronous
  * call to that worker as a Task so Run can provide timeout, abort, cleanup, and
  * monitoring.
@@ -569,10 +567,10 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  * ### What should Task code do with defects?
  *
  * Nothing. Once a defect reaches the {@link Run}, it is too late: the root Run
- * panics, running Tasks are aborted, and the Run tree shuts down. If an
- * operation can throw or reject for a recoverable reason, wrap that operation
- * with {@link trySync} or {@link tryAsync} so the failure becomes a typed
- * {@link Result} error. Let unrecoverable failures propagate as defects.
+ * panics, running Tasks are aborted, and the Run tree shuts down. Use
+ * {@link trySync} or {@link tryAsync} to turn recoverable exceptions and Promise
+ * rejections into typed {@link Result} errors. Let unrecoverable failures
+ * propagate as defects.
  *
  * ### Why does a defect panic the whole Run tree?
  *
@@ -671,13 +669,6 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  * periodically await {@link yieldNow} for cooperative scheduling, and move
  * CPU-bound work to a worker.
  *
- * ### Should a Task be called directly?
- *
- * Only inside Task internals that explicitly require same-Run execution. A
- * direct call, `task(run)`, uses the current Run instead of creating a child
- * Run, so it bypasses child lifetime tracking, scheduling metadata, and child
- * disposal boundaries. Application code should use `run(task)`.
- *
  * ### Where are fork and join?
  *
  * Calling `run(task)` is fork: it starts a child Task and returns a
@@ -1128,7 +1119,6 @@ const createRunInternal = (deps, parent, rootRun, taskMeta) => {
                 if (taskMeta?.priority && scheduler?.postTask) {
                     result = await scheduler.postTask(() => {
                         startSignal.throwIfAborted();
-                        // eslint-disable-next-line evolu/no-direct-task-call -- The executor invokes the Task with its child Run.
                         return task(taskRun);
                     }, {
                         priority: taskMeta.priority,
@@ -1137,7 +1127,6 @@ const createRunInternal = (deps, parent, rootRun, taskMeta) => {
                 }
                 else {
                     startSignal.throwIfAborted();
-                    // eslint-disable-next-line evolu/no-direct-task-call -- The executor invokes the Task with its child Run.
                     result = await task(taskRun);
                 }
                 // Full Result validation is dev-only; production checks only the
@@ -1286,7 +1275,6 @@ const withTaskMeta = (meta) => (task) => {
     const taskInternal = task;
     assert(meta.abortBehavior === undefined ||
         taskInternal[taskMetaSymbol]?.abortBehavior === undefined, "abort behavior helpers cannot wrap the same Task");
-    // eslint-disable-next-line evolu/no-direct-task-call -- Preserve the wrapped Task's child Run.
     const wrapped = (run) => task(run);
     const taskMeta = taskInternal[taskMetaSymbol];
     wrapped[taskMetaSymbol] = taskMeta ? { ...taskMeta, ...meta } : meta;
@@ -1358,7 +1346,7 @@ const mapInput = (input, fn) => Array.isArray(input)
  * This helper is a callback bridge. If `reject` forwards an Error created in a
  * separate async chain, V8 cannot reconstruct the caller's zero-cost async
  * stack through this bridge. Prefer native promise APIs and `await` when the
- * wrapped operation already has a promise-shaped API.
+ * wrapped API already returns a Promise.
  *
  * One-shot settlement applies only to `resolve` and `reject`. A synchronous
  * throw from the setup function is a defect that panics the Run tree even after
@@ -2078,7 +2066,7 @@ export const each = (tasks, onResult, options = {}) => async (run) => {
                     const index = nextIndex;
                     nextIndex += 1;
                     const result = await run(tasks[index]);
-                    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- stopped can flip across the await via sibling workers
+                    // stopped can flip across the await via sibling workers.
                     if (stopped)
                         break;
                     run.signal.throwIfAborted();
@@ -2097,6 +2085,7 @@ export const each = (tasks, onResult, options = {}) => async (run) => {
             active -= 1;
             if (active === 0)
                 wake.resolve();
+            // oxlint-disable-next-line typescript/return-await -- StackTrace.test.ts measures this direct await edge in the worker topology.
             return await parked;
         };
         await Promise.race([
@@ -2197,7 +2186,6 @@ export const yieldNow = async (run) => {
     run.signal.throwIfAborted();
     return ok();
 };
-// Abortability
 /**
  * Waits until the current {@link Run} aborts, then rejects with its
  * {@link AbortError}.
@@ -2281,8 +2269,8 @@ export const waitForAbort = async (run) => {
  * execution. The daemon Task continues under root Run ownership until it
  * settles, observes abort, or the root Run is disposed.
  *
- * This is not a replacement for direct {@link AbortSignal} support in operations
- * that can observe abort, such as {@link fetch}, timers that accept a signal, or
+ * This is not a replacement for direct {@link AbortSignal} support in APIs that
+ * can observe abort, such as {@link fetch}, timers that accept a signal, or
  * callback APIs that accept a signal. Use it as an escape hatch for Tasks that
  * ignore abort when an abort request must stop waiting immediately.
  *
@@ -2343,7 +2331,7 @@ export const waitForAbort = async (run) => {
  * expect(finished).toBe(true);
  * ```
  *
- * Promise-producing operations should start inside the Task, not before it.
+ * Promise-returning functions should be called inside the Task, not before it.
  *
  * ```ts
  * import { createRun, ok, type Result, type Task } from "@evolu/common";
@@ -2460,7 +2448,7 @@ export const unabortable = /*#__PURE__*/ withTaskMeta({
  *
  * An abort request before the mask Task starts prevents entering the mask. Once
  * the body starts, plain child Tasks inherit the mask, so acquire and release
- * can run after abort. Put release operations directly in the original mask's
+ * can run after abort. Start release Tasks directly in the original mask's
  * `finally`; do not wrap release in a nested `unabortableMask`, which is a new
  * critical-section entry and may not start after abort.
  *
@@ -2534,7 +2522,7 @@ export const unabortableMask = (fn) => unabortable((run) => {
     // Only verifies the Run is masked. A direct call inside an already masked
     // Run passes undetected; direct calls bypass Run semantics by design.
     assert(runInternal.abortMask > abortableMask, "unabortableMask requires a masked Run; use run(task), not a direct call");
-    const restoreToken = Symbol();
+    const restoreToken = Symbol("restore");
     // The token is local to this Task Run; descendant Runs inherit the token
     // set so helpers can receive restore while the mask Task is alive.
     // Each set is bounded by its Run lifetime and is intentionally not pruned.
@@ -2560,7 +2548,7 @@ export const unabortableMask = (fn) => unabortable((run) => {
  * Prefer native `using`, `await using`, or {@link AsyncDisposableStack} for
  * owned values that implement {@link Disposable} or {@link AsyncDisposable}. Use
  * `acquireUseRelease` when acquisition must be balanced with a separate release
- * operation, such as unlocking, returning a pooled value, releasing a lease, or
+ * step, such as unlocking, returning a pooled value, releasing a lease, or
  * logging out of a session.
  *
  * ### Example
@@ -2618,7 +2606,7 @@ export const acquireUseRelease = (acquire, use, release) => unabortableMask((res
     if (!resourceResult.ok)
         return resourceResult;
     try {
-        // eslint-disable-next-line react-hooks/rules-of-hooks -- `use` is an acquireUseRelease callback, not a React Hook.
+        // oxlint-disable-next-line react/rules-of-hooks -- `use` is an acquireUseRelease callback, not a React Hook.
         return await run(restore(use(resourceResult.value)));
     }
     finally {
@@ -2736,7 +2724,6 @@ export const createGate = ({ isOpen = false, } = {}) => {
         deferred.resolve(ok());
     return {
         // Direct same-Run delegation is intentional so wait observes the current deferred.
-        // eslint-disable-next-line evolu/no-direct-task-call
         wait: (run) => deferred.task(run),
         open: () => {
             if (isOpen)
@@ -3065,7 +3052,7 @@ export const createMutexRef = (initialValue) => {
 //   filtering, and pluggable log sinks.
 // - Tracing spans with names, timing, parent-child relationships, attributes,
 //   error status, and helpers for annotating the current or child spans.
-// - Metrics for counters, gauges, histograms, and operation durations.
+// - Metrics for counters, gauges, histograms, and Task execution durations.
 // - Resource metadata for service name, service version, deployment
 //   environment, and user-provided attributes.
 // - Exporters for production telemetry backends, including OTLP-compatible
@@ -3078,5 +3065,5 @@ export const createMutexRef = (initialValue) => {
 // - Run labels and structured annotations for rendering useful snapshot trees
 //   instead of anonymous ids.
 // - Snapshot and trace views should preserve ownership boundaries, so reusable
-//   resources and long-lived operations appear as labeled subtrees instead of
-//   unrelated child operations.
+//   resources and long-lived Runs appear as labeled subtrees instead of
+//   unrelated child Runs.

package/dist/src/Test.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Test.d.ts","sourceRoot":"","sources":["../../src/Test.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxC,OAAO,EAAY,KAAK,EAAE,EAAE,MAAM,WAAW,CAAC;AAE9C,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,SAAS,MAAM,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAC1E,EAAE,GACF,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;AAElB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,YAAY,QAAO,YAM/B,CAAC"}
+{"version":3,"file":"Test.d.ts","sourceRoot":"","sources":["../../src/Test.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxC,OAAO,EAAY,KAAK,EAAE,EAAE,MAAM,WAAW,CAAC;AAE9C,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,SAAS,MAAM,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAC1E,EAAE,GACF,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;AAElB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,YAAY,QAAO,YAO/B,CAAC"}

package/dist/src/Test.js

@@ -42,5 +42,6 @@ export const testCreateId = () => {
     const randomBytes = testCreateRandomBytes({
         randomLib: testCreateRandomLib(),
     });
+    // oxlint-disable-next-line typescript/no-unnecessary-type-arguments -- Explicit never resolves createId's conditional brand-validation rest parameter; inference rejects the argument without it.
     return (() => createId({ randomBytes }));
 };

package/dist/src/Time.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Time.d.ts","sourceRoot":"","sources":["../../src/Time.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,OAAO,EAEL,KAAK,OAAO,EASZ,KAAK,YAAY,EAKlB,MAAM,WAAW,CAAC;AAEnB,iCAAiC;AACjC,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,GAAG,EAAE;QACZ,uDAAuD;QACvD,IAAI,MAAM,CAAC;QAEX,sDAAsD;QACtD,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC;KAC5B,CAAC;IAEF,QAAQ,CAAC,WAAW,EAAE;QACpB,uEAAuE;QACvE,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAC;QAE3C;;;;;;;;;WASG;QACH,QAAQ,CAAC,GAAG,EAAE,MAAM,eAAe,CAAC;KACrC,CAAC;IAEF,+DAA+D;IAC/D,QAAQ,CAAC,UAAU,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,KAAK,EAAE,gBAAgB,KAAK,SAAS,CAAC;IAE5E;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,EAAE,EAAE,SAAS,KAAK,IAAI,CAAC;CAChD;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC;AAO3C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU,QAAO,IAwB7B,CAAC;AAoEF;;;;GAIG;AACH,MAAM,WAAW,QAAS,SAAQ,IAAI;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC;CAChD;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,aAAc;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC;CAC/C,KAAG,QAuFH,CAAC;AAKF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,MAAM,+mBAGlB,CAAC;AACF,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,MAAM,CAAC;AAE1C,qCAAqC;AACrC,eAAO,MAAM,cAAc,6rBAAiC,CAAC;AAC7D,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,MAAM,CAAC;AAE1D,oCAAoC;AACpC,eAAO,MAAM,SAAS,EAAQ,MAAM,CAAC;AAErC,oCAAoC;AACpC,eAAO,MAAM,SAAS,EAAkC,MAAM,CAAC;AAE/D;;;GAGG;AACH,eAAO,MAAM,cAAc,UAAW,YAAY,KAAG,MACO,CAAC;AAE7D;;;;;GAKG;AACH,eAAO,MAAM,eAAe,UAAW,MAAM,KAAG,OACK,CAAC;AAEtD,8EAA8E;AAC9E,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,KAAK,CAAC,uBAAuB,CAAC,CAAC;AAE5E,gFAAgF;AAChF,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,KAAK,CAAC,iBAAiB,CAAC,CAAC;AAEhE,8EAA8E;AAC9E,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,KAAK,CAAC,qBAAqB,CAAC,CAAC;AAExE;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,UAC9B,eAAe,OACjB,eAAe,KACnB,mBAGF,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,QAAQ,GAAG,eAAe,GAAG,MAAM,CAAC;AAEhD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,gBAAgB,GAAG,eAAe,GAAG,cAAc,CAAC;AAEhE,gFAAgF;AAChF,eAAO,MAAM,2BAA2B,0kFAIvC,CAAC;AACF,MAAM,MAAM,2BAA2B,GACrC,OAAO,2BAA2B,CAAC,MAAM,CAAC;AAE5C;;;GAGG;AACH,eAAO,MAAM,sBAAsB,yvFAGlC,CAAC;AACF,MAAM,MAAM,sBAAsB,GAAG,OAAO,sBAAsB,CAAC,MAAM,CAAC;AAE1E;;;GAGG;AACH,eAAO,MAAM,sBAAsB,yvFAGlC,CAAC;AACF,MAAM,MAAM,sBAAsB,GAAG,OAAO,sBAAsB,CAAC,MAAM,CAAC;AAE1E;;;GAGG;AACH,eAAO,MAAM,oBAAoB,yyFAGhC,CAAC;AACF,MAAM,MAAM,oBAAoB,GAAG,OAAO,oBAAoB,CAAC,MAAM,CAAC;AAEtE;;;GAGG;AACH,eAAO,MAAM,mBAAmB,6jCAG/B,CAAC;AACF,MAAM,MAAM,mBAAmB,GAAG,OAAO,mBAAmB,CAAC,MAAM,CAAC;AAEpE;;;GAGG;AACH,eAAO,MAAM,oBAAoB,2gGAGhC,CAAC;AACF,MAAM,MAAM,oBAAoB,GAAG,OAAO,oBAAoB,CAAC,MAAM,CAAC;AAEtE;;;GAGG;AACH,eAAO,MAAM,oBAAoB,yiGAGhC,CAAC;AACF,MAAM,MAAM,oBAAoB,GAAG,OAAO,oBAAoB,CAAC,MAAM,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,eAAe,ggkBAQ3B,CAAC;AACF,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC,MAAM,CAAC;AAE5D;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,eAAe,GAAG,cAAc,GACzC,cAAc,CAAC;AAElB,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAAC;AAwB7D;;;;GAIG;AACH,eAAO,MAAM,OAAO,EAAS,MAAM,CAAC;AAEpC;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAQ,MAAM,CAAC;AAEpC;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,EAAS,MAAM,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,sBAAsB,WAAY,MAAM,KAAG,MAuBvD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,uBAAuB,WAAY,MAAM,KAAG,MAOxD,CAAC"}
+{"version":3,"file":"Time.d.ts","sourceRoot":"","sources":["../../src/Time.ts"],"names":[],"mappings":"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"}

package/dist/src/Time.js

@@ -4,6 +4,7 @@
  * @module
  */
 import { assert } from "./Assert.js";
+import { exhaustiveCheck } from "./Function.js";
 import { brand, Digit, Digit1To23, Digit1To51, Digit1To59, Digit1To6, Digit1To9, Digit1To99, lessThan, NonNegativeInt, positive, templateLiteral, union, } from "./Type.js";
 /**
  * Creates a {@link Time} using `Date.now()`, `performance`, and
@@ -116,6 +117,10 @@ export const testCreateTime = (options) => {
             case "microtask":
                 queueMicrotask(incrementNow);
                 break;
+            case undefined:
+                break;
+            default:
+                exhaustiveCheck(autoIncrement);
         }
         return result;
     };
@@ -305,8 +310,10 @@ const durationUnits = {
     m: 60000,
     h: 3600000,
     d: 86400000,
-    w: 604800000, // 7 days
-    y: 31536000000, // 365 days
+    // 7 days
+    w: 604800000,
+    // 365 days
+    y: 31536000000,
 };
 /**
  * Frame budget at 60fps (16ms).

package/dist/src/Type.d.ts

@@ -1,5 +1,5 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-import type { AtLeastTwoReadonlyArray, NonEmptyReadonlyArray } from "./Array.ts";
+import { type AtLeastTwoReadonlyArray, type NonEmptyReadonlyArray } from "./Array.ts";
 import type { Brand } from "./Brand.ts";
 import type { RandomBytesDep } from "./Crypto.ts";
 import { type Thunk } from "./Function.ts";
@@ -779,7 +779,52 @@ export declare function transform<Name extends TypeName, ParentType extends Conc
     readonly from: (value: ParentType["Output"]) => Result<OutputType["Input"], never>;
     readonly to: (value: CanonicalInputOf<OutputType>) => ToOutput;
 }): TransformType<ParentType, OutputType, Name, never, ToOutput>;
-/** Creates a fallible transformed Type with its own error formatter. */
+/**
+ * Creates a fallible transformed Type with its own error formatter.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   Boolean,
+ *   String,
+ *   err,
+ *   ok,
+ *   transform,
+ *   type Result,
+ *   type TypeError,
+ * } from "@evolu/common";
+ *
+ * interface BooleanFromStringError extends TypeError<"BooleanFromString"> {
+ *   readonly value: string;
+ * }
+ *
+ * const BooleanFromString = transform(
+ *   "BooleanFromString",
+ *   String,
+ *   Boolean,
+ *   {
+ *     from: (value): Result<boolean, BooleanFromStringError> =>
+ *       value === "true"
+ *         ? ok(true)
+ *         : value === "false"
+ *           ? ok(false)
+ *           : err({ type: "BooleanFromString", value }),
+ *     to: (value) => (value ? "true" : "false"),
+ *   },
+ *   () => 'Expected "true" or "false".',
+ * );
+ *
+ * expectOk(BooleanFromString.fromUnknown("true"), true);
+ * expect(BooleanFromString.to(false)).toBe("false");
+ *
+ * const invalid = BooleanFromString.fromUnknown("yes");
+ * expectErr(invalid, { type: "BooleanFromString", value: "yes" });
+ * expect(BooleanFromString.formatError(invalid.error)).toBe(
+ *   'Expected "true" or "false".',
+ * );
+ * ```
+ */
 export declare function transform<Name extends TypeName, ParentType extends ConcreteTypeNode, OutputType extends ConcreteTypeNode, ToOutput extends ParentType["Output"], FromError extends {
     readonly type: Name;
     readonly outputError?: never;
@@ -1073,7 +1118,30 @@ interface ObjectTagOutputByName {
  * @group Base
  */
 export declare function objectTag<Name extends keyof ObjectTagOutputByName>(name: ValidateConcreteTypeName<Name>): Type<Name, ObjectTagOutputByName[Name], ObjectTagOutputByName[Name], ObjectTagError<Name>, null, ObjectTagError<Name>, never, ObjectTagOutputByName[Name]>;
-/** Creates an object-tag Type by refining an existing object Type. */
+/**
+ * Creates an object-tag Type by refining an existing object Type.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { instanceOf, objectTag } from "@evolu/common";
+ *
+ * class TaggedValue {
+ *   readonly [globalThis.Symbol.toStringTag] = "TaggedValue";
+ * }
+ *
+ * const TaggedValueType = objectTag(
+ *   "TaggedValue",
+ *   instanceOf(TaggedValue),
+ * );
+ * const value = new TaggedValue();
+ * const result = TaggedValueType.fromUnknown(value);
+ *
+ * expectOk(result, value);
+ * expectTypeOf(result.value).toExtend<TaggedValue>();
+ * expect(TaggedValueType.expected).toBe("TaggedValue");
+ * ```
+ */
 export declare function objectTag<Name extends TypeName, OutputType extends ConcreteTypeNode & {
     readonly Output: object;
 }>(name: ValidateConcreteTypeName<Name>, outputType: ValidateOutput<OutputType> & ([ChildTypeNameValidationError<"ObjectTag", OutputType>] extends [never] ? unknown : ChildTypeNameValidationError<"ObjectTag", OutputType>)): ObjectTagType<Name, OutputType>;
@@ -4130,7 +4198,32 @@ type ObjectProperty = ObjectProps[string];
  * @group Objects
  */
 export declare function object<const Props extends ObjectProps>(props: Props, ...validation: [ObjectValidationError<Props>] extends [never] ? [] : [ValidationFailure<ObjectValidationError<Props>>]): StrictObjectType<Props>;
-/** Creates an Object Type with additional record properties. */
+/**
+ * Creates an Object Type with additional record properties.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { String, object, record } from "@evolu/common";
+ *
+ * const RequestHeaders = object(
+ *   { authorization: String },
+ *   record(String, String),
+ * );
+ * const result = RequestHeaders.fromUnknown({
+ *   authorization: "Bearer token",
+ *   "x-request-id": "request-1",
+ * });
+ *
+ * expectOk(result, {
+ *   authorization: "Bearer token",
+ *   "x-request-id": "request-1",
+ * });
+ * expectTypeOf(result.value["x-request-id"]).toEqualTypeOf<
+ *   string | undefined
+ * >();
+ * ```
+ */
 export declare function object<const Props extends ObjectProps, const Rest extends RecordTypeNode & ConcreteTypeNode>(props: Props, record: Rest, ...validation: [
     ObjectValidationError<Props> | ObjectRecordValidationError<Props, Rest>
 ] extends [never] ? [] : [
@@ -4507,6 +4600,32 @@ export type UnknownResult = typeof UnknownResult.Output;
  * ### Example
  *
  * ```ts
+ * import { String, discriminatedUnion, typed } from "@evolu/common";
+ *
+ * const Loading = typed("Loading");
+ * const Loaded = typed("Loaded", { value: String });
+ * const State = discriminatedUnion(Loading, Loaded);
+ *
+ * expectOk(State.fromUnknown({ type: "Loading" }), { type: "Loading" });
+ * expectOk(State.fromUnknown({ type: "Loaded", value: "Evolu" }), {
+ *   type: "Loaded",
+ *   value: "Evolu",
+ * });
+ * expect(Loading.is({ type: "Loading", progress: 1 })).toBe(false);
+ * expectTypeOf<typeof Loading.Output>().toExtend<{
+ *   readonly type: "Loading";
+ * }>();
+ * ```
+ *
+ * @group Discriminated unions
+ */
+export declare function typed<const Tag extends TypeName>(tag: ValidateTypedTag<Tag>): TypedType<Tag>;
+/**
+ * Creates a Tagged Object Type with declared properties.
+ *
+ * ### Example
+ *
+ * ```ts
  * import { String, typed } from "@evolu/common";
  *
  * const Pending = typed("Pending", {
@@ -4518,13 +4637,31 @@ export type UnknownResult = typeof UnknownResult.Output;
  *   label: "Waiting",
  * });
  * ```
- *
- * @group Discriminated unions
  */
-export declare function typed<const Tag extends TypeName>(tag: ValidateTypedTag<Tag>): TypedType<Tag>;
-/** Creates a Tagged Object Type with declared properties. */
 export declare function typed<const Tag extends TypeName, const Props extends ObjectProps>(tag: ValidateTypedTag<Tag>, props: Props, ...validation: [TypedValidationError<Props>] extends [never] ? [] : [ValidationFailure<TypedValidationError<Props>>]): TypedType<Tag, Props>;
-/** Creates a Tagged Object Type with additional record properties. */
+/**
+ * Creates a Tagged Object Type with additional record properties.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { String, record, typed } from "@evolu/common";
+ *
+ * const Open = typed("Open", { label: String }, record(String, String));
+ * const result = Open.fromUnknown({
+ *   type: "Open",
+ *   label: "Ready",
+ *   note: "Connected",
+ * });
+ *
+ * expectOk(result, {
+ *   type: "Open",
+ *   label: "Ready",
+ *   note: "Connected",
+ * });
+ * expectTypeOf(result.value.note).toEqualTypeOf<string | undefined>();
+ * ```
+ */
 export declare function typed<const Tag extends TypeName, const Props extends ObjectProps, const Rest extends RecordTypeNode & ConcreteTypeNode>(tag: ValidateTypedTag<Tag>, props: Props, record: Rest, ...validation: [
     TypedValidationError<Props> | ObjectRecordValidationError<TypedProps<Tag, Props>, Rest>
 ] extends [never] ? [] : [