@evolu/common 6.0.1-preview.9 → 7.0.0

package/dist/src/Evolu/Evolu.js

@@ -1,39 +1,30 @@
-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 { eqArrayNumber } from "../Eq.js";
 import { exhaustiveCheck } from "../Function.js";
+import { createInstances } from "../Instances.js";
 import { err, ok } from "../Result.js";
-import { isSqlMutation } from "../Sqlite.js";
+import { isSqlMutation, SqliteBoolean, } from "../Sqlite.js";
 import { createStore } from "../Store.js";
 import { createId, } from "../Type.js";
-import { defaultConfig } from "./Config.js";
+import { defaultDbConfig } from "./Db.js";
 import { applyPatches } from "./Diff.js";
-import { kysely } from "./Kysely.js";
-import { DbChange, } from "./Protocol.js";
 import { createSubscribedQueries, emptyRows, serializeQuery, } from "./Query.js";
-import { evoluSchemaToDbSchema, insertable, updateable, upsertable, } from "./Schema.js";
+import { evoluSchemaToDbSchema, insertable, kysely, updateable, upsertable, } from "./Schema.js";
+import { DbChange } from "./Storage.js";
 import { initialSyncState } from "./Sync.js";
-// For hot reloading and Evolu multitenancy.
-const evoluInstances = new Map();
+const evoluInstances = createInstances();
+/**
+ * Unique identifier for the current browser tab or app instance, lazily
+ * initialized on first use to distinguish between multiple tabs.
+ */
 let tabId = 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
  *
@@ -62,59 +53,66 @@ let tabId = 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) => (schema, partialConfig = {}) => {
-    const config = { ...defaultConfig, ...partialConfig };
-    let evolu = evoluInstances.get(config.name);
-    if (evolu == null) {
-        evolu = createEvoluInstance(deps)(schema, config);
-        evoluInstances.set(config.name, evolu);
-    }
-    else {
-        // Hot reloading. Note that indexes are intentionally omitted.
-        evolu.ensureSchema(schema);
-    }
-    return evolu;
-};
-const createEvoluInstance = (deps) => (schema, evoluConfig) => {
-    deps.console.enabled = evoluConfig.enableLogging ?? false;
-    deps.console.log("[evolu]", "createEvoluInstance");
-    const { initialData, indexes, ...config } = evoluConfig;
+export const createEvolu = (deps) => (schema, config) => evoluInstances.ensure(config?.name ?? defaultDbConfig.name, () => createEvoluInstance(deps)(schema, config), (evolu) => {
+    // Hot reloading. Note that indexes are intentionally omitted.
+    evolu.ensureSchema(schema);
+});
+const createEvoluInstance = (deps) => (schema, config) => {
+    deps.console.enabled = config?.enableLogging ?? false;
+    const { indexes, reloadUrl = "/", ...partialDbConfig } = config ?? {};
+    const dbConfig = { ...defaultDbConfig, ...partialDbConfig };
+    deps.console.log("[evolu]", "createEvoluInstance", {
+        name: dbConfig.name,
+    });
     const errorStore = createStore(null);
     const rowsStore = createStore(new Map());
-    const ownerStore = createStore(null);
-    const syncStore = createStore(initialSyncState);
+    const { promise: appOwner, resolve: resolveAppOwner } = Promise.withResolvers();
+    if (config?.externalAppOwner) {
+        resolveAppOwner(config.externalAppOwner);
+    }
+    // TODO: Update it for the owner-api
+    const _syncStore = createStore(initialSyncState);
     const subscribedQueries = createSubscribedQueries(rowsStore);
     const loadingPromises = createLoadingPromises(subscribedQueries);
-    const callbacks = createCallbacks(deps);
-    const appState = deps.createAppState(config);
-    const dbWorker = deps.createDbWorker(config.name);
+    const onCompleteCallbacks = createCallbacks(deps);
+    const exportCallbacks = createCallbacks(deps);
+    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);
-                break;
-            }
             case "onError": {
                 errorStore.set(message.error);
                 break;
             }
-            case "onChange": {
+            case "onGetAppOwner": {
+                resolveAppOwner(message.appOwner);
+                break;
+            }
+            case "onQueryPatches": {
                 if (message.tabId !== getTabId())
                     return;
                 const state = rowsStore.get();
                 const nextState = new Map([
                     ...state,
-                    ...message.patches.map(({ query, patches }) => [
+                    ...message.queryPatches.map(({ query, patches }) => [
                         query,
                         applyPatches(patches, state.get(query) ?? emptyRows),
                     ]),
                 ]);
-                for (const { query } of message.patches) {
+                for (const { query } of message.queryPatches) {
                     loadingPromises.resolve(query, nextState.get(query) ?? emptyRows);
                 }
                 if (deps.flushSync && message.onCompleteIds.length > 0) {
@@ -126,15 +124,19 @@ const createEvoluInstance = (deps) => (schema, evoluConfig) => {
                     rowsStore.set(nextState);
                 }
                 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 });
                 }
@@ -142,15 +144,15 @@ const createEvoluInstance = (deps) => (schema, evoluConfig) => {
             }
             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);
                 break;
             }
             default:
@@ -173,110 +175,86 @@ const createEvoluInstance = (deps) => (schema, evoluConfig) => {
         }
         return type;
     };
-    const initialDataDbChanges = [];
-    /**
-     * 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,
-        dbSchema,
-        initialData: initialDataDbChanges,
-    });
+    dbWorker.postMessage({ type: "init", config: dbConfig, dbSchema });
+    // We can't use `init` to get AppOwner because `init` runs only once per n tabs.
+    dbWorker.postMessage({ type: "getAppOwner" });
     const loadQueryMicrotaskQueue = [];
     const mutateMicrotaskQueue = [];
+    const useOwnerMicrotaskQueue = [];
     const createMutation = (kind) => (table, props, options) => {
-        const Type = getMutationType(table, kind);
-        const result = Type.fromUnknown(props);
+        const result = getMutationType(table, kind).fromUnknown(props);
         const id = kind === "insert"
             ? createId(deps)
             : props.id;
         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 = [];
-                    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));
-                    loadingPromises.releaseUnsubscribed();
-                    if (isNonEmptyArray(changes))
-                        dbWorker.postMessage({
-                            type: "mutate",
-                            tabId: getTabId(),
-                            changes,
-                            onCompleteIds,
-                            subscribedQueries: subscribedQueries.get(),
-                        });
+                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,
                 });
+                mutateMicrotaskQueue.push([
+                    { ...dbChange, ownerId: options?.ownerId },
+                    options?.onComplete,
+                ]);
+            }
+            if (mutateMicrotaskQueue.length === 1) {
+                queueMicrotask(processMutationQueue);
+            }
         }
         if (result.ok)
             return ok({ id });
         return err(result.error);
     };
+    const processMutationQueue = () => {
+        const changes = [];
+        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 = {
         subscribeError: errorStore.subscribe,
         getError: errorStore.get,
-        createQuery: (queryCallback, options) => {
-            const compiledQuery = queryCallback(kysely).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,
-                parameters: compiledQuery.parameters,
-                ...(options && { options }),
-            });
-        },
+        createQuery,
         loadQuery: (query) => {
             const { promise, isNew } = loadingPromises.get(query);
             if (isNew) {
                 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(),
@@ -304,20 +282,16 @@ const createEvoluInstance = (deps) => (schema, evoluConfig) => {
             };
         },
         getQueryRows: (query) => (rowsStore.get().get(query) ?? emptyRows),
-        subscribeAppOwner: ownerStore.subscribe,
-        getAppOwner: ownerStore.get,
-        subscribeSyncState: syncStore.subscribe,
-        getSyncState: syncStore.get,
+        appOwner,
+        // 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();
-            const onCompleteId = callbacks.register(() => {
-                resolve();
-            });
+            const onCompleteId = onCompleteCallbacks.register(resolve);
             dbWorker.postMessage({
                 type: "reset",
                 onCompleteId,
@@ -326,12 +300,8 @@ const createEvoluInstance = (deps) => (schema, evoluConfig) => {
             return promise;
         },
         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();
-            const onCompleteId = callbacks.register(() => {
-                resolve();
-            });
+            const onCompleteId = onCompleteCallbacks.register(resolve);
             dbWorker.postMessage({
                 type: "reset",
                 onCompleteId,
@@ -341,7 +311,7 @@ const createEvoluInstance = (deps) => (schema, evoluConfig) => {
             return promise;
         },
         reloadApp: () => {
-            appState.reset();
+            deps.reloadApp(reloadUrl);
         },
         ensureSchema: (schema) => {
             mutationTypesCache.clear();
@@ -350,20 +320,72 @@ const createEvoluInstance = (deps) => (schema, evoluConfig) => {
         },
         exportDatabase: () => {
             const { promise, resolve } = Promise.withResolvers();
-            const onCompleteId = callbacks.register((arg) => {
-                if (arg instanceof Uint8Array)
-                    resolve(arg);
-            });
+            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 = [];
+                    const skipIndices = new Set();
+                    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) => (name) => `evolu:${config.name}:${name}`;
+export const createQuery = (queryCallback, options) => {
+    const compiledQuery = queryCallback(kysely).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,
+        parameters: compiledQuery.parameters,
+        ...(options && { options }),
+    });
+};
 const createLoadingPromises = (subscribedQueries) => {
     const loadingPromiseMap = new Map();
-    const loadingPromises = {
+    return {
         get: (query) => {
             let loadingPromise = loadingPromiseMap.get(query);
             const isNew = !loadingPromise;
@@ -385,15 +407,12 @@ const createLoadingPromises = (subscribedQueries) => {
                 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,
@@ -402,14 +421,7 @@ const createLoadingPromises = (subscribedQueries) => {
                 loadingPromiseMap.delete(query);
             }
         },
-        /**
-         * 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]) => {
@@ -421,9 +433,6 @@ const createLoadingPromises = (subscribedQueries) => {
                 }
             });
         },
+        getQueries: () => Array.from(loadingPromiseMap.keys()),
     };
-    return loadingPromises;
-};
-const assertValidDbChange = (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.`);
 };

package/dist/src/Evolu/Internal.d.ts

@@ -9,11 +9,9 @@
  *
  * @module
  */
-export * from "./Config.js";
 export * from "./Db.js";
 export * from "./Diff.js";
 export * from "./Evolu.js";
-export * from "./Kysely.js";
 export * from "./Owner.js";
 export * from "./Platform.js";
 export * from "./Protocol.js";

package/dist/src/Evolu/Internal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Internal.d.ts","sourceRoot":"","sources":["../../../src/Evolu/Internal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"Internal.d.ts","sourceRoot":"","sources":["../../../src/Evolu/Internal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC"}

package/dist/src/Evolu/Internal.js

@@ -9,11 +9,9 @@
  *
  * @module
  */
-export * from "./Config.js";
 export * from "./Db.js";
 export * from "./Diff.js";
 export * from "./Evolu.js";
-export * from "./Kysely.js";
 export * from "./Owner.js";
 export * from "./Platform.js";
 export * from "./Protocol.js";