@lix-js/sdk 0.8.4 → 0.10.0

package/dist/lix.js

@@ -0,0 +1,378 @@
+import { invalidArgument } from "./errors.js";
+import { ACTIVE_BRANCH_CLIENT_STATE_KEY, unavailableClientState, } from "./client-state.js";
+import { normalizeOptionals, wrapExecuteResult } from "./result.js";
+import { isSnapshotPersistenceAfterCommitError } from "./snapshot-persistence.js";
+import { normalizeParam, toNativeValue } from "./value.js";
+const transactionFinalizer = new FinalizationRegistry(({ transaction, onFinish }) => {
+    void transaction
+        .rollback()
+        .catch(() => undefined)
+        .finally(onFinish);
+});
+const observeFinalizer = new FinalizationRegistry(({ observe, onClose }) => {
+    onClose();
+    void observe.then((events) => {
+        events?.close();
+    });
+});
+export class Lix {
+    binding;
+    managedClientState;
+    closePromise;
+    clientState;
+    #activeBranchListeners = new Set();
+    #inFlightOperations = new Set();
+    #observations = new Map();
+    #nextObservationId = 0;
+    #transactionsOpening = 0;
+    #activeTransactions = 0;
+    #acceptingOperations = true;
+    constructor(binding, managedClientState) {
+        this.binding = binding;
+        this.managedClientState = managedClientState;
+        this.clientState = managedClientState
+            ? {
+                get: (key) => managedClientState.get(key),
+                set: (key, value) => this.#runOperation(() => managedClientState.set(key, value)),
+                delete: (key) => this.#runOperation(() => managedClientState.delete(key)),
+                subscribe: (listener) => {
+                    this.#assertAcceptingOperations();
+                    return managedClientState.subscribe(listener);
+                },
+            }
+            : unavailableClientState();
+    }
+    async execute(sql, params = [], options) {
+        assertExecuteArgs("lix", sql, params, options);
+        return this.#runOperation(async () => wrapExecuteResult(await this.binding.execute(sql, params.map((param, index) => toNativeValue(normalizeParam(param, index))), options)));
+    }
+    async executeBatch(statements, options) {
+        const normalizedStatements = normalizeBatchStatements(statements, options);
+        return this.#runOperation(async () => {
+            const results = await this.binding.executeBatch(normalizedStatements, options);
+            return results.map(wrapExecuteResult);
+        });
+    }
+    observe(sql, params = []) {
+        assertSqlArgs("observe", "lix", sql, params);
+        const observationId = ++this.#nextObservationId;
+        let events;
+        events = new ObserveEvents(this.#runOperation(() => this.binding.observe(sql, params.map((param, index) => toNativeValue(normalizeParam(param, index))))), () => this.#observations.delete(observationId));
+        this.#observations.set(observationId, new WeakRef(events));
+        return events;
+    }
+    async beginTransaction() {
+        return this.#runOperation(async () => {
+            this.#transactionsOpening += 1;
+            try {
+                const binding = await this.binding.beginTransaction();
+                this.#activeTransactions += 1;
+                let active = true;
+                return new LixTransaction(binding, () => {
+                    if (!active)
+                        return;
+                    active = false;
+                    this.#activeTransactions -= 1;
+                });
+            }
+            finally {
+                this.#transactionsOpening -= 1;
+            }
+        });
+    }
+    async activeBranchId() {
+        return this.#runOperation(() => this.binding.activeBranchId());
+    }
+    async activeAccountId() {
+        return this.#runOperation(() => this.binding.activeAccountId());
+    }
+    /** Subscribes to successful branch switches made through this Lix handle. */
+    subscribeActiveBranch(listener) {
+        if (typeof listener !== "function") {
+            throw new TypeError("subscribeActiveBranch() requires a function");
+        }
+        this.#assertAcceptingOperations();
+        this.#activeBranchListeners.add(listener);
+        return () => this.#activeBranchListeners.delete(listener);
+    }
+    async createBranch(options) {
+        return this.#runOperation(() => this.binding.createBranch(options));
+    }
+    async createCheckpoint() {
+        return this.#runOperation(() => this.binding.createCheckpoint());
+    }
+    async undo() {
+        return this.#runOperation(() => this.binding.undo());
+    }
+    async redo() {
+        return this.#runOperation(() => this.binding.redo());
+    }
+    async switchBranch(options) {
+        return this.#runOperation(async () => {
+            const receipt = await this.binding.switchBranch(options);
+            try {
+                if (this.managedClientState) {
+                    await this.managedClientState.set(ACTIVE_BRANCH_CLIENT_STATE_KEY, receipt.branchId);
+                }
+            }
+            catch {
+                // The remote branch switch already committed. Client persistence is a
+                // best-effort reopen preference and cannot turn that success into a
+                // rejected switch with ambiguous branch state.
+            }
+            for (const listener of [...this.#activeBranchListeners]) {
+                try {
+                    listener();
+                }
+                catch {
+                    // Observers do not participate in the completed branch transaction.
+                }
+            }
+            return receipt;
+        });
+    }
+    async mergeBranchPreview(options) {
+        return this.#runOperation(async () => normalizeOptionals(await this.binding.mergeBranchPreview(options)));
+    }
+    async mergeBranch(options) {
+        return this.#runOperation(async () => {
+            const receipt = normalizeOptionals(await this.binding.mergeBranch(options));
+            receipt.createdMergeCommitId ??= null;
+            return receipt;
+        });
+    }
+    async close() {
+        if (!this.closePromise) {
+            if (this.#transactionsOpening > 0 || this.#activeTransactions > 0) {
+                throw activeTransactionCloseError();
+            }
+            // Flip the public lifecycle gate before the first await. Operations that
+            // already entered the gate are allowed to finish; later calls fail closed.
+            this.#acceptingOperations = false;
+            for (const observation of this.#observations.values()) {
+                observation.deref()?.close();
+            }
+            this.#observations.clear();
+            this.closePromise = (async () => {
+                await Promise.allSettled([...this.#inFlightOperations]);
+                await this.binding.close();
+                await this.managedClientState?.close();
+                this.#activeBranchListeners.clear();
+            })();
+        }
+        await this.closePromise;
+    }
+    #runOperation(operation) {
+        try {
+            this.#assertAcceptingOperations();
+            const result = operation();
+            this.#inFlightOperations.add(result);
+            void result.then(() => this.#inFlightOperations.delete(result), () => this.#inFlightOperations.delete(result));
+            return result;
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+    }
+    #assertAcceptingOperations() {
+        if (this.#acceptingOperations)
+            return;
+        const error = new Error("Lix is closed");
+        error.name = "LixError";
+        error.code = "LIX_ERROR_CLOSED";
+        throw error;
+    }
+}
+function activeTransactionCloseError() {
+    const error = new Error("cannot close Lix while an explicit transaction is active");
+    error.name = "LixError";
+    error.code = "LIX_INVALID_TRANSACTION_STATE";
+    return error;
+}
+export class ObserveEvents {
+    onClose;
+    setup = {};
+    closed = false;
+    observeBinding;
+    constructor(observeBinding, onClose = () => undefined) {
+        this.onClose = onClose;
+        const setup = this.setup;
+        this.observeBinding = observeBinding.catch((error) => {
+            setup.error = error;
+            return undefined;
+        });
+        observeFinalizer.register(this, { observe: this.observeBinding, onClose: this.onClose }, this);
+    }
+    async next() {
+        if (this.closed)
+            return undefined;
+        const binding = await this.observeBinding;
+        if (binding === undefined) {
+            throw this.setup.error;
+        }
+        const event = await binding.next();
+        if (event == null) {
+            return undefined;
+        }
+        return {
+            sequence: event.sequence,
+            mutationSequence: event.mutationSequence,
+            result: wrapExecuteResult(event.rows),
+        };
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.onClose();
+        observeFinalizer.unregister(this);
+        void this.observeBinding.then((binding) => {
+            binding?.close();
+        });
+    }
+}
+export class LixTransaction {
+    binding;
+    onFinish;
+    finishPromise;
+    finished = false;
+    constructor(binding, onFinish = () => undefined) {
+        this.binding = binding;
+        this.onFinish = onFinish;
+        transactionFinalizer.register(this, { transaction: binding, onFinish: this.onFinish }, this);
+    }
+    async execute(sql, params = [], options) {
+        assertExecuteArgs("lixTransaction", sql, params, options);
+        return wrapExecuteResult(await this.binding.execute(sql, params.map((param, index) => toNativeValue(normalizeParam(param, index))), options));
+    }
+    async commit() {
+        return this.finish("transaction.commit");
+    }
+    async rollback() {
+        return this.finish("transaction.rollback");
+    }
+    async finish(kind) {
+        if (this.finished)
+            throw transactionClosedError();
+        if (!this.finishPromise) {
+            this.finishPromise = (async () => {
+                if (kind === "transaction.commit")
+                    await this.binding.commit();
+                else
+                    await this.binding.rollback();
+                this.finished = true;
+                transactionFinalizer.unregister(this);
+                this.onFinish();
+            })();
+        }
+        try {
+            await this.finishPromise;
+        }
+        catch (error) {
+            if (isSnapshotPersistenceAfterCommitError(error)) {
+                // The transaction finished in Rust; only durable snapshot saving
+                // failed. Release the transaction lifecycle while reporting that
+                // durability failure to the caller.
+                this.finished = true;
+                transactionFinalizer.unregister(this);
+                this.onFinish();
+                throw error;
+            }
+            this.finishPromise = undefined;
+            throw error;
+        }
+    }
+}
+function transactionClosedError() {
+    const error = new Error("Lix transaction is closed");
+    error.name = "LixError";
+    error.code = "LIX_INVALID_TRANSACTION_STATE";
+    return error;
+}
+function assertExecuteArgs(receiver, sql, params, options) {
+    assertSqlArgs("execute", receiver, sql, params);
+    if (options === undefined) {
+        return;
+    }
+    if (!options || typeof options !== "object" || Array.isArray(options)) {
+        throw invalidArgument("execute", "options", "object", typeof options, receiver);
+    }
+    if (options.originKey !== undefined &&
+        typeof options.originKey !== "string") {
+        throw invalidArgument("execute", "options.originKey", "string", typeof options.originKey, receiver);
+    }
+    if (options.idempotencyKey !== undefined &&
+        typeof options.idempotencyKey !== "string") {
+        throw invalidArgument("execute", "options.idempotencyKey", "string", typeof options.idempotencyKey, receiver);
+    }
+}
+function assertSqlArgs(operation, receiver, sql, params) {
+    if (typeof sql !== "string") {
+        throw invalidArgument(operation, "sql", "string", typeof sql, receiver);
+    }
+    if (!Array.isArray(params)) {
+        throw invalidArgument(operation, "params", "array", typeof params, receiver);
+    }
+}
+function normalizeBatchStatements(statements, options) {
+    if (!Array.isArray(statements)) {
+        throw invalidArgument("executeBatch", "statements", "array", typeof statements);
+    }
+    if (statements.length === 0) {
+        throw invalidArgument("executeBatch", "statements", "non-empty array", "empty array");
+    }
+    assertBatchOptions(options);
+    return statements.map((statement, statementIndex) => {
+        try {
+            if (!statement ||
+                typeof statement !== "object" ||
+                Array.isArray(statement)) {
+                throw invalidArgument("executeBatch", `statements[${statementIndex}]`, "object", Array.isArray(statement) ? "array" : typeof statement);
+            }
+            if (typeof statement.sql !== "string") {
+                throw invalidArgument("executeBatch", `statements[${statementIndex}].sql`, "string", typeof statement.sql);
+            }
+            const params = statement.params ?? [];
+            if (!Array.isArray(params)) {
+                throw invalidArgument("executeBatch", `statements[${statementIndex}].params`, "array", typeof params);
+            }
+            return {
+                sql: statement.sql,
+                params: params.map((param, parameterIndex) => toNativeValue(normalizeParam(param, parameterIndex))),
+            };
+        }
+        catch (error) {
+            throw withBatchStatementIndex(error, statementIndex);
+        }
+    });
+}
+function assertBatchOptions(options) {
+    if (options === undefined)
+        return;
+    if (!options || typeof options !== "object" || Array.isArray(options)) {
+        throw invalidArgument("executeBatch", "options", "object", typeof options);
+    }
+    if (options.originKey !== undefined &&
+        typeof options.originKey !== "string") {
+        throw invalidArgument("executeBatch", "options.originKey", "string", typeof options.originKey);
+    }
+    if (options.idempotencyKey !== undefined &&
+        typeof options.idempotencyKey !== "string") {
+        throw invalidArgument("executeBatch", "options.idempotencyKey", "string", typeof options.idempotencyKey);
+    }
+}
+function withBatchStatementIndex(error, statementIndex) {
+    if (!error || typeof error !== "object")
+        return error;
+    const lixError = error;
+    const details = lixError.details;
+    lixError.details = {
+        ...(details && typeof details === "object" && !Array.isArray(details)
+            ? details
+            : details === undefined
+                ? {}
+                : { cause: details }),
+        statementIndex,
+    };
+    return error;
+}

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

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

@@ -0,0 +1,117 @@
+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/open-lix.d.ts

@@ -1,5 +1,6 @@
-import { LixWorkerClient } from "./worker/client.js";
-import type { CreateBranchOptions, CreateBranchReceipt, ExecuteOptions, ExecuteResult, LocalFilesystemOptions, MergeBranchOptions, MergeBranchPreview, MergeBranchReceipt, ObserveEvent, OpenLixOptions, SqlParam, SQLiteOptions, SwitchBranchOptions, SwitchBranchReceipt } from "./types.js";
+import { Lix } from "./lix.js";
+import type { LocalFilesystemOptions, OpenLixOptions, SQLiteOptions } from "./types.js";
+export { Lix, LixTransaction, ObserveEvents } from "./lix.js";
 export declare class SQLite {
     readonly path: string;
     constructor(options: SQLiteOptions);
@@ -14,35 +15,3 @@ export declare class LocalFilesystem {
     private client;
 }
 export declare function openLix(options?: OpenLixOptions): Promise<Lix>;
-export declare class Lix {
-    private readonly client;
-    private closePromise;
-    constructor(client: LixWorkerClient);
-    execute(sql: string, params?: SqlParam[], options?: ExecuteOptions): Promise<ExecuteResult>;
-    observe(sql: string, params?: SqlParam[]): ObserveEvents;
-    beginTransaction(): Promise<LixTransaction>;
-    activeBranchId(): Promise<string>;
-    createBranch(options: CreateBranchOptions): Promise<CreateBranchReceipt>;
-    switchBranch(options: SwitchBranchOptions): Promise<SwitchBranchReceipt>;
-    mergeBranchPreview(options: MergeBranchOptions): Promise<MergeBranchPreview>;
-    mergeBranch(options: MergeBranchOptions): Promise<MergeBranchReceipt>;
-    close(): Promise<void>;
-}
-export declare class ObserveEvents {
-    private readonly client;
-    private readonly setup;
-    private closed;
-    private readonly observeId;
-    constructor(client: LixWorkerClient, observeId: Promise<number>);
-    next(): Promise<ObserveEvent | undefined>;
-    close(): void;
-}
-export declare class LixTransaction {
-    private readonly client;
-    private readonly transactionId;
-    constructor(client: LixWorkerClient, transactionId: number);
-    execute(sql: string, params?: SqlParam[], options?: ExecuteOptions): Promise<ExecuteResult>;
-    commit(): Promise<void>;
-    rollback(): Promise<void>;
-    private finish;
-}