@lix-js/sdk 0.11.0 → 0.12.1

package/dist/worker/protocol.d.ts

@@ -1,5 +1,5 @@
 import type { BindingBatchStatement, BindingParam, LixStorageConfig } from "../binding-types.js";
-import type { CreateBranchOptions, ExecuteOptions, JsonValue, LixBatchOptions, MergeBranchOptions, SwitchBranchOptions, LixTelemetrySpan } from "../types.js";
+import type { CreateBranchOptions, ExecuteOptions, LixBatchOptions, MergeBranchOptions, SwitchBranchOptions, LixTelemetrySpan } from "../types.js";
 export type WorkerRequest = {
     id: number;
     operation: WorkerOperation;
@@ -35,18 +35,6 @@ export type WorkerOperation = {
     kind: "activeBranchId";
 } | {
     kind: "activeAccountId";
-} | {
-    kind: "clientState.entries";
-} | {
-    kind: "clientState.get";
-    key: string;
-} | {
-    kind: "clientState.set";
-    key: string;
-    value: JsonValue;
-} | {
-    kind: "clientState.delete";
-    key: string;
 } | {
     kind: "createBranch";
     options: CreateBranchOptions;
@@ -70,8 +58,6 @@ export type WorkerOperation = {
     paths: string[];
 } | {
     kind: "syncDiskToLix";
-} | {
-    kind: "exportSnapshot";
 } | {
     kind: "observe";
     sql: string;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@lix-js/sdk",
 	"type": "module",
-	"version": "0.11.0",
+	"version": "0.12.1",
 	"license": "MIT",
 	"repository": {
 		"type": "git",
@@ -17,13 +17,9 @@
 			"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"
+		"./server-protocol": {
+			"types": "./dist/remote/server-protocol.d.ts",
+			"default": "./dist/remote/server-protocol.js"
 		}
 	},
 	"imports": {
@@ -57,10 +53,10 @@
 		"typecheck": "tsc -p tsconfig.test.json --noEmit"
 	},
 	"optionalDependencies": {
-		"@lix-js/sdk-darwin-arm64": "0.11.0",
-		"@lix-js/sdk-linux-arm64": "0.11.0",
-		"@lix-js/sdk-linux-x64": "0.11.0",
-		"@lix-js/sdk-win32-x64": "0.11.0"
+		"@lix-js/sdk-darwin-arm64": "0.12.1",
+		"@lix-js/sdk-linux-arm64": "0.12.1",
+		"@lix-js/sdk-linux-x64": "0.12.1",
+		"@lix-js/sdk-win32-x64": "0.12.1"
 	},
 	"devDependencies": {
 		"@vitest/browser-playwright": "4.1.10",

package/dist/client-state.d.ts

@@ -1,53 +0,0 @@
-import type { LixBinding } from "./binding-types.js";
-import type { JsonValue, LixSnapshotStorage } from "./types.js";
-export declare const ACTIVE_BRANCH_CLIENT_STATE_KEY = "lix_active_branch_id";
-export declare const ACTIVE_ACCOUNT_CLIENT_STATE_KEY = "lix_active_account_id";
-export type LixClientState = {
-    /** Returns the hydrated client-local value without a network round trip. */
-    get<T extends JsonValue = JsonValue>(key: string): T | undefined;
-    /** Persists a client-local value in the configured client storage. */
-    set(key: string, value: JsonValue): Promise<void>;
-    /** Deletes a client-local value from the configured client storage. */
-    delete(key: string): Promise<void>;
-    /** Subscribes to successful mutations made through this client-state handle. */
-    subscribe(listener: () => void): () => void;
-};
-export type ManagedClientState = LixClientState & {
-    close(): Promise<void>;
-};
-export declare function unavailableClientState(): LixClientState;
-type ClientStateBinding = LixBinding & {
-    exportSnapshot?: () => Promise<Uint8Array>;
-};
-export type OpenClientStateOptions = {
-    readonly binding: ClientStateBinding;
-    readonly saveSnapshot?: (snapshot: Uint8Array) => Promise<void>;
-    readonly closeBinding?: boolean;
-};
-/**
- * Opens the typed client-state facade over a private local Rust Lix.
- *
- * Values are ordinary global, untracked `lix_key_value` rows. The physical
- * prefix is intentionally private so built-in Lix key/value rows never leak
- * through this small API.
- */
-export declare function openClientState(options: OpenClientStateOptions): Promise<ManagedLixClientState>;
-export declare class ManagedLixClientState implements LixClientState {
-    #private;
-    constructor(options: OpenClientStateOptions, initial: Map<string, JsonValue>);
-    get<T extends JsonValue = JsonValue>(key: string): T | undefined;
-    set(key: string, value: JsonValue): Promise<void>;
-    delete(key: string): Promise<void>;
-    subscribe(listener: () => void): () => void;
-    close(): Promise<void>;
-}
-/**
- * Opens client state directly over snapshot storage without starting a local
- * Lix runtime. This is used by remote Lix connections, where the storage
- * option persists client-local state rather than the remote workspace.
- */
-export declare function openStoredClientState(options: {
-    readonly storage: LixSnapshotStorage;
-    readonly namespace: string;
-}): Promise<ManagedClientState>;
-export {};

package/dist/client-state.js

@@ -1,315 +0,0 @@
-import { isSnapshotPersistenceAfterCommitError } from "./snapshot-persistence.js";
-import { Value } from "./value.js";
-export const ACTIVE_BRANCH_CLIENT_STATE_KEY = "lix_active_branch_id";
-export const ACTIVE_ACCOUNT_CLIENT_STATE_KEY = "lix_active_account_id";
-const STORED_CLIENT_STATE_HEADER = "lix-client-state-v1\n";
-export function unavailableClientState() {
-    const unavailable = () => {
-        const error = new Error("Lix client state requires client storage; pass storage to openLix()");
-        error.name = "LixError";
-        error.code = "LIX_CLIENT_STORAGE_REQUIRED";
-        return error;
-    };
-    return {
-        get: () => undefined,
-        set: async () => {
-            throw unavailable();
-        },
-        delete: async () => {
-            throw unavailable();
-        },
-        subscribe: () => () => undefined,
-    };
-}
-/**
- * Opens the typed client-state facade over a private local Rust Lix.
- *
- * Values are ordinary global, untracked `lix_key_value` rows. The physical
- * prefix is intentionally private so built-in Lix key/value rows never leak
- * through this small API.
- */
-export async function openClientState(options) {
-    const entries = options.binding.clientStateEntries;
-    if (!entries) {
-        throw new Error("The selected Lix binding does not support typed client state");
-    }
-    const initial = new Map();
-    for (const entry of await entries.call(options.binding)) {
-        assertClientStateKey(entry.key);
-        assertJsonValue(entry.value);
-        initial.set(entry.key, cloneJsonValue(entry.value));
-    }
-    return new ManagedLixClientState(options, initial);
-}
-export class ManagedLixClientState {
-    #binding;
-    #saveSnapshot;
-    #closeBinding;
-    #values;
-    #listeners = new Set();
-    #operationQueue = Promise.resolve();
-    #closePromise;
-    #acceptingOperations = true;
-    constructor(options, initial) {
-        this.#binding = options.binding;
-        this.#saveSnapshot = options.saveSnapshot;
-        this.#closeBinding = options.closeBinding ?? false;
-        this.#values = initial;
-    }
-    get(key) {
-        assertClientStateKey(key);
-        const value = this.#values.get(key);
-        return value === undefined ? undefined : cloneJsonValue(value);
-    }
-    set(key, value) {
-        assertClientStateKey(key);
-        assertJsonValue(value);
-        this.#assertOpen();
-        const nextValue = cloneJsonValue(value);
-        return this.#enqueue(async () => {
-            const set = this.#binding.clientStateSet;
-            if (!set)
-                throw new Error("Typed Lix client state is unavailable");
-            try {
-                await set.call(this.#binding, key, nextValue);
-            }
-            catch (error) {
-                if (!isSnapshotPersistenceAfterCommitError(error))
-                    throw error;
-                this.#commitSet(key, nextValue);
-                throw error;
-            }
-            this.#commitSet(key, nextValue);
-            await this.#persist();
-        });
-    }
-    delete(key) {
-        assertClientStateKey(key);
-        this.#assertOpen();
-        return this.#enqueue(async () => {
-            const deleteValue = this.#binding.clientStateDelete;
-            if (!deleteValue)
-                throw new Error("Typed Lix client state is unavailable");
-            try {
-                await deleteValue.call(this.#binding, key);
-            }
-            catch (error) {
-                if (!isSnapshotPersistenceAfterCommitError(error))
-                    throw error;
-                this.#commitDelete(key);
-                throw error;
-            }
-            this.#commitDelete(key);
-            await this.#persist();
-        });
-    }
-    subscribe(listener) {
-        if (typeof listener !== "function") {
-            throw new TypeError("clientState.subscribe() requires a function");
-        }
-        this.#assertOpen();
-        this.#listeners.add(listener);
-        return () => this.#listeners.delete(listener);
-    }
-    async close() {
-        if (this.#closePromise)
-            return this.#closePromise;
-        this.#acceptingOperations = false;
-        this.#closePromise = (async () => {
-            await this.#operationQueue;
-            this.#listeners.clear();
-            if (this.#closeBinding)
-                await this.#binding.close();
-        })();
-        return this.#closePromise;
-    }
-    #enqueue(operation) {
-        const result = this.#operationQueue.then(operation, operation);
-        this.#operationQueue = result.then(() => undefined, () => undefined);
-        return result;
-    }
-    async #persist() {
-        if (!this.#saveSnapshot)
-            return;
-        if (!this.#binding.exportSnapshot) {
-            throw new Error("The selected Lix binding cannot export storage snapshots");
-        }
-        await this.#saveSnapshot(await this.#binding.exportSnapshot());
-    }
-    #commitSet(key, value) {
-        this.#values.set(key, value);
-        this.#publish();
-    }
-    #commitDelete(key) {
-        if (this.#values.delete(key))
-            this.#publish();
-    }
-    #publish() {
-        for (const listener of [...this.#listeners]) {
-            try {
-                listener();
-            }
-            catch {
-                // Subscribers do not participate in the completed local transaction.
-            }
-        }
-    }
-    #assertOpen() {
-        if (!this.#acceptingOperations) {
-            throw new Error("Lix client state is closed");
-        }
-    }
-}
-/**
- * Opens client state directly over snapshot storage without starting a local
- * Lix runtime. This is used by remote Lix connections, where the storage
- * option persists client-local state rather than the remote workspace.
- */
-export async function openStoredClientState(options) {
-    const snapshot = await options.storage.load(options.namespace);
-    if (snapshot !== undefined && !(snapshot instanceof Uint8Array)) {
-        throw new TypeError("Client-state storage load() must return a Uint8Array");
-    }
-    return new StoredClientState(options.storage, options.namespace, decodeStoredClientState(snapshot));
-}
-class StoredClientState {
-    #storage;
-    #namespace;
-    #values;
-    #listeners = new Set();
-    #operationQueue = Promise.resolve();
-    #closePromise;
-    #acceptingOperations = true;
-    #dirty = false;
-    constructor(storage, namespace, values) {
-        this.#storage = storage;
-        this.#namespace = namespace;
-        this.#values = values;
-    }
-    get(key) {
-        assertClientStateKey(key);
-        const value = this.#values.get(key);
-        return value === undefined ? undefined : cloneJsonValue(value);
-    }
-    set(key, value) {
-        assertClientStateKey(key);
-        assertJsonValue(value);
-        this.#assertOpen();
-        const nextValue = cloneJsonValue(value);
-        return this.#enqueue(async () => {
-            this.#values.set(key, nextValue);
-            this.#dirty = true;
-            this.#publish();
-            await this.#persist();
-        });
-    }
-    delete(key) {
-        assertClientStateKey(key);
-        this.#assertOpen();
-        return this.#enqueue(async () => {
-            if (this.#values.delete(key))
-                this.#publish();
-            this.#dirty = true;
-            await this.#persist();
-        });
-    }
-    subscribe(listener) {
-        if (typeof listener !== "function") {
-            throw new TypeError("clientState.subscribe() requires a function");
-        }
-        this.#assertOpen();
-        this.#listeners.add(listener);
-        return () => this.#listeners.delete(listener);
-    }
-    async close() {
-        if (this.#closePromise)
-            return this.#closePromise;
-        this.#acceptingOperations = false;
-        this.#closePromise = (async () => {
-            await this.#operationQueue;
-            if (this.#dirty)
-                await this.#persist();
-            this.#listeners.clear();
-        })();
-        return this.#closePromise;
-    }
-    #enqueue(operation) {
-        const result = this.#operationQueue.then(operation, operation);
-        this.#operationQueue = result.then(() => undefined, () => undefined);
-        return result;
-    }
-    async #persist() {
-        await this.#storage.save(this.#namespace, encodeStoredClientState(this.#values));
-        this.#dirty = false;
-    }
-    #publish() {
-        for (const listener of [...this.#listeners]) {
-            try {
-                listener();
-            }
-            catch {
-                // Subscribers do not participate in the completed mutation.
-            }
-        }
-    }
-    #assertOpen() {
-        if (!this.#acceptingOperations) {
-            throw new Error("Lix client state is closed");
-        }
-    }
-}
-function encodeStoredClientState(values) {
-    const entries = [...values].map(([key, value]) => [
-        key,
-        cloneJsonValue(value),
-    ]);
-    return new TextEncoder().encode(`${STORED_CLIENT_STATE_HEADER}${JSON.stringify(entries)}`);
-}
-function decodeStoredClientState(snapshot) {
-    if (snapshot === undefined)
-        return new Map();
-    const header = new TextEncoder().encode(STORED_CLIENT_STATE_HEADER);
-    if (snapshot.length < header.length ||
-        header.some((byte, index) => snapshot[index] !== byte)) {
-        throw new Error("Stored Lix client state header is invalid");
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(snapshot.subarray(header.length)));
-    }
-    catch (error) {
-        throw new Error("Stored Lix client state is invalid", { cause: error });
-    }
-    if (!Array.isArray(parsed)) {
-        throw new Error("Stored Lix client state entries must be an array");
-    }
-    const values = new Map();
-    for (const entry of parsed) {
-        if (!Array.isArray(entry) || entry.length !== 2) {
-            throw new Error("Stored Lix client state entry is invalid");
-        }
-        const [key, value] = entry;
-        assertClientStateKey(key);
-        assertJsonValue(value);
-        values.set(key, cloneJsonValue(value));
-    }
-    return values;
-}
-function assertClientStateKey(key) {
-    if (typeof key !== "string" || key.length === 0) {
-        throw new TypeError("clientState key must be a non-empty string");
-    }
-}
-function assertJsonValue(value) {
-    // Value.json owns the SDK's full JSON validation, including finite numbers,
-    // well-formed strings, plain objects, and cycle detection.
-    Value.json(value);
-}
-function cloneJsonValue(value) {
-    if (Array.isArray(value))
-        return value.map(cloneJsonValue);
-    if (value && typeof value === "object") {
-        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, cloneJsonValue(entry)]));
-    }
-    return value;
-}

package/dist/local-storage-adapter.d.ts

@@ -1,26 +0,0 @@
-import type { LixSnapshotStorage } from "./types.js";
-/** The subset of the browser Storage API used by {@link LocalStorage}. */
-export type WebStorageLike = Pick<Storage, "getItem" | "setItem">;
-export type LocalStorageOptions = {
-    /**
-     * Storage implementation to wrap. Defaults to `globalThis.localStorage`.
-     * Supplying this is useful for non-browser hosts and tests.
-     */
-    storage?: WebStorageLike;
-    /** Prefix used to isolate Lix snapshots from other application records. */
-    prefix?: string;
-};
-/**
- * Persists opaque Lix snapshots in the browser's localStorage.
- *
- * Import this adapter from `@lix-js/sdk/local-storage-adapter`. Keeping it in
- * a separate entrypoint avoids referencing browser storage in applications
- * that do not use it.
- */
-export declare class LocalStorage implements LixSnapshotStorage {
-    #private;
-    constructor(options?: LocalStorageOptions);
-    load(namespace: string): Promise<Uint8Array | undefined>;
-    save(namespace: string, snapshot: Uint8Array): Promise<void>;
-}
-export type { LixSnapshotStorage } from "./types.js";

package/dist/local-storage-adapter.js

@@ -1,117 +0,0 @@
-const SNAPSHOT_FORMAT = "lix-snapshot";
-const SNAPSHOT_VERSION = 1;
-const DEFAULT_PREFIX = "@lix-js/sdk/snapshot/v1";
-/**
- * Persists opaque Lix snapshots in the browser's localStorage.
- *
- * Import this adapter from `@lix-js/sdk/local-storage-adapter`. Keeping it in
- * a separate entrypoint avoids referencing browser storage in applications
- * that do not use it.
- */
-export class LocalStorage {
-    #storage;
-    #prefix;
-    constructor(options = {}) {
-        if (!options || typeof options !== "object" || Array.isArray(options)) {
-            throw new TypeError("LocalStorage options must be an object");
-        }
-        if (options.prefix !== undefined &&
-            (typeof options.prefix !== "string" || options.prefix.length === 0)) {
-            throw new TypeError("LocalStorage prefix must be a non-empty string");
-        }
-        const storage = options.storage ?? defaultLocalStorage();
-        if (!storage ||
-            typeof storage.getItem !== "function" ||
-            typeof storage.setItem !== "function") {
-            throw new TypeError("LocalStorage storage must implement getItem() and setItem()");
-        }
-        this.#storage = storage;
-        this.#prefix = options.prefix ?? DEFAULT_PREFIX;
-    }
-    async load(namespace) {
-        const key = this.#key(namespace);
-        const stored = this.#storage.getItem(key);
-        if (stored === null)
-            return undefined;
-        let value;
-        try {
-            value = JSON.parse(stored);
-        }
-        catch (error) {
-            throw invalidSnapshot(key, "record is not valid JSON", error);
-        }
-        if (!isSnapshotEnvelope(value)) {
-            throw invalidSnapshot(key, "record has an unsupported format or version");
-        }
-        try {
-            return base64ToBytes(value.data);
-        }
-        catch (error) {
-            throw invalidSnapshot(key, "record contains invalid base64", error);
-        }
-    }
-    async save(namespace, snapshot) {
-        const key = this.#key(namespace);
-        if (!(snapshot instanceof Uint8Array)) {
-            throw new TypeError("LocalStorage snapshot must be a Uint8Array");
-        }
-        const envelope = {
-            format: SNAPSHOT_FORMAT,
-            version: SNAPSHOT_VERSION,
-            data: bytesToBase64(snapshot),
-        };
-        this.#storage.setItem(key, JSON.stringify(envelope));
-    }
-    #key(namespace) {
-        if (typeof namespace !== "string" || namespace.length === 0) {
-            throw new TypeError("LocalStorage snapshot namespace must be a non-empty string");
-        }
-        return `${this.#prefix}:${encodeURIComponent(namespace)}`;
-    }
-}
-function defaultLocalStorage() {
-    const storage = globalThis.localStorage;
-    if (storage === undefined) {
-        throw new Error("LocalStorage requires browser localStorage or an explicit storage option");
-    }
-    return storage;
-}
-function isSnapshotEnvelope(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        return false;
-    const envelope = value;
-    return (envelope.format === SNAPSHOT_FORMAT &&
-        envelope.version === SNAPSHOT_VERSION &&
-        typeof envelope.data === "string");
-}
-function bytesToBase64(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) {
-    if (!isCanonicalBase64(base64)) {
-        throw new Error("invalid base64");
-    }
-    const binary = atob(base64);
-    const bytes = new Uint8Array(binary.length);
-    for (let index = 0; index < binary.length; index += 1) {
-        bytes[index] = binary.charCodeAt(index);
-    }
-    return bytes;
-}
-function isCanonicalBase64(value) {
-    if (value.length === 0)
-        return true;
-    if (value.length % 4 !== 0)
-        return false;
-    return /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value);
-}
-function invalidSnapshot(key, reason, cause) {
-    return new Error(`Invalid Lix snapshot in localStorage key '${key}': ${reason}`, {
-        cause,
-    });
-}

package/dist/snapshot-persistence.d.ts

@@ -1,7 +0,0 @@
-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

@@ -1,26 +0,0 @@
-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);
-}