@lix-js/sdk 0.8.4 → 0.9.0

package/dist/types.d.ts

@@ -6,8 +6,47 @@ export type LocalFilesystemOptions = {
     lixDir?: string;
     syncAllFiles: boolean;
 };
+export type RemoteLixFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export type RemoteLixServerOptions = {
+    mode: "remote";
+    url: string | URL;
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    fetch?: RemoteLixFetch;
+};
+export type LixTelemetrySpan = {
+    schemaVersion: 1;
+    name: string;
+    startedAtUnixMs: number;
+    durationMs: number;
+    status: "ok" | "error";
+    attributes: Record<string, string | number | boolean>;
+};
+export type LixTelemetryOptions = {
+    onSpan(span: LixTelemetrySpan): void;
+};
+/**
+ * Persists opaque Lix snapshots under SDK-provided namespaces.
+ *
+ * Implementations must treat snapshots as bytes owned by Lix. The namespace
+ * selects one logical Lix and allows a single adapter to persist more than one
+ * instance without collisions.
+ */
+export interface LixSnapshotStorage {
+    load(namespace: string): Promise<Uint8Array | undefined>;
+    save(namespace: string, snapshot: Uint8Array): Promise<void>;
+}
 export type OpenLixOptions = {
-    storage?: import("./open-lix.js").SQLite | import("./open-lix.js").LocalFilesystem;
+    storage?: import("./open-lix.js").SQLite | import("./open-lix.js").LocalFilesystem | LixSnapshotStorage;
+    server?: never;
+    telemetry?: LixTelemetryOptions;
+} | {
+    /**
+     * Optional client-local storage. In remote mode workspace SQL remains on
+     * the server; only `lix.clientState` is stored here.
+     */
+    storage?: LixSnapshotStorage;
+    server: RemoteLixServerOptions;
+    telemetry?: never;
 };
 export type LixValue = {
     kind: "null";
@@ -37,6 +76,21 @@ export type JsonValue = null | boolean | number | string | readonly JsonValue[]
 export type SqlParam = JsonValue | Uint8Array | import("./value.js").Value;
 export type ExecuteOptions = {
     originKey?: string;
+    /**
+     * Stable identity for one logical remote SQL mutation. Supply the same key
+     * when retrying after a lost response; remote Lix generates one per call
+     * when this is omitted. This is sent as `Idempotency-Key`, not SQL options.
+     */
+    idempotencyKey?: string;
+};
+export type LixBatchStatement = {
+    sql: string;
+    params?: readonly SqlParam[];
+};
+export type LixBatchOptions = {
+    originKey?: string;
+    /** See {@link ExecuteOptions.idempotencyKey}. */
+    idempotencyKey?: string;
 };
 export type ExecuteResult = {
     columns: string[];
@@ -75,6 +129,9 @@ export type CreateBranchReceipt = {
     hidden: boolean;
     commitId: string;
 };
+export type CreateCheckpointReceipt = {
+    commitId: string;
+};
 export type SwitchBranchOptions = {
     branchId: string;
 };

package/dist/wasm/lix_js_sdk.d.ts

@@ -7,9 +7,15 @@ export class WasmLix {
     [Symbol.dispose](): void;
     activeBranchId(): Promise<string>;
     beginTransaction(): Promise<WasmLixTransaction>;
+    clientStateDelete(key: string): Promise<void>;
+    clientStateEntries(): Promise<any>;
+    clientStateGet(key: string): Promise<any>;
+    clientStateSet(key: string, value: any): Promise<void>;
     close(): Promise<void>;
     createBranch(options: any): Promise<any>;
+    createCheckpoint(): Promise<any>;
     execute(sql: string, params: any, options?: any | null): Promise<any>;
+    executeBatch(statements: any, options?: any | null): Promise<any>;
     exportSnapshot(): Promise<Uint8Array>;
     mergeBranch(options: any): Promise<any>;
     mergeBranchPreview(options: any): Promise<any>;
@@ -34,9 +40,9 @@ export class WasmObserveEvents {
     next(): Promise<any>;
 }
 
-export function openMemory(plugin_runtime_dispatch: Function): Promise<WasmLix>;
+export function openMemory(telemetry_dispatch?: Function | null): Promise<WasmLix>;
 
-export function openMemoryFromSnapshot(plugin_runtime_dispatch: Function, snapshot?: Uint8Array | null): Promise<WasmLix>;
+export function openMemoryFromSnapshot(telemetry_dispatch?: Function | null, snapshot?: Uint8Array | null): Promise<WasmLix>;
 
 export function parseSqlScript(sql: string, provided_param_count: number): any;
 
@@ -52,9 +58,15 @@ export interface InitOutput {
     readonly parseSqlScript: (a: number, b: number, c: number, d: number) => void;
     readonly wasmlix_activeBranchId: (a: number) => number;
     readonly wasmlix_beginTransaction: (a: number) => number;
+    readonly wasmlix_clientStateDelete: (a: number, b: number, c: number) => number;
+    readonly wasmlix_clientStateEntries: (a: number) => number;
+    readonly wasmlix_clientStateGet: (a: number, b: number, c: number) => number;
+    readonly wasmlix_clientStateSet: (a: number, b: number, c: number, d: number) => number;
     readonly wasmlix_close: (a: number) => number;
     readonly wasmlix_createBranch: (a: number, b: number) => number;
+    readonly wasmlix_createCheckpoint: (a: number) => number;
     readonly wasmlix_execute: (a: number, b: number, c: number, d: number, e: number) => number;
+    readonly wasmlix_executeBatch: (a: number, b: number, c: number) => number;
     readonly wasmlix_exportSnapshot: (a: number) => number;
     readonly wasmlix_mergeBranch: (a: number, b: number) => number;
     readonly wasmlix_mergeBranchPreview: (a: number, b: number) => number;
@@ -65,8 +77,8 @@ export interface InitOutput {
     readonly wasmlixtransaction_rollback: (a: number) => number;
     readonly wasmobserveevents_close: (a: number) => void;
     readonly wasmobserveevents_next: (a: number) => number;
-    readonly __wasm_bindgen_func_elem_101667: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_101669: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_111270: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_111272: (a: number, b: number, c: number, d: number) => void;
     readonly __wbindgen_export: (a: number, b: number) => number;
     readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_export3: (a: number) => void;

package/dist/wasm/lix_js_sdk.js

@@ -31,6 +31,44 @@ export class WasmLix {
         const ret = wasm.wasmlix_beginTransaction(this.__wbg_ptr);
         return takeObject(ret);
     }
+    /**
+     * @param {string} key
+     * @returns {Promise<void>}
+     */
+    clientStateDelete(key) {
+        const ptr0 = passStringToWasm0(key, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmlix_clientStateDelete(this.__wbg_ptr, ptr0, len0);
+        return takeObject(ret);
+    }
+    /**
+     * @returns {Promise<any>}
+     */
+    clientStateEntries() {
+        const ret = wasm.wasmlix_clientStateEntries(this.__wbg_ptr);
+        return takeObject(ret);
+    }
+    /**
+     * @param {string} key
+     * @returns {Promise<any>}
+     */
+    clientStateGet(key) {
+        const ptr0 = passStringToWasm0(key, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmlix_clientStateGet(this.__wbg_ptr, ptr0, len0);
+        return takeObject(ret);
+    }
+    /**
+     * @param {string} key
+     * @param {any} value
+     * @returns {Promise<void>}
+     */
+    clientStateSet(key, value) {
+        const ptr0 = passStringToWasm0(key, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmlix_clientStateSet(this.__wbg_ptr, ptr0, len0, addHeapObject(value));
+        return takeObject(ret);
+    }
     /**
      * @returns {Promise<void>}
      */
@@ -46,6 +84,13 @@ export class WasmLix {
         const ret = wasm.wasmlix_createBranch(this.__wbg_ptr, addHeapObject(options));
         return takeObject(ret);
     }
+    /**
+     * @returns {Promise<any>}
+     */
+    createCheckpoint() {
+        const ret = wasm.wasmlix_createCheckpoint(this.__wbg_ptr);
+        return takeObject(ret);
+    }
     /**
      * @param {string} sql
      * @param {any} params
@@ -58,6 +103,15 @@ export class WasmLix {
         const ret = wasm.wasmlix_execute(this.__wbg_ptr, ptr0, len0, addHeapObject(params), isLikeNone(options) ? 0 : addHeapObject(options));
         return takeObject(ret);
     }
+    /**
+     * @param {any} statements
+     * @param {any | null} [options]
+     * @returns {Promise<any>}
+     */
+    executeBatch(statements, options) {
+        const ret = wasm.wasmlix_executeBatch(this.__wbg_ptr, addHeapObject(statements), isLikeNone(options) ? 0 : addHeapObject(options));
+        return takeObject(ret);
+    }
     /**
      * @returns {Promise<Uint8Array>}
      */
@@ -180,23 +234,23 @@ export class WasmObserveEvents {
 if (Symbol.dispose) WasmObserveEvents.prototype[Symbol.dispose] = WasmObserveEvents.prototype.free;
 
 /**
- * @param {Function} plugin_runtime_dispatch
+ * @param {Function | null} [telemetry_dispatch]
  * @returns {Promise<WasmLix>}
  */
-export function openMemory(plugin_runtime_dispatch) {
-    const ret = wasm.openMemory(addHeapObject(plugin_runtime_dispatch));
+export function openMemory(telemetry_dispatch) {
+    const ret = wasm.openMemory(isLikeNone(telemetry_dispatch) ? 0 : addHeapObject(telemetry_dispatch));
     return takeObject(ret);
 }
 
 /**
- * @param {Function} plugin_runtime_dispatch
+ * @param {Function | null} [telemetry_dispatch]
  * @param {Uint8Array | null} [snapshot]
  * @returns {Promise<WasmLix>}
  */
-export function openMemoryFromSnapshot(plugin_runtime_dispatch, snapshot) {
+export function openMemoryFromSnapshot(telemetry_dispatch, snapshot) {
     var ptr0 = isLikeNone(snapshot) ? 0 : passArray8ToWasm0(snapshot, wasm.__wbindgen_export);
     var len0 = WASM_VECTOR_LEN;
-    const ret = wasm.openMemoryFromSnapshot(addHeapObject(plugin_runtime_dispatch), ptr0, len0);
+    const ret = wasm.openMemoryFromSnapshot(isLikeNone(telemetry_dispatch) ? 0 : addHeapObject(telemetry_dispatch), ptr0, len0);
     return takeObject(ret);
 }
 
@@ -364,6 +418,10 @@ function __wbg_get_imports() {
             const ret = getObject(arg0)[arg1 >>> 0];
             return addHeapObject(ret);
         },
+        __wbg_get_de6a0f7d4d18a304: function() { return handleError(function (arg0, arg1) {
+            const ret = Reflect.get(getObject(arg0), getObject(arg1));
+            return addHeapObject(ret);
+        }, arguments); },
         __wbg_get_unchecked_33f6e5c9e2f2d6b2: function(arg0, arg1) {
             const ret = getObject(arg0)[arg1 >>> 0];
             return addHeapObject(ret);
@@ -457,7 +515,7 @@ function __wbg_get_imports() {
                     const a = state0.a;
                     state0.a = 0;
                     try {
-                        return __wasm_bindgen_func_elem_101669(a, state0.b, arg0, arg1);
+                        return __wasm_bindgen_func_elem_111272(a, state0.b, arg0, arg1);
                     } finally {
                         state0.a = a;
                     }
@@ -480,6 +538,10 @@ function __wbg_get_imports() {
             const ret = Date.now();
             return ret;
         }, arguments); },
+        __wbg_now_190933fa139cc119: function() {
+            const ret = Date.now();
+            return ret;
+        },
         __wbg_now_e7c6795a7f81e10f: function(arg0) {
             const ret = getObject(arg0).now();
             return ret;
@@ -542,10 +604,6 @@ function __wbg_get_imports() {
             const ret = typeof window === 'undefined' ? null : window;
             return isLikeNone(ret) ? 0 : addHeapObject(ret);
         },
-        __wbg_then_18f476d590e58992: function(arg0, arg1, arg2) {
-            const ret = getObject(arg0).then(getObject(arg1), getObject(arg2));
-            return addHeapObject(ret);
-        },
         __wbg_then_ac7b025999b52837: function(arg0, arg1) {
             const ret = getObject(arg0).then(getObject(arg1));
             return addHeapObject(ret);
@@ -567,8 +625,8 @@ function __wbg_get_imports() {
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000001: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 29113, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_101667);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 29773, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_111270);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000002: function(arg0) {
@@ -617,10 +675,10 @@ function __wbg_get_imports() {
     };
 }
 
-function __wasm_bindgen_func_elem_101667(arg0, arg1, arg2) {
+function __wasm_bindgen_func_elem_111270(arg0, arg1, arg2) {
     try {
         const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-        wasm.__wasm_bindgen_func_elem_101667(retptr, arg0, arg1, addHeapObject(arg2));
+        wasm.__wasm_bindgen_func_elem_111270(retptr, arg0, arg1, addHeapObject(arg2));
         var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
         var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
         if (r1) {
@@ -631,8 +689,8 @@ function __wasm_bindgen_func_elem_101667(arg0, arg1, arg2) {
     }
 }
 
-function __wasm_bindgen_func_elem_101669(arg0, arg1, arg2, arg3) {
-    wasm.__wasm_bindgen_func_elem_101669(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
+function __wasm_bindgen_func_elem_111272(arg0, arg1, arg2, arg3) {
+    wasm.__wasm_bindgen_func_elem_111272(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
 }
 
 const WasmLixFinalization = (typeof FinalizationRegistry === 'undefined')

package/dist/wasm/lix_js_sdk_bg.wasm.d.ts

@@ -9,9 +9,15 @@ export const openMemoryFromSnapshot: (a: number, b: number, c: number) => number
 export const parseSqlScript: (a: number, b: number, c: number, d: number) => void;
 export const wasmlix_activeBranchId: (a: number) => number;
 export const wasmlix_beginTransaction: (a: number) => number;
+export const wasmlix_clientStateDelete: (a: number, b: number, c: number) => number;
+export const wasmlix_clientStateEntries: (a: number) => number;
+export const wasmlix_clientStateGet: (a: number, b: number, c: number) => number;
+export const wasmlix_clientStateSet: (a: number, b: number, c: number, d: number) => number;
 export const wasmlix_close: (a: number) => number;
 export const wasmlix_createBranch: (a: number, b: number) => number;
+export const wasmlix_createCheckpoint: (a: number) => number;
 export const wasmlix_execute: (a: number, b: number, c: number, d: number, e: number) => number;
+export const wasmlix_executeBatch: (a: number, b: number, c: number) => number;
 export const wasmlix_exportSnapshot: (a: number) => number;
 export const wasmlix_mergeBranch: (a: number, b: number) => number;
 export const wasmlix_mergeBranchPreview: (a: number, b: number) => number;
@@ -22,8 +28,8 @@ export const wasmlixtransaction_execute: (a: number, b: number, c: number, d: nu
 export const wasmlixtransaction_rollback: (a: number) => number;
 export const wasmobserveevents_close: (a: number) => void;
 export const wasmobserveevents_next: (a: number) => number;
-export const __wasm_bindgen_func_elem_101667: (a: number, b: number, c: number, d: number) => void;
-export const __wasm_bindgen_func_elem_101669: (a: number, b: number, c: number, d: number) => void;
+export const __wasm_bindgen_func_elem_111270: (a: number, b: number, c: number, d: number) => void;
+export const __wasm_bindgen_func_elem_111272: (a: number, b: number, c: number, d: number) => void;
 export const __wbindgen_export: (a: number, b: number) => number;
 export const __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
 export const __wbindgen_export3: (a: number) => void;

package/dist/worker/client.d.ts

@@ -1,13 +1,32 @@
-import type { LixStorageConfig } from "../binding-types.js";
+import type { LixBinding, LixStorageConfig } from "../binding-types.js";
+import type { LixSnapshotStorage, LixTelemetryOptions } from "../types.js";
 import { type WorkerConnection, type WorkerNotification, type WorkerOperation } from "./protocol.js";
-export declare function openLixWorker(storage: LixStorageConfig, onDisposed?: () => void): Promise<LixWorkerClient>;
+export declare function openLixWorker(storage: LixStorageConfig, onDisposed?: () => void, telemetry?: LixTelemetryOptions): Promise<LixWorkerClient>;
+/** Opens the local worker transport behind the semantic Lix binding. */
+export declare function openLixWorkerBinding(storage: LixStorageConfig, onDisposed?: () => void, telemetry?: LixTelemetryOptions): Promise<LixBinding>;
+export type OpenPersistentLixWorkerBindingOptions = {
+    storage: LixSnapshotStorage;
+    namespace: string;
+    telemetry?: LixTelemetryOptions;
+};
+/**
+ * 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 declare function openPersistentLixWorkerBinding(options: OpenPersistentLixWorkerBindingOptions): Promise<LixBinding>;
 export declare class LixWorkerClient {
-    private readonly onDisposed?;
     private readonly connection;
     private nextRequestId;
     private readonly pending;
     private disposed;
-    constructor(onDisposed?: (() => void) | undefined, connection?: WorkerConnection);
+    private leased;
+    private onDisposed?;
+    private telemetry?;
+    constructor(connection?: WorkerConnection);
+    get isDisposed(): boolean;
+    beginLease(onDisposed?: () => void, telemetry?: LixTelemetryOptions): void;
+    endLease(): void;
     request<T>(operation: WorkerOperation): Promise<T>;
     notify(notification: WorkerNotification): void;
     terminate(): Promise<void>;