@evolu/common 6.0.1-preview.9 → 7.0.0

package/src/Evolu/Evolu.ts

@@ -1,13 +1,25 @@
-import { isNonEmptyArray, isNonEmptyReadonlyArray } from "../Array.js";
-import { assert, assertNonEmptyArray } from "../Assert.js";
+import { pack } from "msgpackr";
+import {
+  dedupeArray,
+  isNonEmptyArray,
+  isNonEmptyReadonlyArray,
+} from "../Array.js";
+import { assertNonEmptyReadonlyArray } from "../Assert.js";
 import { createCallbacks } from "../Callbacks.js";
 import { ConsoleDep } from "../Console.js";
-import { SymmetricCryptoDecryptError } from "../Crypto.js";
+import { RandomBytesDep, SymmetricCryptoDecryptError } from "../Crypto.js";
+import { eqArrayNumber } from "../Eq.js";
 import { TransferableError } from "../Error.js";
 import { exhaustiveCheck } from "../Function.js";
-import { NanoIdLibDep } from "../NanoId.js";
+import { createInstances, Instances } from "../Instances.js";
 import { err, ok, Result } from "../Result.js";
-import { isSqlMutation, SafeSql, SqliteError, SqliteQuery } from "../Sqlite.js";
+import {
+  isSqlMutation,
+  SafeSql,
+  SqliteBoolean,
+  SqliteError,
+  SqliteQuery,
+} from "../Sqlite.js";
 import { createStore, StoreSubscribe } from "../Store.js";
 import { TimeDep } from "../Time.js";
 import {
@@ -18,19 +30,16 @@ import {
   InferType,
   Mnemonic,
   ObjectType,
+  SimpleName,
+  ValidMutationSize,
+  ValidMutationSizeError,
 } from "../Type.js";
 import { IntentionalNever } from "../Types.js";
-import { Config, defaultConfig } from "./Config.js";
-import { CreateDbWorkerDep } from "./Db.js";
+import { CreateDbWorkerDep, DbConfig, defaultDbConfig } from "./Db.js";
 import { applyPatches } from "./Diff.js";
-import { kysely } from "./Kysely.js";
 import { AppOwner } from "./Owner.js";
-import { CreateAppStateDep, FlushSyncDep } from "./Platform.js";
-import {
-  DbChange,
-  ProtocolError,
-  ProtocolUnsupportedVersionError,
-} from "./Protocol.js";
+import { FlushSyncDep, ReloadAppDep } from "./Platform.js";
+import { ProtocolError } from "./Protocol.js";
 import {
   createSubscribedQueries,
   emptyRows,
@@ -47,21 +56,55 @@ import {
   CreateQuery,
   EvoluSchema,
   evoluSchemaToDbSchema,
+  IndexesConfig,
   insertable,
+  kysely,
   Mutation,
+  MutationChange,
   MutationKind,
   MutationMapping,
   MutationOptions,
+  SystemColumns,
   updateable,
   upsertable,
   ValidateSchema,
-  ValidMutationSize,
-  ValidMutationSizeError,
 } from "./Schema.js";
-import { initialSyncState, SyncState } from "./Sync.js";
+import { DbChange } from "./Storage.js";
+import { initialSyncState, SyncOwner, SyncState } from "./Sync.js";
 import { TimestampError } from "./Timestamp.js";
 
-export interface Evolu<S extends EvoluSchema = EvoluSchema> {
+export interface EvoluConfig extends Partial<DbConfig> {
+  /**
+   * Use the `indexes` option to define SQLite indexes.
+   *
+   * Table and column names are not typed because Kysely doesn't support it.
+   *
+   * https://medium.com/@JasonWyatt/squeezing-performance-from-sqlite-indexes-indexes-c4e175f3c346
+   *
+   * ### Example
+   *
+   * ```ts
+   * const evolu = createEvolu(evoluReactDeps)(Schema, {
+   *   indexes: (create) => [
+   *     create("todoCreatedAt").on("todo").column("createdAt"),
+   *     create("todoCategoryCreatedAt")
+   *       .on("todoCategory")
+   *       .column("createdAt"),
+   *   ],
+   * });
+   * ```
+   */
+  readonly indexes?: IndexesConfig;
+
+  /**
+   * URL to reload browser tabs after reset or restore.
+   *
+   * The default value is `/`.
+   */
+  readonly reloadUrl?: string;
+}
+
+export interface Evolu<S extends EvoluSchema = EvoluSchema> extends Disposable {
   /**
    * Subscribe to {@link EvoluError} changes.
    *
@@ -88,7 +131,8 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> {
    * All this function does is compile the Kysely query and serialize it into a
    * unique string. Both operations are fast and cheap.
    *
-   * For mutations, use {@link Evolu#insert} and {@link Evolu#update}.
+   * For mutations, use {@link Evolu#insert}, {@link Evolu#update}, or
+   * {@link Evolu#upsert}.
    *
    * ### Example
    *
@@ -108,43 +152,16 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> {
   /**
    * Load {@link Query} and return a promise with {@link QueryRows}.
    *
-   * A returned promise always resolves successfully because there is no reason
-   * why loading should fail. All data are local, and the query is typed. A
-   * serious unexpected Evolu error shall be handled with
-   * {@link Evolu#subscribeError}.
-   *
-   * Loading is batched, and returned promises are cached, so there is no need
-   * for an additional cache. Evolu's internal cache is invalidated on
-   * mutation.
-   *
-   * The returned promise is enriched with special status and value properties
-   * for the upcoming React `use` Hook, but other UI libraries can also leverage
-   * them. Speaking of React, there are two essential React Suspense-related
-   * patterns that every developer should be aware of—passing promises to
-   * children and caching over mutations.
+   * 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}.
    *
-   * With promises passed to children, we can load a query as soon as possible,
-   * but we don't have to use the returned promise immediately. That's useful
-   * for prefetching, which is generally not necessary for local-first apps but
-   * can be if a query takes a long time to load.
+   * 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).
    *
-   * Caching over mutation is a pattern that every developer should know. As we
-   * said, Evolu caches promise until a mutation happens. A query loaded after
-   * that will return a new pending promise. That's okay for general usage but
-   * not for UI with React Suspense because a mutation would suspend rerendered
-   * queries on a page, and that's not a good UX.
-   *
-   * We call this pattern "caching over mutation" because it has no globally
-   * accepted name yet. React RFC for React Cache does not exist yet.
-   *
-   * For better UX, a query must be subscribed for updates. This way, instead of
-   * Suspense flashes, the user sees new data immediately because Evolu replaces
-   * cached promises with fresh, already resolved new ones.
-   *
-   * If you are curious why Evolu does not do that for all queries by default,
-   * the answer is simple: performance. Tracking changes is costly and
-   * meaningful only for visible (hence subscribed) queries anyway. To subscribe
-   * to a query, use {@link Evolu#subscribeQuery}.
+   * To subscribe a query for automatic updates, use
+   * {@link Evolu#subscribeQuery}.
    *
    * ### Example
    *
@@ -152,7 +169,7 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> {
    * const allTodos = evolu.createQuery((db) =>
    *   db.selectFrom("todo").selectAll(),
    * );
-   * evolu.loadQuery(allTodos).then(({ rows }) => {
+   * evolu.loadQuery(allTodos).then((rows) => {
    *   console.log(rows);
    * });
    * ```
@@ -201,86 +218,168 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> {
   readonly getQueryRows: <R extends Row>(query: Query<R>) => QueryRows<R>;
 
   /**
-   * Subscribe to {@link AppOwner} changes.
+   * Promise that resolves to {@link AppOwner} when available.
    *
-   * ### Example
-   *
-   * ```ts
-   * const unsubscribe = evolu.subscribeAppOwner(() => {
-   *   const owner = evolu.getAppOwner();
-   * });
-   * ```
-   */
-  readonly subscribeAppOwner: StoreSubscribe;
-
-  /**
-   * Get {@link AppOwner}.
+   * Note: With web-only deps, this promise will not resolve during SSR because
+   * there is no AppOwner on the server.
    *
    * ### Example
    *
    * ```ts
-   * const unsubscribe = evolu.subscribeAppOwner(() => {
-   *   const owner = evolu.getAppOwner();
-   * });
+   * const owner = await evolu.appOwner;
    * ```
    */
-  readonly getAppOwner: () => AppOwner | null;
+  readonly appOwner: Promise<AppOwner>;
 
   /**
-   * Subscribe to {@link SyncState} changes.
+   * Inserts a row into the database and returns a {@link Result} with the new
+   * {@link Id}.
    *
-   * ### Example
+   * 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.
    *
-   * ```ts
-   * const unsubscribe = evolu.subscribeSyncState(() => {
-   *   const syncState = evolu.getSyncState();
-   * });
-   * ```
-   */
-  readonly subscribeSyncState: StoreSubscribe;
-
-  /**
-   * Get {@link SyncState}.
+   * 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.
+   *
+   * 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 unsubscribe = evolu.subscribeSyncState(() => {
-   *   const syncState = evolu.getSyncState();
+   * const result = evolu.insert("todo", {
+   *   title: "Learn Evolu",
+   *   isCompleted: false,
    * });
-   * ```
-   */
-  readonly getSyncState: () => SyncState;
-
-  /**
-   * Inserts a row.
    *
-   * ### Example
+   * if (result.ok) {
+   *   console.log("Todo created with ID:", result.value.id);
+   * } else {
+   *   console.error("Validation error:", result.error);
+   * }
    *
-   * ```ts
-   * // TODO:
+   * // With onComplete callback
+   * evolu.insert(
+   *   "todo",
+   *   { title: "Another todo" },
+   *   {
+   *     onComplete: () => {
+   *       console.log("Insert completed");
+   *     },
+   *   },
+   * );
    * ```
    */
   insert: Mutation<S, "insert">;
 
   /**
-   * Updates a row.
+   * 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}.
    *
    * ### Example
    *
    * ```ts
-   * // TODO:
+   * const result = evolu.update("todo", {
+   *   id: todoId,
+   *   title: "Updated title",
+   *   isCompleted: true,
+   * });
+   *
+   * 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");
+   *     },
+   *   },
+   * );
    * ```
    */
   update: Mutation<S, "update">;
 
   /**
-   * Upserts a row.
+   * 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.
+   *
+   * 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.
+   *
+   * 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.
+   *
+   * 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
-   * // TODO:
+   * // 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
+   * });
+   *
+   * // With onComplete callback
+   * evolu.upsert(
+   *   "todo",
+   *   { id: stableId, title: "Updated title" },
+   *   {
+   *     onComplete: () => {
+   *       console.log("Upsert completed");
+   *     },
+   *   },
+   * );
    * ```
    */
   upsert: Mutation<S, "upsert">;
@@ -315,18 +414,48 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> {
    */
   readonly reloadApp: () => void;
 
-  /** Export SQLite database file as Uint8Array. */
-  readonly exportDatabase: () => Promise<Uint8Array>;
+  /**
+   * 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>>;
+
+  /**
+   * Use an owner. Using an owner means syncing it and subscribing to
+   * broadcasted changes. Returns a function to stop using the owner.
+   *
+   * Transport connections are automatically deduplicated and reference-counted,
+   * so multiple owners using the same transport will share a single
+   * connection.
+   *
+   * ### Example
+   *
+   * ```ts
+   * // Use an owner (starts syncing and subscribing to changes).
+   * const unuse = evolu.useOwner(shardOwner);
+   *
+   * // Later, stop using the owner.
+   * unuse();
+   *
+   * // Bulk operations.
+   * const unuses = owners.map((owner) => evolu.useOwner(owner));
+   * // Later: unuses.forEach(unuse => unuse());
+   * ```
+   *
+   * @experimental
+   */
+  readonly useOwner: (owner: SyncOwner) => () => void;
 }
 
-/** Represent errors that can occur in Evolu. */
+/** Represents errors that can occur in Evolu. */
 export type EvoluError =
-  | TimestampError
   | ProtocolError
-  | TransferableError
+  | SqliteError
   | SymmetricCryptoDecryptError
-  | ProtocolUnsupportedVersionError
-  | SqliteError;
+  | TimestampError
+  | TransferableError;
 
 interface InternalEvoluInstance<S extends EvoluSchema = EvoluSchema>
   extends Evolu<S> {
@@ -337,68 +466,25 @@ interface InternalEvoluInstance<S extends EvoluSchema = EvoluSchema>
   readonly ensureSchema: (schema: EvoluSchema) => void;
 }
 
-export type EvoluDeps = CreateDbWorkerDep &
-  TimeDep &
-  NanoIdLibDep &
+export type EvoluDeps = ConsoleDep &
+  CreateDbWorkerDep &
   Partial<FlushSyncDep> &
-  ConsoleDep &
-  CreateAppStateDep;
+  RandomBytesDep &
+  ReloadAppDep &
+  TimeDep;
 
-export interface EvoluConfigWithInitialData<S extends EvoluSchema = EvoluSchema>
-  extends Config {
-  /**
-   * Use this option to create initial data (fixtures).
-   *
-   * ### Example
-   *
-   * ```ts
-   * const evolu = createEvolu(evoluReactWebDeps)(Schema, {
-   *   initialData: (evolu) => {
-   *     const todoCategory = evolu.insert("todoCategory", {
-   *       name: "Not Urgent",
-   *     });
-   *
-   *     // This is a developer error, which should be fixed immediately.
-   *     assert(todoCategory.ok, "invalid initial data");
-   *
-   *     evolu.insert("todo", {
-   *       title: "Try React Suspense",
-   *       categoryId: todoCategory.value.id,
-   *     });
-   *   },
-   * });
-   * ```
-   */
-  initialData?: (evolu: EvoluForInitialData<S>) => void;
-}
-
-export interface EvoluForInitialData<S extends EvoluSchema = EvoluSchema> {
-  insert: Mutation<S, "insert">;
-}
-
-// For hot reloading and Evolu multitenancy.
-const evoluInstances = new Map<string, InternalEvoluInstance>();
+const evoluInstances = createInstances<SimpleName, InternalEvoluInstance>();
 
+/**
+ * Unique identifier for the current browser tab or app instance, lazily
+ * initialized on first use to distinguish between multiple tabs.
+ */
 let tabId: Id | null = null;
 
 /**
- * Creates an {@link Evolu} instance configured with the specified
- * {@link EvoluSchema} and optional configuration.
- *
- * This function returns a configured Evolu instance, providing a typed
- * interface for querying, mutating, and syncing your application's data. The
- * returned instance includes:
- *
- * - Subscription methods for receiving updates on queries, the owner, errors, and
- *   sync state.
- * - Methods for creating, updating, or deleting rows in a type-safe manner.
- * - Methods for querying data using Evolu's typed SQL queries, leveraging Kysely
- *   under the hood.
- * - Built-in support for local-first and offline-first data with automatic sync
- *   and merging.
- * - Automatic schema evolution that updates the underlying database with new
- *   columns or tables.
- * - Managing owner data with resetAppOwner and restoreAppOwner.
+ * 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
  *
@@ -427,79 +513,88 @@ let tabId: Id | null = null;
  *
  * const evolu = createEvolu(evoluReactDeps)(Schema);
  * ```
+ *
+ * ### Instance Caching
+ *
+ * `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.
  */
 export const createEvolu =
   (deps: EvoluDeps) =>
   <S extends EvoluSchema>(
     schema: ValidateSchema<S> extends never ? S : ValidateSchema<S>,
-    partialConfig: Partial<EvoluConfigWithInitialData<S>> = {},
-  ): Evolu<S> => {
-    const config = { ...defaultConfig, ...partialConfig };
-
-    let evolu = evoluInstances.get(config.name);
-
-    if (evolu == null) {
-      evolu = createEvoluInstance(deps)(
-        schema as EvoluSchema,
-        config as IntentionalNever,
-      );
-      evoluInstances.set(config.name, evolu);
-    } else {
-      // Hot reloading. Note that indexes are intentionally omitted.
-      evolu.ensureSchema(schema as EvoluSchema);
-    }
-
-    return evolu as IntentionalNever;
-  };
+    config?: EvoluConfig,
+  ): Evolu<S> =>
+    evoluInstances.ensure(
+      config?.name ?? defaultDbConfig.name,
+      () => createEvoluInstance(deps)(schema as EvoluSchema, config),
+      (evolu) => {
+        // Hot reloading. Note that indexes are intentionally omitted.
+        evolu.ensureSchema(schema as EvoluSchema);
+      },
+    ) as Evolu<S>;
 
 const createEvoluInstance =
   (deps: EvoluDeps) =>
-  (
-    schema: EvoluSchema,
-    evoluConfig: EvoluConfigWithInitialData,
-  ): InternalEvoluInstance => {
-    deps.console.enabled = evoluConfig.enableLogging ?? false;
+  (schema: EvoluSchema, config?: EvoluConfig): InternalEvoluInstance => {
+    deps.console.enabled = config?.enableLogging ?? false;
 
-    deps.console.log("[evolu]", "createEvoluInstance");
+    const { indexes, reloadUrl = "/", ...partialDbConfig } = config ?? {};
 
-    const { initialData, indexes, ...config } = evoluConfig;
+    const dbConfig: DbConfig = { ...defaultDbConfig, ...partialDbConfig };
+
+    deps.console.log("[evolu]", "createEvoluInstance", {
+      name: dbConfig.name,
+    });
 
     const errorStore = createStore<EvoluError | null>(null);
     const rowsStore = createStore<QueryRowsMap>(new Map());
-    const ownerStore = createStore<AppOwner | null>(null);
-    const syncStore = createStore<SyncState>(initialSyncState);
+
+    const { promise: appOwner, resolve: resolveAppOwner } =
+      Promise.withResolvers<AppOwner>();
+
+    if (config?.externalAppOwner) {
+      resolveAppOwner(config.externalAppOwner);
+    }
+
+    // TODO: Update it for the owner-api
+    const _syncStore = createStore<SyncState>(initialSyncState);
 
     const subscribedQueries = createSubscribedQueries(rowsStore);
     const loadingPromises = createLoadingPromises(subscribedQueries);
-    const callbacks = createCallbacks(deps);
+    const onCompleteCallbacks = createCallbacks(deps);
+    const exportCallbacks = createCallbacks<Uint8Array<ArrayBuffer>>(deps);
 
-    const appState = deps.createAppState(config);
-    const dbWorker = deps.createDbWorker(config.name);
+    const dbWorker = deps.createDbWorker(dbConfig.name);
 
     const getTabId = () => {
       tabId ??= createId(deps);
       return tabId;
     };
 
+    // Worker responses are delivered to all tabs. Each case must handle this
+    // properly (e.g., AppOwner promise resolves only once, tabId filtering).
     dbWorker.onMessage((message) => {
       switch (message.type) {
-        case "onInit": {
-          ownerStore.set(message.owner);
+        case "onError": {
+          errorStore.set(message.error);
           break;
         }
 
-        case "onError": {
-          errorStore.set(message.error);
+        case "onGetAppOwner": {
+          resolveAppOwner(message.appOwner);
           break;
         }
 
-        case "onChange": {
+        case "onQueryPatches": {
           if (message.tabId !== getTabId()) return;
 
           const state = rowsStore.get();
           const nextState = new Map([
             ...state,
-            ...message.patches.map(
+            ...message.queryPatches.map(
               ({ query, patches }): [Query, ReadonlyArray<Row>] => [
                 query,
                 applyPatches(patches, state.get(query) ?? emptyRows),
@@ -507,7 +602,7 @@ const createEvoluInstance =
             ),
           ]);
 
-          for (const { query } of message.patches) {
+          for (const { query } of message.queryPatches) {
             loadingPromises.resolve(query, nextState.get(query) ?? emptyRows);
           }
 
@@ -520,33 +615,43 @@ const createEvoluInstance =
           }
 
           for (const id of message.onCompleteIds) {
-            callbacks.execute(id);
+            onCompleteCallbacks.execute(id);
           }
           break;
         }
 
-        case "onReceive": {
+        case "refreshQueries": {
           if (message.tabId && message.tabId === getTabId()) return;
 
-          loadingPromises.releaseUnsubscribed();
-          const queries = subscribedQueries.get();
+          const loadingPromisesQueries = loadingPromises.getQueries();
+          loadingPromises.releaseUnsubscribedOnMutation();
+
+          const queries = dedupeArray([
+            ...loadingPromisesQueries,
+            ...subscribedQueries.get(),
+          ]);
+
           if (isNonEmptyReadonlyArray(queries)) {
             dbWorker.postMessage({ type: "query", tabId: getTabId(), queries });
           }
+
           break;
         }
 
         case "onReset": {
           if (message.reload) {
-            appState.reset();
+            deps.reloadApp(reloadUrl);
           } else {
-            callbacks.execute(message.onCompleteId);
+            onCompleteCallbacks.execute(message.onCompleteId);
           }
           break;
         }
 
         case "onExport": {
-          callbacks.execute(message.onCompleteId, message.file);
+          exportCallbacks.execute(
+            message.onCompleteId,
+            message.file as Uint8Array<ArrayBuffer>,
+          );
           break;
         }
 
@@ -579,44 +684,19 @@ const createEvoluInstance =
       return type;
     };
 
-    const initialDataDbChanges: Array<DbChange> = [];
-
-    /**
-     * Note that the initial data function is called even if it is unnecessary
-     * (initial data are already in the DB) because we don't want to wait for
-     * SQLite's response. Initial data should be small (because they are inlined
-     * in the code), so it's ok.
-     */
-    if (initialData)
-      initialData({
-        insert: (table, props) => {
-          const id = createId(deps);
-          const values = getMutationType(table, "insert").fromUnknown(props);
-
-          if (values.ok) {
-            const dbChange = { table, id, values: values.value };
-            assertValidDbChange(dbChange);
-            initialDataDbChanges.push(dbChange);
-            return ok({ id });
-          }
-
-          return values;
-        },
-      });
+    dbWorker.postMessage({ type: "init", config: dbConfig, dbSchema });
 
-    dbWorker.postMessage({
-      type: "init",
-      config,
-      dbSchema,
-      initialData: initialDataDbChanges,
-    });
+    // We can't use `init` to get AppOwner because `init` runs only once per n tabs.
+    dbWorker.postMessage({ type: "getAppOwner" });
 
     const loadQueryMicrotaskQueue: Array<Query> = [];
 
     const mutateMicrotaskQueue: Array<
-      [DbChange | undefined, MutationOptions["onComplete"] | undefined]
+      [MutationChange | null, MutationOptions["onComplete"] | undefined]
     > = [];
 
+    const useOwnerMicrotaskQueue: Array<[SyncOwner, boolean, Uint8Array]> = [];
+
     const createMutation =
       <Kind extends MutationKind>(kind: Kind) =>
       <TableName extends keyof typeof schema>(
@@ -632,8 +712,7 @@ const createEvoluInstance =
             ObjectType<MutationMapping<(typeof schema)[TableName], Kind>>
           >
       > => {
-        const Type = getMutationType(table, kind);
-        const result = Type.fromUnknown(props);
+        const result = getMutationType(table, kind).fromUnknown(props);
 
         const id =
           kind === "insert"
@@ -642,51 +721,28 @@ const createEvoluInstance =
 
         if (options?.onlyValidate !== true) {
           if (!result.ok) {
-            // One error must invalidate the whole queue.
-            // We insert `undefined` to detect such a situation.
-            mutateMicrotaskQueue.push([undefined, undefined]);
+            // Mark the transaction as invalid by pushing null
+            mutateMicrotaskQueue.push([null, undefined]);
           } else {
-            // Remove `id` from values.
-            const { id: _id, ...values } = result.value;
-            const dbChange = { table, id, values };
-            assertValidDbChange(dbChange);
-            mutateMicrotaskQueue.push([dbChange, options?.onComplete]);
-          }
-
-          if (mutateMicrotaskQueue.length === 1)
-            queueMicrotask(() => {
-              const changes: Array<DbChange> = [];
-              const onCompletes = [];
-
-              for (const [change, onComplete] of mutateMicrotaskQueue) {
-                if (change) changes.push(change);
-                if (onComplete) onCompletes.push(onComplete);
-              }
-
-              const mutateMicrotaskQueueLength = mutateMicrotaskQueue.length;
-              mutateMicrotaskQueue.length = 0;
-
-              // Don't mutate anything if there was a validation error.
-              // All mutations within a queue are considered to be a transaction.
-              if (changes.length !== mutateMicrotaskQueueLength) {
-                return;
-              }
-
-              const onCompleteIds = onCompletes.map((onComplete) =>
-                callbacks.register(onComplete),
-              );
+            const { id: _, isDeleted, ...values } = result.value;
+
+            const dbChange = DbChange.orThrow({
+              table,
+              id,
+              values,
+              isInsert: kind === "insert" || kind === "upsert",
+              isDelete: SqliteBoolean.is(isDeleted) ? Boolean(isDeleted) : null,
+            });
 
-              loadingPromises.releaseUnsubscribed();
+            mutateMicrotaskQueue.push([
+              { ...dbChange, ownerId: options?.ownerId },
+              options?.onComplete,
+            ]);
+          }
 
-              if (isNonEmptyArray(changes))
-                dbWorker.postMessage({
-                  type: "mutate",
-                  tabId: getTabId(),
-                  changes,
-                  onCompleteIds,
-                  subscribedQueries: subscribedQueries.get(),
-                });
-            });
+          if (mutateMicrotaskQueue.length === 1) {
+            queueMicrotask(processMutationQueue);
+          }
         }
 
         if (result.ok) return ok({ id });
@@ -700,28 +756,43 @@ const createEvoluInstance =
         );
       };
 
+    const processMutationQueue = () => {
+      const changes: Array<MutationChange> = [];
+      const onCompletes = [];
+
+      for (const [change, onComplete] of mutateMicrotaskQueue) {
+        if (change !== null) changes.push(change);
+        if (onComplete) onCompletes.push(onComplete);
+      }
+
+      const queueLength = mutateMicrotaskQueue.length;
+      mutateMicrotaskQueue.length = 0;
+
+      // Don't process any mutations if there was a validation error.
+      // All mutations within a queue run as a single transaction.
+      if (changes.length !== queueLength) {
+        return;
+      }
+
+      const onCompleteIds = onCompletes.map(onCompleteCallbacks.register);
+      loadingPromises.releaseUnsubscribedOnMutation();
+
+      if (!isNonEmptyArray(changes)) return;
+
+      dbWorker.postMessage({
+        type: "mutate",
+        tabId: getTabId(),
+        changes,
+        onCompleteIds,
+        subscribedQueries: subscribedQueries.get(),
+      });
+    };
+
     const evolu: InternalEvoluInstance = {
       subscribeError: errorStore.subscribe,
       getError: errorStore.get,
 
-      createQuery: (queryCallback, options) => {
-        const compiledQuery = queryCallback(
-          kysely as IntentionalNever,
-        ).compile();
-
-        if (isSqlMutation(compiledQuery.sql))
-          throw new Error(
-            "SQL mutation (INSERT, UPDATE, DELETE, etc.) isn't allowed in the Evolu `createQuery` function. Kysely suggests it because there is no read-only Kysely yet, and removing such an API is not possible. For mutations, use Evolu Mutation API.",
-          );
-
-        return serializeQuery({
-          sql: compiledQuery.sql as SafeSql,
-          parameters: compiledQuery.parameters as NonNullable<
-            SqliteQuery["parameters"]
-          >,
-          ...(options && { options }),
-        });
-      },
+      createQuery,
 
       loadQuery: <R extends Row>(query: Query<R>): Promise<QueryRows<R>> => {
         const { promise, isNew } = loadingPromises.get(query);
@@ -730,10 +801,10 @@ const createEvoluInstance =
           loadQueryMicrotaskQueue.push(query);
           if (loadQueryMicrotaskQueue.length === 1) {
             queueMicrotask(() => {
-              // Dedupe
-              const queries = [...new Set(loadQueryMicrotaskQueue)];
+              const queries = dedupeArray(loadQueryMicrotaskQueue);
               loadQueryMicrotaskQueue.length = 0;
-              assertNonEmptyArray(queries);
+              assertNonEmptyReadonlyArray(queries);
+              deps.console.log("[evolu]", "loadQuery", { queries });
               dbWorker.postMessage({
                 type: "query",
                 tabId: getTabId(),
@@ -769,23 +840,19 @@ const createEvoluInstance =
       getQueryRows: <R extends Row>(query: Query<R>): QueryRows<R> =>
         (rowsStore.get().get(query) ?? emptyRows) as QueryRows<R>,
 
-      subscribeAppOwner: ownerStore.subscribe,
-      getAppOwner: ownerStore.get,
+      appOwner,
 
-      subscribeSyncState: syncStore.subscribe,
-      getSyncState: syncStore.get,
+      // TODO: Update it for the owner-api
+      // subscribeSyncState: syncStore.subscribe,
+      // getSyncState: syncStore.get,
 
       insert: createMutation("insert"),
       update: createMutation("update"),
       upsert: createMutation("upsert"),
 
       resetAppOwner: (options) => {
-        // Eslint bug, Promise<void> is correct by docs.
-        // eslint-disable-next-line @typescript-eslint/no-invalid-void-type
-        const { promise, resolve } = Promise.withResolvers<void>();
-        const onCompleteId = callbacks.register(() => {
-          resolve();
-        });
+        const { promise, resolve } = Promise.withResolvers<undefined>();
+        const onCompleteId = onCompleteCallbacks.register(resolve);
         dbWorker.postMessage({
           type: "reset",
           onCompleteId,
@@ -795,13 +862,8 @@ const createEvoluInstance =
       },
 
       restoreAppOwner: (mnemonic, options) => {
-        // Eslint bug, Promise<void> is correct by docs.
-        // eslint-disable-next-line @typescript-eslint/no-invalid-void-type
-        const { promise, resolve } = Promise.withResolvers<void>();
-        const onCompleteId = callbacks.register(() => {
-          resolve();
-        });
-
+        const { promise, resolve } = Promise.withResolvers<undefined>();
+        const onCompleteId = onCompleteCallbacks.register(resolve);
         dbWorker.postMessage({
           type: "reset",
           onCompleteId,
@@ -812,7 +874,7 @@ const createEvoluInstance =
       },
 
       reloadApp: () => {
-        appState.reset();
+        deps.reloadApp(reloadUrl);
       },
 
       ensureSchema: (schema) => {
@@ -822,22 +884,95 @@ const createEvoluInstance =
       },
 
       exportDatabase: () => {
-        const { promise, resolve } = Promise.withResolvers<Uint8Array>();
-        const onCompleteId = callbacks.register((arg) => {
-          if (arg instanceof Uint8Array) resolve(arg);
-        });
+        const { promise, resolve } =
+          Promise.withResolvers<Uint8Array<ArrayBuffer>>();
+        const onCompleteId = exportCallbacks.register(resolve);
         dbWorker.postMessage({ type: "export", onCompleteId });
         return promise;
       },
+
+      useOwner: (owner) => {
+        const scheduleOwnerQueueProcessing = () => {
+          if (useOwnerMicrotaskQueue.length !== 1) return;
+          queueMicrotask(() => {
+            const queue = [...useOwnerMicrotaskQueue];
+            useOwnerMicrotaskQueue.length = 0;
+
+            const result: Array<[SyncOwner, boolean, Uint8Array]> = [];
+            const skipIndices = new Set<number>();
+
+            for (let i = 0; i < queue.length; i++) {
+              if (skipIndices.has(i)) continue;
+
+              const [currentOwner, currentUse, currentOwnerSerialized] =
+                queue[i];
+
+              // Look for opposite action with same owner
+              for (let j = i + 1; j < queue.length; j++) {
+                if (skipIndices.has(j)) continue;
+
+                const [, otherUse, otherOwnerSerialized] = queue[j];
+
+                if (
+                  currentUse !== otherUse &&
+                  eqArrayNumber(currentOwnerSerialized, otherOwnerSerialized)
+                ) {
+                  // Found cancel-out pair, skip both
+                  skipIndices.add(i).add(j);
+                  break;
+                }
+              }
+
+              if (!skipIndices.has(i)) {
+                result.push([currentOwner, currentUse, currentOwnerSerialized]);
+              }
+            }
+
+            for (const [owner, use] of result) {
+              dbWorker.postMessage({ type: "useOwner", owner, use });
+            }
+          });
+        };
+
+        useOwnerMicrotaskQueue.push([owner, true, pack(owner)]);
+        scheduleOwnerQueueProcessing();
+
+        const unuse = () => {
+          useOwnerMicrotaskQueue.push([owner, false, pack(owner)]);
+          scheduleOwnerQueueProcessing();
+        };
+
+        return unuse;
+      },
+
+      /** Disposal is not implemented yet. */
+      [Symbol.dispose]: () => {
+        throw new Error("Evolu instance disposal is not yet implemented");
+      },
     };
 
     return evolu;
   };
 
-export const createNamespaceName =
-  (config: Config) =>
-  (name: string): string =>
-    `evolu:${config.name}:${name}`;
+export const createQuery = <R extends Row>(
+  queryCallback: Parameters<CreateQuery<EvoluSchema>>[0],
+  options?: Parameters<CreateQuery<EvoluSchema>>[1],
+): Query<R> => {
+  const compiledQuery = queryCallback(kysely as IntentionalNever).compile();
+
+  if (isSqlMutation(compiledQuery.sql))
+    throw new Error(
+      "SQL mutation (INSERT, UPDATE, DELETE, etc.) isn't allowed in the Evolu `createQuery` function. Kysely suggests it because there is no read-only Kysely yet, and removing such an API is not possible. For mutations, use Evolu Mutation API.",
+    );
+
+  return serializeQuery({
+    sql: compiledQuery.sql as SafeSql,
+    parameters: compiledQuery.parameters as NonNullable<
+      SqliteQuery["parameters"]
+    >,
+    ...(options && { options }),
+  });
+};
 
 interface LoadingPromises {
   get: <R extends Row>(
@@ -849,11 +984,13 @@ interface LoadingPromises {
 
   resolve: (query: Query, rows: ReadonlyArray<Row>) => void;
 
-  releaseUnsubscribed: () => void;
+  releaseUnsubscribedOnMutation: () => void;
+
+  getQueries: () => ReadonlyArray<Query>;
 }
 
 interface LoadingPromise {
-  /** Promise with props for the upcoming React use hook. */
+  /** Promise with props for the React use hook. */
   promise: Promise<QueryRows> & {
     status?: "pending" | "fulfilled" | "rejected";
     value?: QueryRows;
@@ -868,7 +1005,7 @@ const createLoadingPromises = (
 ): LoadingPromises => {
   const loadingPromiseMap = new Map<Query, LoadingPromise>();
 
-  const loadingPromises: LoadingPromises = {
+  return {
     get: <R extends Row>(
       query: Query<R>,
     ): {
@@ -895,16 +1032,13 @@ const createLoadingPromises = (
       if (loadingPromise.promise.status !== "fulfilled") {
         loadingPromise.resolve(rows);
       } else {
-        // A promise can't be fulfilled 2x, so we need a new one.
         loadingPromise.promise = Promise.resolve(rows);
       }
 
-      /**
-       * "For example, a data framework can set the status and value fields on a
-       * promise preemptively, before passing to React, so that React can unwrap
-       * it without waiting a microtask."
-       * https://github.com/acdlite/rfcs/blob/first-class-promises/text/0000-first-class-support-for-promises.md
-       */
+      // Set status and value fields for React's `use` Hook to unwrap synchronously.
+      // While undocumented in React docs, React still uses these properties internally,
+      // and Evolu's own promise caching logic depends on checking `promise.status`.
+      // https://github.com/acdlite/rfcs/blob/first-class-promises/text/0000-first-class-support-for-promises.md
       void Object.assign(loadingPromise.promise, {
         status: "fulfilled",
         value: rows,
@@ -915,14 +1049,7 @@ const createLoadingPromises = (
       }
     },
 
-    /**
-     * We can't delete loading promises in `resolveLoadingPromises` because they
-     * must be cached, so repeated calls to `loadQuery` will always return the
-     * same promise until the data changes, and we also can't cache them forever
-     * because only subscribed queries are automatically updated (reactivity is
-     * expensive) hence this function must be called manually on any mutation.
-     */
-    releaseUnsubscribed: () => {
+    releaseUnsubscribedOnMutation: () => {
       [...loadingPromiseMap.entries()]
         .filter(([query]) => !subscribedQueries.has(query))
         .forEach(([query, loadingPromise]) => {
@@ -933,18 +1060,7 @@ const createLoadingPromises = (
           }
         });
     },
-  };
 
-  return loadingPromises;
-};
-
-const assertValidDbChange: (dbChange: {
-  table: string;
-  id: Id;
-  values: unknown;
-}) => asserts dbChange is DbChange = (dbChange) => {
-  assert(
-    DbChange.is(dbChange),
-    `Failed to create DbChange for table "${dbChange.table}". If you see this message, you either disabled EvoluSchema validation or Evolu has a bug - please report it.`,
-  );
+    getQueries: () => Array.from(loadingPromiseMap.keys()),
+  };
 };