@lix-js/sdk 0.12.2 → 0.14.0

package/dist/remote/server-protocol.d.ts

@@ -1,7 +1,6 @@
 import type { BindingExecuteResult, BindingObserveEvent } from "../binding-types.js";
 import type { NativeLixValue } from "../value.js";
-export declare const SERVER_PROTOCOL_VERSION = 2;
-export declare const SERVER_PROTOCOL_PATH = "/lix/v1/";
+export declare const SERVER_PROTOCOL_VERSION = 6;
 export type WireValue = {
     kind: "null";
     value: null;
@@ -20,6 +19,9 @@ export type WireValue = {
 } | {
     kind: "jsonb";
     value: unknown;
+} | {
+    kind: "row_ref";
+    value: string;
 } | {
     kind: "timestamptz";
     value: string;
@@ -65,7 +67,7 @@ export type ServerProtocolExecuteBatchRequest = {
     cacheBlobs?: true;
 };
 export type ServerProtocolExecuteResponse = {
-    columns: string[];
+    columns: BindingExecuteResult["columns"];
     rows: WireValue[][];
     rowsAffected: number;
     notices: Array<{
@@ -128,9 +130,6 @@ export type ServerProtocolCreateBranchResponse = {
     hidden: boolean;
     commitId: string;
 };
-export type ServerProtocolCreateCheckpointResponse = {
-    commitId: string;
-};
 export type ServerProtocolUndoResponse = {
     branchId: string;
     targetCommitId: string;

package/dist/remote/server-protocol.js

@@ -1,5 +1,4 @@
-export const SERVER_PROTOCOL_VERSION = 2;
-export const SERVER_PROTOCOL_PATH = "/lix/v1/";
+export const SERVER_PROTOCOL_VERSION = 6;
 export function encodeWireValue(value) {
     switch (value.kind) {
         case "null":
@@ -14,6 +13,8 @@ export function encodeWireValue(value) {
             return { kind: "text", value: value.value };
         case "jsonb":
             return { kind: "jsonb", value: value.value };
+        case "row_ref":
+            return { kind: "row_ref", value: value.value };
         case "timestamptz":
             return { kind: "timestamptz", value: value.value };
         case "blob":
@@ -22,7 +23,16 @@ export function encodeWireValue(value) {
 }
 export function decodeExecuteResult(value) {
     const result = record(value, "execute result");
-    const columns = stringArray(result.columns, "execute result columns");
+    if (!Array.isArray(result.columns)) {
+        throw protocolError("execute result columns must be an array");
+    }
+    const columns = result.columns.map((column, index) => {
+        const item = record(column, `execute result column ${index}`);
+        if (typeof item.name !== "string" || !isResultColumnType(item.type)) {
+            throw protocolError(`execute result column ${index} requires a string name and valid type`);
+        }
+        return { name: item.name, type: item.type };
+    });
     if (!Array.isArray(result.rows)) {
         throw protocolError("execute result rows must be an array");
     }
@@ -33,7 +43,14 @@ export function decodeExecuteResult(value) {
         if (row.length !== columns.length) {
             throw protocolError(`execute result row ${rowIndex} has ${row.length} values for ${columns.length} columns`);
         }
-        return row.map((entry) => decodeWireValue(entry));
+        return row.map((entry, columnIndex) => {
+            const decoded = decodeWireValue(entry);
+            const declaredType = columns[columnIndex]?.type;
+            if (decoded.kind !== "null" && decoded.kind !== declaredType) {
+                throw protocolError(`execute result row ${rowIndex} column ${columnIndex} declares ${String(declaredType)} but contains ${decoded.kind}`);
+            }
+            return decoded;
+        });
     });
     if (typeof result.rowsAffected !== "number" ||
         !Number.isSafeInteger(result.rowsAffected) ||
@@ -59,6 +76,17 @@ export function decodeExecuteResult(value) {
     });
     return { columns, rows, rowsAffected: result.rowsAffected, notices };
 }
+function isResultColumnType(value) {
+    return (value === "null" ||
+        value === "boolean" ||
+        value === "integer" ||
+        value === "real" ||
+        value === "text" ||
+        value === "jsonb" ||
+        value === "row_ref" ||
+        value === "timestamptz" ||
+        value === "blob");
+}
 export function decodeExecuteBatchResult(value) {
     const result = record(value, "execute batch result");
     const statementIndex = nonNegativeSafeInteger(result.statementIndex, "execute batch result statementIndex");
@@ -146,7 +174,8 @@ function applyObserveBlobDelta(delta, sequence, base) {
     }
     const baseValue = base.rows.rows[0]?.[0];
     if (base.rows.columns.length !== 1 ||
-        base.rows.columns[0] !== "content" ||
+        base.rows.columns[0]?.name !== "content" ||
+        base.rows.columns[0]?.type !== "blob" ||
         base.rows.rows.length !== 1 ||
         base.rows.rows[0]?.length !== 1 ||
         base.rows.rowsAffected !== 0 ||
@@ -173,7 +202,7 @@ function applyObserveBlobDelta(delta, sequence, base) {
     blob.set(insert, prefixBytes);
     blob.set(baseValue.blob.subarray(baseValue.blob.byteLength - suffixBytes), prefixBytes + insert.byteLength);
     return {
-        columns: ["content"],
+        columns: [{ name: "content", type: "blob" }],
         rows: [[{ kind: "blob", value: null, blob }]],
         rowsAffected: 0,
         notices: [],
@@ -265,9 +294,6 @@ export function record(value, description) {
     }
     return value;
 }
-function isRecord(value) {
-    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
 function decodeWireValue(value) {
     const wire = record(value, "wire value");
     switch (wire.kind) {
@@ -298,6 +324,11 @@ function decodeWireValue(value) {
         case "jsonb":
             assertJsonValue(wire.value, "jsonb wire value");
             return { kind: "jsonb", value: wire.value };
+        case "row_ref":
+            if (typeof wire.value !== "string") {
+                throw protocolError("row_ref wire value is invalid");
+            }
+            return { kind: "row_ref", value: wire.value };
         case "timestamptz":
             if (typeof wire.value !== "string") {
                 throw protocolError("timestamptz wire value is invalid");

package/dist/result.d.ts

@@ -1,19 +1,12 @@
-import { type NativeLixValue, Value } from "./value.js";
-import type { ExecuteBatchResult, ExecuteResult, LixValue } from "./types.js";
-export declare class Row {
-    private readonly columns;
-    private readonly values;
-    constructor(columns: string[], values: Value[]);
-    static fromRaw(columns: string[], values: LixValue[]): Row;
-    get(column: string): unknown;
-    value(column: string): Value;
-    toObject(): Record<string, unknown>;
-    toValueMap(): Record<string, Value>;
-}
+import { type NativeLixValue } from "./value.js";
+import type { ExecuteBatchResult, ExecuteResult, ResultArrayRow, ResultObjectRow, ResultRow } from "./types.js";
 type NativeExecuteResult = Omit<ExecuteResult, "rows"> & {
     rows: NativeLixValue[][];
 };
 export declare function wrapExecuteResult(result: NativeExecuteResult): ExecuteResult;
-export declare function wrapExecuteBatchResult(result: NativeExecuteResult): ExecuteBatchResult;
+export declare function wrapExecuteResult(result: NativeExecuteResult, rowMode: "object"): ExecuteResult<ResultObjectRow>;
+export declare function wrapExecuteResult(result: NativeExecuteResult, rowMode: "array"): ExecuteResult<ResultArrayRow>;
+export declare function wrapExecuteResult(result: NativeExecuteResult, rowMode: "object" | "array"): ExecuteResult<ResultRow>;
+export declare function wrapExecuteBatchResult(result: NativeExecuteResult, rowMode?: "object" | "array"): ExecuteBatchResult<ResultRow>;
 export declare function normalizeOptionals<T>(value: T): T;
 export {};

package/dist/result.js

@@ -1,42 +1,16 @@
 import { fromNativeValue, Value } from "./value.js";
-export class Row {
-    columns;
-    values;
-    constructor(columns, values) {
-        this.columns = columns;
-        this.values = values;
-    }
-    static fromRaw(columns, values) {
-        return new Row(columns, values.map((value) => Value._fromNative(value)));
-    }
-    get(column) {
-        return this.value(column).toJS();
-    }
-    value(column) {
-        const index = this.columns.indexOf(column);
-        if (index === -1) {
-            throw new Error(`Unknown column "${column}". Available columns: ${this.columns.join(", ")}`);
-        }
-        const value = this.values[index];
-        if (!value) {
-            throw new Error(`Column "${column}" is missing a value`);
-        }
-        return value;
-    }
-    toObject() {
-        return Object.fromEntries(this.columns.map((column, index) => [column, this.values[index]?.toJS()]));
-    }
-    toValueMap() {
-        return Object.fromEntries(this.columns.map((column, index) => [column, this.values[index]]));
-    }
-}
-export function wrapExecuteResult(result) {
+export function wrapExecuteResult(result, rowMode = "object") {
     return {
         ...result,
-        rows: result.rows.map((row) => Row.fromRaw(result.columns, row.map(fromNativeValue))),
+        rows: result.rows.map((row) => {
+            const values = row.map((value) => Value._fromNative(fromNativeValue(value)).toJS());
+            if (rowMode === "array")
+                return values;
+            return Object.fromEntries(result.columns.map((column, index) => [column.name, values[index]]));
+        }),
     };
 }
-export function wrapExecuteBatchResult(result) {
+export function wrapExecuteBatchResult(result, rowMode = "object") {
     const statementIndex = result.statementIndex;
     if (typeof statementIndex !== "number" ||
         !Number.isSafeInteger(statementIndex) ||
@@ -44,7 +18,7 @@ export function wrapExecuteBatchResult(result) {
         throw new Error("executeBatch result is missing a valid statementIndex");
     }
     return {
-        ...wrapExecuteResult(result),
+        ...wrapExecuteResult(result, rowMode),
         statementIndex,
     };
 }

package/dist/snapshot-restore.d.ts

@@ -0,0 +1,6 @@
+import type { SnapshotRestoreBinding } from "./binding-types.js";
+export declare const SNAPSHOT_RESTORE_CHUNK_BYTES: number;
+/** Copies arbitrary caller-owned input into bounded transport-owned chunks. */
+export declare function ownedSnapshotRestoreChunks(chunk: Uint8Array): Generator<Uint8Array>;
+/** Pumps a snapshot into a bounded native restore without buffering the artifact. */
+export declare function restoreSnapshot<T>(source: ReadableStream<Uint8Array>, restore: SnapshotRestoreBinding<T>): Promise<T>;

package/dist/snapshot-restore.js

@@ -0,0 +1,101 @@
+export const SNAPSHOT_RESTORE_CHUNK_BYTES = 64 * 1024;
+/** Copies arbitrary caller-owned input into bounded transport-owned chunks. */
+export function* ownedSnapshotRestoreChunks(chunk) {
+    for (let offset = 0; offset < chunk.byteLength;) {
+        const end = Math.min(offset + SNAPSHOT_RESTORE_CHUNK_BYTES, chunk.byteLength);
+        const owned = new Uint8Array(end - offset);
+        owned.set(chunk.subarray(offset, end));
+        yield owned;
+        offset = end;
+    }
+}
+function waitForSnapshotRestoreCompletion(restore) {
+    return new Promise((resolve, reject) => {
+        const poll = () => {
+            try {
+                if (restore.isComplete()) {
+                    resolve();
+                    return;
+                }
+            }
+            catch (error) {
+                reject(error);
+                return;
+            }
+            // Keep this lightweight for long-running imports while still surfacing a
+            // decoder failure promptly when the producer has stopped yielding data.
+            setTimeout(poll, 10);
+        };
+        poll();
+    });
+}
+/** Pumps a snapshot into a bounded native restore without buffering the artifact. */
+export async function restoreSnapshot(source, restore) {
+    let reader;
+    try {
+        reader = source.getReader();
+    }
+    catch (error) {
+        // Some internal callers create the restore before entering this helper.
+        // Completion-aware cancellation prevents a locked source from stranding it.
+        await Promise.resolve()
+            .then(() => restore.cancel())
+            .catch(() => undefined);
+        throw error;
+    }
+    const backendCompletion = waitForSnapshotRestoreCompletion(restore).then(() => ({ kind: "backend-complete" }), (error) => ({ kind: "completion-error", error }));
+    let inputOpen = true;
+    try {
+        while (true) {
+            const outcome = await Promise.race([
+                reader.read().then((result) => ({ kind: "source", result }), (error) => ({ kind: "source-error", error })),
+                backendCompletion,
+            ]);
+            if (outcome.kind === "completion-error")
+                throw outcome.error;
+            if (outcome.kind === "backend-complete") {
+                // The decoder can reject after accepting a malformed chunk while the
+                // producer stalls forever. Stop that pending read and drain finish() so
+                // the backend's structured semantic error remains authoritative.
+                await reader.cancel().catch(() => undefined);
+                inputOpen = false;
+                return await restore.finish();
+            }
+            if (outcome.kind === "source-error")
+                throw outcome.error;
+            const { value, done } = outcome.result;
+            if (done)
+                break;
+            if (!(value instanceof Uint8Array)) {
+                throw new TypeError("snapshot stream chunks must be Uint8Array values");
+            }
+            for (const chunk of ownedSnapshotRestoreChunks(value)) {
+                try {
+                    await restore.write(chunk);
+                }
+                catch (writeError) {
+                    // The decoder may have rejected before accepting this chunk. Stop the
+                    // producer, then drain finish() so its semantic Lix error wins over the
+                    // transport-level write rejection.
+                    await reader.cancel(writeError).catch(() => undefined);
+                    inputOpen = false;
+                    return await restore.finish();
+                }
+            }
+        }
+        inputOpen = false;
+        return await restore.finish();
+    }
+    catch (error) {
+        if (inputOpen) {
+            inputOpen = false;
+            await Promise.resolve()
+                .then(() => restore.cancel())
+                .catch(() => undefined);
+        }
+        throw error;
+    }
+    finally {
+        reader.releaseLock();
+    }
+}

package/dist/storage-adapter.d.ts

@@ -1,30 +1,186 @@
+/** Opaque package-level storage selection accepted by `openLix()`. */
+export type LixStorage = {
+    readonly lixStorage: object;
+};
 /**
- * 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.
+ * Worker-loadable registration emitted by JavaScript storage packages.
+ * `moduleUrl` must export `createLixStorageProvider(options)` and is loaded in
+ * the same dedicated worker as the Lix Wasm engine.
  */
-export type LixStorageConnection = {
+export type LixStorageProviderRegistration = {
+    readonly version: 3;
+    readonly moduleUrl: string;
+    readonly options: unknown;
+};
+type JsProviderLixStorage = LixStorage & {
+    readonly lixStorage: LixStorageProviderRegistration;
+};
+type FilesystemStorageConnection = {
     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;
+type FilesystemLixStorage = LixStorage & {
+    readonly lixStorage: {
+        readonly version: 1;
+        readonly config: {
+            kind: "filesystem";
+            path: string;
+            syncAllFiles: boolean;
+        };
+        connect(connection: FilesystemStorageConnection | undefined): void;
+    };
 };
+export declare function isLixStorage(value: unknown): value is FilesystemLixStorage;
+export declare function isJsProviderLixStorage(value: unknown): value is JsProviderLixStorage;
 /**
- * Protocol implemented by JavaScript storage packages accepted by `openLix()`.
+ * JavaScript representation of `lix::storage::StorageSpace`.
  *
- * Applications normally use a concrete package such as
- * `@lix-js/storage-filesystem` rather than implementing this directly.
+ * These provider types intentionally mirror the Rust storage traits. Changes
+ * to `Storage`, `StorageRead`, `StorageWrite`, or `StorageScanSource` must be
+ * reflected here and in the single Rust↔JS bridge.
  */
-export type LixStorage = {
-    readonly lixStorage: {
-        readonly version: 1;
-        readonly config: LixStorageAdapterConfig;
-        connect(connection: LixStorageConnection | undefined): void;
+export type LixStorageSpace = {
+    id: number;
+    name: string;
+    valueSemantics: "mutable" | "immutable";
+    valueIntegrity: "backendVerified" | "contentAddressed";
+};
+export type LixStorageKeyRange = {
+    lower: LixStorageBound;
+    upper: LixStorageBound;
+};
+export type LixStorageBound = {
+    kind: "unbounded";
+} | {
+    kind: "included";
+    key: Uint8Array;
+} | {
+    kind: "excluded";
+    key: Uint8Array;
+};
+export type LixStorageProjection = "keyOnly" | "fullValue";
+export type LixStorageScanOrder = "ascending" | "descending";
+export type LixStorageReadOptions = {
+    snapshot?: Uint8Array;
+    consistency: "snapshot" | "staleOk" | "latest";
+    durability: "visible" | "durable";
+    /** Canonical unsigned 64-bit base-10 token obtained from `acquireSession()`. */
+    sessionToken?: string;
+};
+export type LixStorageWriteOptions = {
+    baseSnapshot?: Uint8Array;
+    idempotencyKey?: Uint8Array;
+    awaitDurable: boolean;
+    preconditions: LixStoragePrecondition[];
+    batchCapacityHintBytes: number;
+    /** Canonical unsigned 64-bit base-10 token obtained from `acquireSession()`. */
+    sessionToken?: string;
+};
+export type LixStoragePrecondition = {
+    kind: "keyAbsent";
+    space: LixStorageSpace;
+    key: Uint8Array;
+} | {
+    kind: "keyPresent";
+    space: LixStorageSpace;
+    key: Uint8Array;
+} | {
+    kind: "keyValueHashEquals";
+    space: LixStorageSpace;
+    key: Uint8Array;
+    hash: Uint8Array;
+} | {
+    kind: "keyValueEquals";
+    space: LixStorageSpace;
+    key: Uint8Array;
+    expected: Uint8Array;
+} | {
+    kind: "rangeEmpty";
+    space: LixStorageSpace;
+    range: LixStorageKeyRange;
+} | {
+    kind: "branchEquals";
+    refKey: Uint8Array;
+    expected: Uint8Array;
+};
+export type LixStorageGetManyRequest = {
+    space: LixStorageSpace;
+    keys: Uint8Array[];
+    options: {
+        projection: LixStorageProjection;
     };
 };
-export declare function isLixStorage(value: unknown): value is LixStorage;
+export type LixStorageProjectedValue = {
+    kind: "keyOnly";
+} | {
+    kind: "fullValue";
+    value: Uint8Array;
+};
+export type LixStorageReadEntry = {
+    key: Uint8Array;
+    value: LixStorageProjectedValue;
+};
+export type LixStoragePutEntry = {
+    key: Uint8Array;
+    value: Uint8Array;
+};
+export type LixStorageWriteStats = {
+    putEntries: number;
+    deletedEntries: number;
+    deletedRanges: number;
+    writtenBytes: number;
+    storageCalls: number;
+};
+export type LixStorageCommitResult = {
+    commitId?: Uint8Array;
+    stats: LixStorageWriteStats;
+};
+/** Mirrors `lix::storage::Storage`. */
+export interface LixStorageProvider {
+    /** Joins the active generation and returns its canonical unsigned 64-bit base-10 token. */
+    acquireSession(): Promise<string>;
+    beginRead(options: LixStorageReadOptions): Promise<LixStorageRead>;
+    beginWrite(options: LixStorageWriteOptions): Promise<LixStorageWrite>;
+    watchForChanges(): Promise<LixStorageChangeWatch>;
+    /** SDK lifecycle hook corresponding to releasing the Rust storage owner. */
+    close(): Promise<void>;
+}
+/** Mirrors `lix::storage::StorageChangeWatch`. */
+export interface LixStorageChangeWatch {
+    changed(): Promise<void>;
+    close(): void;
+}
+/** Mirrors `lix::storage::StorageRead`. */
+export interface LixStorageRead {
+    /** Decimal u128, or undefined to disable snapshot-derived caching. */
+    snapshotCacheKey(): string | undefined;
+    getMany(requests: LixStorageGetManyRequest[]): Promise<Array<LixStorageProjectedValue | null>>;
+    beginScan(space: LixStorageSpace, range: LixStorageKeyRange, options: {
+        projection: LixStorageProjection;
+        order: LixStorageScanOrder;
+    }): Promise<LixStorageScanSource>;
+}
+/** Mirrors `lix::storage::StorageScanSource`. */
+export interface LixStorageScanSource {
+    nextPage(limitRows: number): Promise<{
+        entries: LixStorageReadEntry[];
+        hasMore: boolean;
+    }>;
+}
+/** Mirrors `lix::storage::StorageWrite`. */
+export interface LixStorageWrite {
+    putMany(space: LixStorageSpace, entries: LixStoragePutEntry[]): Promise<void>;
+    replaceMany(space: LixStorageSpace, entries: LixStoragePutEntry[]): Promise<void>;
+    deleteMany(space: LixStorageSpace, keys: Uint8Array[]): Promise<void>;
+    deleteRange(space: LixStorageSpace, range: LixStorageKeyRange): Promise<void>;
+    commit(): Promise<LixStorageCommitResult>;
+    rollback(): Promise<void>;
+}
+export type LixStorageErrorCode = "LIX_STORAGE_UNSUPPORTED" | "LIX_STORAGE_INVALID_KEY" | "LIX_STORAGE_INVALID_CURSOR" | "LIX_STORAGE_READ_EXPIRED" | "LIX_STORAGE_WRITE_CONFLICT" | "LIX_STORAGE_PRECONDITION_FAILED" | "LIX_STORAGE_DURABILITY" | "LIX_STORAGE_FENCED" | "LIX_STORAGE_CLOSED" | "LIX_STORAGE_COMMIT_OUTCOME_UNKNOWN" | "LIX_STORAGE_CORRUPTION" | "LIX_STORAGE_IO";
+/** Error representation decoded back into `lix::storage::StorageError`. */
+export declare class LixStorageError extends Error {
+    readonly code: LixStorageErrorCode;
+    readonly details?: unknown;
+    constructor(code: LixStorageErrorCode, message: string, details?: unknown);
+}
+export {};

package/dist/storage-adapter.js

@@ -10,3 +10,24 @@ export function isLixStorage(value) {
         adapter.config?.kind ===
             "filesystem");
 }
+export function isJsProviderLixStorage(value) {
+    if (!value || typeof value !== "object" || !("lixStorage" in value)) {
+        return false;
+    }
+    const registration = value.lixStorage;
+    return Boolean(registration &&
+        typeof registration === "object" &&
+        registration.version === 3 &&
+        typeof registration.moduleUrl === "string");
+}
+/** Error representation decoded back into `lix::storage::StorageError`. */
+export class LixStorageError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "LixStorageError";
+        this.code = code;
+        this.details = details;
+    }
+}