@evolu/common 8.0.0-next.4 → 8.0.0

package/src/local-first/Evolu.ts

@@ -9,46 +9,43 @@ import {
   isNonEmptyArray,
   mapArray,
   type NonEmptyReadonlyArray,
-} from "../Array.js";
-import {
-  assert,
-  assertNonEmptyReadonlyArray,
-  assertNotDisposed,
-} from "../Assert.js";
-import { createCallbacks } from "../Callbacks.js";
-import type { ConsoleDep } from "../Console.js";
-import { createConsole } from "../Console.js";
-import { createUnknownError } from "../Error.js";
-import { exhaustiveCheck, todo } from "../Function.js";
+} from "../Array.ts";
+import { assert, assertNonEmptyReadonlyArray } from "../Assert.ts";
+import { createCallbacks } from "../Callbacks.ts";
+import type { ConsoleDep } from "../Console.ts";
+import { createConsole } from "../Console.ts";
+import { createUnknownError } from "../Error.ts";
+import { disposable, exhaustiveCheck, todo } from "../Function.ts";
 import {
   acquireLeaderLock,
   acquireLeaderLockCallback,
   type LockManagerDep,
-} from "../LockManager.js";
-import { createMicrotaskBatch } from "../Microtask.js";
-import type { FlushSyncDep, ReloadAppDep } from "../Platform.js";
-import { createRefCountByKey } from "../RefCount.js";
-import { err, ok } from "../Result.js";
-import { isNonEmptySet } from "../Set.js";
-import { SqliteBoolean, sqliteBooleanToBoolean } from "../Sqlite.js";
-import type { Listener, ReadonlyStore, Unsubscribe } from "../Store.js";
-import { createStore } from "../Store.js";
-import { type createRun, type Task } from "../Task.js";
-import type { Id, TypeError } from "../Type.js";
+} from "../LockManager.ts";
+import { createMicrotaskBatch } from "../Microtask.ts";
+import type { FlushSyncDep, ReloadAppDep } from "../Platform.ts";
+import { createRefCountByKey } from "../RefCount.ts";
+import { err, ok } from "../Result.ts";
+import { isNonEmptySet } from "../Set.ts";
+import { SqliteBoolean, sqliteBooleanToBoolean } from "../Sqlite.ts";
+import type { Listener, ReadonlyStore, Unsubscribe } from "../Store.ts";
+import { createStore } from "../Store.ts";
+import type { Task } from "../Task.ts";
 import {
   brand,
   createId,
   createIdFromString,
+  type ExtractTyped,
+  type Id,
   Name,
+  type TypeError,
   UrlSafeString,
-} from "../Type.js";
-import type { ExtractType } from "../Types.js";
+} from "../Type.ts";
 import type {
   CreateBroadcastChannelDep,
   CreateMessageChannelDep,
-} from "../Worker.js";
-import type { CreateDbWorkerDep } from "./Db.js";
-import type { EvoluError } from "./Error.js";
+} from "../Worker.ts";
+import type { CreateDbWorkerDep } from "./Db.ts";
+import type { EvoluError } from "./Error.ts";
 import type {
   AppOwner,
   Owner,
@@ -56,8 +53,8 @@ import type {
   OwnerTransport,
   ReadonlyOwner,
   SyncOwner,
-} from "./Owner.js";
-import { createOwnerWebSocketTransport } from "./Owner.js";
+} from "./Owner.ts";
+import { createOwnerWebSocketTransport } from "./Owner.ts";
 import type {
   Queries,
   QueriesToQueryRowsPromises,
@@ -65,25 +62,25 @@ import type {
   QueryRows,
   Row,
   RowsByQueryMap,
-} from "./Query.js";
-import { applyPatches } from "./Query.js";
+} from "./Query.ts";
+import { applyPatches } from "./Query.ts";
 import type {
   EvoluSchema,
   IndexesConfig,
   Mutation,
   MutationChange,
   ValidateSchema,
-} from "./Schema.js";
-import { evoluSchemaToSqliteSchema } from "./Schema.js";
+} from "./Schema.ts";
+import { evoluSchemaToSqliteSchema } from "./Schema.ts";
 import type {
   ConsoleEntryOrError,
   EvoluInput,
   EvoluOutput,
   SharedWorkerDep,
-} from "./Shared.js";
-import { consoleEntryOrErrorBroadcastChannelName } from "./Shared.js";
-import { DbChange } from "./Storage.js";
-import type { Timestamp } from "./Timestamp.js";
+} from "./Shared.ts";
+import { consoleEntryOrErrorBroadcastChannelName } from "./Shared.ts";
+import { DbChange } from "./Storage.ts";
+import type { Timestamp } from "./Timestamp.ts";
 
 export interface EvoluConfig {
   /**
@@ -100,7 +97,10 @@ export interface EvoluConfig {
    * ### Example
    *
    * ```ts
-   * // appName: AppName.orThrow("MyApp")
+   * import { AppName } from "@evolu/common";
+   *
+   * const appName = AppName.orThrow("MyApp");
+   * expect(appName).toBe("MyApp");
    * ```
    */
   readonly appName: AppName;
@@ -108,20 +108,20 @@ export interface EvoluConfig {
   /**
    * {@link AppOwner} used to create this {@link Evolu} instance.
    *
-   * Exposed as {@link Evolu.appOwner}. If `appOwner` is not passed, Evolu
-   * creates one.
+   * Exposed as {@link Evolu.appOwner}. Create an AppOwner before the first run,
+   * or restore one from secure storage before creating Evolu.
    *
    * AppOwner controls access to the encrypted local SQLite database. If its
    * secret material (Owner secret / Mnemonic) is not stored safely, data
    * written by that instance is permanently inaccessible.
    *
-   * Best onboarding UX is accountless first use: let users try a ready-to-use
-   * app, then prompt backup of `evolu.appOwner`.
+   * Best onboarding UX is accountless first use: create an AppOwner, let users
+   * try a ready-to-use app, then prompt backup of `evolu.appOwner`.
    *
    * Recommended usage:
    *
-   * - Omit `appOwner` for first run, then persist `evolu.appOwner` after user
-   *   activity and guide the user to back it up.
+   * - Create and persist an `appOwner` for first run, then guide the user to back
+   *   it up after user activity.
    * - Pass `appOwner` restored from secure storage (for example, Expo
    *   SecureStore, WebAuthn-backed storage, or app-managed account recovery
    *   flow).
@@ -158,33 +158,51 @@ export interface EvoluConfig {
    *
    * The default value is:
    *
-   * `{ type: "WebSocket", url: "wss://free.evoluhq.com" }`.
+   * `[{ type: "WebSocket", url: "wss://free.evoluhq.com" }]`.
    *
    * ### Example
    *
    * ```ts
-   * // Single WebSocket relay
-   * transports: [{ type: "WebSocket", url: "wss://relay1.example.com" }];
+   * import {
+   *   createAppOwner,
+   *   createOwnerWebSocketTransport,
+   *   createOwnerSecret,
+   *   createRandomBytes,
+   *   type OwnerTransport,
+   * } from "@evolu/common";
+   *
+   * // Create once, persist the mnemonic securely, and restore it on later runs.
+   * const appOwner = createAppOwner(
+   *   createOwnerSecret({ randomBytes: createRandomBytes() }),
+   * );
+   *
+   * // Use one relay.
+   * const singleRelay = [
+   *   { type: "WebSocket", url: "wss://relay1.example.com" },
+   * ] satisfies ReadonlyArray<OwnerTransport>;
    *
-   * // Multiple WebSocket relays for redundancy
-   * transports: [
+   * // Use independent relays for redundancy.
+   * const redundantRelays = [
    *   { type: "WebSocket", url: "wss://relay1.example.com" },
    *   { type: "WebSocket", url: "wss://relay2.example.com" },
-   *   { type: "WebSocket", url: "wss://relay3.example.com" },
-   * ];
+   * ] satisfies ReadonlyArray<OwnerTransport>;
    *
-   * // Local-only instance (no sync) - useful for device settings or when relay
-   * // URL will be provided later (e.g., after authentication), allowing users
-   * // to work offline before the app connects
-   * transports: [];
+   * // Start local-only before authentication. After authentication, pass an
+   * // owner-scoped transport to evolu.useOwner.
+   * const localOnlyBeforeAuthentication =
+   *   [] satisfies ReadonlyArray<OwnerTransport>;
    *
-   * // Using createOwnerWebSocketTransport helper for relay authentication
-   * transports: [
+   * // Include the OwnerId when the relay authenticates owners.
+   * const authenticatedRelay = [
    *   createOwnerWebSocketTransport({
-   *     url: "ws://localhost:4000",
-   *     ownerId,
+   *     url: "wss://relay.example.com",
+   *     ownerId: appOwner.id,
    *   }),
    * ];
+   *
+   * expect(authenticatedRelay[0]?.url).toBe(
+   *   `wss://relay.example.com?ownerId=${appOwner.id}`,
+   * );
    * ```
    */
   readonly transports?: ReadonlyArray<OwnerTransport>;
@@ -211,7 +229,28 @@ export interface EvoluConfig {
    * ### Example
    *
    * ```ts
-   * const evolu = createEvolu(evoluReactDeps)(Schema, {
+   * import {
+   *   AppName,
+   *   createAppOwner,
+   *   createEvolu,
+   *   createOwnerSecret,
+   *   createRandomBytes,
+   *   id,
+   * } from "@evolu/common";
+   *
+   * const Schema = {
+   *   todo: { id: id("Todo") },
+   *   todoCategory: { id: id("TodoCategory") },
+   * };
+   * // Create once, persist the mnemonic securely, and restore it on later runs.
+   * const appOwner = createAppOwner(
+   *   createOwnerSecret({ randomBytes: createRandomBytes() }),
+   * );
+   *
+   * const createTodoEvolu = createEvolu(Schema, {
+   *   appName: AppName.orThrow("IndexedTodos"),
+   *   appOwner,
+   *   transports: [],
    *   indexes: (create) => [
    *     create("todoCreatedAt").on("todo").column("createdAt"),
    *     create("todoCategoryCreatedAt")
@@ -219,6 +258,8 @@ export interface EvoluConfig {
    *       .column("createdAt"),
    *   ],
    * });
+   *
+   * expect(createTodoEvolu).toBeTypeOf("function");
    * ```
    */
   readonly indexes?: IndexesConfig;
@@ -250,13 +291,20 @@ export interface EvoluConfig {
  * Uses the same safe alphabet as {@link UrlSafeString} (letters, digits, `-`,
  * `_`) and must be between 1 and 41 characters.
  */
-export const AppName = /*#__PURE__*/ brand("AppName", UrlSafeString, (value) =>
-  value.length >= 1 && value.length <= 41
-    ? ok(value)
-    : err<AppNameError>({ type: "AppName", value }),
+export const AppName = /*#__PURE__*/ brand(
+  "AppName",
+  UrlSafeString,
+  (value) =>
+    value.length >= 1 && value.length <= 41
+      ? ok()
+      : err<AppNameError>({ type: "AppName", value }),
+  (error) =>
+    `The value ${JSON.stringify(error.value)} is not between 1 and 41 characters.`,
 );
-export type AppName = typeof AppName.Type;
-export interface AppNameError extends TypeError<"AppName"> {}
+export type AppName = typeof AppName.Output;
+export interface AppNameError extends TypeError<"AppName"> {
+  readonly value: UrlSafeString;
+}
 
 export const testAppName = /*#__PURE__*/ AppName.orThrow("AppName");
 
@@ -285,19 +333,45 @@ export interface Evolu<
    * every row has a globally unique, conflict-free identifier without
    * coordination.
    *
+   * Pass `onComplete` when follow-up work must wait until the mutation and its
+   * query patches have been applied.
+   *
    * ### Example
    *
    * ```ts
-   * const { id } = evolu.insert("todo", {
-   *   title: NonEmptyString100.orThrow("Learn Evolu"),
-   * });
-   *
-   * // With onComplete callback
-   * evolu.insert(
-   *   "todo",
-   *   { title: NonEmptyString100.orThrow("Another todo") },
-   *   { onComplete: () => console.log("Insert completed") },
-   * );
+   * import {
+   *   id,
+   *   NonEmptyTrimmedString100,
+   *   type Evolu,
+   * } from "@evolu/common";
+   *
+   * const TodoId = id("Todo");
+   * type TodoId = typeof TodoId.Output;
+   * const Schema = {
+   *   todo: { id: TodoId, title: NonEmptyTrimmedString100 },
+   * };
+   *
+   * const insertTodo = (evolu: Evolu<typeof Schema>) =>
+   *   evolu.insert("todo", {
+   *     title: NonEmptyTrimmedString100.orThrow("Learn Evolu"),
+   *   }).id;
+   *
+   * const insertTodoAndNotify = (
+   *   evolu: Evolu<typeof Schema>,
+   *   onComplete: () => void,
+   * ) =>
+   *   evolu.insert(
+   *     "todo",
+   *     { title: NonEmptyTrimmedString100.orThrow("Another todo") },
+   *     { onComplete },
+   *   ).id;
+   *
+   * expectTypeOf<
+   *   [
+   *     ReturnType<typeof insertTodo>,
+   *     ReturnType<typeof insertTodoAndNotify>,
+   *   ]
+   * >().toEqualTypeOf<[TodoId, TodoId]>();
    * ```
    *
    * @see {@link Mutation}
@@ -312,13 +386,31 @@ export interface Evolu<
    * ### Example
    *
    * ```ts
-   * const { id } = evolu.update("todo", {
-   *   id: todoId,
-   *   title: NonEmptyString100.orThrow("Updated title"),
-   * });
-   *
-   * // Soft delete
-   * evolu.update("todo", { id: todoId, isDeleted: sqliteTrue });
+   * import {
+   *   id,
+   *   NonEmptyTrimmedString100,
+   *   sqliteTrue,
+   *   type Evolu,
+   * } from "@evolu/common";
+   *
+   * const TodoId = id("Todo");
+   * type TodoId = typeof TodoId.Output;
+   * const Schema = {
+   *   todo: { id: TodoId, title: NonEmptyTrimmedString100 },
+   * };
+   *
+   * const renameTodo = (evolu: Evolu<typeof Schema>, todoId: TodoId) =>
+   *   evolu.update("todo", {
+   *     id: todoId,
+   *     title: NonEmptyTrimmedString100.orThrow("Updated title"),
+   *   }).id;
+   *
+   * const softDeleteTodo = (evolu: Evolu<typeof Schema>, todoId: TodoId) =>
+   *   evolu.update("todo", { id: todoId, isDeleted: sqliteTrue }).id;
+   *
+   * expectTypeOf<
+   *   [ReturnType<typeof renameTodo>, ReturnType<typeof softDeleteTodo>]
+   * >().toEqualTypeOf<[TodoId, TodoId]>();
    * ```
    *
    * @see {@link Mutation}
@@ -340,11 +432,26 @@ export interface Evolu<
    * ### Example
    *
    * ```ts
-   * const stableId = createIdFromString("my-todo-1");
-   * const { id } = evolu.upsert("todo", {
-   *   id: stableId,
-   *   title: NonEmptyString100.orThrow("Learn Evolu"),
-   * });
+   * import {
+   *   createIdFromString,
+   *   id,
+   *   NonEmptyTrimmedString100,
+   *   type Evolu,
+   * } from "@evolu/common";
+   *
+   * const TodoId = id("Todo");
+   * type TodoId = typeof TodoId.Output;
+   * const Schema = {
+   *   todo: { id: TodoId, title: NonEmptyTrimmedString100 },
+   * };
+   * const stableId = TodoId.orThrow(createIdFromString("my-todo-1"));
+   * const upsertTodo = (evolu: Evolu<typeof Schema>) =>
+   *   evolu.upsert("todo", {
+   *     id: stableId,
+   *     title: NonEmptyTrimmedString100.orThrow("Learn Evolu"),
+   *   }).id;
+   *
+   * expectTypeOf(upsertTodo).returns.toEqualTypeOf<TodoId>();
    * ```
    *
    * @see {@link Mutation}
@@ -369,13 +476,29 @@ export interface Evolu<
    * ### Example
    *
    * ```ts
+   * import {
+   *   createQueryBuilder,
+   *   id,
+   *   NonEmptyTrimmedString100,
+   *   type Evolu,
+   *   type QueryRows,
+   * } from "@evolu/common";
+   *
+   * const Schema = {
+   *   todo: { id: id("Todo"), title: NonEmptyTrimmedString100 },
+   * };
    * const createQuery = createQueryBuilder(Schema);
    * const allTodos = createQuery((db) =>
    *   db.selectFrom("todo").selectAll(),
    * );
-   * evolu.loadQuery(allTodos).then((rows) => {
-   *   console.log(rows);
-   * });
+   * const loadTodos = async (evolu: Evolu<typeof Schema>) => {
+   *   const rows = await evolu.loadQuery(allTodos);
+   *   return rows;
+   * };
+   *
+   * expectTypeOf(loadTodos).returns.toEqualTypeOf<
+   *   Promise<QueryRows<typeof allTodos.Row>>
+   * >();
    * ```
    */
   readonly loadQuery: <R extends Row>(
@@ -383,14 +506,47 @@ export interface Evolu<
   ) => Promise<QueryRows<R>>;
 
   /**
-   * Load an array of {@link Query} queries and return an array of
+   * Load an array of {@link Query} values and return an array of
    * {@link QueryRows} promises. It's like `queries.map(loadQuery)` but with
    * proper types for returned promises.
    *
    * ### Example
    *
    * ```ts
-   * evolu.loadQueries([allTodos, todoById(1)]);
+   * import {
+   *   createIdFromString,
+   *   createQueryBuilder,
+   *   id,
+   *   NonEmptyTrimmedString100,
+   *   type Evolu,
+   *   type QueryRows,
+   * } from "@evolu/common";
+   *
+   * const TodoId = id("Todo");
+   * type TodoId = typeof TodoId.Output;
+   * const Schema = {
+   *   todo: { id: TodoId, title: NonEmptyTrimmedString100 },
+   * };
+   * const createQuery = createQueryBuilder(Schema);
+   * const allTodos = createQuery((db) =>
+   *   db.selectFrom("todo").select(["id", "title"]),
+   * );
+   * const todoById = (todoId: TodoId) =>
+   *   createQuery((db) =>
+   *     db.selectFrom("todo").select("title").where("id", "=", todoId),
+   *   );
+   * const firstTodo = todoById(
+   *   TodoId.orThrow(createIdFromString("first-todo")),
+   * );
+   * const loadTodoQueries = (evolu: Evolu<typeof Schema>) =>
+   *   evolu.loadQueries([allTodos, firstTodo]);
+   *
+   * expectTypeOf(loadTodoQueries).returns.toEqualTypeOf<
+   *   [
+   *     Promise<QueryRows<typeof allTodos.Row>>,
+   *     Promise<QueryRows<typeof firstTodo.Row>>,
+   *   ]
+   * >();
    * ```
    */
   readonly loadQueries: <Q extends Queries<S>>(
@@ -403,9 +559,31 @@ export interface Evolu<
    * ### Example
    *
    * ```ts
-   * const unsubscribe = evolu.subscribeQuery(allTodos)(() => {
-   *   const rows = evolu.getQueryRows(allTodos);
-   * });
+   * import {
+   *   createQueryBuilder,
+   *   id,
+   *   NonEmptyTrimmedString100,
+   *   type Evolu,
+   *   type QueryRows,
+   *   type Unsubscribe,
+   * } from "@evolu/common";
+   *
+   * const Schema = {
+   *   todo: { id: id("Todo"), title: NonEmptyTrimmedString100 },
+   * };
+   * const createQuery = createQueryBuilder(Schema);
+   * const allTodos = createQuery((db) =>
+   *   db.selectFrom("todo").select("title"),
+   * );
+   * const subscribeToTodos = (
+   *   evolu: Evolu<typeof Schema>,
+   *   onRows: (rows: QueryRows<typeof allTodos.Row>) => void,
+   * ) =>
+   *   evolu.subscribeQuery(allTodos)(() => {
+   *     onRows(evolu.getQueryRows(allTodos));
+   *   });
+   *
+   * expectTypeOf(subscribeToTodos).returns.toEqualTypeOf<Unsubscribe>();
    * ```
    */
   readonly subscribeQuery: (
@@ -418,9 +596,27 @@ export interface Evolu<
    * ### Example
    *
    * ```ts
-   * const unsubscribe = evolu.subscribeQuery(allTodos)(() => {
-   *   const rows = evolu.getQueryRows(allTodos);
-   * });
+   * import {
+   *   createQueryBuilder,
+   *   id,
+   *   NonEmptyTrimmedString100,
+   *   type Evolu,
+   *   type QueryRows,
+   * } from "@evolu/common";
+   *
+   * const Schema = {
+   *   todo: { id: id("Todo"), title: NonEmptyTrimmedString100 },
+   * };
+   * const createQuery = createQueryBuilder(Schema);
+   * const allTodos = createQuery((db) =>
+   *   db.selectFrom("todo").select("title"),
+   * );
+   * const getTodos = (evolu: Evolu<typeof Schema>) =>
+   *   evolu.getQueryRows(allTodos);
+   *
+   * expectTypeOf(getTodos).returns.toEqualTypeOf<
+   *   QueryRows<typeof allTodos.Row>
+   * >();
    * ```
    */
   readonly getQueryRows: <R extends Row>(query: Query<S, R>) => QueryRows<R>;
@@ -452,6 +648,8 @@ export interface Evolu<
    *
    * All instances identified by {@link Evolu.name} will be self-disposed. Use
    * {@link EvoluConfig.onDatabaseDeleted} to update app UI when that happens.
+   *
+   * Currently not implemented.
    */
   readonly deleteDatabase: () => void;
 
@@ -463,6 +661,8 @@ export interface Evolu<
    *
    * It also stops using that owner across all tabs and instances. Use
    * {@link EvoluConfig.onOwnerDeleted} to update app UI when that happens.
+   *
+   * Currently not implemented.
    */
   readonly deleteOwner: (owner: Owner) => void;
 
@@ -482,20 +682,51 @@ export interface Evolu<
    * ### Example
    *
    * ```ts
-   * // Use an Owner (starts syncing).
-   * const unuseOwner = evolu.useOwner(shardOwner, [
-   *   createOwnerWebSocketTransport({
-   *     url: "ws://localhost:4000",
-   *     ownerId: shardOwner.id,
-   *   }),
-   * ]);
-   *
-   * // Later, stop using the Owner.
-   * unuseOwner();
-   *
-   * // Bulk operations.
-   * const unuseOwners = owners.map(evolu.useOwner);
-   * // Later: for (const unuse of unuseOwners) unuse();
+   * import {
+   *   createAppOwner,
+   *   createOwnerWebSocketTransport,
+   *   createOwnerSecret,
+   *   createRandomBytes,
+   *   deriveShardOwner,
+   *   type Evolu,
+   *   type ReadonlyOwner,
+   *   type UnuseOwner,
+   * } from "@evolu/common";
+   *
+   * // Create once, persist the mnemonic securely, and restore it on later runs.
+   * const appOwner = createAppOwner(
+   *   createOwnerSecret({ randomBytes: createRandomBytes() }),
+   * );
+   * const shardOwner = deriveShardOwner(appOwner, ["todos", 1]);
+   * const shardTransport = createOwnerWebSocketTransport({
+   *   url: "wss://relay.example.com",
+   *   ownerId: shardOwner.id,
+   * });
+   * const useShardOwner = (evolu: Evolu): UnuseOwner =>
+   *   evolu.useOwner(shardOwner, [shardTransport]);
+   *
+   * const useOwners = (
+   *   evolu: Evolu,
+   *   owners: ReadonlyArray<ReadonlyOwner>,
+   * ): UnuseOwner => {
+   *   const unuseOwners = owners.map((owner) =>
+   *     evolu.useOwner(owner, [
+   *       createOwnerWebSocketTransport({
+   *         url: "wss://relay.example.com",
+   *         ownerId: owner.id,
+   *       }),
+   *     ]),
+   *   );
+   *   return () => {
+   *     for (const unuse of unuseOwners) unuse();
+   *   };
+   * };
+   *
+   * // Call each returned UnuseOwner once to stop syncing.
+   * expect(shardTransport).toEqual({
+   *   type: "WebSocket",
+   *   url: `wss://relay.example.com?ownerId=${shardOwner.id}`,
+   * });
    * ```
    */
   readonly useOwner: (
@@ -512,18 +743,28 @@ export interface EvoluErrorDep {
    * {@link ReadonlyStore} of {@link EvoluError} shared by all {@link Evolu}
    * instances created from the same {@link createEvoluDeps} result.
    *
-   * Subscribe once to show user-facing messages across all instances. Logging
-   * is handled by platform {@link createRun} global error handlers.
+   * Subscribe once to show user-facing error messages across all instances.
    *
    * ### Example
    *
    * ```ts
+   * import { createStore, Millis, type EvoluError } from "@evolu/common";
+   * import type { EvoluErrorDep } from "@evolu/common/local-first";
+   *
+   * // Stand-in for run.deps.evoluError from createEvoluDeps.
+   * using evoluError = createStore<EvoluError | null>(null);
+   * const deps = { evoluError } satisfies EvoluErrorDep;
+   * let displayedMessage = "";
+   * const showMessage = (message: string) => {
+   *   displayedMessage = message;
+   * };
+   *
    * deps.evoluError.subscribe(() => {
    *   const error = deps.evoluError.get();
    *   if (!error) return;
    *
    *   switch (error.type) {
-   *     case "InvalidComputerClock":
+   *     case "TimestampDriftError":
    *       // Show guidance specific to the detected error.
    *       showMessage(
    *         "Your system clock appears incorrect. Please fix it.",
@@ -534,6 +775,15 @@ export interface EvoluErrorDep {
    *       showMessage("Something went wrong. Please try again.");
    *   }
    * });
+   *
+   * deps.evoluError.set({
+   *   type: "TimestampDriftError",
+   *   next: Millis.orThrow(360000),
+   *   now: Millis.orThrow(0),
+   * });
+   * expect(displayedMessage).toBe(
+   *   "Your system clock appears incorrect. Please fix it.",
+   * );
    * ```
    */
   readonly evoluError: ReadonlyStore<EvoluError | null>;
@@ -545,7 +795,10 @@ export interface EvoluErrorDep {
  * Includes platform adapters, the shared {@link EvoluErrorDep.evoluError} store,
  * and disposal for owned resources.
  */
-export type EvoluDeps = EvoluPlatformDeps & EvoluErrorDep & Disposable;
+export type EvoluDeps = EvoluPlatformDeps &
+  ConsoleDep &
+  EvoluErrorDep &
+  Disposable;
 
 /**
  * Platform-specific dependencies required to create {@link EvoluDeps}.
@@ -620,13 +873,14 @@ export const createEvoluDeps = (deps: EvoluPlatformDeps): EvoluDeps => {
     }),
   );
 
-  const disposables = disposer.move();
-
-  return {
-    ...deps,
-    evoluError,
-    [Symbol.dispose]: () => disposables.dispose(),
-  };
+  return disposable<EvoluDeps>(
+    {
+      ...deps,
+      console,
+      evoluError,
+    },
+    disposer,
+  );
 };
 
 /**
@@ -745,52 +999,13 @@ export const createEvolu =
       exportDatabasePending = null;
     });
 
-    const mutateBatch = disposer.use(
-      createMicrotaskBatch<{
-        readonly change: MutationChange;
-        readonly onComplete: (() => void) | undefined;
-      }>((items) => {
-        console.debug("mutateBatch", { changeCount: items.length });
-        releaseUnsubscribedLoadingPromises();
-
-        postMessage({
-          type: "Mutate",
-          changes: mapArray(items, (item) => item.change),
-          onCompleteIds: items.flatMap((item) =>
-            item.onComplete
-              ? [onMutateCompleteCallbacks.register(item.onComplete)]
-              : [],
-          ),
-          subscribedQueries: subscribedQueriesRefCount.keys(),
-        });
-      }),
-    );
-
-    const queryBatch = disposer.use(
-      createMicrotaskBatch<Query>((queries) => {
-        const dedupedQueries = new Set(queries);
-        assert(
-          isNonEmptySet(dedupedQueries),
-          "Expected non-empty query batch.",
-        );
-        console.debug("queryBatch", { queryCount: dedupedQueries.size });
-        postMessage({ type: "Query", queries: dedupedQueries });
-      }),
-    );
-
-    const useOwnerBatch = disposer.use(
-      createMicrotaskBatch<
-        ExtractType<EvoluInput, "UseOwner">["actions"][number]
-      >((actions) => postMessage({ type: "UseOwner", actions })),
-    );
-
     let postMessage: (input: EvoluInput) => void;
 
     // Scope worker/channel wiring and keep only postMessage outside.
     {
       const id = createId<"EvoluInstance">(run.deps);
       const { createMessageChannel, sharedWorker } = run.deps;
-      disposer.use(await run.orThrow(acquireLeaderLock(id)));
+      disposer.use(await run.ok(acquireLeaderLock(id)));
 
       const evoluChannel = disposer.use(
         createMessageChannel<EvoluInput, EvoluOutput>(),
@@ -890,13 +1105,55 @@ export const createEvolu =
       postMessage = evoluChannel.port1.postMessage;
     }
 
+    const mutateBatch = disposer.use(
+      createMicrotaskBatch<{
+        readonly change: MutationChange;
+        readonly onComplete: (() => void) | undefined;
+      }>((items) => {
+        if (disposed) return;
+        console.debug("mutateBatch", { changeCount: items.length });
+        releaseUnsubscribedLoadingPromises();
+
+        postMessage({
+          type: "Mutate",
+          changes: mapArray(items, (item) => item.change),
+          onCompleteIds: items.flatMap((item) =>
+            item.onComplete
+              ? [onMutateCompleteCallbacks.register(item.onComplete)]
+              : [],
+          ),
+          subscribedQueries: subscribedQueriesRefCount.keys(),
+        });
+      }),
+    );
+
+    const queryBatch = disposer.use(
+      createMicrotaskBatch<Query>((queries) => {
+        if (disposed) return;
+        const dedupedQueries = new Set(queries);
+        assert(
+          isNonEmptySet(dedupedQueries),
+          "Expected non-empty query batch.",
+        );
+        console.debug("queryBatch", { queryCount: dedupedQueries.size });
+        postMessage({ type: "Query", queries: dedupedQueries });
+      }),
+    );
+
+    const useOwnerBatch = disposer.use(
+      createMicrotaskBatch<
+        ExtractTyped<EvoluInput, "UseOwner">["actions"][number]
+      >((actions) => {
+        if (disposed) return;
+        postMessage({ type: "UseOwner", actions });
+      }),
+    );
+
     const createMutation =
       <Kind extends "insert" | "update" | "upsert">(
         kind: Kind,
       ): Mutation<S, Kind> =>
       (table, values, options) => {
-        assertNotDisposed(disposables);
-
         const {
           id = createId(run.deps),
           isDeleted,
@@ -929,8 +1186,6 @@ export const createEvolu =
     const loadQuery = <R extends Row>(
       query: Query<S, R>,
     ): Promise<QueryRows<R>> => {
-      assertNotDisposed(disposables);
-
       const loadingPromise = loadingPromisesByQuery.get(query);
       if (loadingPromise) {
         return loadingPromise.promise as Promise<QueryRows<R>>;
@@ -951,19 +1206,13 @@ export const createEvolu =
       return typedPromise as Promise<QueryRows<R>>;
     };
 
-    const getQueryRows = <R extends Row>(query: Query<S, R>): QueryRows<R> => {
-      assertNotDisposed(disposables);
-
-      return (rowsByQueryMapStore.get().get(query) ??
-        emptyArray) as QueryRows<R>;
-    };
+    const getQueryRows = <R extends Row>(query: Query<S, R>): QueryRows<R> =>
+      (rowsByQueryMapStore.get().get(query) ?? emptyArray) as QueryRows<R>;
 
     const useOwner = (
       owner: ReadonlyOwner | Owner,
       ownerTransports?: NonEmptyReadonlyArray<OwnerTransport>,
     ): UnuseOwner => {
-      assertNotDisposed(disposables);
-
       const effectiveTransports = ownerTransports ?? transports;
       assertNonEmptyReadonlyArray(
         effectiveTransports,
@@ -983,7 +1232,7 @@ export const createEvolu =
       let isUsed = true;
 
       return () => {
-        if (disposables.disposed) return;
+        if (disposed) return;
         assert(isUsed, "UnuseOwner can be called only once.");
         isUsed = false;
         useOwnerBatch.push({
@@ -993,91 +1242,87 @@ export const createEvolu =
       };
     };
 
-    const disposables = disposer.move();
+    let disposed = false;
+    disposer.defer(() => {
+      disposed = true;
+      console.info("disposeEvolu");
+    });
 
     if (isNonEmptyArray(transports)) useOwner(appOwner);
 
-    if (run.signal.aborted) {
-      await disposables.disposeAsync();
-    }
-
-    return ok({
-      name,
-      appOwner,
-
-      insert: createMutation("insert"),
-      update: createMutation("update"),
-      upsert: createMutation("upsert"),
-
-      loadQuery,
-      loadQueries: <Q extends Queries<S>>(
-        queries: [...Q],
-      ): [...QueriesToQueryRowsPromises<Q>] =>
-        queries.map((query) => loadQuery(query)) as [
-          ...QueriesToQueryRowsPromises<Q>,
-        ],
-
-      subscribeQuery: (query) => (listener) => {
-        assertNotDisposed(disposables);
+    run.signal.throwIfAborted();
 
-        subscribedQueriesRefCount.increment(query);
-        let isSubscribed = true;
-
-        let previousRows: unknown = null;
-
-        const unsubscribe = rowsByQueryMapStore.subscribe(() => {
-          const rows = getQueryRows(query);
-          if (previousRows === rows) return;
-          previousRows = rows;
-          listener();
-        });
-
-        return () => {
-          assert(
-            isSubscribed,
-            "subscribeQuery unsubscribe can be called only once.",
-          );
-          isSubscribed = false;
+    return ok(
+      disposable<Evolu<S>>(
+        {
+          name,
+          appOwner,
+
+          insert: createMutation("insert"),
+          update: createMutation("update"),
+          upsert: createMutation("upsert"),
+
+          loadQuery,
+          loadQueries: <Q extends Queries<S>>(
+            queries: [...Q],
+          ): [...QueriesToQueryRowsPromises<Q>] =>
+            queries.map((query) => loadQuery(query)) as [
+              ...QueriesToQueryRowsPromises<Q>,
+            ],
+
+          subscribeQuery: (query) => (listener) => {
+            subscribedQueriesRefCount.increment(query);
+            let isSubscribed = true;
+
+            let previousRows: unknown = null;
+
+            const unsubscribe = rowsByQueryMapStore.subscribe(() => {
+              const rows = getQueryRows(query);
+              if (previousRows === rows) return;
+              previousRows = rows;
+              listener();
+            });
 
-          previousRows = null;
-          unsubscribe();
+            return () => {
+              assert(
+                isSubscribed,
+                "subscribeQuery unsubscribe can be called only once.",
+              );
+              isSubscribed = false;
 
-          if (disposables.disposed) return;
+              previousRows = null;
 
-          subscribedQueriesRefCount.decrement(query);
-        };
-      },
-      getQueryRows,
+              if (disposed) return;
 
-      exportDatabase: () => {
-        assertNotDisposed(disposables);
+              unsubscribe();
+              subscribedQueriesRefCount.decrement(query);
+            };
+          },
+          getQueryRows,
 
-        if (!exportDatabasePending) {
-          exportDatabasePending =
-            Promise.withResolvers<Uint8Array<ArrayBuffer>>();
-          postMessage({ type: "Export" });
-        }
-        return exportDatabasePending.promise;
-      },
+          exportDatabase: () => {
+            if (!exportDatabasePending) {
+              exportDatabasePending =
+                Promise.withResolvers<Uint8Array<ArrayBuffer>>();
+              postMessage({ type: "Export" });
+            }
+            return exportDatabasePending.promise;
+          },
 
-      deleteDatabase: () => {
-        assertNotDisposed(disposables);
-        todo();
-      },
+          deleteDatabase: () => {
+            todo();
+          },
 
-      deleteOwner: (owner) => {
-        assertNotDisposed(disposables);
-        void owner;
-        todo();
-      },
+          deleteOwner: (owner) => {
+            void owner;
+            todo();
+          },
 
-      useOwner,
-
-      [Symbol.asyncDispose]: () => {
-        if (!disposables.disposed) console.info("disposeEvolu");
-        return disposables.disposeAsync();
-      },
-    } as Evolu<S>);
+          useOwner,
+        },
+        disposer,
+      ),
+    );
   };
 
 //     case "onReset": {