@evolu/common 7.4.0 → 8.0.0-next.0

package/dist/src/local-first/Evolu.d.ts

@@ -1,19 +1,134 @@
-import { ConsoleDep } from "../Console.js";
-import { RandomBytesDep, SymmetricCryptoDecryptError } from "../Crypto.js";
-import { TransferableError } from "../Error.js";
-import { SqliteError } from "../Sqlite.js";
-import { StoreSubscribe } from "../Store.js";
-import { TimeDep } from "../Time.js";
-import { Mnemonic } from "../Type.js";
-import { CreateDbWorkerDep, DbConfig } from "./Db.js";
-import { AppOwner } from "./Owner.js";
-import { FlushSyncDep, ReloadAppDep } from "./Platform.js";
-import { ProtocolError } from "./Protocol.js";
-import { Queries, QueriesToQueryRowsPromises, Query, QueryRows, Row } from "./Query.js";
-import { CreateQuery, EvoluSchema, IndexesConfig, Mutation, ValidateSchema } from "./Schema.js";
-import { SyncOwner } from "./Sync.js";
-import { TimestampError } from "./Timestamp.js";
-export interface EvoluConfig extends Partial<DbConfig> {
+/**
+ * Local-first platform.
+ *
+ * @module
+ */
+import { type NonEmptyReadonlyArray } from "../Array.js";
+import type { ConsoleDep } from "../Console.js";
+import type { FlushSyncDep, ReloadAppDep } from "../Platform.js";
+import type { Listener, ReadonlyStore, Unsubscribe } from "../Store.js";
+import { type Task } from "../Task.js";
+import type { TypeError } from "../Type.js";
+import { Name } from "../Type.js";
+import type { CreateMessageChannelDep } from "../Worker.js";
+import type { CreateDbWorkerDep } from "./Db.js";
+import type { EvoluError } from "./Error.js";
+import type { AppOwner, Owner, OwnerTransport, ReadonlyOwner } from "./Owner.js";
+import type { Queries, QueriesToQueryRowsPromises, Query, QueryRows, Row } from "./Query.js";
+import type { EvoluSchema, IndexesConfig, Mutation, ValidateSchema } from "./Schema.js";
+import type { SharedWorkerDep } from "./Shared.js";
+export interface EvoluConfig {
+    /**
+     * The app name. Evolu is multitenant - it can run multiple instances
+     * concurrently. The same app can have multiple instances for different
+     * accounts.
+     *
+     * Evolu derives the final instance name from `appName` and `appOwner` in
+     * {@link EvoluConfig}. The derived instance name is used as the SQLite
+     * database filename and as the log prefix. This ensures that each
+     * {@link Owner} gets a separate local database while preserving a readable app
+     * prefix.
+     *
+     * ### Example
+     *
+     * ```ts
+     * // appName: AppName.orThrow("MyApp")
+     * ```
+     */
+    readonly appName: AppName;
+    /**
+     * {@link AppOwner} used to create this {@link Evolu} instance.
+     *
+     * Exposed as {@link Evolu.appOwner}. If `appOwner` is not passed, Evolu
+     * creates one.
+     *
+     * 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`.
+     *
+     * Recommended usage:
+     *
+     * - Omit `appOwner` for first run, then persist `evolu.appOwner` after user
+     *   activity and guide the user to back it up.
+     * - Pass `appOwner` restored from secure storage (for example, Expo
+     *   SecureStore, WebAuthn-backed storage, or app-managed account recovery
+     *   flow).
+     */
+    readonly appOwner: AppOwner;
+    /**
+     * Transport configuration for sync and backup.
+     *
+     * If not specified, Evolu uses the default Evolu relay. Pass one or more
+     * transports to override it with your own relays. Pass an empty array to
+     * disable sync, which is useful when sync should be configured later.
+     *
+     * Empty transports start the instance without sync. In that case,
+     * {@link Evolu.useOwner} must be called with explicit non-empty transports to
+     * enable sync for any Owner, including the AppOwner.
+     *
+     * **Redundancy:** The ideal setup uses at least two completely independent
+     * relays - for example, a home relay and a geographically separate relay.
+     * Data is sent to both relays simultaneously, providing true redundancy
+     * similar to using two independent clouds. This eliminates vendor lock-in and
+     * ensures your app continues working regardless of circumstances - whether
+     * home relay hardware fails or disappears, or a remote relay provider shuts
+     * down.
+     *
+     * Currently supports:
+     *
+     * - WebSocket: Real-time bidirectional communication with relay servers
+     *
+     * Use {@link createOwnerWebSocketTransport} to create WebSocket transport
+     * configurations with proper URL formatting and {@link OwnerId} inclusion. The
+     * {@link OwnerId} in the URL enables relay authentication, allowing relay
+     * servers to control access (e.g., for paid tiers or private instances).
+     *
+     * The default value is:
+     *
+     * `{ type: "WebSocket", url: "wss://free.evoluhq.com" }`.
+     *
+     * ### Example
+     *
+     * ```ts
+     * // Single WebSocket relay
+     * transports: [{ type: "WebSocket", url: "wss://relay1.example.com" }];
+     *
+     * // Multiple WebSocket relays for redundancy
+     * transports: [
+     *   { type: "WebSocket", url: "wss://relay1.example.com" },
+     *   { type: "WebSocket", url: "wss://relay2.example.com" },
+     *   { type: "WebSocket", url: "wss://relay3.example.com" },
+     * ];
+     *
+     * // 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: [];
+     *
+     * // Using createOwnerWebSocketTransport helper for relay authentication
+     * transports: [
+     *   createOwnerWebSocketTransport({
+     *     url: "ws://localhost:4000",
+     *     ownerId,
+     *   }),
+     * ];
+     * ```
+     */
+    readonly transports?: ReadonlyArray<OwnerTransport>;
+    /**
+     * Keep local data only in memory instead of persisting it on this device.
+     * Useful for testing, temporary data, or sensitive data that should not be
+     * recoverable from local storage after the process ends.
+     *
+     * Local data stored in memory is completely destroyed when the process ends.
+     * Sync can still persist data remotely when transports are enabled.
+     *
+     * The default value is: `false`.
+     */
+    readonly memoryOnly?: boolean;
     /**
      * Use the `indexes` option to define SQLite indexes.
      *
@@ -36,75 +151,139 @@ export interface EvoluConfig extends Partial<DbConfig> {
      */
     readonly indexes?: IndexesConfig;
     /**
-     * URL to reload browser tabs after reset or restore.
+     * Called when this instance's local database is deleted.
      *
-     * The default value is `/`.
+     * Apps can use this to update UI immediately because the corresponding
+     * {@link Evolu} instance becomes unusable after local database deletion.
+     */
+    readonly onDatabaseDeleted?: () => void;
+    /**
+     * Called when local data for an {@link Owner} is deleted.
      *
-     * Note: This option will be moved to web platform deps in the next major
-     * version.
+     * Apps can use this to update UI immediately because that owner stops being
+     * used across tabs and instances.
      */
-    readonly reloadUrl?: string;
+    readonly onOwnerDeleted?: (owner: Owner) => void;
+}
+/**
+ * Application name.
+ *
+ * Evolu uses AppName as the base prefix for {@link Evolu.name}. The final
+ * instance name is derived per {@link AppOwner} as
+ * `${appName}-${createIdFromString(appOwner.id)}`.
+ *
+ * Uses the same safe alphabet as {@link UrlSafeString} (letters, digits, `-`,
+ * `_`) and must be between 1 and 41 characters.
+ */
+export declare const AppName: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"String", string, string, import("../Type.js").StringError, string, import("../Type.js").StringError>, "UrlSafeString", import("../Type.js").RegexError<"UrlSafeString">, import("../Type.js").StringError>, "AppName", AppNameError, import("../Type.js").StringError | import("../Type.js").RegexError<"UrlSafeString">>;
+export type AppName = typeof AppName.Type;
+export interface AppNameError extends TypeError<"AppName"> {
 }
-export interface Evolu<S extends EvoluSchema = EvoluSchema> extends Disposable {
+export declare const testAppName: string & import("../Brand.js").Brand<"UrlSafeString"> & import("../Brand.js").Brand<"AppName">;
+/**
+ * Local-first SQL database with typed queries, mutations, and sync.
+ *
+ * TODO: Better docs.
+ */
+export interface Evolu<S extends EvoluSchema = EvoluSchema> extends AsyncDisposable {
     /**
-     * Subscribe to {@link EvoluError} changes.
+     * Evolu instance name is derived from {@link EvoluConfig.appName} and
+     * {@link AppOwner}'s hash.
+     */
+    readonly name: Name;
+    /** {@link AppOwner}. */
+    readonly appOwner: AppOwner;
+    /**
+     * Inserts a row and returns the generated {@link Id}.
+     *
+     * All non-nullable columns are required, nullable columns are optional, and
+     * `id` is omitted because Evolu generates it automatically. This ensures
+     * every row has a globally unique, conflict-free identifier without
+     * coordination.
      *
      * ### Example
      *
      * ```ts
-     * const unsubscribe = evolu.subscribeError(() => {
-     *   const error = evolu.getError();
-     *   console.log(error);
+     * 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") },
+     * );
      * ```
+     *
+     * @see {@link Mutation}
      */
-    readonly subscribeError: StoreSubscribe;
-    /** Get {@link EvoluError}. */
-    readonly getError: () => EvoluError | null;
+    readonly insert: Mutation<S, "insert">;
     /**
-     * Create type-safe SQL {@link Query}.
+     * Updates a row and returns the {@link Id}.
      *
-     * Evolu uses Kysely - the type-safe SQL query builder for TypeScript. See
-     * https://kysely.dev.
+     * Only `id` is required, all other columns are optional.
      *
-     * All this function does is compile the Kysely query and serialize it into a
-     * unique string. Both operations are fast and cheap.
+     * ### Example
      *
-     * For mutations, use {@link Evolu#insert}, {@link Evolu#update}, or
-     * {@link Evolu#upsert}.
+     * ```ts
+     * const { id } = evolu.update("todo", {
+     *   id: todoId,
+     *   title: NonEmptyString100.orThrow("Updated title"),
+     * });
+     *
+     * // Soft delete
+     * evolu.update("todo", { id: todoId, isDeleted: sqliteTrue });
+     * ```
+     *
+     * @see {@link Mutation}
+     */
+    readonly update: Mutation<S, "update">;
+    /**
+     * Upserts a row and returns the {@link Id}.
+     *
+     * Like insert, but requires an `id`. Useful for rows with external ID via
+     * {@link createIdFromString}. All other non-nullable columns are required,
+     * nullable columns are optional.
+     *
+     * `createdAt` and `updatedAt` cannot be set manually. Evolu derives both from
+     * the CRDT {@link Timestamp} — they share the same value, encoded once to
+     * avoid redundancy. Timestamps are always generated by Evolu to preserve CRDT
+     * consistency guarantees.
      *
      * ### Example
      *
      * ```ts
-     * const allTodos = evolu.createQuery((db) =>
-     *   db.selectFrom("todo").selectAll(),
-     * );
-     *
-     * const todoById = (id: TodoId) =>
-     *   evolu.createQuery((db) =>
-     *     db.selectFrom("todo").selectAll().where("id", "=", id),
-     *   );
+     * const stableId = createIdFromString("my-todo-1");
+     * const { id } = evolu.upsert("todo", {
+     *   id: stableId,
+     *   title: NonEmptyString100.orThrow("Learn Evolu"),
+     * });
      * ```
+     *
+     * @see {@link Mutation}
      */
-    readonly createQuery: CreateQuery<S>;
+    readonly upsert: Mutation<S, "upsert">;
     /**
      * Load {@link Query} and return a promise with {@link QueryRows}.
      *
      * The returned promise always resolves successfully because there is no
-     * reason why loading should fail. All data are local, and the query is typed.
-     * Unexpected errors are handled with {@link Evolu#subscribeError}.
+     * reason why loading should fail. All data are local, and the query is
+     * typed.
      *
-     * Loading is batched, and returned promises are cached until resolved to
-     * prevent redundant database queries and to support React Suspense (which
-     * requires stable promise references while pending).
+     * Loading is batched. Returned promises are cached while pending and can be
+     * reused after fulfillment until mutation-driven invalidation, which prevents
+     * redundant database queries and supports React Suspense (stable references
+     * while pending).
      *
      * To subscribe a query for automatic updates, use
-     * {@link Evolu#subscribeQuery}.
+     * {@link Evolu.subscribeQuery}.
      *
      * ### Example
      *
      * ```ts
-     * const allTodos = evolu.createQuery((db) =>
+     * const createQuery = createQueryBuilder(Schema);
+     * const allTodos = createQuery((db) =>
      *   db.selectFrom("todo").selectAll(),
      * );
      * evolu.loadQuery(allTodos).then((rows) => {
@@ -112,7 +291,7 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> extends Disposable {
      * });
      * ```
      */
-    readonly loadQuery: <R extends Row>(query: Query<R>) => Promise<QueryRows<R>>;
+    readonly loadQuery: <R extends Row>(query: Query<S, R>) => Promise<QueryRows<R>>;
     /**
      * Load an array of {@link Query} queries and return an array of
      * {@link QueryRows} promises. It's like `queries.map(loadQuery)` but with
@@ -124,7 +303,7 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> extends Disposable {
      * evolu.loadQueries([allTodos, todoById(1)]);
      * ```
      */
-    readonly loadQueries: <R extends Row, Q extends Queries<R>>(queries: [...Q]) => [...QueriesToQueryRowsPromises<Q>];
+    readonly loadQueries: <Q extends Queries<S>>(queries: [...Q]) => [...QueriesToQueryRowsPromises<Q>];
     /**
      * Subscribe to {@link Query} {@link QueryRows} changes.
      *
@@ -136,7 +315,7 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> extends Disposable {
      * });
      * ```
      */
-    readonly subscribeQuery: (query: Query) => StoreSubscribe;
+    readonly subscribeQuery: (query: Query<S>) => (listener: Listener) => Unsubscribe;
     /**
      * Get {@link QueryRows}.
      *
@@ -148,273 +327,139 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> extends Disposable {
      * });
      * ```
      */
-    readonly getQueryRows: <R extends Row>(query: Query<R>) => QueryRows<R>;
+    readonly getQueryRows: <R extends Row>(query: Query<S, R>) => QueryRows<R>;
     /**
-     * Promise that resolves to {@link AppOwner} when available.
-     *
-     * Note: With web-only deps, this promise will not resolve during SSR because
-     * there is no AppOwner on the server.
+     * Exports the SQLite database file.
      *
-     * ### Example
+     * Exports are sequential: concurrent calls share one pending export instead
+     * of starting parallel exports.
      *
-     * ```ts
-     * const owner = await evolu.appOwner;
-     * ```
+     * The pending promise rejects if this {@link Evolu} instance is disposed
+     * before export completion.
      */
-    readonly appOwner: Promise<AppOwner>;
+    readonly exportDatabase: () => Promise<Uint8Array<ArrayBuffer>>;
     /**
-     * Inserts a row into the database and returns a {@link Result} with the new
-     * {@link Id}.
-     *
-     * The first argument is the table name, and the second is an object
-     * containing the row data. An optional third argument provides mutation
-     * options including an `onComplete` callback and `onlyValidate` flag.
+     * Delete the local SQLite database for this {@link Evolu} instance on the
+     * current device.
      *
-     * Returns a Result type - use `.ok` to check if the insertion succeeded, and
-     * `.value.id` to access the generated ID on success, or `.error` to handle
-     * validation errors.
+     * **Warning**: This first drops all tables. “The dropped table is completely
+     * removed from the database schema and the disk file. The table can not be
+     * recovered. All indices and triggers associated with the table are also
+     * deleted.” https://sqlite.org/lang_droptable.html
      *
-     * Evolu does not use SQL for mutations to ensure data can be safely and
-     * predictably merged without conflicts. Explicit mutations also allow Evolu
-     * to automatically update {@link SystemColumns}.
-     *
-     * ### Example
-     *
-     * ```ts
-     * const result = evolu.insert("todo", {
-     *   title: "Learn Evolu",
-     *   isCompleted: false,
-     * });
+     * After that, it deletes the SQLite file identified by {@link Evolu.name},
+     * permanently forgetting all local data for that instance on this device.
      *
-     * if (result.ok) {
-     *   console.log("Todo created with ID:", result.value.id);
-     * } else {
-     *   console.error("Validation error:", result.error);
-     * }
-     *
-     * // With onComplete callback
-     * evolu.insert(
-     *   "todo",
-     *   { title: "Another todo" },
-     *   {
-     *     onComplete: () => {
-     *       console.log("Insert completed");
-     *     },
-     *   },
-     * );
-     * ```
+     * All instances identified by {@link Evolu.name} will be self-disposed. Use
+     * {@link EvoluConfig.onDatabaseDeleted} to update app UI when that happens.
      */
-    insert: Mutation<S, "insert">;
+    readonly deleteDatabase: () => void;
     /**
-     * Updates a row in the database and returns a {@link Result} with the existing
-     * {@link Id}.
-     *
-     * The first argument is the table name, and the second is an object
-     * containing the row data including the required `id` field. An optional
-     * third argument provides mutation options including an `onComplete` callback
-     * and `onlyValidate` flag.
-     *
-     * Returns a Result type - use `.ok` to check if the update succeeded, and
-     * `.value.id` to access the ID on success, or `.error` to handle validation
-     * errors.
-     *
-     * Evolu does not use SQL for mutations to ensure data can be safely and
-     * predictably merged without conflicts. Explicit mutations also allow Evolu
-     * to automatically update {@link SystemColumns}.
+     * Delete all local data for a specific {@link Owner}.
      *
-     * ### Example
-     *
-     * ```ts
-     * const result = evolu.update("todo", {
-     *   id: todoId,
-     *   title: "Updated title",
-     *   isCompleted: true,
-     * });
+     * This deletes all rows whose `ownerId` matches the provided owner and
+     * deletes that owner's local history as well.
      *
-     * if (result.ok) {
-     *   console.log("Todo updated with ID:", result.value.id);
-     * } else {
-     *   console.error("Validation error:", result.error);
-     * }
-     *
-     * // To delete a row, set isDeleted to true
-     * evolu.update("todo", { id: todoId, isDeleted: true });
-     *
-     * // With onComplete callback
-     * evolu.update(
-     *   "todo",
-     *   { id: todoId, title: "New title" },
-     *   {
-     *     onComplete: () => {
-     *       console.log("Update completed");
-     *     },
-     *   },
-     * );
-     * ```
+     * It also stops using that owner across all tabs and instances. Use
+     * {@link EvoluConfig.onOwnerDeleted} to update app UI when that happens.
      */
-    update: Mutation<S, "update">;
+    readonly deleteOwner: (owner: Owner) => void;
     /**
-     * Upserts a row in the database and returns a {@link Result} with the existing
-     * {@link Id}.
-     *
-     * The first argument is the table name, and the second is an object
-     * containing the row data including the required `id` field. An optional
-     * third argument provides mutation options including an `onComplete` callback
-     * and `onlyValidate` flag.
+     * Use an Owner for sync. Returns a {@link UnuseOwner}.
      *
-     * This function allows you to use custom IDs and optionally set `createdAt`,
-     * which is useful for external systems, data migrations, or when the same row
-     * may already be created on a different device.
+     * Using an Owner means syncing it with the provided transports, or with the
+     * default transports defined in {@link EvoluConfig} when transports are
+     * omitted.
      *
-     * Returns a Result type - use `.ok` to check if the upsert succeeded, and
-     * `.value.id` to access the ID on success, or `.error` to handle validation
-     * errors.
+     * If {@link EvoluConfig.transports} is an empty array, this method must be
+     * called with explicit non-empty transports.
      *
-     * Evolu does not use SQL for mutations to ensure data can be safely and
-     * predictably merged without conflicts. Explicit mutations also allow Evolu
-     * to automatically update {@link SystemColumns}.
+     * Transports are automatically deduplicated and reference-counted, so
+     * multiple Owners using the same transport will share a single connection.
      *
      * ### Example
      *
      * ```ts
-     * // Use deterministic ID for stable upserts across devices
-     * const stableId = createIdFromString("my-todo-1");
-     *
-     * const result = evolu.upsert("todo", {
-     *   id: stableId,
-     *   title: "Learn Evolu",
-     *   isCompleted: false,
-     * });
-     *
-     * if (result.ok) {
-     *   console.log("Todo upserted with ID:", result.value.id);
-     * } else {
-     *   console.error("Validation error:", result.error);
-     * }
-     *
-     * // Data migration with custom createdAt
-     * evolu.upsert("todo", {
-     *   id: externalId,
-     *   title: "Migrated todo",
-     *   createdAt: new Date("2023-01-01"), // Preserve original timestamp
-     * });
+     * // Use an Owner (starts syncing).
+     * const unuseOwner = evolu.useOwner(shardOwner, [
+     *   createOwnerWebSocketTransport({
+     *     url: "ws://localhost:4000",
+     *     ownerId: shardOwner.id,
+     *   }),
+     * ]);
+     *
+     * // Later, stop using the Owner.
+     * unuseOwner();
      *
-     * // With onComplete callback
-     * evolu.upsert(
-     *   "todo",
-     *   { id: stableId, title: "Updated title" },
-     *   {
-     *     onComplete: () => {
-     *       console.log("Upsert completed");
-     *     },
-     *   },
-     * );
+     * // Bulk operations.
+     * const unuseOwners = owners.map(evolu.useOwner);
+     * // Later: for (const unuse of unuseOwners) unuse();
      * ```
      */
-    upsert: Mutation<S, "upsert">;
-    /**
-     * Delete {@link AppOwner} and all their data from the current device. After
-     * the deletion, Evolu will purge the application state. For browsers, this
-     * will reload all tabs using Evolu. For native apps, it will restart the
-     * app.
-     *
-     * Reloading can be turned off via options if you want to provide a different
-     * UX.
-     */
-    readonly resetAppOwner: (options?: {
-        readonly reload?: boolean;
-    }) => Promise<void>;
-    /**
-     * Restore {@link AppOwner} with all their synced data. It uses
-     * {@link Evolu#resetAppOwner}, so be careful.
-     */
-    readonly restoreAppOwner: (mnemonic: Mnemonic, options?: {
-        readonly reload?: boolean;
-    }) => Promise<void>;
-    /**
-     * Reload the app in a platform-specific way. For browsers, this will reload
-     * all tabs using Evolu. For native apps, it will restart the app.
-     */
-    readonly reloadApp: () => void;
-    /**
-     * Export SQLite database file as Uint8Array.
-     *
-     * In the future, it will be possible to import a database and export/import
-     * history for 1:1 migrations across owners.
-     */
-    readonly exportDatabase: () => Promise<Uint8Array<ArrayBuffer>>;
+    readonly useOwner: (owner: ReadonlyOwner | Owner, transports?: NonEmptyReadonlyArray<OwnerTransport>) => UnuseOwner;
+}
+/** Function returned by {@link Evolu.useOwner} to stop using an Owner for sync. */
+export type UnuseOwner = () => void;
+export interface EvoluErrorDep {
     /**
-     * Use a {@link SyncOwner}. Returns a {@link UnuseOwner}.
-     *
-     * Using an owner means syncing it with its transports, or the transports
-     * defined in Evolu config if the owner has no transports defined.
+     * {@link ReadonlyStore} of {@link EvoluError} shared by all {@link Evolu}
+     * instances created from the same {@link createEvoluDeps} result.
      *
-     * Transport are automatically deduplicated and reference-counted, so multiple
-     * owners using the same transport will share a single connection.
+     * Subscribe once to show user-facing messages across all instances. Logging
+     * is handled by platform {@link createRun} global error handlers.
      *
      * ### Example
      *
      * ```ts
-     * // Use an owner (starts syncing).
-     * const unuseOwner = evolu.useOwner(shardOwner);
-     *
-     * // Later, stop using the owner.
-     * unuseOwner();
-     *
-     * // Bulk operations.
-     * const unuseOwners = owners.map((owner) => evolu.useOwner(owner));
-     * // Later: for (const unuse of unuseOwners) unuse();
+     * deps.evoluError.subscribe(() => {
+     *   const error = deps.evoluError.get();
+     *   if (!error) return;
+     *
+     *   switch (error.type) {
+     *     case "InvalidComputerClock":
+     *       // Show guidance specific to the detected error.
+     *       showMessage(
+     *         "Your system clock appears incorrect. Please fix it.",
+     *       );
+     *       break;
+     *     default:
+     *       // Show a generic user message for other operational errors.
+     *       showMessage("Something went wrong. Please try again.");
+     *   }
+     * });
      * ```
-     *
-     * @experimental
      */
-    readonly useOwner: (owner: SyncOwner) => UnuseOwner;
+    readonly evoluError: ReadonlyStore<EvoluError | null>;
 }
-/** Function returned by {@link Evolu#useOwner} to stop using an {@link SyncOwner}. */
-export type UnuseOwner = () => void;
-/** Represents errors that can occur in Evolu. */
-export type EvoluError = ProtocolError | SqliteError | SymmetricCryptoDecryptError | TimestampError | TransferableError;
-export type EvoluDeps = ConsoleDep & CreateDbWorkerDep & Partial<FlushSyncDep> & RandomBytesDep & ReloadAppDep & TimeDep;
 /**
- * Creates an {@link Evolu} instance for a platform configured with the specified
- * {@link EvoluSchema} and optional {@link EvoluConfig} providing a typed
- * interface for querying, mutating, and syncing your application's data.
- *
- * ### Example
+ * Shared platform dependencies for creating {@link Evolu} instances.
  *
- * ```ts
- * const TodoId = id("Todo");
- * type TodoId = InferType<typeof TodoId>;
- *
- * const TodoCategoryId = id("TodoCategory");
- * type TodoCategoryId = InferType<typeof TodoCategoryId>;
- *
- * const NonEmptyString50 = maxLength(50, NonEmptyString);
- * type NonEmptyString50 = InferType<typeof NonEmptyString50>;
- *
- * const Schema = {
- *   todo: {
- *     id: TodoId,
- *     title: NonEmptyString1000,
- *     isCompleted: nullOr(SqliteBoolean),
- *     categoryId: nullOr(TodoCategoryId),
- *   },
- *   todoCategory: {
- *     id: TodoCategoryId,
- *     name: NonEmptyString50,
- *   },
- * };
+ * Includes platform adapters, the shared {@link EvoluErrorDep.evoluError} store,
+ * and disposal for owned resources.
+ */
+export type EvoluDeps = EvoluPlatformDeps & EvoluErrorDep & Disposable;
+/**
+ * Platform-specific dependencies required to create {@link EvoluDeps}.
  *
- * const evolu = createEvolu(evoluReactDeps)(Schema);
- * ```
+ * Provides worker and channel adapters plus optional platform integrations for
+ * logging and synchronous UI flush.
+ */
+export type EvoluPlatformDeps = CreateDbWorkerDep & CreateMessageChannelDep & ReloadAppDep & SharedWorkerDep & Partial<ConsoleDep> & Partial<FlushSyncDep>;
+/**
+ * Creates shared dependencies used by all {@link createEvolu} instances on a
+ * platform.
  *
- * ### Instance Caching
+ * Call this once per platform and reuse the returned deps when creating
+ * multiple Evolu instances. The returned deps object owns long-lived resources
+ * such as worker channels and the shared {@link EvoluErrorDep.evoluError}
+ * store.
  *
- * `createEvolu` caches instances using {@link Instances} by {@link EvoluConfig}
- * name to enable hot reloading and prevent database corruption from multiple
- * connections. For testing, use unique instance names to ensure proper
- * isolation.
+ * Dispose it only during app shutdown.
+ */
+export declare const createEvoluDeps: (deps: EvoluPlatformDeps) => EvoluDeps;
+/**
+ * Creates an {@link Evolu} instance from {@link EvoluSchema} and
+ * {@link EvoluConfig}.
  */
-export declare const createEvolu: (deps: EvoluDeps) => <S extends EvoluSchema>(schema: ValidateSchema<S> extends never ? S : ValidateSchema<S>, config?: EvoluConfig) => Evolu<S>;
-export declare const createQuery: <R extends Row>(queryCallback: Parameters<CreateQuery<EvoluSchema>>[0], options?: Parameters<CreateQuery<EvoluSchema>>[1]) => Query<R>;
+export declare const createEvolu: <S extends EvoluSchema>(schema: ValidateSchema<S> extends never ? S : ValidateSchema<S>, config: EvoluConfig) => Task<Evolu<S>, never, EvoluPlatformDeps>;
 //# sourceMappingURL=Evolu.d.ts.map