@lix-js/sdk 0.10.0 → 0.12.0

package/dist/remote/{protocol.d.ts → server-protocol.d.ts}

@@ -1,7 +1,7 @@
 import type { BindingExecuteResult, BindingObserveEvent } from "../binding-types.js";
 import type { NativeLixValue } from "../value.js";
-export declare const REMOTE_PROTOCOL_VERSION = 2;
-export declare const REMOTE_PROTOCOL_PATH = "/lix/v1/";
+export declare const SERVER_PROTOCOL_VERSION = 2;
+export declare const SERVER_PROTOCOL_PATH = "/lix/v1/";
 export type WireValue = {
     kind: "null";
     value: null;
@@ -18,8 +18,11 @@ export type WireValue = {
     kind: "text";
     value: string;
 } | {
-    kind: "json";
+    kind: "jsonb";
     value: unknown;
+} | {
+    kind: "timestamptz";
+    value: string;
 } | {
     kind: "blob";
     base64: string;
@@ -33,17 +36,16 @@ export type WireRequestBlobSplice = {
     insertBase64: string;
 };
 export type WireRequestValue = WireValue | WireRequestBlobSplice;
-export type RemoteHandshake = {
+export type ServerProtocolHandshake = {
     protocolVersion: number;
     activeBranchId: string;
     activeAccountId: string;
     sessionId: string;
 };
-export type RemoteHandshakeRequest = {
+export type ServerProtocolHandshakeRequest = {
     activeBranchId?: string;
-    activeAccountId?: string;
 };
-export type RemoteExecuteRequest = {
+export type ServerProtocolExecuteRequest = {
     sql: string;
     params: WireRequestValue[];
     options?: {
@@ -51,17 +53,18 @@ export type RemoteExecuteRequest = {
     };
     cacheBlobs?: true;
 };
-export type RemoteExecuteBatchRequest = {
+export type ServerProtocolExecuteBatchRequest = {
     statements: Array<{
         sql: string;
         params: WireRequestValue[];
+        label?: string;
     }>;
     options?: {
         originKey?: string;
     };
     cacheBlobs?: true;
 };
-export type RemoteExecuteResponse = {
+export type ServerProtocolExecuteResponse = {
     columns: string[];
     rows: WireValue[][];
     rowsAffected: number;
@@ -71,76 +74,80 @@ export type RemoteExecuteResponse = {
         hint?: string;
     }>;
 };
-export type RemoteObserveRequest = {
+export type ServerProtocolExecuteBatchResponse = ServerProtocolExecuteResponse & {
+    statementIndex: number;
+    label?: string;
+};
+export type ServerProtocolObserveRequest = {
     sql: string;
     params: WireValue[];
 };
-export type RemoteObserveSubscription = RemoteObserveRequest & {
+export type ServerProtocolObserveSubscription = ServerProtocolObserveRequest & {
     id: string;
 };
-export type RemoteMultiplexObserveRequest = {
-    subscriptions: RemoteObserveSubscription[];
+export type ServerProtocolMultiplexObserveRequest = {
+    subscriptions: ServerProtocolObserveSubscription[];
 };
-type RemoteObserveEventBase = {
+type ServerProtocolObserveEventBase = {
     sequence: number;
     mutationSequence: number;
 };
-export type RemoteObserveBlobDelta = {
+export type ServerProtocolObserveBlobDelta = {
     kind: "single-blob-splice";
     baseSequence: number;
     prefixBytes: number;
     suffixBytes: number;
     insertBase64: string;
 };
-type RemoteObserveRowSplice = {
+type ServerProtocolObserveRowSplice = {
     kind: "row-splice";
     baseSequence: number;
     prefixRows: number;
     deleteRows: number;
     insertRows: WireValue[][];
 };
-type RemoteObserveDelta = RemoteObserveBlobDelta | RemoteObserveRowSplice;
-export type RemoteObserveEvent = RemoteObserveEventBase & ({
-    result: RemoteExecuteResponse;
+type ServerProtocolObserveDelta = ServerProtocolObserveBlobDelta | ServerProtocolObserveRowSplice;
+export type ServerProtocolObserveEvent = ServerProtocolObserveEventBase & ({
+    result: ServerProtocolExecuteResponse;
     delta?: never;
 } | {
     result?: never;
-    delta: RemoteObserveDelta;
+    delta: ServerProtocolObserveDelta;
 });
-export type RemoteMultiplexObserveEvent = RemoteObserveEvent & {
+export type ServerProtocolMultiplexObserveEvent = ServerProtocolObserveEvent & {
     subscriptionId: string;
 };
-export type RemoteCreateBranchRequest = {
+export type ServerProtocolCreateBranchRequest = {
     id?: string;
     name: string;
     fromCommitId?: string;
 };
-export type RemoteCreateBranchResponse = {
+export type ServerProtocolCreateBranchResponse = {
     id: string;
     name: string;
     hidden: boolean;
     commitId: string;
 };
-export type RemoteCreateCheckpointResponse = {
+export type ServerProtocolCreateCheckpointResponse = {
     commitId: string;
 };
-export type RemoteUndoResponse = {
+export type ServerProtocolUndoResponse = {
     branchId: string;
     targetCommitId: string;
     inverseCommitId: string;
 };
-export type RemoteRedoResponse = {
+export type ServerProtocolRedoResponse = {
     branchId: string;
     targetCommitId: string;
     replayCommitId: string;
 };
-export type RemoteSwitchBranchRequest = {
+export type ServerProtocolSwitchBranchRequest = {
     branchId: string;
 };
-export type RemoteSwitchBranchResponse = {
+export type ServerProtocolSwitchBranchResponse = {
     branchId: string;
 };
-export type RemoteErrorBody = {
+export type ServerProtocolErrorBody = {
     error: {
         code?: string;
         message?: string;
@@ -148,15 +155,16 @@ export type RemoteErrorBody = {
         details?: unknown;
     };
 };
-export type RemoteObserveErrorEvent = RemoteErrorBody & {
+export type ServerProtocolObserveErrorEvent = ServerProtocolErrorBody & {
     retryable?: boolean;
 };
-export type RemoteMultiplexObserveErrorEvent = RemoteObserveErrorEvent & {
+export type ServerProtocolMultiplexObserveErrorEvent = ServerProtocolObserveErrorEvent & {
     subscriptionId?: string;
 };
 export declare function encodeWireValue(value: NativeLixValue): WireValue;
 export declare function decodeExecuteResult(value: unknown): BindingExecuteResult;
-export declare function decodeHandshake(value: unknown): RemoteHandshake;
+export declare function decodeExecuteBatchResult(value: unknown): BindingExecuteResult;
+export declare function decodeHandshake(value: unknown): ServerProtocolHandshake;
 export declare function decodeObserveEvent(value: unknown, base?: BindingObserveEvent): BindingObserveEvent;
 export declare function remoteError(code: string, message: string, options?: {
     hint?: string;

package/dist/remote/{protocol.js → server-protocol.js}

@@ -1,5 +1,5 @@
-export const REMOTE_PROTOCOL_VERSION = 2;
-export const REMOTE_PROTOCOL_PATH = "/lix/v1/";
+export const SERVER_PROTOCOL_VERSION = 2;
+export const SERVER_PROTOCOL_PATH = "/lix/v1/";
 export function encodeWireValue(value) {
     switch (value.kind) {
         case "null":
@@ -12,8 +12,10 @@ export function encodeWireValue(value) {
             return { kind: "float", value: value.value };
         case "text":
             return { kind: "text", value: value.value };
-        case "json":
-            return { kind: "json", value: value.value };
+        case "jsonb":
+            return { kind: "jsonb", value: value.value };
+        case "timestamptz":
+            return { kind: "timestamptz", value: value.value };
         case "blob":
             return { kind: "blob", base64: bytesToBase64(value.blob) };
     }
@@ -57,25 +59,37 @@ export function decodeExecuteResult(value) {
     });
     return { columns, rows, rowsAffected: result.rowsAffected, notices };
 }
+export function decodeExecuteBatchResult(value) {
+    const result = record(value, "execute batch result");
+    const statementIndex = nonNegativeSafeInteger(result.statementIndex, "execute batch result statementIndex");
+    if (result.label !== undefined && typeof result.label !== "string") {
+        throw protocolError("execute batch result label must be a string when present");
+    }
+    return {
+        ...decodeExecuteResult(value),
+        statementIndex,
+        ...(result.label === undefined ? {} : { label: result.label }),
+    };
+}
 export function decodeHandshake(value) {
-    const handshake = record(value, "remote handshake");
-    if (handshake.protocolVersion !== REMOTE_PROTOCOL_VERSION) {
-        throw protocolError(`unsupported remote protocol version: ${String(handshake.protocolVersion)}`);
+    const handshake = record(value, "Lix Server Protocol handshake");
+    if (handshake.protocolVersion !== SERVER_PROTOCOL_VERSION) {
+        throw protocolError(`unsupported Lix Server Protocol version: ${String(handshake.protocolVersion)}`);
     }
     if (typeof handshake.activeBranchId !== "string" ||
         handshake.activeBranchId.length === 0) {
-        throw protocolError("remote handshake requires activeBranchId");
+        throw protocolError("Lix Server Protocol handshake requires activeBranchId");
     }
     if (typeof handshake.activeAccountId !== "string" ||
         handshake.activeAccountId.length === 0) {
-        throw protocolError("remote handshake requires activeAccountId");
+        throw protocolError("Lix Server Protocol handshake requires activeAccountId");
     }
     if (typeof handshake.sessionId !== "string" ||
         !/^[\x21-\x7e]{1,256}$/.test(handshake.sessionId)) {
-        throw protocolError("remote handshake requires a valid sessionId");
+        throw protocolError("Lix Server Protocol handshake requires a valid sessionId");
     }
     return {
-        protocolVersion: REMOTE_PROTOCOL_VERSION,
+        protocolVersion: SERVER_PROTOCOL_VERSION,
         activeBranchId: handshake.activeBranchId,
         activeAccountId: handshake.activeAccountId,
         sessionId: handshake.sessionId,
@@ -228,11 +242,11 @@ export function remoteError(code, message, options = {}) {
     return error;
 }
 export function protocolError(message) {
-    return remoteError("LIX_REMOTE_PROTOCOL_ERROR", message);
+    return remoteError("LIX_SERVER_PROTOCOL_ERROR", message);
 }
 export function errorFromResponseBody(value, status) {
-    const body = record(value, "remote error response");
-    const rawError = record(body.error, "remote error response error");
+    const body = record(value, "Lix Server Protocol error response");
+    const rawError = record(body.error, "Lix Server Protocol error response error");
     return remoteError(typeof rawError.code === "string"
         ? rawError.code
         : "LIX_REMOTE_REQUEST_FAILED", typeof rawError.message === "string"
@@ -281,9 +295,14 @@ function decodeWireValue(value) {
                 throw protocolError("text wire value is invalid");
             }
             return { kind: "text", value: wire.value };
-        case "json":
-            assertJsonValue(wire.value, "json wire value");
-            return { kind: "json", value: wire.value };
+        case "jsonb":
+            assertJsonValue(wire.value, "jsonb wire value");
+            return { kind: "jsonb", value: wire.value };
+        case "timestamptz":
+            if (typeof wire.value !== "string") {
+                throw protocolError("timestamptz wire value is invalid");
+            }
+            return { kind: "timestamptz", value: wire.value };
         case "blob":
             if (typeof wire.base64 !== "string") {
                 throw protocolError("blob wire value is invalid");

package/dist/result.d.ts

@@ -1,5 +1,5 @@
 import { type NativeLixValue, Value } from "./value.js";
-import type { ExecuteResult, LixValue } from "./types.js";
+import type { ExecuteBatchResult, ExecuteResult, LixValue } from "./types.js";
 export declare class Row {
     private readonly columns;
     private readonly values;
@@ -14,5 +14,6 @@ type NativeExecuteResult = Omit<ExecuteResult, "rows"> & {
     rows: NativeLixValue[][];
 };
 export declare function wrapExecuteResult(result: NativeExecuteResult): ExecuteResult;
+export declare function wrapExecuteBatchResult(result: NativeExecuteResult): ExecuteBatchResult;
 export declare function normalizeOptionals<T>(value: T): T;
 export {};

package/dist/result.js

@@ -36,6 +36,18 @@ export function wrapExecuteResult(result) {
         rows: result.rows.map((row) => Row.fromRaw(result.columns, row.map(fromNativeValue))),
     };
 }
+export function wrapExecuteBatchResult(result) {
+    const statementIndex = result.statementIndex;
+    if (typeof statementIndex !== "number" ||
+        !Number.isSafeInteger(statementIndex) ||
+        statementIndex < 0) {
+        throw new Error("executeBatch result is missing a valid statementIndex");
+    }
+    return {
+        ...wrapExecuteResult(result),
+        statementIndex,
+    };
+}
 export function normalizeOptionals(value) {
     if (Array.isArray(value))
         return value.map(normalizeOptionals);

package/dist/storage-adapter.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Operations exposed to a storage adapter while its Lix is open.
+ *
+ * This is intentionally narrower than the engine binding. Storage packages
+ * receive only the controls required to manage their own persistence layer.
+ */
+export type LixStorageConnection = {
+    importFilesystemPaths(paths: string[]): Promise<void>;
+    syncDiskToLix(): Promise<void>;
+};
+/** Engine configuration currently supported by external JavaScript storage packages. */
+export type LixStorageAdapterConfig = {
+    kind: "filesystem";
+    path: string;
+    syncAllFiles: boolean;
+};
+/**
+ * Protocol implemented by JavaScript storage packages accepted by `openLix()`.
+ *
+ * Applications normally use a concrete package such as
+ * `@lix-js/storage-filesystem` rather than implementing this directly.
+ */
+export type LixStorage = {
+    readonly lixStorage: {
+        readonly version: 1;
+        readonly config: LixStorageAdapterConfig;
+        connect(connection: LixStorageConnection | undefined): void;
+    };
+};
+export declare function isLixStorage(value: unknown): value is LixStorage;

package/dist/storage-adapter.js

@@ -0,0 +1,12 @@
+export function isLixStorage(value) {
+    if (!value || typeof value !== "object" || !("lixStorage" in value)) {
+        return false;
+    }
+    const adapter = value.lixStorage;
+    return Boolean(adapter &&
+        typeof adapter === "object" &&
+        adapter.version === 1 &&
+        typeof adapter.connect === "function" &&
+        adapter.config?.kind ===
+            "filesystem");
+}

package/dist/types.d.ts

@@ -1,10 +1,9 @@
-export type SQLiteOptions = {
-    path: string;
-};
-export type LocalFilesystemOptions = {
-    path: string;
-    lixDir?: string;
-    syncAllFiles: boolean;
+export type IndexedDbStorageOptions = {
+    /**
+     * Identifies one persistent Lix database within the current origin.
+     * A database name can be opened by only one Lix handle at a time.
+     */
+    name: string;
 };
 export type RemoteLixFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 export type RemoteLixServerOptions = {
@@ -24,27 +23,12 @@ export type LixTelemetrySpan = {
 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 | LixSnapshotStorage;
+    storage?: import("./storage-adapter.js").LixStorage | import("./open-lix.js").IndexedDbStorage;
     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;
+    storage?: never;
     server: RemoteLixServerOptions;
     telemetry?: never;
 };
@@ -64,8 +48,11 @@ export type LixValue = {
     kind: "text";
     value: string;
 } | {
-    kind: "json";
+    kind: "jsonb";
     value: JsonValue;
+} | {
+    kind: "timestamptz";
+    value: string;
 } | {
     kind: "blob";
     value: Uint8Array;
@@ -86,6 +73,7 @@ export type ExecuteOptions = {
 export type LixBatchStatement = {
     sql: string;
     params?: readonly SqlParam[];
+    label?: string;
 };
 export type LixBatchOptions = {
     originKey?: string;
@@ -93,6 +81,8 @@ export type LixBatchOptions = {
     idempotencyKey?: string;
 };
 export type ExecuteResult = {
+    statementIndex?: number;
+    label?: string;
     columns: string[];
     rows: RowLike[];
     rowsAffected: number;
@@ -102,9 +92,17 @@ export type ExecuteResult = {
         hint?: string;
     }>;
 };
+export type ExecuteBatchResult = ExecuteResult & {
+    statementIndex: number;
+};
 export type ObserveEvent = {
     sequence: number;
     mutationSequence: number;
+    /**
+     * The current result of the observed query. Remote observations reconcile
+     * the first frame of every stream through execute before publishing it, so
+     * reconnects cannot expose a stale server snapshot to consumers.
+     */
     result: ExecuteResult;
 };
 export type RowLike = {
@@ -180,9 +178,9 @@ export type MergeChangeStats = {
     removed: number;
 };
 export type MergeConflict = {
-    kind: "sameEntityChanged";
+    kind: "sameRowChanged";
     schemaKey: string;
-    entityPk: unknown;
+    rowPk: unknown;
     fileId: string | null;
     target: MergeConflictSide;
     source: MergeConflictSide;

package/dist/value.d.ts

@@ -8,7 +8,8 @@ export declare class Value {
     static integer(value: number): Value;
     static real(value: number): Value;
     static text(value: string): Value;
-    static json(value: JsonValue): Value;
+    static jsonb(value: JsonValue): Value;
+    static timestamptz(value: string): Value;
     static blob(value: Uint8Array): Value;
     static from(value: SqlParam): Value;
     static _fromNative(value: LixValue): Value;

package/dist/value.js

@@ -2,9 +2,9 @@ import { invalidParam } from "./errors.js";
 export class Value {
     kind;
     #raw;
-    constructor(raw) {
+    constructor(raw, clone = true) {
         validateExplicitValue(raw);
-        this.#raw = cloneValue(raw);
+        this.#raw = clone ? cloneValue(raw) : raw;
         this.kind = this.#raw.kind;
     }
     static null() {
@@ -22,8 +22,11 @@ export class Value {
     static text(value) {
         return new Value({ kind: "text", value });
     }
-    static json(value) {
-        return new Value({ kind: "json", value });
+    static jsonb(value) {
+        return new Value({ kind: "jsonb", value });
+    }
+    static timestamptz(value) {
+        return new Value({ kind: "timestamptz", value });
     }
     static blob(value) {
         return new Value({ kind: "blob", value });
@@ -32,7 +35,11 @@ export class Value {
         return new Value(normalizeParam(value));
     }
     static _fromNative(value) {
-        return new Value(value);
+        // Native execute results are newly materialized for this result set. Keep
+        // the native value as-is and defer the defensive copy until toJS(). This
+        // avoids cloning every structured result once during row wrapping and
+        // again when callers read it.
+        return new Value(value, false);
     }
     _toNative() {
         return toNativeValue(this.#raw);
@@ -101,7 +108,7 @@ export function normalizeParam(value, index = 0, seen = new WeakSet()) {
             throw invalidParam(index, "typed array SQL parameters must be Uint8Array", value.constructor.name);
         }
         assertJsonSerializable(value, seen, index);
-        return { kind: "json", value };
+        return { kind: "jsonb", value };
     }
     throw invalidParam(index, `${typeof value} is not a valid SQL parameter`, typeof value);
 }
@@ -113,7 +120,8 @@ function unwrapValue(value) {
         case "integer":
         case "real":
         case "text":
-        case "json":
+        case "timestamptz":
+        case "jsonb":
             return cloneJsonValue(value.value);
         case "blob":
             return new Uint8Array(value.value);
@@ -193,9 +201,14 @@ function validateExplicitValue(value) {
                 throw invalidParam(0, "string SQL parameters must be well-formed UTF-16", "string");
             }
             return;
-        case "json":
+        case "jsonb":
             assertJsonSerializable(value.value, new WeakSet(), 0);
             return;
+        case "timestamptz":
+            if (typeof value.value === "string" && !Number.isNaN(Date.parse(value.value))) {
+                return;
+            }
+            break;
         case "blob":
             if (value.value instanceof Uint8Array)
                 return;
@@ -209,8 +222,8 @@ function cloneValue(value) {
     if (value.kind === "blob") {
         return { kind: "blob", value: new Uint8Array(value.value) };
     }
-    if (value.kind === "json") {
-        return { kind: "json", value: cloneJsonValue(value.value) };
+    if (value.kind === "jsonb") {
+        return { kind: "jsonb", value: cloneJsonValue(value.value) };
     }
     return value;
 }

package/dist/wasm/lix_js_sdk.d.ts

@@ -8,10 +8,6 @@ export class WasmLix {
     activeAccountId(): Promise<string>;
     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>;
@@ -43,6 +39,8 @@ export class WasmObserveEvents {
     next(): Promise<any>;
 }
 
+export function openIndexedDb(backend: any, telemetry_dispatch?: Function | null): Promise<WasmLix>;
+
 export function openMemory(telemetry_dispatch?: Function | null): Promise<WasmLix>;
 
 export function openMemoryFromSnapshot(telemetry_dispatch?: Function | null, snapshot?: Uint8Array | null): Promise<WasmLix>;
@@ -56,16 +54,13 @@ export interface InitOutput {
     readonly __wbg_wasmlix_free: (a: number, b: number) => void;
     readonly __wbg_wasmlixtransaction_free: (a: number, b: number) => void;
     readonly __wbg_wasmobserveevents_free: (a: number, b: number) => void;
+    readonly openIndexedDb: (a: number, b: number) => number;
     readonly openMemory: (a: number) => number;
     readonly openMemoryFromSnapshot: (a: number, b: number, c: number) => number;
     readonly parseSqlScript: (a: number, b: number, c: number, d: number) => void;
     readonly wasmlix_activeAccountId: (a: number) => number;
     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;
@@ -83,8 +78,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_120695: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_120697: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_119239: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_119241: (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;