@lix-js/sdk 0.6.0-preview.0 → 0.6.0-preview.2

package/dist/open-lix.js

@@ -1,5 +1,74 @@
 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()}`);
+        }
+        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;
+    }
+    tryValue(columnName) {
+        const index = this.columns.indexOf(columnName);
+        return index === -1 ? undefined : this.valuesByIndex[index];
+    }
+    getAt(index) {
+        return valueToNative(this.valueAt(index));
+    }
+    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;
+    }
+    values() {
+        return [...this.valuesByIndex];
+    }
+    toObject() {
+        return Object.fromEntries(this.columns.map((column, index) => [
+            column,
+            valueToNative(this.valueAt(index)),
+        ]));
+    }
+    toValueMap() {
+        return Object.fromEntries(this.columns.map((column, index) => [column, this.valueAt(index)]));
+    }
+    availableColumns() {
+        return this.columns.length === 0 ? "<none>" : this.columns.join(", ");
+    }
+}
+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();
+    }
+}
 let wasmReady = null;
 async function ensureWasmReady() {
     if (!wasmReady) {
@@ -13,7 +82,7 @@ export async function openLix(options = {}) {
     await ensureWasmReady();
     try {
         const wasmLix = (await wasmModule.openLix(options));
-        return createLixHandle(wasmLix, options.backend);
+        return createLixHandle(wasmLix);
     }
     catch (error) {
         try {
@@ -22,17 +91,11 @@ export async function openLix(options = {}) {
         catch {
             // Preserve the original open failure.
         }
-        throw error;
+        throw normalizeThrownError(error);
     }
 }
-function createLixHandle(wasmLix, backend) {
-    let closed = false;
+function createLixHandle(wasmLix) {
     let operationQueue = Promise.resolve();
-    const ensureOpen = (methodName) => {
-        if (closed) {
-            throw new Error(`lix is closed; ${methodName}() is unavailable`);
-        }
-    };
     const acquireOperationSlot = async () => {
         const previous = operationQueue;
         let releaseCurrent;
@@ -48,57 +111,158 @@ function createLixHandle(wasmLix, backend) {
         try {
             return await operation();
         }
+        catch (error) {
+            throw normalizeThrownError(error);
+        }
         finally {
             release();
         }
     };
     return {
         async execute(sql, params = []) {
-            ensureOpen("execute");
-            const result = await runQueued(() => wasmLix.execute(sql, params.map((param) => Value.from(param))));
+            validateExecuteArguments(sql, params);
+            const values = params.map((param, index) => valueFromExecuteParam(param, index));
+            const result = await runQueued(() => wasmLix.execute(sql, values));
             return normalizeExecuteResult(result);
         },
         async activeVersionId() {
-            ensureOpen("activeVersionId");
             return await runQueued(() => wasmLix.activeVersionId());
         },
         async createVersion(options) {
-            ensureOpen("createVersion");
             return await runQueued(() => wasmLix.createVersion(options));
         },
         async switchVersion(options) {
-            ensureOpen("switchVersion");
             return await runQueued(() => wasmLix.switchVersion(options));
         },
+        async mergeVersionPreview(options) {
+            return await runQueued(() => wasmLix.mergeVersionPreview(options));
+        },
         async mergeVersion(options) {
-            ensureOpen("mergeVersion");
             return await runQueued(() => wasmLix.mergeVersion(options));
         },
         async close() {
-            if (closed)
-                return;
-            try {
-                await runQueued(() => wasmLix.close());
-            }
-            finally {
-                backend?.close?.();
-                closed = true;
-            }
+            await runQueued(() => wasmLix.close());
         },
     };
 }
-function normalizeExecuteResult(result) {
-    if (result.kind === "rows") {
-        return {
-            kind: "rows",
-            rows: {
-                columns: [...result.rows.columns],
-                rows: result.rows.rows.map((row) => row.map((value) => Value.from(value))),
-            },
-        };
+function validateExecuteArguments(sql, params) {
+    if (typeof sql !== "string") {
+        throw invalidArgumentError("execute", "sql", "string", sql);
+    }
+    if (!Array.isArray(params)) {
+        throw invalidArgumentError("execute", "params", "array", params);
+    }
+}
+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);
+    }
+}
+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 {
-        kind: "affectedRows",
-        affectedRows: result.affectedRows,
+        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;
+    }
+    if (options.details !== undefined) {
+        error.details = options.details;
+    }
+    if (options.cause !== undefined) {
+        error.cause = options.cause;
+    }
+    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,
+        });
+    }
+    if (error instanceof Error) {
+        return createLixError("LIX_ERROR_UNKNOWN", error.message, { cause: error });
+    }
+    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/sqlite/index.js

@@ -51,21 +51,21 @@ class BetterSqlite3Backend {
         this.#db = db;
         this.#registryKey = registryKey;
     }
-    beginTransaction(mode) {
+    beginReadTransaction() {
         this.#ensureOpen();
         if (this.#db.inTransaction) {
             throw new Error("cannot open nested Lix backend transaction");
         }
-        this.#db.exec(mode === "write" ? "BEGIN IMMEDIATE" : "BEGIN DEFERRED");
+        this.#db.exec("BEGIN DEFERRED");
         return new BetterSqlite3Transaction(this.#db);
     }
-    kvGet(namespace, key) {
+    beginWriteTransaction() {
         this.#ensureOpen();
-        return kvGet(this.#db, namespace, key);
-    }
-    kvScan(namespace, range, limit) {
-        this.#ensureOpen();
-        return kvScan(this.#db, namespace, range, limit);
+        if (this.#db.inTransaction) {
+            throw new Error("cannot open nested Lix backend transaction");
+        }
+        this.#db.exec("BEGIN IMMEDIATE");
+        return new BetterSqlite3Transaction(this.#db);
     }
     close() {
         if (this.#closed)
@@ -92,27 +92,59 @@ class BetterSqlite3Transaction {
     constructor(db) {
         this.#db = db;
     }
-    kvGet(namespace, key) {
+    getValues(request) {
+        this.#ensureOpen();
+        return getValues(this.#db, request);
+    }
+    existsMany(request) {
         this.#ensureOpen();
-        return kvGet(this.#db, namespace, key);
+        return existsMany(this.#db, request);
     }
-    kvScan(namespace, range, limit) {
+    scanKeys(request) {
         this.#ensureOpen();
-        return kvScan(this.#db, namespace, range, limit);
+        const { pairs, resumeAfter } = scanPage(this.#db, request);
+        return {
+            keys: pairs.map(({ key }) => key),
+            resumeAfter,
+        };
     }
-    kvPut(namespace, key, value) {
+    scanValues(request) {
         this.#ensureOpen();
-        this.#db
-            .prepare(`INSERT INTO lix_kv (namespace, key, value)
-				 VALUES (?, ?, ?)
-				 ON CONFLICT(namespace, key) DO UPDATE SET value = excluded.value`)
-            .run(namespace, sqliteBytes(key), sqliteBytes(value));
+        const { pairs, resumeAfter } = scanPage(this.#db, request);
+        return {
+            values: pairs.map(({ value }) => value),
+            resumeAfter,
+        };
     }
-    kvDelete(namespace, key) {
+    scanEntries(request) {
         this.#ensureOpen();
-        this.#db
-            .prepare("DELETE FROM lix_kv WHERE namespace = ? AND key = ?")
-            .run(namespace, sqliteBytes(key));
+        const { pairs, resumeAfter } = scanPage(this.#db, request);
+        return {
+            keys: pairs.map(({ key }) => key),
+            values: pairs.map(({ value }) => value),
+            resumeAfter,
+        };
+    }
+    writeKvBatch(batch) {
+        this.#ensureOpen();
+        const stats = {
+            puts: 0,
+            deletes: 0,
+            bytesWritten: 0,
+        };
+        for (const group of batch.groups) {
+            for (const put of group.puts) {
+                stats.puts += 1;
+                stats.bytesWritten += put.key.length + put.value.length;
+                kvPut(this.#db, group.namespace, put.key, put.value);
+            }
+            for (const key of group.deletes) {
+                stats.deletes += 1;
+                stats.bytesWritten += key.length;
+                kvDelete(this.#db, group.namespace, key);
+            }
+        }
+        return stats;
     }
     commit() {
         this.#ensureOpen();
@@ -130,6 +162,34 @@ class BetterSqlite3Transaction {
         }
     }
 }
+function getValues(db, request) {
+    return {
+        groups: request.groups.map((group) => ({
+            namespace: group.namespace,
+            values: group.keys.map((key) => kvGet(db, group.namespace, key)),
+        })),
+    };
+}
+function existsMany(db, request) {
+    return {
+        groups: request.groups.map((group) => ({
+            namespace: group.namespace,
+            exists: group.keys.map((key) => kvGet(db, group.namespace, key) !== null),
+        })),
+    };
+}
+function scanPage(db, request) {
+    const scanLimit = request.limit + 1 + (request.after ? 1 : 0);
+    const pairs = kvScan(db, request.namespace, request.range, scanLimit).filter((pair) => !request.after || compareBytes(pair.key, request.after) > 0);
+    const hasMore = pairs.length > request.limit;
+    const pagePairs = pairs.slice(0, request.limit);
+    return {
+        pairs: pagePairs,
+        resumeAfter: hasMore
+            ? (pagePairs.at(-1)?.key ?? null)
+            : null,
+    };
+}
 function kvGet(db, namespace, key) {
     const row = db
         .prepare("SELECT value FROM lix_kv WHERE namespace = ? AND key = ?")
@@ -139,6 +199,14 @@ function kvGet(db, namespace, key) {
     }
     return bytesFromUnknown(row.value, "lix_kv.value");
 }
+function kvPut(db, namespace, key, value) {
+    db.prepare(`INSERT INTO lix_kv (namespace, key, value)
+		 VALUES (?, ?, ?)
+		 ON CONFLICT(namespace, key) DO UPDATE SET value = excluded.value`).run(namespace, sqliteBytes(key), sqliteBytes(value));
+}
+function kvDelete(db, namespace, key) {
+    db.prepare("DELETE FROM lix_kv WHERE namespace = ? AND key = ?").run(namespace, sqliteBytes(key));
+}
 function kvScan(db, namespace, range, limit) {
     const { sql, params } = scanQuery(namespace, range, limit);
     return db.prepare(sql).all(...params).map((row) => {
@@ -174,6 +242,15 @@ function scanQuery(namespace, range, limit) {
     }
     return { sql, params };
 }
+function compareBytes(left, right) {
+    const length = Math.min(left.length, right.length);
+    for (let index = 0; index < length; index++) {
+        const delta = left[index] - right[index];
+        if (delta !== 0)
+            return delta;
+    }
+    return left.length - right.length;
+}
 function prefixUpperBound(prefix) {
     const end = new Uint8Array(prefix);
     for (let index = end.length - 1; index >= 0; index--) {

package/dist-engine-src/README.md

@@ -0,0 +1,18 @@
+# Bundled Lix Engine Source
+
+This directory is a generated snapshot of the Rust engine source that backs this @lix-js/sdk release.
+
+Source in the Lix monorepo: `packages/engine/src`
+
+Agents should inspect these files when SDK behavior is unclear instead of relying only on SKILL.md prose.
+
+Useful entry points:
+
+- `src/sql2/entity_provider.rs` - registered schema SQL surfaces
+- `src/sql2/change_provider.rs` - `lix_change` projection
+- `src/sql2/version_provider.rs` - writable `lix_version` surface
+- `src/transaction/validation.rs` - primary-key, unique, foreign-key, and shape validation
+- `src/schema/definition.json` - Lix schema-definition meta-schema
+- `src/schema/builtin/` - built-in schema definitions
+
+Regenerate with `pnpm --filter @lix-js/sdk sync:engine-src` from the repo root.