@lix-js/sdk 0.8.3 → 0.9.0

package/dist/worker/client.js

@@ -1,9 +1,22 @@
 import { createWorkerConnection } from "#worker-factory";
+import { snapshotPersistenceAfterCommitError } from "../snapshot-persistence.js";
 import { deserializeWorkerError, } from "./protocol.js";
-export async function openLixWorker(storage, onDisposed) {
-    const client = new LixWorkerClient(onDisposed);
+const MAX_IDLE_WORKERS = 1;
+// The common serial reopen path retains one worker so its prepared plugin cache
+// survives close(). Concurrent opens still receive isolated workers.
+const idleWorkers = [];
+export async function openLixWorker(storage, onDisposed, telemetry) {
+    let client = idleWorkers.pop();
+    while (client?.isDisposed)
+        client = idleWorkers.pop();
+    client ??= new LixWorkerClient();
+    client.beginLease(onDisposed, telemetry);
     try {
-        await client.request({ kind: "open", storage });
+        await client.request({
+            kind: "open",
+            storage,
+            telemetryEnabled: telemetry !== undefined,
+        });
         return client;
     }
     catch (error) {
@@ -11,21 +24,276 @@ export async function openLixWorker(storage, onDisposed) {
         throw error;
     }
 }
+/** Opens the local worker transport behind the semantic Lix binding. */
+export async function openLixWorkerBinding(storage, onDisposed, telemetry) {
+    const client = await openLixWorker(storage, onDisposed, telemetry);
+    return workerBinding(client);
+}
+/**
+ * Opens a browser memory binding from an opaque snapshot and persists a fresh
+ * snapshot after every successful mutation. This is an internal composition
+ * seam for public storage adapters; it does not route workspace operations.
+ */
+export async function openPersistentLixWorkerBinding(options) {
+    if (!options || typeof options !== "object") {
+        throw new TypeError("openPersistentLixWorkerBinding() options must be an object");
+    }
+    if (!options.storage ||
+        typeof options.storage.load !== "function" ||
+        typeof options.storage.save !== "function") {
+        throw new TypeError("openPersistentLixWorkerBinding() storage must implement load() and save()");
+    }
+    if (typeof options.namespace !== "string" || options.namespace.length === 0) {
+        throw new TypeError("openPersistentLixWorkerBinding() namespace must be a non-empty string");
+    }
+    const snapshot = await options.storage.load(options.namespace);
+    if (snapshot !== undefined && !(snapshot instanceof Uint8Array)) {
+        throw new TypeError("Snapshot storage load() must return a Uint8Array");
+    }
+    const binding = await openLixWorkerBinding({
+        kind: "memory",
+        ...(snapshot === undefined ? {} : { snapshot }),
+    }, undefined, options.telemetry);
+    const persistent = persistentSnapshotBinding(binding, options.storage, options.namespace);
+    if (snapshot === undefined) {
+        try {
+            await persistent.persist();
+        }
+        catch (error) {
+            await binding.close().catch(() => undefined);
+            throw error;
+        }
+    }
+    return persistent.binding;
+}
+function workerBinding(client) {
+    let closed = false;
+    const request = (operation) => {
+        if (closed)
+            return Promise.reject(workerClosedError());
+        return client.request(operation);
+    };
+    const notify = (notification) => {
+        if (!closed)
+            client.notify(notification);
+    };
+    return {
+        execute: (sql, params, options) => request({ kind: "execute", sql, params, options }),
+        executeBatch: (statements, options) => request({ kind: "executeBatch", statements, options }),
+        observe: async (sql, params) => {
+            const observeId = await request({
+                kind: "observe",
+                sql,
+                params,
+            });
+            return workerObserveBinding(request, notify, observeId);
+        },
+        beginTransaction: async () => {
+            const transactionId = await request({
+                kind: "beginTransaction",
+            });
+            return workerTransactionBinding(request, transactionId);
+        },
+        activeBranchId: () => request({ kind: "activeBranchId" }),
+        clientStateEntries: () => request({ kind: "clientState.entries" }),
+        clientStateGet: (key) => request({ kind: "clientState.get", key }),
+        clientStateSet: (key, value) => request({ kind: "clientState.set", key, value }),
+        clientStateDelete: (key) => request({ kind: "clientState.delete", key }),
+        createBranch: (options) => request({ kind: "createBranch", options }),
+        createCheckpoint: () => request({ kind: "createCheckpoint" }),
+        switchBranch: (options) => request({ kind: "switchBranch", options }),
+        importFilesystemPaths: (paths) => request({ kind: "importFilesystemPaths", paths }),
+        mergeBranchPreview: (options) => request({ kind: "mergeBranchPreview", options }),
+        mergeBranch: (options) => request({ kind: "mergeBranch", options }),
+        syncDiskToLix: () => request({ kind: "syncDiskToLix" }),
+        exportSnapshot: () => request({ kind: "exportSnapshot" }),
+        close: async () => {
+            if (closed)
+                return;
+            await request({ kind: "close" });
+            closed = true;
+            await releaseWorker(client);
+        },
+    };
+}
+function persistentSnapshotBinding(binding, storage, namespace) {
+    let persistenceTail = Promise.resolve();
+    let closePromise;
+    let bindingClosed = false;
+    const persist = () => {
+        const operation = persistenceTail.then(async () => {
+            const exportSnapshot = binding.exportSnapshot;
+            if (!exportSnapshot) {
+                throw new Error("The open Lix binding does not support snapshot export");
+            }
+            const snapshot = await exportSnapshot.call(binding);
+            await storage.save(namespace, snapshot);
+        });
+        persistenceTail = operation.catch(() => undefined);
+        return operation;
+    };
+    const afterMutation = async (operation) => {
+        const result = await operation;
+        try {
+            await persist();
+        }
+        catch (error) {
+            // The Rust transaction is already committed. Preserve that fact so
+            // synchronous facades can reflect the live session value while still
+            // reporting that durability failed.
+            throw snapshotPersistenceAfterCommitError(error);
+        }
+        return result;
+    };
+    const persistentBinding = {
+        execute: (sql, params, executeOptions) => afterMutation(binding.execute(sql, params, executeOptions)),
+        executeBatch: (statements, batchOptions) => afterMutation(binding.executeBatch(statements, batchOptions)),
+        observe: (sql, params) => binding.observe(sql, params),
+        beginTransaction: async () => {
+            const transaction = await binding.beginTransaction();
+            return {
+                execute: (sql, params, executeOptions) => transaction.execute(sql, params, executeOptions),
+                commit: () => afterMutation(transaction.commit()),
+                rollback: () => transaction.rollback(),
+            };
+        },
+        activeBranchId: () => binding.activeBranchId(),
+        clientStateEntries: () => {
+            const method = binding.clientStateEntries;
+            if (!method)
+                return Promise.reject(clientStateUnsupportedError());
+            return method.call(binding);
+        },
+        clientStateGet: (key) => {
+            const method = binding.clientStateGet;
+            if (!method)
+                return Promise.reject(clientStateUnsupportedError());
+            return method.call(binding, key);
+        },
+        clientStateSet: (key, value) => {
+            const method = binding.clientStateSet;
+            if (!method)
+                return Promise.reject(clientStateUnsupportedError());
+            return afterMutation(method.call(binding, key, value));
+        },
+        clientStateDelete: (key) => {
+            const method = binding.clientStateDelete;
+            if (!method)
+                return Promise.reject(clientStateUnsupportedError());
+            return afterMutation(method.call(binding, key));
+        },
+        createBranch: (branchOptions) => afterMutation(binding.createBranch(branchOptions)),
+        createCheckpoint: () => afterMutation(binding.createCheckpoint()),
+        switchBranch: (branchOptions) => afterMutation(binding.switchBranch(branchOptions)),
+        importFilesystemPaths: (paths) => afterMutation(binding.importFilesystemPaths(paths)),
+        mergeBranchPreview: (branchOptions) => binding.mergeBranchPreview(branchOptions),
+        mergeBranch: (branchOptions) => afterMutation(binding.mergeBranch(branchOptions)),
+        syncDiskToLix: () => afterMutation(binding.syncDiskToLix()),
+        exportSnapshot: () => {
+            const exportSnapshot = binding.exportSnapshot;
+            if (!exportSnapshot) {
+                return Promise.reject(new Error("The open Lix binding does not support snapshot export"));
+            }
+            return exportSnapshot.call(binding);
+        },
+        close: () => {
+            if (closePromise)
+                return closePromise;
+            closePromise = (async () => {
+                let persistenceError;
+                try {
+                    await persist();
+                }
+                catch (error) {
+                    persistenceError = error;
+                }
+                await binding.close();
+                bindingClosed = true;
+                if (persistenceError !== undefined)
+                    throw persistenceError;
+            })();
+            void closePromise.catch((error) => {
+                if (!bindingClosed && isActiveTransactionCloseError(error)) {
+                    closePromise = undefined;
+                }
+            });
+            return closePromise;
+        },
+    };
+    return { binding: persistentBinding, persist };
+}
+function isActiveTransactionCloseError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "LIX_INVALID_TRANSACTION_STATE");
+}
+function clientStateUnsupportedError() {
+    return new Error("The open Lix binding does not support typed client state");
+}
+function workerTransactionBinding(request, transactionId) {
+    return {
+        execute: (sql, params, options) => request({
+            kind: "transaction.execute",
+            transactionId,
+            sql,
+            params,
+            options,
+        }),
+        commit: () => request({ kind: "transaction.commit", transactionId }),
+        rollback: () => request({ kind: "transaction.rollback", transactionId }),
+    };
+}
+function workerObserveBinding(request, notify, observeId) {
+    return {
+        next: () => request({ kind: "observe.next", observeId }),
+        close: () => notify({ kind: "observe.close", observeId }),
+    };
+}
+async function releaseWorker(client) {
+    client.endLease();
+    if (!client.isDisposed && idleWorkers.length < MAX_IDLE_WORKERS) {
+        idleWorkers.push(client);
+        return;
+    }
+    await client.terminate();
+}
 export class LixWorkerClient {
-    onDisposed;
     connection;
     nextRequestId = 1;
     pending = new Map();
     disposed = false;
-    constructor(onDisposed, connection = createWorkerConnection()) {
-        this.onDisposed = onDisposed;
+    leased = false;
+    onDisposed;
+    telemetry;
+    constructor(connection = createWorkerConnection()) {
         this.connection = connection;
         connection.onMessage((message) => this.handleMessage(message));
         connection.onFatal((error) => this.handleFatal(error));
     }
+    get isDisposed() {
+        return this.disposed;
+    }
+    beginLease(onDisposed, telemetry) {
+        if (this.disposed || this.leased)
+            throw workerClosedError();
+        this.leased = true;
+        this.onDisposed = onDisposed;
+        this.telemetry = telemetry;
+    }
+    endLease() {
+        if (!this.leased)
+            return;
+        this.leased = false;
+        const onDisposed = this.onDisposed;
+        this.onDisposed = undefined;
+        this.telemetry = undefined;
+        onDisposed?.();
+    }
     request(operation) {
-        if (this.disposed)
+        if (this.disposed || !this.leased) {
             return Promise.reject(workerClosedError());
+        }
         const id = this.nextRequestId++;
         if (this.pending.size === 0)
             this.connection.ref();
@@ -46,7 +314,7 @@ export class LixWorkerClient {
         });
     }
     notify(notification) {
-        if (this.disposed)
+        if (this.disposed || !this.leased)
             return;
         try {
             this.connection.postMessage(notification);
@@ -64,10 +332,19 @@ export class LixWorkerClient {
             await this.connection.terminate();
         }
         finally {
-            this.onDisposed?.();
+            this.endLease();
         }
     }
     handleMessage(message) {
+        if ("kind" in message) {
+            try {
+                this.telemetry?.onSpan(message.span);
+            }
+            catch {
+                // Telemetry callbacks are isolated from Lix operation results.
+            }
+            return;
+        }
         const pending = this.pending.get(message.id);
         if (!pending)
             return;
@@ -87,7 +364,7 @@ export class LixWorkerClient {
         fatal.name = "LixError";
         fatal.code ??= "LIX_WORKER_TERMINATED";
         this.rejectPending(fatal);
-        this.onDisposed?.();
+        this.endLease();
     }
     rejectPending(error) {
         for (const pending of this.pending.values())

package/dist/worker/host.js

@@ -1,5 +1,4 @@
 import { openLixBinding } from "#binding";
-import { createPluginRuntimeDispatch } from "../plugin-runtime.js";
 import { serializeWorkerError, } from "./protocol.js";
 export function startWorkerHost(endpoint) {
     let lix;
@@ -58,10 +57,14 @@ export function startWorkerHost(endpoint) {
             case "open":
                 if (lix)
                     throw workerStateError("Lix worker is already open");
-                lix = await openLixBinding(operation.storage, createPluginRuntimeDispatch());
+                lix = await openLixBinding(operation.storage, operation.telemetryEnabled
+                    ? (span) => endpoint.postMessage({ kind: "telemetry", span })
+                    : undefined);
                 return undefined;
             case "execute":
                 return requiredLix().execute(operation.sql, operation.params, operation.options);
+            case "executeBatch":
+                return requiredLix().executeBatch(operation.statements, operation.options);
             case "beginTransaction": {
                 const transaction = await requiredLix().beginTransaction();
                 const transactionId = nextTransactionId++;
@@ -84,8 +87,18 @@ export function startWorkerHost(endpoint) {
             }
             case "activeBranchId":
                 return requiredLix().activeBranchId();
+            case "clientState.entries":
+                return requiredClientStateMethod("clientStateEntries")();
+            case "clientState.get":
+                return requiredClientStateMethod("clientStateGet")(operation.key);
+            case "clientState.set":
+                return requiredClientStateMethod("clientStateSet")(operation.key, operation.value);
+            case "clientState.delete":
+                return requiredClientStateMethod("clientStateDelete")(operation.key);
             case "createBranch":
                 return requiredLix().createBranch(operation.options);
+            case "createCheckpoint":
+                return requiredLix().createCheckpoint();
             case "switchBranch":
                 return requiredLix().switchBranch(operation.options);
             case "mergeBranchPreview":
@@ -96,6 +109,14 @@ export function startWorkerHost(endpoint) {
                 return requiredLix().importFilesystemPaths(operation.paths);
             case "syncDiskToLix":
                 return requiredLix().syncDiskToLix();
+            case "exportSnapshot": {
+                const lix = requiredLix();
+                const exportSnapshot = lix.exportSnapshot;
+                if (!exportSnapshot) {
+                    throw workerStateError("The open Lix storage does not support snapshot export");
+                }
+                return exportSnapshot.call(lix);
+            }
             case "observe": {
                 const events = await requiredLix().observe(operation.sql, operation.params);
                 const observeId = nextObserveId++;
@@ -127,6 +148,13 @@ export function startWorkerHost(endpoint) {
             throw workerStateError("Lix worker is closed");
         return lix;
     }
+    function requiredClientStateMethod(key) {
+        const method = requiredLix()[key];
+        if (!method) {
+            throw workerStateError("The open Lix binding does not support typed client state");
+        }
+        return method.bind(requiredLix());
+    }
     function requiredTransaction(transactionId) {
         const transaction = transactions.get(transactionId);
         if (!transaction) {

package/dist/worker/protocol.d.ts

@@ -1,5 +1,5 @@
-import type { BindingParam, LixStorageConfig } from "../binding-types.js";
-import type { CreateBranchOptions, ExecuteOptions, MergeBranchOptions, SwitchBranchOptions } from "../types.js";
+import type { BindingBatchStatement, BindingParam, LixStorageConfig } from "../binding-types.js";
+import type { CreateBranchOptions, ExecuteOptions, JsonValue, LixBatchOptions, MergeBranchOptions, SwitchBranchOptions, LixTelemetrySpan } from "../types.js";
 export type WorkerRequest = {
     id: number;
     operation: WorkerOperation;
@@ -7,11 +7,16 @@ export type WorkerRequest = {
 export type WorkerOperation = {
     kind: "open";
     storage: LixStorageConfig;
+    telemetryEnabled: boolean;
 } | {
     kind: "execute";
     sql: string;
     params: BindingParam[];
     options?: ExecuteOptions;
+} | {
+    kind: "executeBatch";
+    statements: BindingBatchStatement[];
+    options?: LixBatchOptions;
 } | {
     kind: "beginTransaction";
 } | {
@@ -28,9 +33,23 @@ export type WorkerOperation = {
     transactionId: number;
 } | {
     kind: "activeBranchId";
+} | {
+    kind: "clientState.entries";
+} | {
+    kind: "clientState.get";
+    key: string;
+} | {
+    kind: "clientState.set";
+    key: string;
+    value: JsonValue;
+} | {
+    kind: "clientState.delete";
+    key: string;
 } | {
     kind: "createBranch";
     options: CreateBranchOptions;
+} | {
+    kind: "createCheckpoint";
 } | {
     kind: "switchBranch";
     options: SwitchBranchOptions;
@@ -45,6 +64,8 @@ export type WorkerOperation = {
     paths: string[];
 } | {
     kind: "syncDiskToLix";
+} | {
+    kind: "exportSnapshot";
 } | {
     kind: "observe";
     sql: string;
@@ -91,6 +112,9 @@ export type WorkerResponse = {
     id: number;
     ok: false;
     error: SerializedWorkerError;
+} | {
+    kind: "telemetry";
+    span: LixTelemetrySpan;
 };
 export declare function serializeWorkerError(error: unknown): SerializedWorkerError;
 export declare function deserializeWorkerError(error: SerializedWorkerError): Error;

package/dist/workerd.d.ts

@@ -1,10 +1,20 @@
 import type { LixBinding } from "./binding-types.js";
+export type SqlScriptPlan = {
+    statements: SqlScriptStatement[];
+};
+export type SqlScriptStatement = {
+    sql: string;
+    paramStart: number;
+    paramEnd: number;
+};
 export interface OpenMemoryLixOptions {
     snapshot?: Uint8Array;
 }
 export interface WorkerdLixBinding extends LixBinding {
     exportSnapshot(): Promise<Uint8Array>;
 }
+/** Parses SQL using the same DataFusion dialect and transaction policy as Lix. */
+export declare function parseSqlScript(sql: string, providedParamCount: number): SqlScriptPlan;
 /**
  * Opens an in-memory Lix binding directly in a Cloudflare Worker isolate.
  *

package/dist/workerd.js

@@ -2,7 +2,7 @@
 // @ts-expect-error Generated by build:wasm.
 import wasmModule from "./wasm/lix_js_sdk_bg.wasm";
 // @ts-expect-error Generated by build:wasm.
-import { initSync, openMemoryFromSnapshot } from "./wasm/lix_js_sdk.js";
+import { initSync, openMemoryFromSnapshot, parseSqlScript as parseSqlScriptBinding } from "./wasm/lix_js_sdk.js";
 let initialized = false;
 function initializeWasm() {
     if (initialized)
@@ -10,6 +10,11 @@ function initializeWasm() {
     initSync({ module: wasmModule });
     initialized = true;
 }
+/** Parses SQL using the same DataFusion dialect and transaction policy as Lix. */
+export function parseSqlScript(sql, providedParamCount) {
+    initializeWasm();
+    return parseSqlScriptBinding(sql, providedParamCount);
+}
 /**
  * Opens an in-memory Lix binding directly in a Cloudflare Worker isolate.
  *
@@ -26,7 +31,5 @@ export async function openMemoryLix(options = {}) {
         throw new TypeError("openMemoryLix() snapshot must be a Uint8Array");
     }
     initializeWasm();
-    return openMemoryFromSnapshot(async () => {
-        throw new Error("Lix plugin execution is unavailable in Workerd");
-    }, options.snapshot);
+    return openMemoryFromSnapshot(undefined, options.snapshot);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@lix-js/sdk",
 	"type": "module",
-	"version": "0.8.3",
+	"version": "0.9.0",
 	"license": "MIT",
 	"repository": {
 		"type": "git",
@@ -16,6 +16,14 @@
 			"types": "./dist/workerd.d.ts",
 			"workerd": "./dist/workerd.js",
 			"default": "./dist/workerd.js"
+		},
+		"./remote-protocol": {
+			"types": "./dist/remote/protocol.d.ts",
+			"default": "./dist/remote/protocol.js"
+		},
+		"./local-storage-adapter": {
+			"types": "./dist/local-storage-adapter.d.ts",
+			"default": "./dist/local-storage-adapter.js"
 		}
 	},
 	"imports": {
@@ -23,10 +31,6 @@
 			"node": "./dist/binding.node.js",
 			"default": "./dist/binding.browser.js"
 		},
-		"#jco-transpile": {
-			"node": "@bytecodealliance/jco-transpile",
-			"default": "./dist/jco-transpile.browser.js"
-		},
 		"#worker-factory": {
 			"node": "./dist/worker/factory.node.js",
 			"default": "./dist/worker/factory.browser.js"
@@ -36,13 +40,13 @@
 		"dist"
 	],
 	"scripts": {
-		"build": "npm run clean && npm run build:native && npm run build:wasm && npm run build:ts && npm run build:jco-browser && npm run build:plugins",
-		"build:browser": "npm run clean && npm run build:wasm && npm run build:ts && npm run build:jco-browser && npm run build:plugins",
-		"build:jco-browser": "node ./scripts/build-jco-browser.js",
+		"build": "npm run clean && npm run build:native && npm run build:wasm && npm run build:ts && npm run build:plugins",
+		"build:browser": "npm run clean && npm run build:wasm && npm run build:ts && npm run build:plugins",
 		"build:native": "node ./scripts/build-native.js",
 		"build:wasm": "node ./scripts/build-wasm.js",
 		"build:wasm:dev": "LIX_WASM_PROFILE=dev node ./scripts/build-wasm.js",
 		"build:plugins": "node ./scripts/build-bundled-plugins.js",
+		"benchmark:plugin-reopen": "node ./scripts/benchmark-plugin-reopen.mjs",
 		"clean": "node ./scripts/clean.js",
 		"prepare:native-package": "node ./scripts/prepare-native-package.js",
 		"build:ts": "tsc -p tsconfig.json",
@@ -53,21 +57,20 @@
 		"typecheck": "tsc -p tsconfig.test.json --noEmit"
 	},
 	"optionalDependencies": {
-		"@lix-js/sdk-darwin-arm64": "0.8.3",
-		"@lix-js/sdk-linux-arm64": "0.8.3",
-		"@lix-js/sdk-linux-x64": "0.8.3",
-		"@lix-js/sdk-win32-x64": "0.8.3"
+		"@lix-js/sdk-darwin-arm64": "0.9.0",
+		"@lix-js/sdk-linux-arm64": "0.9.0",
+		"@lix-js/sdk-linux-x64": "0.9.0",
+		"@lix-js/sdk-win32-x64": "0.9.0"
 	},
 	"devDependencies": {
-		"@vitest/browser-playwright": "4.0.18",
+		"@vitest/browser-playwright": "4.1.10",
 		"@types/node": "^24.10.2",
 		"playwright": "1.57.0",
 		"typescript": "^5.5.4",
-		"vitest": "^4.0.18"
+		"vite": "8.1.4",
+		"vitest": "4.1.10"
 	},
 	"dependencies": {
-		"@bytecodealliance/jco-transpile": "0.4.2",
-		"@bytecodealliance/preview2-shim": "0.19.0",
 		"fflate": "^0.8.3"
 	}
 }