@lix-js/sdk 0.6.0-preview.4 → 0.6.0

package/dist/open-lix.js

@@ -1,307 +1,82 @@
-import init, { resolveEngineWasmModuleOrPath, Value, } from "./engine-wasm/index.js";
-import * as wasmModule from "./engine-wasm/index.js";
-export class Row {
-    columns;
-    valuesByIndex;
-    constructor(columns, values) {
-        this.columns = columns;
-        this.valuesByIndex = values;
-    }
-    get(columnName) {
-        return valueToNative(this.value(columnName));
-    }
-    tryGet(columnName) {
-        const value = this.tryValue(columnName);
-        return value === undefined ? undefined : valueToNative(value);
-    }
-    value(columnName) {
-        const index = this.columns.indexOf(columnName);
-        if (index === -1) {
-            throw createLixError("LIX_COLUMN_NOT_FOUND", `Column "${columnName}" does not exist. Available columns: ${this.availableColumns()}`);
+import { invalidArgument } from "./errors.js";
+import { addon } from "./native.js";
+import { normalizeOptionals, wrapExecuteResult } from "./result.js";
+import { normalizeParam, toNativeValue } from "./value.js";
+export class SqliteBackend {
+    path;
+    constructor(options) {
+        if (!options || typeof options.path !== "string" || options.path.length === 0) {
+            throw new TypeError("SqliteBackend requires a non-empty path");
         }
-        const value = this.valuesByIndex[index];
-        if (value === undefined) {
-            throw createLixError("LIX_COLUMN_NOT_FOUND", `Column "${columnName}" is outside row width ${this.valuesByIndex.length}.`);
-        }
-        return value;
+        this.path = options.path;
     }
-    tryValue(columnName) {
-        const index = this.columns.indexOf(columnName);
-        return index === -1 ? undefined : this.valuesByIndex[index];
+}
+export async function openLix(options = {}) {
+    if (!options || typeof options !== "object") {
+        throw new TypeError("openLix() options must be an object");
     }
-    getAt(index) {
-        return valueToNative(this.valueAt(index));
+    if (options.backend === undefined) {
+        return new Lix(addon.Lix.openMemory());
     }
-    valueAt(index) {
-        const value = this.valuesByIndex[index];
-        if (value === undefined) {
-            throw createLixError("LIX_COLUMN_NOT_FOUND", `Column index ${index} is outside row width ${this.valuesByIndex.length}.`);
-        }
-        return value;
+    if (!(options.backend instanceof SqliteBackend)) {
+        throw new TypeError("openLix() requires { backend: new SqliteBackend({ path }) }");
     }
-    values() {
-        return [...this.valuesByIndex];
+    return new Lix(addon.Lix.openSqlite(options.backend.path));
+}
+export class Lix {
+    native;
+    constructor(native) {
+        this.native = native;
     }
-    toObject() {
-        return Object.fromEntries(this.columns.map((column, index) => [
-            column,
-            valueToNative(this.valueAt(index)),
-        ]));
+    async execute(sql, params = []) {
+        assertExecuteArgs("lix", sql, params);
+        return wrapExecuteResult(this.native.execute(sql, params.map((param, index) => toNativeValue(normalizeParam(param, index)))));
     }
-    toValueMap() {
-        return Object.fromEntries(this.columns.map((column, index) => [column, this.valueAt(index)]));
+    async beginTransaction() {
+        return new LixTransaction(this.native.beginTransaction());
     }
-    availableColumns() {
-        return this.columns.length === 0 ? "<none>" : this.columns.join(", ");
+    async activeBranchId() {
+        return this.native.activeBranchId();
     }
-}
-function valueToNative(value) {
-    switch (value.kind) {
-        case "null":
-            return null;
-        case "boolean":
-        case "integer":
-        case "real":
-        case "text":
-        case "json":
-            return value.value;
-        case "blob":
-            return value.asBlob() ?? new Uint8Array();
+    async createBranch(options) {
+        return this.native.createBranch(options);
     }
-}
-let wasmReady = null;
-async function ensureWasmReady() {
-    if (!wasmReady) {
-        wasmReady = resolveEngineWasmModuleOrPath()
-            .then((module_or_path) => init({ module_or_path }))
-            .then(() => undefined);
+    async switchBranch(options) {
+        return this.native.switchBranch(options);
     }
-    await wasmReady;
-}
-export async function openLix(options = {}) {
-    await ensureWasmReady();
-    try {
-        const wasmLix = (await wasmModule.openLix(options));
-        return createLixHandle(wasmLix);
+    async mergeBranchPreview(options) {
+        return normalizeOptionals(this.native.mergeBranchPreview(options));
     }
-    catch (error) {
-        try {
-            options.backend?.close?.();
-        }
-        catch {
-            // Preserve the original open failure.
-        }
-        throw normalizeThrownError(error);
+    async mergeBranch(options) {
+        const receipt = normalizeOptionals(this.native.mergeBranch(options));
+        receipt.createdMergeCommitId ??= null;
+        return receipt;
     }
-}
-function createLixHandle(wasmLix) {
-    let operationQueue = Promise.resolve();
-    const acquireOperationSlot = async () => {
-        const previous = operationQueue;
-        let releaseCurrent;
-        const current = new Promise((resolve) => {
-            releaseCurrent = resolve;
-        });
-        operationQueue = previous.then(() => current);
-        await previous;
-        return () => releaseCurrent?.();
-    };
-    const runQueued = async (operation) => {
-        const release = await acquireOperationSlot();
-        try {
-            return await operation();
-        }
-        catch (error) {
-            throw normalizeThrownError(error);
-        }
-        finally {
-            release();
-        }
-    };
-    return {
-        async execute(sql, params = []) {
-            validateExecuteArguments(sql, params);
-            const values = params.map((param, index) => valueFromExecuteParam(param, index));
-            const result = await runQueued(() => wasmLix.execute(sql, values));
-            return normalizeExecuteResult(result);
-        },
-        async beginTransaction() {
-            const wasmTransaction = await runQueued(() => wasmLix.beginTransaction());
-            return createLixTransactionHandle(wasmTransaction, runQueued);
-        },
-        async activeVersionId() {
-            return await runQueued(() => wasmLix.activeVersionId());
-        },
-        async createVersion(options) {
-            return await runQueued(() => wasmLix.createVersion(options));
-        },
-        async switchVersion(options) {
-            return await runQueued(() => wasmLix.switchVersion(options));
-        },
-        async mergeVersionPreview(options) {
-            return await runQueued(() => wasmLix.mergeVersionPreview(options));
-        },
-        async mergeVersion(options) {
-            return await runQueued(() => wasmLix.mergeVersion(options));
-        },
-        async close() {
-            await runQueued(() => wasmLix.close());
-        },
-    };
-}
-function createLixTransactionHandle(wasmTransaction, runQueued) {
-    let closed = false;
-    const ensureOpen = () => {
-        if (closed) {
-            throw createLixError("LIX_INVALID_TRANSACTION_STATE", "Lix transaction is closed");
-        }
-    };
-    return {
-        async execute(sql, params = []) {
-            ensureOpen();
-            validateExecuteArguments(sql, params);
-            const values = params.map((param, index) => valueFromExecuteParam(param, index));
-            const result = await runQueued(() => wasmTransaction.execute(sql, values));
-            return normalizeExecuteResult(result);
-        },
-        async commit() {
-            ensureOpen();
-            try {
-                await runQueued(() => wasmTransaction.commit());
-            }
-            finally {
-                closed = true;
-            }
-        },
-        async rollback() {
-            ensureOpen();
-            try {
-                await runQueued(() => wasmTransaction.rollback());
-            }
-            finally {
-                closed = true;
-            }
-        },
-    };
-}
-function validateExecuteArguments(sql, params) {
-    if (typeof sql !== "string") {
-        throw invalidArgumentError("execute", "sql", "string", sql);
-    }
-    if (!Array.isArray(params)) {
-        throw invalidArgumentError("execute", "params", "array", params);
+    async close() {
+        return this.native.close();
     }
 }
-function invalidArgumentError(operation, argument, expected, actualValue) {
-    return createLixError("LIX_INVALID_ARGUMENT", `lix.${operation}() expected ${argument} to be ${expectedArticle(expected)} ${expected}`, {
-        details: {
-            operation,
-            argument,
-            expected,
-            actual: runtimeTypeName(actualValue),
-        },
-    });
-}
-function valueFromExecuteParam(param, index) {
-    try {
-        return Value.from(param);
-    }
-    catch (error) {
-        throw invalidParamError(index, param, error);
+export class LixTransaction {
+    native;
+    constructor(native) {
+        this.native = native;
     }
-}
-function invalidParamError(index, actualValue, cause) {
-    const message = cause instanceof Error && cause.message
-        ? cause.message
-        : "parameter is not a valid Lix SQL value";
-    return createLixError("LIX_INVALID_PARAM", `lix.execute() invalid parameter $${index + 1}: ${message}`, {
-        details: {
-            operation: "execute",
-            parameter_index: index + 1,
-            argument: `params[${index}]`,
-            actual: runtimeTypeName(actualValue),
-        },
-        cause,
-    });
-}
-function expectedArticle(expected) {
-    return /^[aeiou]/i.test(expected) ? "an" : "a";
-}
-function runtimeTypeName(value) {
-    if (value === null)
-        return "null";
-    if (Array.isArray(value))
-        return "array";
-    if (value instanceof Date)
-        return "Date";
-    if (value instanceof ArrayBuffer)
-        return "ArrayBuffer";
-    if (ArrayBuffer.isView(value))
-        return value.constructor.name;
-    return typeof value;
-}
-function normalizeExecuteResult(result) {
-    const columns = [...result.columns];
-    return {
-        columns,
-        rows: result.rows.map((row) => new Row(columns, row.map((value) => Value.from(value)))),
-        rowsAffected: result.rowsAffected,
-        notices: result.notices ?? [],
-    };
-}
-function createLixError(code, message, options = {}) {
-    const error = new Error(message);
-    error.name = "LixError";
-    error.code = code;
-    if (options.hint !== undefined) {
-        error.hint = options.hint;
+    async execute(sql, params = []) {
+        assertExecuteArgs("lixTransaction", sql, params);
+        return wrapExecuteResult(this.native.execute(sql, params.map((param, index) => toNativeValue(normalizeParam(param, index)))));
     }
-    if (options.details !== undefined) {
-        error.details = options.details;
+    async commit() {
+        return this.native.commit();
     }
-    if (options.cause !== undefined) {
-        error.cause = options.cause;
+    async rollback() {
+        return this.native.rollback();
     }
-    return error;
 }
-function normalizeThrownError(error) {
-    if (isLixErrorLike(error)) {
-        const hint = typeof error.hint === "string"
-            ? error.hint
-            : extractHintFromMessage(error.message);
-        const details = "details" in error ? error.details : undefined;
-        if (error instanceof Error) {
-            if (hint !== undefined && error.hint === undefined) {
-                error.hint = hint;
-            }
-            if (details !== undefined && error.details === undefined) {
-                error.details = details;
-            }
-            return error;
-        }
-        const message = typeof error.message === "string" ? error.message : error.code;
-        return createLixError(error.code, message, { hint, details });
-    }
-    if (error instanceof WebAssembly.RuntimeError) {
-        return createLixError("LIX_WASM_RUNTIME_ERROR", error.message, {
-            hint: "The Lix engine encountered a WebAssembly runtime trap. Please report this as an engine bug with the SQL statement or API call that triggered it.",
-            cause: error,
-        });
+function assertExecuteArgs(receiver, sql, params) {
+    if (typeof sql !== "string") {
+        throw invalidArgument("execute", "sql", "string", typeof sql, receiver);
     }
-    if (error instanceof Error) {
-        return createLixError("LIX_ERROR_UNKNOWN", error.message, { cause: error });
+    if (!Array.isArray(params)) {
+        throw invalidArgument("execute", "params", "array", typeof params, receiver);
     }
-    return createLixError("LIX_ERROR_UNKNOWN", String(error));
-}
-function extractHintFromMessage(message) {
-    if (typeof message !== "string")
-        return undefined;
-    const match = message.match(/(?:^|\n)hint:\s*(.+)$/s);
-    return match?.[1]?.trim();
-}
-function isLixErrorLike(error) {
-    return (typeof error === "object" &&
-        error !== null &&
-        typeof error.code === "string" &&
-        error.code.startsWith("LIX_"));
 }

package/dist/result.d.ts

@@ -0,0 +1,18 @@
+import { type NativeLixValue, Value } from "./value.js";
+import type { 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>;
+}
+type NativeExecuteResult = Omit<ExecuteResult, "rows"> & {
+    rows: NativeLixValue[][];
+};
+export declare function wrapExecuteResult(result: NativeExecuteResult): ExecuteResult;
+export declare function normalizeOptionals<T>(value: T): T;
+export {};

package/dist/result.js

@@ -0,0 +1,48 @@
+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) {
+    return {
+        ...result,
+        rows: result.rows.map((row) => Row.fromRaw(result.columns, row.map(fromNativeValue))),
+    };
+}
+export function normalizeOptionals(value) {
+    if (Array.isArray(value))
+        return value.map(normalizeOptionals);
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+        key,
+        entry === undefined ? null : normalizeOptionals(entry),
+    ]));
+}

package/dist/types.d.ts

@@ -1 +1,114 @@
-export type { JsonValue, LixRuntimeValue } from "./open-lix.js";
+export type SqliteBackendOptions = {
+    path: string;
+};
+export type OpenLixOptions = {
+    backend?: import("./open-lix.js").SqliteBackend;
+};
+export type LixValue = {
+    kind: "null";
+    value: null;
+} | {
+    kind: "boolean";
+    value: boolean;
+} | {
+    kind: "integer";
+    value: number;
+} | {
+    kind: "real";
+    value: number;
+} | {
+    kind: "text";
+    value: string;
+} | {
+    kind: "json";
+    value: JsonValue;
+} | {
+    kind: "blob";
+    value: Uint8Array;
+};
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+export type SqlParam = JsonValue | Uint8Array | import("./value.js").Value;
+export type ExecuteResult = {
+    columns: string[];
+    rows: RowLike[];
+    rowsAffected: number;
+    notices: Array<{
+        code: string;
+        message: string;
+        hint?: string;
+    }>;
+};
+export type RowLike = {
+    get(column: string): unknown;
+    value(column: string): ValueLike;
+    toObject(): Record<string, unknown>;
+    toValueMap(): Record<string, ValueLike>;
+};
+export type ValueLike = {
+    readonly kind: LixValue["kind"];
+    toJS(): unknown;
+    asBytes(): Uint8Array | undefined;
+};
+export type CreateBranchOptions = {
+    id?: string;
+    name: string;
+    fromCommitId?: string;
+};
+export type CreateBranchReceipt = {
+    id: string;
+    name: string;
+    hidden: boolean;
+    commitId: string;
+};
+export type SwitchBranchOptions = {
+    branchId: string;
+};
+export type SwitchBranchReceipt = {
+    branchId: string;
+};
+export type MergeBranchOptions = {
+    sourceBranchId: string;
+};
+export type MergeBranchOutcome = "alreadyUpToDate" | "fastForward" | "mergeCommitted";
+export type MergeBranchReceipt = {
+    outcome: MergeBranchOutcome;
+    targetBranchId: string;
+    sourceBranchId: string;
+    baseCommitId: string;
+    targetHeadBeforeCommitId: string;
+    sourceHeadBeforeCommitId: string;
+    targetHeadAfterCommitId: string;
+    createdMergeCommitId: string | null;
+    changeStats: MergeChangeStats;
+};
+export type MergeBranchPreview = {
+    outcome: MergeBranchOutcome;
+    targetBranchId: string;
+    sourceBranchId: string;
+    baseCommitId: string;
+    targetHeadCommitId: string;
+    sourceHeadCommitId: string;
+    changeStats: MergeChangeStats;
+    conflicts: MergeConflict[];
+};
+export type MergeChangeStats = {
+    total: number;
+    added: number;
+    modified: number;
+    removed: number;
+};
+export type MergeConflict = {
+    kind: "sameEntityChanged";
+    schemaKey: string;
+    entityPk: unknown;
+    fileId: string | null;
+    target: MergeConflictSide;
+    source: MergeConflictSide;
+};
+export type MergeConflictSide = {
+    kind: "added" | "modified" | "removed";
+    beforeChangeId: string | null;
+    afterChangeId: string | null;
+};

package/dist/value.d.ts

@@ -0,0 +1,28 @@
+import type { JsonValue, LixValue, SqlParam } from "./types.js";
+export declare class Value {
+    #private;
+    readonly kind: LixValue["kind"];
+    private constructor();
+    static null(): Value;
+    static boolean(value: boolean): Value;
+    static integer(value: number): Value;
+    static real(value: number): Value;
+    static text(value: string): Value;
+    static json(value: JsonValue): Value;
+    static blob(value: Uint8Array): Value;
+    static from(value: SqlParam): Value;
+    static _fromNative(value: LixValue): Value;
+    _toNative(): NativeLixValue;
+    toJS(): unknown;
+    asBytes(): Uint8Array<ArrayBuffer> | undefined;
+}
+export type NativeLixValue = Exclude<LixValue, {
+    kind: "blob";
+}> | {
+    kind: "blob";
+    value?: null;
+    blob: Uint8Array;
+};
+export declare function toNativeValue(value: LixValue): NativeLixValue;
+export declare function fromNativeValue(value: NativeLixValue): LixValue;
+export declare function normalizeParam(value: SqlParam, index?: number, seen?: WeakSet<object>): LixValue;