@lix-js/sdk 0.8.4 → 0.10.0

package/dist/client-state.js

@@ -0,0 +1,318 @@
+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)) {
+        // Remote storage previously contained a full Lix snapshot. Backward
+        // compatibility is intentionally not provided: start with empty state and
+        // replace it on the next write.
+        return new Map();
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder().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/index.d.ts

@@ -2,4 +2,5 @@ export { LocalFilesystem, Lix, LixTransaction, ObserveEvents, openLix, SQLite, }
 export { bundledPluginArchives, type BundledPluginArchive, } from "./bundled-plugins.js";
 export { Row } from "./result.js";
 export { Value } from "./value.js";
-export type { CreateBranchOptions, CreateBranchReceipt, ExecuteOptions, ExecuteResult, LocalFilesystemOptions, JsonValue, LixValue, MergeBranchOptions, MergeBranchOutcome, MergeBranchPreview, MergeBranchReceipt, MergeChangeStats, MergeConflict, MergeConflictSide, ObserveEvent, OpenLixOptions, SqlParam, SQLiteOptions, SwitchBranchOptions, SwitchBranchReceipt, } from "./types.js";
+export type { LixClientState } from "./client-state.js";
+export type { CreateBranchOptions, CreateBranchReceipt, CreateCheckpointReceipt, RedoReceipt, ExecuteOptions, ExecuteResult, LixBatchOptions, LixBatchStatement, LocalFilesystemOptions, JsonValue, LixValue, MergeBranchOptions, MergeBranchOutcome, MergeBranchPreview, MergeBranchReceipt, MergeChangeStats, MergeConflict, MergeConflictSide, ObserveEvent, OpenLixOptions, LixTelemetryOptions, LixTelemetrySpan, LixSnapshotStorage, RemoteLixFetch, RemoteLixServerOptions, UndoReceipt, SqlParam, SQLiteOptions, SwitchBranchOptions, SwitchBranchReceipt, } from "./types.js";

package/dist/lix.d.ts

@@ -0,0 +1,47 @@
+import { type LixClientState, type ManagedClientState } from "./client-state.js";
+import type { LixBinding, LixTransactionBinding, ObserveEventsBinding } from "./binding-types.js";
+import type { CreateBranchOptions, CreateBranchReceipt, CreateCheckpointReceipt, RedoReceipt, ExecuteOptions, ExecuteResult, LixBatchOptions, LixBatchStatement, MergeBranchOptions, MergeBranchPreview, MergeBranchReceipt, ObserveEvent, SqlParam, SwitchBranchOptions, SwitchBranchReceipt, UndoReceipt } from "./types.js";
+export declare class Lix {
+    #private;
+    private readonly binding;
+    private readonly managedClientState?;
+    private closePromise;
+    readonly clientState: LixClientState;
+    constructor(binding: LixBinding, managedClientState?: ManagedClientState | undefined);
+    execute(sql: string, params?: SqlParam[], options?: ExecuteOptions): Promise<ExecuteResult>;
+    executeBatch(statements: readonly LixBatchStatement[], options?: LixBatchOptions): Promise<readonly ExecuteResult[]>;
+    observe(sql: string, params?: SqlParam[]): ObserveEvents;
+    beginTransaction(): Promise<LixTransaction>;
+    activeBranchId(): Promise<string>;
+    activeAccountId(): Promise<string>;
+    /** Subscribes to successful branch switches made through this Lix handle. */
+    subscribeActiveBranch(listener: () => void): () => void;
+    createBranch(options: CreateBranchOptions): Promise<CreateBranchReceipt>;
+    createCheckpoint(): Promise<CreateCheckpointReceipt>;
+    undo(): Promise<UndoReceipt>;
+    redo(): Promise<RedoReceipt>;
+    switchBranch(options: SwitchBranchOptions): Promise<SwitchBranchReceipt>;
+    mergeBranchPreview(options: MergeBranchOptions): Promise<MergeBranchPreview>;
+    mergeBranch(options: MergeBranchOptions): Promise<MergeBranchReceipt>;
+    close(): Promise<void>;
+}
+export declare class ObserveEvents {
+    private readonly onClose;
+    private readonly setup;
+    private closed;
+    private readonly observeBinding;
+    constructor(observeBinding: Promise<ObserveEventsBinding>, onClose?: () => void);
+    next(): Promise<ObserveEvent | undefined>;
+    close(): void;
+}
+export declare class LixTransaction {
+    private readonly binding;
+    private readonly onFinish;
+    private finishPromise;
+    private finished;
+    constructor(binding: LixTransactionBinding, onFinish?: () => void);
+    execute(sql: string, params?: SqlParam[], options?: ExecuteOptions): Promise<ExecuteResult>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+    private finish;
+}