@lix-js/sdk 0.12.3 → 0.15.0

package/dist/worker/factory.browser.d.ts

@@ -1,4 +1,4 @@
-import type { LixBinding, LixStorageConfig, TelemetryDispatch } from "../binding-types.js";
+import type { LixBinding, LixStorageConfig, TelemetryDispatch, TelemetryParentContext, OpenProgressDispatch, SyncServerBindingOptions } from "../binding-types.js";
 import type { WorkerConnection } from "./protocol.js";
-export declare const openDirectLixBinding: undefined | ((storage: LixStorageConfig, telemetry?: TelemetryDispatch) => Promise<LixBinding>);
+export declare const openDirectLixBinding: undefined | ((storage: LixStorageConfig, telemetry?: TelemetryDispatch, telemetryParent?: TelemetryParentContext, server?: SyncServerBindingOptions, openProgress?: OpenProgressDispatch, snapshot?: ReadableStream<Uint8Array>) => Promise<LixBinding>);
 export declare function createWorkerConnection(): WorkerConnection;

package/dist/worker/factory.node.d.ts

@@ -1,5 +1,5 @@
-import type { LixBinding, LixStorageConfig, TelemetryDispatch } from "../binding-types.js";
+import type { LixBinding, LixStorageConfig, SyncServerBindingOptions, TelemetryDispatch, TelemetryParentContext, OpenProgressDispatch } from "../binding-types.js";
 import type { WorkerConnection } from "./protocol.js";
 export declare function createWorkerConnection(): WorkerConnection;
 export declare function workerExecArgv(execArgv: readonly string[]): string[];
-export declare const openDirectLixBinding: (storage: LixStorageConfig, telemetry?: TelemetryDispatch) => Promise<LixBinding | undefined>;
+export declare const openDirectLixBinding: (storage: LixStorageConfig, telemetry?: TelemetryDispatch, telemetryParent?: TelemetryParentContext, server?: SyncServerBindingOptions, openProgress?: OpenProgressDispatch, snapshot?: ReadableStream<Uint8Array>) => Promise<LixBinding | undefined>;

package/dist/worker/factory.node.js

@@ -1,5 +1,5 @@
 import { Worker } from "node:worker_threads";
-import { openNativeLixBinding } from "../binding.node.js";
+import { openLixBinding } from "../binding.node.js";
 export function createWorkerConnection() {
     const worker = new Worker(new URL("./entry.node.js", import.meta.url), {
         name: "lix",
@@ -52,13 +52,6 @@ export function workerExecArgv(execArgv) {
 /// Native Lix already owns a dedicated serialized engine actor. Routing it
 /// through a second JavaScript worker adds two message-port hops per query
 /// without adding isolation or concurrency.
-export const openDirectLixBinding = async (storage, telemetry) => {
-    try {
-        return await openNativeLixBinding(storage, telemetry);
-    }
-    catch (error) {
-        if (storage.kind === "memory")
-            return undefined;
-        throw error;
-    }
+export const openDirectLixBinding = async (storage, telemetry, telemetryParent, server, openProgress, snapshot) => {
+    return openLixBinding(storage, telemetry, telemetryParent, server, openProgress, snapshot);
 };

package/dist/worker/host.d.ts

@@ -1,2 +1,4 @@
-import { type WorkerHostEndpoint } from "./protocol.js";
-export declare function startWorkerHost(endpoint: WorkerHostEndpoint): void;
+import { openLixBinding } from "#binding";
+import { type WorkerHostEndpoint, type WorkerSyncFetchResponse } from "./protocol.js";
+export declare function startWorkerHost(endpoint: WorkerHostEndpoint, openBinding?: typeof openLixBinding): void;
+export declare function responseFromSyncFetch(resolved: WorkerSyncFetchResponse): Response;

package/dist/worker/host.js

@@ -1,24 +1,77 @@
 import { openLixBinding } from "#binding";
-import { serializeWorkerError, } from "./protocol.js";
-export function startWorkerHost(endpoint) {
-    let lix;
+import { deserializeWorkerError, serializeWorkerError, } from "./protocol.js";
+export function startWorkerHost(endpoint, openBinding = openLixBinding) {
+    const sessions = new Map();
+    let nextSessionId = 1;
     let nextTransactionId = 1;
     let nextObserveId = 1;
     const transactions = new Map();
     const observations = new Map();
+    let nextSnapshotExportId = 1;
+    const snapshotExports = new Map();
+    const snapshotInputs = new Map();
+    let nextSyncRequestId = 1;
+    const pendingSyncHeaders = new Map();
+    const pendingSyncFetch = new Map();
+    const pendingSyncStreamPulls = new Map();
+    const syncStreamCleanup = new Map();
     let finiteQueue = Promise.resolve();
     endpoint.onMessage((message) => {
         if (!("id" in message)) {
             handleNotification(message);
             return;
         }
-        if (message.operation.kind === "observe.next") {
-            const observeId = message.operation.observeId;
-            void respond(message, () => handleObserveNext(observeId));
+        if (message.operation.kind === "openSnapshot.write" ||
+            message.operation.kind === "openSnapshot.finish") {
+            const operation = message.operation;
+            void respond(message, () => handleSnapshotInput(operation));
+            return;
+        }
+        if (message.operation.kind === "open" &&
+            message.operation.snapshotId !== undefined) {
+            ensureSnapshotInput(message.operation.snapshotId);
+        }
+        if (message.operation.kind === "observe.next" ||
+            message.operation.kind === "exportSnapshot.next" ||
+            message.operation.kind === "exportSnapshot.cancel") {
+            if (message.operation.kind === "observe.next") {
+                const observeId = message.operation.observeId;
+                void respond(message, () => handleObserveNext(observeId, message.telemetryParent));
+            }
+            else if (message.operation.kind === "exportSnapshot.next") {
+                const exportId = message.operation.exportId;
+                void respond(message, () => handleSnapshotNext(exportId));
+            }
+            else {
+                const exportId = message.operation.exportId;
+                void respond(message, () => handleSnapshotCancel(exportId));
+            }
+            return;
+        }
+        if (message.operation.kind === "observe") {
+            const operation = message.operation;
+            // Observation setup is metadata-only. Keeping it behind the global
+            // finite-operation queue lets an authority mutation that is waiting for
+            // local publication block a newly mounted server-first History query.
+            // The live `next()` lane is already independent for the same reason.
+            void respond(message, () => handleObserveRegistration(message.sessionId, operation.sql, operation.params));
             return;
         }
         finiteQueue = finiteQueue.then(async () => {
-            await respond(message, () => handleFiniteOperation(message.operation));
+            try {
+                await respond(message, async () => {
+                    if (message.operation.kind !== "open") {
+                        requiredLix(message.sessionId).setTelemetryParent(message.telemetryParent);
+                    }
+                    return handleFiniteOperation(message.sessionId, message.operation, message.telemetryParent);
+                });
+            }
+            finally {
+                // The mutable FFI carrier is safe only within this serialized
+                // operation. Clear it before another request or background task
+                // can accidentally inherit a stale remote parent.
+                (sessions.get(message.sessionId) ?? sessions.get(0))?.setTelemetryParent();
+            }
         });
     });
     function handleNotification(message) {
@@ -29,6 +82,13 @@ export function startWorkerHost(endpoint) {
                 events?.close();
                 break;
             }
+            case "openSnapshot.cancel": {
+                const input = snapshotInputs.get(message.snapshotId);
+                snapshotInputs.delete(message.snapshotId);
+                if (input)
+                    void input.writer.abort().catch(() => undefined);
+                break;
+            }
             case "transaction.abandon":
                 finiteQueue = finiteQueue.then(async () => {
                     const transaction = transactions.get(message.transactionId);
@@ -37,8 +97,57 @@ export function startWorkerHost(endpoint) {
                         await transaction.rollback().catch(() => undefined);
                 });
                 break;
+            case "sync.headers.result": {
+                const pending = pendingSyncHeaders.get(message.requestId);
+                pendingSyncHeaders.delete(message.requestId);
+                if (!pending)
+                    break;
+                if (message.result.ok)
+                    pending.resolve(message.result.headers);
+                else
+                    pending.reject(deserializeWorkerError(message.result.error));
+                break;
+            }
+            case "sync.fetch.result": {
+                const pending = pendingSyncFetch.get(message.requestId);
+                pendingSyncFetch.delete(message.requestId);
+                if (!pending)
+                    break;
+                if (message.result.ok)
+                    pending.resolve(message.result.response);
+                else
+                    pending.reject(deserializeWorkerError(message.result.error));
+                break;
+            }
+            case "sync.fetch.stream.result": {
+                const pending = pendingSyncStreamPulls.get(message.requestId);
+                pendingSyncStreamPulls.delete(message.requestId);
+                if (!pending)
+                    break;
+                if (!message.result.ok) {
+                    const error = deserializeWorkerError(message.result.error);
+                    pending.controller.error(error);
+                    pending.reject(error);
+                    finishSyncStream(message.requestId);
+                }
+                else if (message.result.done) {
+                    pending.controller.close();
+                    pending.resolve();
+                    finishSyncStream(message.requestId);
+                }
+                else {
+                    pending.controller.enqueue(message.result.chunk);
+                    pending.resolve();
+                }
+                break;
+            }
         }
     }
+    function finishSyncStream(requestId) {
+        const cleanup = syncStreamCleanup.get(requestId);
+        syncStreamCleanup.delete(requestId);
+        cleanup?.();
+    }
     async function respond(request, operation) {
         try {
             const value = await operation();
@@ -52,21 +161,45 @@ export function startWorkerHost(endpoint) {
             });
         }
     }
-    async function handleFiniteOperation(operation) {
+    async function handleFiniteOperation(sessionId, operation, telemetryParent) {
         switch (operation.kind) {
             case "open":
-                if (lix)
+                if (sessions.size > 0)
                     throw workerStateError("Lix worker is already open");
-                lix = await openLixBinding(operation.storage, operation.telemetryEnabled
-                    ? (span) => endpoint.postMessage({ kind: "telemetry", span })
-                    : undefined);
-                return undefined;
+                {
+                    const snapshot = operation.snapshotId === undefined
+                        ? undefined
+                        : requiredSnapshotInput(operation.snapshotId).readable;
+                    try {
+                        const opened = await openBinding(operation.storage, operation.telemetryEnabled
+                            ? (span) => endpoint.postMessage({ kind: "telemetry", span })
+                            : undefined, telemetryParent, createSyncServerBridge(operation.server), operation.progressEnabled
+                            ? (progress) => endpoint.postMessage({ kind: "open.progress", progress })
+                            : undefined, snapshot);
+                        sessions.set(0, opened);
+                        return opened.openReport?.();
+                    }
+                    finally {
+                        if (operation.snapshotId !== undefined) {
+                            snapshotInputs.delete(operation.snapshotId);
+                        }
+                    }
+                }
+            case "openSnapshot.write":
+            case "openSnapshot.finish":
+                throw workerStateError("snapshot input uses the restore lane");
+            case "openAnotherSession": {
+                const opened = await requiredLix(sessionId).openAnotherSession(operation.options);
+                const openedSessionId = nextSessionId++;
+                sessions.set(openedSessionId, opened);
+                return openedSessionId;
+            }
             case "execute":
-                return requiredLix().execute(operation.sql, operation.params, operation.options);
+                return requiredLix(sessionId).execute(operation.sql, operation.params, operation.options);
             case "executeBatch":
-                return requiredLix().executeBatch(operation.statements, operation.options);
+                return requiredLix(sessionId).executeBatch(operation.statements, operation.options);
             case "beginTransaction": {
-                const transaction = await requiredLix().beginTransaction();
+                const transaction = await requiredLix(sessionId).beginTransaction();
                 const transactionId = nextTransactionId++;
                 transactions.set(transactionId, transaction);
                 return transactionId;
@@ -86,56 +219,247 @@ export function startWorkerHost(endpoint) {
                 return undefined;
             }
             case "activeBranchId":
-                return requiredLix().activeBranchId();
+                return requiredLix(sessionId).activeBranchId();
             case "activeAccountId":
-                return requiredLix().activeAccountId();
+                return requiredLix(sessionId).activeAccountId();
             case "createBranch":
-                return requiredLix().createBranch(operation.options);
-            case "createCheckpoint":
-                return requiredLix().createCheckpoint();
+                return requiredLix(sessionId).createBranch(operation.options);
             case "undo":
-                return requiredLix().undo();
+                return requiredLix(sessionId).undo();
             case "redo":
-                return requiredLix().redo();
+                return requiredLix(sessionId).redo();
             case "switchBranch":
-                return requiredLix().switchBranch(operation.options);
+                return requiredLix(sessionId).switchBranch(operation.options);
             case "mergeBranchPreview":
-                return requiredLix().mergeBranchPreview(operation.options);
+                return requiredLix(sessionId).mergeBranchPreview(operation.options);
             case "mergeBranch":
-                return requiredLix().mergeBranch(operation.options);
+                return requiredLix(sessionId).mergeBranch(operation.options);
             case "importFilesystemPaths":
-                return requiredLix().importFilesystemPaths(operation.paths);
+                return requiredLix(sessionId).importFilesystemPaths(operation.paths);
             case "syncDiskToLix":
-                return requiredLix().syncDiskToLix();
-            case "observe": {
-                const events = await requiredLix().observe(operation.sql, operation.params);
-                const observeId = nextObserveId++;
-                observations.set(observeId, events);
-                return observeId;
-            }
+                return requiredLix(sessionId).syncDiskToLix();
+            case "exportSnapshot":
+                {
+                    const binding = requiredLix(sessionId);
+                    const exportSnapshot = binding.exportSnapshot;
+                    if (!exportSnapshot) {
+                        throw workerStateError("this Lix binding cannot export snapshots");
+                    }
+                    const snapshot = exportSnapshot.call(binding);
+                    const exportId = nextSnapshotExportId++;
+                    snapshotExports.set(exportId, snapshot);
+                    return exportId;
+                }
+            case "exportSnapshot.next":
+                throw workerStateError("snapshot pulls bypass the finite operation queue");
+            case "exportSnapshot.cancel":
+                throw workerStateError("snapshot cancellation bypasses the finite operation queue");
+            case "observe":
+                throw workerStateError("observe must use the observation lane");
             case "close": {
-                const openLix = requiredLix();
+                const openLix = requiredLix(sessionId);
                 await openLix.close();
-                for (const events of observations.values())
-                    events.close();
-                observations.clear();
-                transactions.clear();
-                lix = undefined;
+                sessions.delete(sessionId);
                 return undefined;
             }
             case "observe.next":
                 throw workerStateError("observe.next must use the observation lane");
         }
     }
-    async function handleObserveNext(observeId) {
+    async function handleSnapshotNext(exportId) {
+        const snapshot = snapshotExports.get(exportId);
+        if (!snapshot)
+            return undefined;
+        try {
+            const chunk = await snapshot.next();
+            if (chunk == null)
+                snapshotExports.delete(exportId);
+            return chunk ?? undefined;
+        }
+        catch (error) {
+            snapshotExports.delete(exportId);
+            await Promise.resolve(snapshot.cancel()).catch(() => undefined);
+            throw error;
+        }
+    }
+    async function handleSnapshotCancel(exportId) {
+        const snapshot = snapshotExports.get(exportId);
+        snapshotExports.delete(exportId);
+        if (snapshot)
+            await snapshot.cancel();
+    }
+    function ensureSnapshotInput(snapshotId) {
+        if (snapshotInputs.has(snapshotId))
+            return;
+        const stream = new TransformStream(undefined, { highWaterMark: 0 }, { highWaterMark: 0 });
+        snapshotInputs.set(snapshotId, {
+            readable: stream.readable,
+            writer: stream.writable.getWriter(),
+        });
+    }
+    function requiredSnapshotInput(snapshotId) {
+        const input = snapshotInputs.get(snapshotId);
+        if (!input)
+            throw workerStateError("snapshot restore input is closed");
+        return input;
+    }
+    async function handleSnapshotInput(operation) {
+        const input = requiredSnapshotInput(operation.snapshotId);
+        if (operation.kind === "openSnapshot.write") {
+            await input.writer.write(operation.chunk);
+            return;
+        }
+        await input.writer.close();
+    }
+    function createSyncServerBridge(server) {
+        if (!server)
+            return undefined;
+        return {
+            url: server.url,
+            headers: server.headers ?? [],
+            headerProvider: server.dynamicHeaders
+                ? () => {
+                    const requestId = nextSyncRequestId++;
+                    return new Promise((resolve, reject) => {
+                        pendingSyncHeaders.set(requestId, { resolve, reject });
+                        endpoint.postMessage({ kind: "sync.headers", requestId });
+                    });
+                }
+                : undefined,
+            fetch: server.customFetch ? bridgeFetch : undefined,
+        };
+    }
+    async function bridgeFetch(input, init) {
+        const extension = init;
+        const streaming = extension?.lixResponseStream === true;
+        const responseLimit = extension?.lixResponseLimit;
+        if (!streaming &&
+            (typeof responseLimit !== "number" ||
+                !Number.isSafeInteger(responseLimit) ||
+                responseLimit <= 0)) {
+            throw new TypeError("Browser sync fetch has no valid response limit");
+        }
+        const requestId = nextSyncRequestId++;
+        const requestBase = {
+            url: typeof input === "string"
+                ? input
+                : input instanceof URL
+                    ? input.toString()
+                    : input.url,
+            method: init?.method ?? "GET",
+            headers: headerEntries(init?.headers),
+            body: serializableBody(init?.body),
+            credentials: init?.credentials,
+        };
+        const request = streaming
+            ? { ...requestBase, responseMode: "stream" }
+            : {
+                ...requestBase,
+                responseMode: "buffered",
+                responseLimit: responseLimit,
+            };
+        const response = new Promise((resolve, reject) => {
+            pendingSyncFetch.set(requestId, { resolve, reject });
+            endpoint.postMessage({ kind: "sync.fetch", requestId, request });
+        });
+        const abort = () => {
+            const pending = pendingSyncFetch.get(requestId);
+            pendingSyncFetch.delete(requestId);
+            if (pending) {
+                pending.reject(new DOMException("The operation was aborted", "AbortError"));
+            }
+            const pull = pendingSyncStreamPulls.get(requestId);
+            pendingSyncStreamPulls.delete(requestId);
+            if (pull) {
+                const error = new DOMException("The operation was aborted", "AbortError");
+                pull.controller.error(error);
+                pull.reject(error);
+            }
+            endpoint.postMessage({ kind: "sync.fetch.cancel", requestId });
+            finishSyncStream(requestId);
+        };
+        if (init?.signal?.aborted)
+            abort();
+        else
+            init?.signal?.addEventListener("abort", abort, { once: true });
+        let streamEstablished = false;
+        try {
+            const resolved = await response;
+            if (resolved.streaming) {
+                const signal = init?.signal;
+                if (signal?.aborted) {
+                    abort();
+                    throw new DOMException("The operation was aborted", "AbortError");
+                }
+                if (resolved.status === 204 ||
+                    resolved.status === 205 ||
+                    resolved.status === 304) {
+                    endpoint.postMessage({ kind: "sync.fetch.cancel", requestId });
+                    return new Response(null, {
+                        status: resolved.status,
+                        statusText: resolved.statusText,
+                        headers: resolved.headers,
+                    });
+                }
+                syncStreamCleanup.set(requestId, () => signal?.removeEventListener("abort", abort));
+                const body = new ReadableStream({
+                    pull: (controller) => new Promise((resolve, reject) => {
+                        pendingSyncStreamPulls.set(requestId, {
+                            controller,
+                            resolve,
+                            reject,
+                        });
+                        endpoint.postMessage({
+                            kind: "sync.fetch.stream.pull",
+                            requestId,
+                        });
+                    }),
+                    cancel: abort,
+                });
+                const streamedResponse = new Response(body, {
+                    status: resolved.status,
+                    statusText: resolved.statusText,
+                    headers: resolved.headers,
+                });
+                streamEstablished = true;
+                return streamedResponse;
+            }
+            return responseFromSyncFetch(resolved);
+        }
+        catch (error) {
+            if (streaming && !streamEstablished) {
+                endpoint.postMessage({ kind: "sync.fetch.cancel", requestId });
+                finishSyncStream(requestId);
+            }
+            throw error;
+        }
+        finally {
+            pendingSyncFetch.delete(requestId);
+            if (!streamEstablished) {
+                init?.signal?.removeEventListener("abort", abort);
+            }
+        }
+    }
+    async function handleObserveNext(observeId, telemetryParent) {
         const events = observations.get(observeId);
         if (!events)
             return undefined;
+        events.setTelemetryParent(telemetryParent);
         return events.next();
     }
-    function requiredLix() {
+    async function handleObserveRegistration(sessionId, sql, params) {
+        // Do not touch the mutable Lix telemetry carrier here: it belongs to the
+        // serialized finite lane. Each `observe.next` supplies telemetry directly
+        // to its observation binding.
+        const events = await requiredLix(sessionId).observe(sql, params);
+        const observeId = nextObserveId++;
+        observations.set(observeId, events);
+        return observeId;
+    }
+    function requiredLix(sessionId) {
+        const lix = sessions.get(sessionId);
         if (!lix)
-            throw workerStateError("Lix worker is closed");
+            throw workerStateError("Lix session is closed");
         return lix;
     }
     function requiredTransaction(transactionId) {
@@ -148,9 +472,43 @@ export function startWorkerHost(endpoint) {
         return transaction;
     }
 }
+export function responseFromSyncFetch(resolved) {
+    if (resolved.streaming) {
+        throw new TypeError("Streaming sync responses require the worker stream bridge");
+    }
+    const body = resolved.status === 204 ||
+        resolved.status === 205 ||
+        resolved.status === 304
+        ? null
+        : resolved.body.slice().buffer;
+    return new Response(body, {
+        status: resolved.status,
+        statusText: resolved.statusText,
+        headers: resolved.headers,
+    });
+}
 function workerStateError(message) {
     const error = new Error(message);
     error.name = "LixError";
     error.code = "LIX_ERROR_CLOSED";
     return error;
 }
+function headerEntries(headers) {
+    const entries = [];
+    new Headers(headers).forEach((value, name) => entries.push([name, value]));
+    return entries;
+}
+function serializableBody(body) {
+    if (body === undefined || body === null)
+        return undefined;
+    if (typeof body === "string")
+        return body;
+    if (body instanceof Uint8Array)
+        return body;
+    if (body instanceof ArrayBuffer)
+        return new Uint8Array(body);
+    if (ArrayBuffer.isView(body)) {
+        return new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
+    }
+    throw new TypeError("Browser sync fetch body is not structured-cloneable");
+}