@lix-js/sdk 0.8.4 → 0.10.0

package/dist/remote/protocol.d.ts

@@ -0,0 +1,178 @@
+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 type WireValue = {
+    kind: "null";
+    value: null;
+} | {
+    kind: "bool";
+    value: boolean;
+} | {
+    kind: "int";
+    value: number;
+} | {
+    kind: "float";
+    value: number;
+} | {
+    kind: "text";
+    value: string;
+} | {
+    kind: "json";
+    value: unknown;
+} | {
+    kind: "blob";
+    base64: string;
+};
+export type WireRequestBlobSplice = {
+    kind: "blob-splice";
+    baseSha256: string;
+    resultSha256: string;
+    prefixBytes: number;
+    suffixBytes: number;
+    insertBase64: string;
+};
+export type WireRequestValue = WireValue | WireRequestBlobSplice;
+export type RemoteHandshake = {
+    protocolVersion: number;
+    activeBranchId: string;
+    activeAccountId: string;
+    sessionId: string;
+};
+export type RemoteHandshakeRequest = {
+    activeBranchId?: string;
+    activeAccountId?: string;
+};
+export type RemoteExecuteRequest = {
+    sql: string;
+    params: WireRequestValue[];
+    options?: {
+        originKey?: string;
+    };
+    cacheBlobs?: true;
+};
+export type RemoteExecuteBatchRequest = {
+    statements: Array<{
+        sql: string;
+        params: WireRequestValue[];
+    }>;
+    options?: {
+        originKey?: string;
+    };
+    cacheBlobs?: true;
+};
+export type RemoteExecuteResponse = {
+    columns: string[];
+    rows: WireValue[][];
+    rowsAffected: number;
+    notices: Array<{
+        code: string;
+        message: string;
+        hint?: string;
+    }>;
+};
+export type RemoteObserveRequest = {
+    sql: string;
+    params: WireValue[];
+};
+export type RemoteObserveSubscription = RemoteObserveRequest & {
+    id: string;
+};
+export type RemoteMultiplexObserveRequest = {
+    subscriptions: RemoteObserveSubscription[];
+};
+type RemoteObserveEventBase = {
+    sequence: number;
+    mutationSequence: number;
+};
+export type RemoteObserveBlobDelta = {
+    kind: "single-blob-splice";
+    baseSequence: number;
+    prefixBytes: number;
+    suffixBytes: number;
+    insertBase64: string;
+};
+type RemoteObserveRowSplice = {
+    kind: "row-splice";
+    baseSequence: number;
+    prefixRows: number;
+    deleteRows: number;
+    insertRows: WireValue[][];
+};
+type RemoteObserveDelta = RemoteObserveBlobDelta | RemoteObserveRowSplice;
+export type RemoteObserveEvent = RemoteObserveEventBase & ({
+    result: RemoteExecuteResponse;
+    delta?: never;
+} | {
+    result?: never;
+    delta: RemoteObserveDelta;
+});
+export type RemoteMultiplexObserveEvent = RemoteObserveEvent & {
+    subscriptionId: string;
+};
+export type RemoteCreateBranchRequest = {
+    id?: string;
+    name: string;
+    fromCommitId?: string;
+};
+export type RemoteCreateBranchResponse = {
+    id: string;
+    name: string;
+    hidden: boolean;
+    commitId: string;
+};
+export type RemoteCreateCheckpointResponse = {
+    commitId: string;
+};
+export type RemoteUndoResponse = {
+    branchId: string;
+    targetCommitId: string;
+    inverseCommitId: string;
+};
+export type RemoteRedoResponse = {
+    branchId: string;
+    targetCommitId: string;
+    replayCommitId: string;
+};
+export type RemoteSwitchBranchRequest = {
+    branchId: string;
+};
+export type RemoteSwitchBranchResponse = {
+    branchId: string;
+};
+export type RemoteErrorBody = {
+    error: {
+        code?: string;
+        message?: string;
+        hint?: string;
+        details?: unknown;
+    };
+};
+export type RemoteObserveErrorEvent = RemoteErrorBody & {
+    retryable?: boolean;
+};
+export type RemoteMultiplexObserveErrorEvent = RemoteObserveErrorEvent & {
+    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 decodeObserveEvent(value: unknown, base?: BindingObserveEvent): BindingObserveEvent;
+export declare function remoteError(code: string, message: string, options?: {
+    hint?: string;
+    details?: unknown;
+    status?: number;
+}): Error & {
+    code: string;
+    hint?: string;
+    details?: unknown;
+    status?: number;
+};
+export declare function protocolError(message: string): Error & {
+    code: string;
+};
+export declare function errorFromResponseBody(value: unknown, status?: number): Error & {
+    code: string;
+};
+export declare function record(value: unknown, description: string): Record<string, unknown>;
+export {};

package/dist/remote/protocol.js

@@ -0,0 +1,367 @@
+export const REMOTE_PROTOCOL_VERSION = 2;
+export const REMOTE_PROTOCOL_PATH = "/lix/v1/";
+export function encodeWireValue(value) {
+    switch (value.kind) {
+        case "null":
+            return { kind: "null", value: null };
+        case "boolean":
+            return { kind: "bool", value: value.value };
+        case "integer":
+            return { kind: "int", value: value.value };
+        case "real":
+            return { kind: "float", value: value.value };
+        case "text":
+            return { kind: "text", value: value.value };
+        case "json":
+            return { kind: "json", value: value.value };
+        case "blob":
+            return { kind: "blob", base64: bytesToBase64(value.blob) };
+    }
+}
+export function decodeExecuteResult(value) {
+    const result = record(value, "execute result");
+    const columns = stringArray(result.columns, "execute result columns");
+    if (!Array.isArray(result.rows)) {
+        throw protocolError("execute result rows must be an array");
+    }
+    const rows = result.rows.map((row, rowIndex) => {
+        if (!Array.isArray(row)) {
+            throw protocolError(`execute result row ${rowIndex} must be an array`);
+        }
+        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));
+    });
+    if (typeof result.rowsAffected !== "number" ||
+        !Number.isSafeInteger(result.rowsAffected) ||
+        result.rowsAffected < 0) {
+        throw protocolError("execute result rowsAffected must be a non-negative safe integer");
+    }
+    if (!Array.isArray(result.notices)) {
+        throw protocolError("execute result notices must be an array");
+    }
+    const notices = result.notices.map((notice, index) => {
+        const item = record(notice, `execute result notice ${index}`);
+        if (typeof item.code !== "string" || typeof item.message !== "string") {
+            throw protocolError(`execute result notice ${index} requires code and message`);
+        }
+        if (item.hint !== undefined && typeof item.hint !== "string") {
+            throw protocolError(`execute result notice ${index} hint must be a string`);
+        }
+        return {
+            code: item.code,
+            message: item.message,
+            ...(item.hint === undefined ? {} : { hint: item.hint }),
+        };
+    });
+    return { columns, rows, rowsAffected: result.rowsAffected, notices };
+}
+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)}`);
+    }
+    if (typeof handshake.activeBranchId !== "string" ||
+        handshake.activeBranchId.length === 0) {
+        throw protocolError("remote handshake requires activeBranchId");
+    }
+    if (typeof handshake.activeAccountId !== "string" ||
+        handshake.activeAccountId.length === 0) {
+        throw protocolError("remote handshake requires activeAccountId");
+    }
+    if (typeof handshake.sessionId !== "string" ||
+        !/^[\x21-\x7e]{1,256}$/.test(handshake.sessionId)) {
+        throw protocolError("remote handshake requires a valid sessionId");
+    }
+    return {
+        protocolVersion: REMOTE_PROTOCOL_VERSION,
+        activeBranchId: handshake.activeBranchId,
+        activeAccountId: handshake.activeAccountId,
+        sessionId: handshake.sessionId,
+    };
+}
+export function decodeObserveEvent(value, base) {
+    const event = record(value, "observe event");
+    if (typeof event.sequence !== "number" ||
+        !Number.isSafeInteger(event.sequence) ||
+        event.sequence < 0) {
+        throw protocolError("observe event sequence must be a non-negative safe integer");
+    }
+    if (typeof event.mutationSequence !== "number" ||
+        !Number.isSafeInteger(event.mutationSequence) ||
+        event.mutationSequence < 0) {
+        throw protocolError("observe event mutationSequence must be a non-negative safe integer");
+    }
+    const hasResult = event.result !== undefined;
+    const hasDelta = event.delta !== undefined;
+    if (hasResult === hasDelta) {
+        throw protocolError("observe event requires exactly one of result or delta");
+    }
+    const sequence = event.sequence;
+    return {
+        sequence,
+        mutationSequence: event.mutationSequence,
+        rows: hasResult
+            ? decodeExecuteResult(event.result)
+            : applyObserveDelta(event.delta, sequence, base),
+    };
+}
+function applyObserveDelta(value, sequence, base) {
+    const delta = record(value, "observe event delta");
+    switch (delta.kind) {
+        case "single-blob-splice":
+            return applyObserveBlobDelta(delta, sequence, base);
+        case "row-splice":
+            return applyObserveRowSplice(delta, sequence, base);
+        default:
+            throw protocolError(`unknown observe delta kind: ${String(delta.kind)}`);
+    }
+}
+function applyObserveBlobDelta(delta, sequence, base) {
+    const baseSequence = nonNegativeSafeInteger(delta.baseSequence, "observe delta baseSequence");
+    const prefixBytes = nonNegativeSafeInteger(delta.prefixBytes, "observe delta prefixBytes");
+    const suffixBytes = nonNegativeSafeInteger(delta.suffixBytes, "observe delta suffixBytes");
+    if (typeof delta.insertBase64 !== "string") {
+        throw protocolError("observe delta insertBase64 must be a string");
+    }
+    if (base === undefined ||
+        base.sequence !== baseSequence ||
+        sequence !== baseSequence + 1) {
+        throw protocolError("observe blob delta does not match its transport base");
+    }
+    const baseValue = base.rows.rows[0]?.[0];
+    if (base.rows.columns.length !== 1 ||
+        base.rows.columns[0] !== "content" ||
+        base.rows.rows.length !== 1 ||
+        base.rows.rows[0]?.length !== 1 ||
+        base.rows.rowsAffected !== 0 ||
+        base.rows.notices.length !== 0 ||
+        baseValue?.kind !== "blob") {
+        throw protocolError("observe blob delta base is not a point blob result");
+    }
+    if (prefixBytes + suffixBytes > baseValue.blob.byteLength) {
+        throw protocolError("observe blob delta prefix and suffix overlap");
+    }
+    const insert = base64ToBytes(delta.insertBase64);
+    const nextLength = prefixBytes + insert.byteLength + suffixBytes;
+    if (!Number.isSafeInteger(nextLength)) {
+        throw protocolError("observe blob delta result is too large");
+    }
+    let blob;
+    try {
+        blob = new Uint8Array(nextLength);
+    }
+    catch {
+        throw protocolError("observe blob delta result is too large");
+    }
+    blob.set(baseValue.blob.subarray(0, prefixBytes), 0);
+    blob.set(insert, prefixBytes);
+    blob.set(baseValue.blob.subarray(baseValue.blob.byteLength - suffixBytes), prefixBytes + insert.byteLength);
+    return {
+        columns: ["content"],
+        rows: [[{ kind: "blob", value: null, blob }]],
+        rowsAffected: 0,
+        notices: [],
+    };
+}
+function applyObserveRowSplice(delta, sequence, base) {
+    const baseSequence = nonNegativeSafeInteger(delta.baseSequence, "observe row delta baseSequence");
+    const prefixRows = nonNegativeSafeInteger(delta.prefixRows, "observe row delta prefixRows");
+    const deleteRows = nonNegativeSafeInteger(delta.deleteRows, "observe row delta deleteRows");
+    if (base === undefined ||
+        base.sequence !== baseSequence ||
+        sequence !== baseSequence + 1) {
+        throw protocolError("observe row delta does not match its transport base");
+    }
+    if (!Array.isArray(delta.insertRows)) {
+        throw protocolError("observe row delta insertRows must be an array");
+    }
+    if (prefixRows > base.rows.rows.length ||
+        deleteRows > base.rows.rows.length - prefixRows) {
+        throw protocolError("observe row delta splice range is outside its transport base");
+    }
+    const suffixStart = prefixRows + deleteRows;
+    const nextRowCount = prefixRows + delta.insertRows.length + (base.rows.rows.length - suffixStart);
+    if (!Number.isSafeInteger(nextRowCount) ||
+        nextRowCount > 0xffff_ffff) {
+        throw protocolError("observe row delta result is too large");
+    }
+    let rows;
+    try {
+        rows = new Array(nextRowCount);
+    }
+    catch {
+        throw protocolError("observe row delta result is too large");
+    }
+    let destination = 0;
+    for (let index = 0; index < prefixRows; index += 1) {
+        rows[destination++] = base.rows.rows[index];
+    }
+    for (let rowIndex = 0; rowIndex < delta.insertRows.length; rowIndex += 1) {
+        const row = delta.insertRows[rowIndex];
+        if (!Array.isArray(row)) {
+            throw protocolError(`observe row delta insert row ${rowIndex} must be an array`);
+        }
+        if (row.length !== base.rows.columns.length) {
+            throw protocolError(`observe row delta insert row ${rowIndex} has ${row.length} values for ${base.rows.columns.length} columns`);
+        }
+        rows[destination++] = row.map((entry) => decodeWireValue(entry));
+    }
+    for (let index = suffixStart; index < base.rows.rows.length; index += 1) {
+        rows[destination++] = base.rows.rows[index];
+    }
+    return {
+        columns: [...base.rows.columns],
+        rows,
+        rowsAffected: base.rows.rowsAffected,
+        notices: base.rows.notices.map((notice) => ({ ...notice })),
+    };
+}
+export function remoteError(code, message, options = {}) {
+    const error = new Error(message);
+    error.name = "LixError";
+    error.code = code;
+    error.hint = options.hint;
+    error.details = options.details;
+    error.status = options.status;
+    return error;
+}
+export function protocolError(message) {
+    return remoteError("LIX_REMOTE_PROTOCOL_ERROR", message);
+}
+export function errorFromResponseBody(value, status) {
+    const body = record(value, "remote error response");
+    const rawError = record(body.error, "remote error response error");
+    return remoteError(typeof rawError.code === "string"
+        ? rawError.code
+        : "LIX_REMOTE_REQUEST_FAILED", typeof rawError.message === "string"
+        ? rawError.message
+        : status === undefined
+            ? "Remote Lix operation failed"
+            : `Remote Lix request failed with status ${status}`, {
+        hint: typeof rawError.hint === "string" ? rawError.hint : undefined,
+        details: rawError.details,
+        status,
+    });
+}
+export function record(value, description) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw protocolError(`${description} must be an object`);
+    }
+    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) {
+        case "null":
+            if (wire.value !== null)
+                throw protocolError("null wire value is invalid");
+            return { kind: "null", value: null };
+        case "bool":
+            if (typeof wire.value !== "boolean") {
+                throw protocolError("bool wire value is invalid");
+            }
+            return { kind: "boolean", value: wire.value };
+        case "int":
+            if (typeof wire.value !== "number" || !Number.isSafeInteger(wire.value)) {
+                throw protocolError("int wire value is invalid");
+            }
+            return { kind: "integer", value: wire.value };
+        case "float":
+            if (typeof wire.value !== "number" || !Number.isFinite(wire.value)) {
+                throw protocolError("float wire value is invalid");
+            }
+            return { kind: "real", value: wire.value };
+        case "text":
+            if (typeof wire.value !== "string") {
+                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 "blob":
+            if (typeof wire.base64 !== "string") {
+                throw protocolError("blob wire value is invalid");
+            }
+            return { kind: "blob", value: null, blob: base64ToBytes(wire.base64) };
+        default:
+            throw protocolError(`unknown wire value kind: ${String(wire.kind)}`);
+    }
+}
+function stringArray(value, description) {
+    if (!Array.isArray(value) ||
+        !value.every((entry) => typeof entry === "string")) {
+        throw protocolError(`${description} must be an array of strings`);
+    }
+    return [...value];
+}
+function nonNegativeSafeInteger(value, description) {
+    if (typeof value !== "number" ||
+        !Number.isSafeInteger(value) ||
+        value < 0) {
+        throw protocolError(`${description} must be a non-negative safe integer`);
+    }
+    return value;
+}
+function assertJsonValue(value, description) {
+    if (value === null ||
+        typeof value === "boolean" ||
+        (typeof value === "number" &&
+            Number.isFinite(value) &&
+            (!Number.isInteger(value) || Number.isSafeInteger(value))) ||
+        (typeof value === "string" && value.isWellFormed())) {
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const entry of value)
+            assertJsonValue(entry, description);
+        return;
+    }
+    if (value && typeof value === "object") {
+        for (const entry of Object.values(value)) {
+            assertJsonValue(entry, description);
+        }
+        return;
+    }
+    throw protocolError(`${description} is not valid Lix JSON`);
+}
+function bytesToBase64(bytes) {
+    const nativeToBase64 = bytes.toBase64;
+    if (typeof nativeToBase64 === "function") {
+        return nativeToBase64.call(bytes);
+    }
+    let binary = "";
+    const chunkSize = 0x8000;
+    for (let offset = 0; offset < bytes.length; offset += chunkSize) {
+        binary += String.fromCharCode(...bytes.subarray(offset, offset + chunkSize));
+    }
+    return btoa(binary);
+}
+function base64ToBytes(base64) {
+    const nativeFromBase64 = Uint8Array.fromBase64;
+    if (typeof nativeFromBase64 === "function") {
+        try {
+            return nativeFromBase64(base64);
+        }
+        catch {
+            throw protocolError("blob wire value contains invalid base64");
+        }
+    }
+    let binary;
+    try {
+        binary = atob(base64);
+    }
+    catch {
+        throw protocolError("blob wire value contains invalid base64");
+    }
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1) {
+        bytes[index] = binary.charCodeAt(index);
+    }
+    return bytes;
+}

package/dist/remote/sse.d.ts

@@ -0,0 +1,12 @@
+export type SseEvent = {
+    event: string;
+    data: string;
+    retry?: number;
+};
+/**
+ * Parses a fetch response body as a stream of server-sent events.
+ *
+ * The caller remains responsible for validating the response status and
+ * content type before passing its body here.
+ */
+export declare function readSseEvents(stream: ReadableStream<Uint8Array>): AsyncGenerator<SseEvent, void, void>;

package/dist/remote/sse.js

@@ -0,0 +1,87 @@
+/**
+ * Parses a fetch response body as a stream of server-sent events.
+ *
+ * The caller remains responsible for validating the response status and
+ * content type before passing its body here.
+ */
+export async function* readSseEvents(stream) {
+    const decoder = new TextDecoder();
+    const reader = stream.getReader();
+    let bufferedText = "";
+    let eventName = "";
+    let retry;
+    let dataLines = [];
+    function processLine(line) {
+        if (line.length === 0) {
+            return dispatchEvent();
+        }
+        if (line.startsWith(":")) {
+            return undefined;
+        }
+        const colonIndex = line.indexOf(":");
+        const field = colonIndex === -1 ? line : line.slice(0, colonIndex);
+        let value = colonIndex === -1 ? "" : line.slice(colonIndex + 1);
+        if (value.startsWith(" "))
+            value = value.slice(1);
+        switch (field) {
+            case "event":
+                eventName = value;
+                break;
+            case "data":
+                dataLines.push(value);
+                break;
+            case "retry": {
+                if (/^\d+$/.test(value)) {
+                    const parsed = Number(value);
+                    if (Number.isSafeInteger(parsed))
+                        retry = parsed;
+                }
+                break;
+            }
+            // Event IDs and extension fields are intentionally ignored. Remote Lix
+            // observations use their payload sequence for resumption instead.
+            default:
+                break;
+        }
+        return undefined;
+    }
+    function dispatchEvent() {
+        const hasData = dataLines.length !== 0;
+        const event = hasData
+            ? {
+                event: eventName.length === 0 ? "message" : eventName,
+                data: dataLines.join("\n"),
+                ...(retry === undefined ? {} : { retry }),
+            }
+            : undefined;
+        eventName = "";
+        retry = undefined;
+        dataLines = [];
+        return event;
+    }
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            bufferedText += decoder.decode(value, { stream: true });
+            let newlineIndex = bufferedText.indexOf("\n");
+            while (newlineIndex !== -1) {
+                let line = bufferedText.slice(0, newlineIndex);
+                bufferedText = bufferedText.slice(newlineIndex + 1);
+                if (line.endsWith("\r"))
+                    line = line.slice(0, -1);
+                const event = processLine(line);
+                if (event !== undefined)
+                    yield event;
+                newlineIndex = bufferedText.indexOf("\n");
+            }
+        }
+        decoder.decode();
+        // SSE dispatches only at a blank line. An incomplete final frame indicates
+        // a truncated connection and is deliberately left for the caller to retry.
+    }
+    finally {
+        reader.releaseLock();
+    }
+}

package/dist/snapshot-persistence.d.ts

@@ -0,0 +1,7 @@
+export type SnapshotPersistenceAfterCommitError = Error & {
+    readonly code: "LIX_SNAPSHOT_PERSISTENCE_FAILED";
+    readonly lixSnapshotOperationCommitted: true;
+};
+/** Marks that the engine operation committed before durable snapshot saving failed. */
+export declare function snapshotPersistenceAfterCommitError(cause: unknown): SnapshotPersistenceAfterCommitError;
+export declare function isSnapshotPersistenceAfterCommitError(error: unknown): error is SnapshotPersistenceAfterCommitError;

package/dist/snapshot-persistence.js

@@ -0,0 +1,26 @@
+const OPERATION_COMMITTED = "lixSnapshotOperationCommitted";
+/** Marks that the engine operation committed before durable snapshot saving failed. */
+export function snapshotPersistenceAfterCommitError(cause) {
+    const message = cause instanceof Error
+        ? cause.message
+        : "Saving the committed Lix snapshot failed";
+    const error = new Error(message, { cause });
+    error.name = "LixSnapshotPersistenceError";
+    Object.defineProperties(error, {
+        code: {
+            value: "LIX_SNAPSHOT_PERSISTENCE_FAILED",
+            enumerable: true,
+        },
+        [OPERATION_COMMITTED]: {
+            value: true,
+            enumerable: true,
+        },
+    });
+    return error;
+}
+export function isSnapshotPersistenceAfterCommitError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        OPERATION_COMMITTED in error &&
+        error[OPERATION_COMMITTED] === true);
+}