@lix-js/sdk 0.12.2 → 0.14.0

package/dist/lix.js

@@ -15,26 +15,44 @@ const observeFinalizer = new FinalizationRegistry(({ observe, onClose }) => {
 });
 export class Lix {
     binding;
+    openReport;
     closePromise;
     #activeBranchListeners = new Set();
     #inFlightOperations = new Set();
     #observations = new Map();
+    #snapshotExports = new Set();
     #nextObservationId = 0;
     #transactionsOpening = 0;
     #activeTransactions = 0;
     #acceptingOperations = true;
     constructor(binding) {
         this.binding = binding;
+        const report = binding.openReport?.();
+        this.openReport = report
+            ? Object.freeze({
+                ...report,
+                ...(report.migration
+                    ? { migration: Object.freeze({ ...report.migration }) }
+                    : {}),
+            })
+            : undefined;
+    }
+    /** Opens an independent session over the same repository storage. */
+    async openAnotherSession(options = {}) {
+        assertOpenAnotherSessionOptions(options);
+        return this.#runOperation(async () => new Lix(await this.binding.openAnotherSession(options)));
     }
     async execute(sql, params = [], options) {
         assertExecuteArgs("lix", sql, params, options);
-        return this.#runOperation(async () => wrapExecuteResult(await this.binding.execute(sql, params.map((param, index) => toNativeValue(normalizeParam(param, index))), options)));
+        const { rowMode = "object", ...bindingOptions } = options ?? {};
+        return this.#runOperation(async () => wrapExecuteResult(await this.binding.execute(sql, params.map((param, index) => toNativeValue(normalizeParam(param, index))), bindingOptions), rowMode));
     }
     async executeBatch(statements, options) {
         const normalizedStatements = normalizeBatchStatements(statements, options);
+        const { rowMode = "object", ...bindingOptions } = options ?? {};
         return this.#runOperation(async () => {
-            const results = await this.binding.executeBatch(normalizedStatements, options);
-            return results.map(wrapExecuteBatchResult);
+            const results = await this.binding.executeBatch(normalizedStatements, bindingOptions);
+            return results.map((result) => wrapExecuteBatchResult(result, rowMode));
         });
     }
     observe(sql, params = []) {
@@ -82,8 +100,90 @@ export class Lix {
     async createBranch(options) {
         return this.#runOperation(() => this.binding.createBranch(options));
     }
-    async createCheckpoint() {
-        return this.#runOperation(() => this.binding.createCheckpoint());
+    /** Streams a deterministic snapshot of the complete Lix. */
+    exportSnapshot() {
+        let snapshot;
+        const start = () => {
+            if (snapshot)
+                return snapshot;
+            let finish;
+            const completed = new Promise((resolve) => {
+                finish = resolve;
+            });
+            let resolveBinding;
+            let rejectBinding;
+            const binding = new Promise((resolve, reject) => {
+                resolveBinding = resolve;
+                rejectBinding = reject;
+            });
+            const operation = this.#runOperation(async () => {
+                try {
+                    const exportSnapshot = this.binding.exportSnapshot;
+                    if (!exportSnapshot) {
+                        const error = new Error("snapshot export is not available for remote Lix handles");
+                        error.name = "LixError";
+                        error.code = "LIX_UNSUPPORTED_STORAGE";
+                        throw error;
+                    }
+                    resolveBinding(exportSnapshot.call(this.binding));
+                    await completed;
+                }
+                catch (error) {
+                    rejectBinding(error);
+                    throw error;
+                }
+            });
+            // Pull observes setup errors through `binding`; this catch only prevents
+            // the lifecycle-tracking promise from becoming an unhandled rejection.
+            void operation.catch((error) => rejectBinding(error));
+            let finished = false;
+            let cancelPromise;
+            const active = {
+                binding,
+                finish: () => {
+                    if (finished)
+                        return;
+                    finished = true;
+                    this.#snapshotExports.delete(active);
+                    finish();
+                },
+                cancel: () => (cancelPromise ??= (async () => {
+                    try {
+                        await (await binding).cancel();
+                    }
+                    finally {
+                        active.finish();
+                    }
+                })()),
+            };
+            snapshot = active;
+            this.#snapshotExports.add(active);
+            return snapshot;
+        };
+        return new ReadableStream({
+            pull: async (controller) => {
+                const active = start();
+                const binding = await active.binding;
+                try {
+                    const chunk = await binding.next();
+                    if (chunk == null) {
+                        active.finish();
+                        controller.close();
+                        return;
+                    }
+                    controller.enqueue(chunk);
+                }
+                catch (error) {
+                    await active.cancel().catch(() => undefined);
+                    throw error;
+                }
+            },
+            cancel: async () => {
+                if (!snapshot)
+                    return;
+                await snapshot.cancel();
+            },
+        }, { highWaterMark: 0 });
     }
     async undo() {
         return this.#runOperation(() => this.binding.undo());
@@ -118,7 +218,10 @@ export class Lix {
     async close() {
         if (!this.closePromise) {
             if (this.#transactionsOpening > 0 || this.#activeTransactions > 0) {
-                throw activeTransactionCloseError();
+                const error = new Error("cannot close Lix while an explicit transaction is active");
+                error.name = "LixError";
+                error.code = "LIX_INVALID_TRANSACTION_STATE";
+                throw error;
             }
             // Flip the public lifecycle gate before the first await. Operations that
             // already entered the gate are allowed to finish; later calls fail closed.
@@ -128,6 +231,7 @@ export class Lix {
             }
             this.#observations.clear();
             this.closePromise = (async () => {
+                await Promise.allSettled([...this.#snapshotExports].map((snapshot) => snapshot.cancel()));
                 await Promise.allSettled([...this.#inFlightOperations]);
                 const results = await Promise.allSettled([
                     Promise.resolve().then(() => this.binding.close()),
@@ -161,11 +265,19 @@ export class Lix {
         throw error;
     }
 }
-function activeTransactionCloseError() {
-    const error = new Error("cannot close Lix while an explicit transaction is active");
-    error.name = "LixError";
-    error.code = "LIX_INVALID_TRANSACTION_STATE";
-    return error;
+function assertOpenAnotherSessionOptions(options) {
+    if (!options || typeof options !== "object" || Array.isArray(options)) {
+        throw new TypeError("openAnotherSession() options must be an object");
+    }
+    for (const [name, value] of [
+        ["branchId", options.branchId],
+        ["accountId", options.accountId],
+    ]) {
+        if (value !== undefined &&
+            (typeof value !== "string" || value.length === 0)) {
+            throw new TypeError(`openAnotherSession() ${name} must be a non-empty string`);
+        }
+    }
 }
 export class ObserveEvents {
     onClose;
@@ -221,7 +333,8 @@ export class LixTransaction {
     }
     async execute(sql, params = [], options) {
         assertExecuteArgs("lixTransaction", sql, params, options);
-        return wrapExecuteResult(await this.binding.execute(sql, params.map((param, index) => toNativeValue(normalizeParam(param, index))), options));
+        const { rowMode = "object", ...bindingOptions } = options ?? {};
+        return wrapExecuteResult(await this.binding.execute(sql, params.map((param, index) => toNativeValue(normalizeParam(param, index))), bindingOptions), rowMode);
     }
     async commit() {
         return this.finish("transaction.commit");
@@ -274,6 +387,11 @@ function assertExecuteArgs(receiver, sql, params, options) {
         typeof options.idempotencyKey !== "string") {
         throw invalidArgument("execute", "options.idempotencyKey", "string", typeof options.idempotencyKey, receiver);
     }
+    if (options.rowMode !== undefined &&
+        options.rowMode !== "object" &&
+        options.rowMode !== "array") {
+        throw invalidArgument("execute", "options.rowMode", '"object" | "array"', typeof options.rowMode, receiver);
+    }
 }
 function assertSqlArgs(operation, receiver, sql, params) {
     if (typeof sql !== "string") {
@@ -334,6 +452,11 @@ function assertBatchOptions(options) {
         typeof options.idempotencyKey !== "string") {
         throw invalidArgument("executeBatch", "options.idempotencyKey", "string", typeof options.idempotencyKey);
     }
+    if (options.rowMode !== undefined &&
+        options.rowMode !== "object" &&
+        options.rowMode !== "array") {
+        throw invalidArgument("lix.executeBatch", "options.rowMode", '"object" | "array"', typeof options.rowMode);
+    }
 }
 function withBatchStatementIndex(error, statementIndex) {
     if (!error || typeof error !== "object")

package/dist/open-lix.d.ts

@@ -1,8 +1,7 @@
 import { Lix } from "./lix.js";
-import type { IndexedDbStorageOptions, OpenLixOptions } from "./types.js";
+import type { OpenLixOptions } from "./types.js";
 export { Lix, LixTransaction, ObserveEvents } from "./lix.js";
-export declare class IndexedDbStorage {
-    readonly name: string;
-    constructor(options: IndexedDbStorageOptions);
-}
 export declare function openLix(options?: OpenLixOptions): Promise<Lix>;
+export declare namespace openLix {
+    function fromSnapshot(source: ReadableStream<Uint8Array> | Uint8Array, options?: OpenLixOptions): Promise<Lix>;
+}

package/dist/open-lix.js

@@ -1,18 +1,11 @@
 import { Lix } from "./lix.js";
-import { isLixStorage } from "./storage-adapter.js";
+import { isJsProviderLixStorage, isLixStorage, } from "./storage-adapter.js";
 export { Lix, LixTransaction, ObserveEvents } from "./lix.js";
 const openStorages = new WeakSet();
-const openIndexedDbStorageNames = new Set();
-export class IndexedDbStorage {
-    name;
-    constructor(options) {
-        if (!options || typeof options.name !== "string" || options.name.length === 0) {
-            throw new TypeError("IndexedDbStorage requires a non-empty name");
-        }
-        this.name = options.name;
-    }
+export function openLix(options = {}) {
+    return openLixInternal(options);
 }
-export async function openLix(options = {}) {
+async function openLixInternal(options, snapshot) {
     if (!options || typeof options !== "object") {
         throw new TypeError("openLix() options must be an object");
     }
@@ -24,16 +17,52 @@ export async function openLix(options = {}) {
             typeof options.telemetry.onSpan !== "function")) {
         throw new TypeError("openLix() telemetry requires an onSpan callback");
     }
+    if (options.telemetry?.parentContext !== undefined &&
+        typeof options.telemetry.parentContext !== "function") {
+        throw new TypeError("openLix() telemetry parentContext must be a context provider function");
+    }
+    if (options.onProgress !== undefined &&
+        typeof options.onProgress !== "function") {
+        throw new TypeError("openLix() onProgress must be a function");
+    }
     if (options.server !== undefined) {
-        const { openRemoteLixBinding } = await import("./remote/client.js");
-        if ("storage" in options && options.storage !== undefined) {
-            throw new TypeError("openLix() remote mode does not accept storage");
+        if (snapshot) {
+            throw new TypeError("openLix.fromSnapshot() does not accept server mode");
+        }
+        if (options.server.mode === "remote") {
+            const { openRemoteLixBinding } = await import("./remote/client.js");
+            if ("storage" in options && options.storage !== undefined) {
+                throw new TypeError("openLix() remote mode does not accept storage");
+            }
+            return new Lix(await openRemoteLixBinding(options.server));
+        }
+    }
+    const syncServer = options.server?.mode === "sync"
+        ? {
+            url: new URL(options.server.url).toString(),
+            headers: options.server.headers,
+            fetch: options.server.fetch,
         }
-        return new Lix(await openRemoteLixBinding(options.server));
+        : undefined;
+    if (syncServer?.fetch !== undefined && typeof syncServer.fetch !== "function") {
+        throw new TypeError("openLix() sync server fetch must be a function");
+    }
+    if (syncServer?.headers !== undefined && typeof syncServer.headers !== "function") {
+        // Validate static headers before opening a worker/native runtime.
+        new Headers(syncServer.headers);
+    }
+    if (options.server !== undefined && syncServer === undefined) {
+        throw new TypeError("openLix() server mode must be 'remote' or 'sync'");
+    }
+    if (syncServer !== undefined && options.storage === undefined) {
+        throw new TypeError("openLix() sync mode requires a durability-capable storage adapter");
     }
     const { openLixWorkerBinding } = await import("./worker/client.js");
     if (options.storage === undefined) {
-        return new Lix(await openLixWorkerBinding({ kind: "memory" }, undefined, options.telemetry));
+        return new Lix(await openLixWorkerBinding({ kind: "memory" }, undefined, options.telemetry, syncServer, options.onProgress, snapshot));
+    }
+    if (isJsProviderLixStorage(options.storage)) {
+        return openJsProviderStorage(options.storage, options.telemetry, syncServer, options.onProgress, snapshot);
     }
     if (isLixStorage(options.storage)) {
         const storage = options.storage;
@@ -47,12 +76,13 @@ export async function openLix(options = {}) {
             openStorages.delete(storage);
         };
         try {
-            binding = await openLixWorkerBinding(storage.lixStorage.config, disconnect, options.telemetry);
+            binding = await openLixWorkerBinding(storage.lixStorage.config, disconnect, options.telemetry, syncServer, options.onProgress, snapshot);
+            const routed = routeStorageBinding(binding);
             storage.lixStorage.connect({
-                importFilesystemPaths: (paths) => binding.importFilesystemPaths(paths),
-                syncDiskToLix: () => binding.syncDiskToLix(),
+                importFilesystemPaths: (paths) => routed.current().importFilesystemPaths(paths),
+                syncDiskToLix: () => routed.current().syncDiskToLix(),
             });
-            return new Lix(binding);
+            return new Lix(routed.binding);
         }
         catch (error) {
             disconnect();
@@ -60,25 +90,135 @@ export async function openLix(options = {}) {
             throw error;
         }
     }
-    if (options.storage instanceof IndexedDbStorage) {
-        const storage = options.storage;
-        const databaseName = storage.name;
-        if (openIndexedDbStorageNames.has(databaseName)) {
-            throw new Error("IndexedDbStorage is already open");
-        }
-        openIndexedDbStorageNames.add(databaseName);
-        let binding;
+    throw new TypeError("openLix() requires a Lix storage adapter");
+}
+function routeStorageBinding(root) {
+    const live = new Set();
+    const wrap = (binding) => {
+        live.add(binding);
+        return new Proxy(binding, {
+            get(target, property, receiver) {
+                if (property === "openAnotherSession") {
+                    return async (options) => wrap(await target.openAnotherSession(options));
+                }
+                if (property === "close") {
+                    return async () => {
+                        try {
+                            await target.close();
+                        }
+                        finally {
+                            live.delete(target);
+                        }
+                    };
+                }
+                const value = Reflect.get(target, property, receiver);
+                return typeof value === "function" ? value.bind(target) : value;
+            },
+        });
+    };
+    return {
+        binding: wrap(root),
+        current: () => {
+            const bindings = [...live];
+            return bindings[bindings.length - 1] ?? root;
+        },
+    };
+}
+async function openJsProviderStorage(storage, telemetry, syncServer, onProgress, snapshot) {
+    const { openLixWorkerBinding } = await import("./worker/client.js");
+    if (openStorages.has(storage))
+        throw storageAlreadyOpen();
+    openStorages.add(storage);
+    let binding;
+    try {
+        const opened = await openLixWorkerBinding({
+            kind: "jsStorage",
+            moduleUrl: storage.lixStorage.moduleUrl,
+            options: storage.lixStorage.options,
+        }, () => openStorages.delete(storage), telemetry, syncServer, onProgress, snapshot);
+        binding = opened;
+        return new Lix(opened);
+    }
+    catch (error) {
+        openStorages.delete(storage);
+        await binding?.close().catch(() => undefined);
+        throw error;
+    }
+}
+(function (openLix) {
+    async function fromSnapshot(source, options = {}) {
+        const prepared = prepareSnapshotSource(source);
         try {
-            binding = await openLixWorkerBinding({ kind: "indexedDb", name: databaseName }, () => openIndexedDbStorageNames.delete(databaseName), options.telemetry);
-            return new Lix(binding);
+            return await openLixInternal(options, prepared.stream);
         }
         catch (error) {
-            openIndexedDbStorageNames.delete(databaseName);
-            await binding?.close().catch(() => undefined);
+            await prepared.cancel(error);
             throw error;
         }
     }
-    throw new TypeError("openLix() requires a Lix storage adapter or IndexedDbStorage");
+    openLix.fromSnapshot = fromSnapshot;
+})(openLix || (openLix = {}));
+function prepareSnapshotSource(source) {
+    if (source instanceof Uint8Array) {
+        let sent = false;
+        const stream = new ReadableStream({
+            pull(controller) {
+                if (!sent) {
+                    sent = true;
+                    controller.enqueue(source);
+                }
+                controller.close();
+            },
+        }, { highWaterMark: 0 });
+        return {
+            stream,
+            cancel: async (reason) => {
+                await stream.cancel(reason).catch(() => undefined);
+            },
+        };
+    }
+    if (!source || typeof source.getReader !== "function") {
+        throw new TypeError("openLix.fromSnapshot() requires a ReadableStream<Uint8Array> or Uint8Array");
+    }
+    // Acquire the caller's stream before openLixInternal can start a native or
+    // worker restore. A locked source therefore fails without creating backend work.
+    const reader = source.getReader();
+    let released = false;
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        reader.releaseLock();
+    };
+    const cancel = async (reason) => {
+        if (released)
+            return;
+        try {
+            await reader.cancel(reason);
+        }
+        finally {
+            release();
+        }
+    };
+    const stream = new ReadableStream({
+        async pull(controller) {
+            try {
+                const result = await reader.read();
+                if (result.done) {
+                    release();
+                    controller.close();
+                    return;
+                }
+                controller.enqueue(result.value);
+            }
+            catch (error) {
+                release();
+                controller.error(error);
+            }
+        },
+        cancel,
+    }, { highWaterMark: 0 });
+    return { stream, cancel };
 }
 function storageAlreadyOpen() {
     const error = new Error("openLix() storage is already open; close the existing Lix or create a new storage adapter");

package/dist/remote/client.d.ts

@@ -1,8 +1,7 @@
 import type { LixBinding } from "../binding-types.js";
 import type { RemoteLixServerOptions } from "../types.js";
-import { type ServerProtocolHandshakeRequest } from "./server-protocol.js";
 type RemoteLixClientOptions = {
-    initialActiveBranchId?: ServerProtocolHandshakeRequest["activeBranchId"];
+    initialActiveBranchId?: string;
 };
 export declare function openRemoteLixBinding(options: RemoteLixServerOptions, clientOptions?: RemoteLixClientOptions): Promise<LixBinding>;
 export {};