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

package/dist/generated/builtin-schemas.js

@@ -52,30 +52,6 @@ export const LixActiveAccountSchema = {
     ],
     "additionalProperties": false
 };
-export const LixActiveVersionSchema = {
-    "x-lix-key": "lix_active_version",
-    "x-lix-version": "1",
-    "description": "Singleton tracking which version is currently checked out in the local runtime. Exactly one row exists at all times; writing to this surface is how clients switch versions.",
-    "x-lix-primary-key": [
-        "/id"
-    ],
-    "type": "object",
-    "properties": {
-        "id": {
-            "type": "string",
-            "description": "Fixed singleton key (constant, not a UUID); the primary-key column exists to satisfy entity-model requirements and enforces the one-row invariant."
-        },
-        "version_id": {
-            "type": "string",
-            "description": "The currently active version; references `lix_version_descriptor.id` and drives the default scope for reads and writes in the session."
-        }
-    },
-    "required": [
-        "id",
-        "version_id"
-    ],
-    "additionalProperties": false
-};
 export const LixBinaryBlobRefSchema = {
     "x-lix-key": "lix_binary_blob_ref",
     "x-lix-version": "1",
@@ -109,7 +85,7 @@ export const LixBinaryBlobRefSchema = {
 export const LixChangeSchema = {
     "x-lix-key": "lix_change",
     "x-lix-version": "1",
-    "description": "Canonical immutable change fact. This surface represents the authoritative stream of journaled change facts. Commit lineage and non-commit scope are modeled separately around these facts. The public `untracked` field is retained as convenience metadata and should not be treated as proof that trackedness is intrinsic to the canonical fact row itself.",
+    "description": "Canonical immutable change fact. This surface represents the authoritative stream of journaled change facts. Commit lineage and non-commit scope are modeled separately around these facts.",
     "x-lix-primary-key": [
         "/id"
     ],
@@ -139,13 +115,6 @@ export const LixChangeSchema = {
             ],
             "description": "Filesystem-scoped file identifier when the change belongs to a file; NULL for engine-internal entities (commits, versions, settings)."
         },
-        "plugin_key": {
-            "type": [
-                "string",
-                "null"
-            ],
-            "description": "Plugin that authored the change; NULL for engine-internal changes."
-        },
         "metadata": {
             "type": [
                 "object",
@@ -157,10 +126,6 @@ export const LixChangeSchema = {
             "type": "string",
             "description": "ISO-8601 timestamp at which the change was recorded (set via `lix_timestamp()` at write time)."
         },
-        "untracked": {
-            "type": "boolean",
-            "description": "Public convenience field indicating that the change currently participates in non-commit visibility rather than commit lineage. This is intended to become derived metadata rather than intrinsic canonical storage truth."
-        },
         "snapshot_content": {
             "type": [
                 "object",
@@ -175,9 +140,7 @@ export const LixChangeSchema = {
         "schema_key",
         "schema_version",
         "file_id",
-        "plugin_key",
-        "created_at",
-        "untracked"
+        "created_at"
     ],
     "additionalProperties": false
 };
@@ -248,7 +211,7 @@ export const LixChangeSetSchema = {
 export const LixChangeSetElementSchema = {
     "x-lix-key": "lix_change_set_element",
     "x-lix-version": "1",
-    "description": "Derived relational index mapping a change_set to the canonical changes it contains. Rebuildable from `lix_commit.change_ids` plus the referenced `lix_change` rows; the unique constraint enforces at most one change per (entity, schema, file) tuple within a single change_set.",
+    "description": "Derived relational index mapping a change_set to the canonical changes introduced by its commit relative to the commit's first parent. Rebuildable from `lix_commit.change_ids` plus the referenced `lix_change` rows; the unique constraint enforces at most one change per (entity, schema, file) tuple within a single change_set.",
     "x-lix-primary-key": [
         "/change_set_id",
         "/change_id"
@@ -293,7 +256,7 @@ export const LixChangeSetElementSchema = {
         },
         "change_id": {
             "type": "string",
-            "description": "The canonical change included in the change_set (references `lix_change.id`)."
+            "description": "The canonical change introduced/adopted by the change_set's commit (references `lix_change.id`)."
         },
         "entity_id": {
             "type": "string",
@@ -323,7 +286,7 @@ export const LixChangeSetElementSchema = {
 export const LixCommitSchema = {
     "x-lix-key": "lix_commit",
     "x-lix-version": "1",
-    "description": "Commit header change. Canonical commit membership is stored in change_ids as the ordered list of non-header member changes for this commit. Derived projections such as lix_change_set_element must be rebuildable from this header plus the referenced change rows. Version head pointers such as lix_version_ref are maintained separately and are not commit members.",
+    "description": "Commit header change. Canonical commit membership is stored in change_ids as the ordered list of canonical changes whose effects this commit introduces relative to its first parent. A merge commit may reference canonical changes originally authored in another parent instead of copying them. Derived projections such as lix_change_set_element must be rebuildable from this header plus the referenced change rows. Version head pointers such as lix_version_ref are maintained separately and are not commit members.",
     "x-lix-primary-key": [
         "/id"
     ],
@@ -357,7 +320,7 @@ export const LixCommitSchema = {
             "items": {
                 "type": "string"
             },
-            "description": "Canonical ordered membership list of non-header change IDs that belong to this commit. Derived indexes such as lix_change_set_element must be rebuildable from this list. This does not include lix_version_ref pointer rows."
+            "description": "Canonical ordered membership list of non-header change IDs whose effects this commit introduces relative to its first parent. Merge commits may reference existing changes from another parent instead of minting equivalent copies. Derived indexes such as lix_change_set_element must be rebuildable from this list. This does not include lix_version_ref pointer rows."
         },
         "author_account_ids": {
             "type": "array",
@@ -440,6 +403,19 @@ export const LixDirectoryDescriptorSchema = {
             "/name"
         ]
     ],
+    "x-lix-foreign-keys": [
+        {
+            "properties": [
+                "/parent_id"
+            ],
+            "references": {
+                "schemaKey": "lix_directory_descriptor",
+                "properties": [
+                    "/id"
+                ]
+            }
+        }
+    ],
     "type": "object",
     "properties": {
         "id": {
@@ -540,10 +516,22 @@ export const LixFileDescriptorSchema = {
     "x-lix-unique": [
         [
             "/directory_id",
-            "/name",
-            "/extension"
+            "/name"
         ]
     ],
+    "x-lix-foreign-keys": [
+        {
+            "properties": [
+                "/directory_id"
+            ],
+            "references": {
+                "schemaKey": "lix_directory_descriptor",
+                "properties": [
+                    "/id"
+                ]
+            }
+        }
+    ],
     "type": "object",
     "properties": {
         "id": {
@@ -558,14 +546,7 @@ export const LixFileDescriptorSchema = {
         },
         "name": {
             "type": "string",
-            "pattern": "^[^/\\\\]+$"
-        },
-        "extension": {
-            "type": [
-                "string",
-                "null"
-            ],
-            "pattern": "^[^./\\\\]+$"
+            "pattern": "^(?!\\.{1,2}$)[^/\\\\]+$"
         },
         "hidden": {
             "type": "boolean",
@@ -575,8 +556,7 @@ export const LixFileDescriptorSchema = {
     "required": [
         "id",
         "directory_id",
-        "name",
-        "extension"
+        "name"
     ],
     "additionalProperties": false
 };
@@ -681,12 +661,17 @@ export const LixVersionDescriptorSchema = {
     "x-lix-primary-key": [
         "/id"
     ],
+    "x-lix-unique": [
+        [
+            "/name"
+        ]
+    ],
     "type": "object",
     "properties": {
         "id": {
             "type": "string",
             "x-lix-default": "lix_uuid_v7()",
-            "description": "Stable version identifier (UUIDv7). Referenced by `lix_version_ref.id` and `lix_active_version.version_id`."
+            "description": "Stable version identifier (UUIDv7). Referenced by `lix_version_ref.id`."
         },
         "name": {
             "type": "string",
@@ -712,6 +697,17 @@ export const LixVersionRefSchema = {
         "/id"
     ],
     "x-lix-foreign-keys": [
+        {
+            "properties": [
+                "/id"
+            ],
+            "references": {
+                "schemaKey": "lix_version_descriptor",
+                "properties": [
+                    "/id"
+                ]
+            }
+        },
         {
             "properties": [
                 "/commit_id"

package/dist/open-lix.d.ts

@@ -3,17 +3,33 @@ export type JsonValue = null | boolean | number | string | JsonValue[] | {
     [key: string]: JsonValue;
 };
 export type LixRuntimeValue = JsonValue | Uint8Array | ArrayBuffer | Value;
-export type RowSet = {
+export type LixNativeValue = JsonValue | Uint8Array;
+export type ExecuteResult = {
     columns: string[];
-    rows: Value[][];
+    rows: Row[];
+    rowsAffected: number;
+    notices: LixNotice[];
 };
-export type ExecuteResult = {
-    kind: "rows";
-    rows: RowSet;
-} | {
-    kind: "affectedRows";
-    affectedRows: number;
+export type LixNotice = {
+    code: string;
+    message: string;
+    hint?: string;
 };
+export declare class Row {
+    readonly columns: string[];
+    private readonly valuesByIndex;
+    constructor(columns: string[], values: Value[]);
+    get(columnName: string): LixNativeValue;
+    tryGet(columnName: string): LixNativeValue | undefined;
+    value(columnName: string): Value;
+    tryValue(columnName: string): Value | undefined;
+    getAt(index: number): LixNativeValue;
+    valueAt(index: number): Value;
+    values(): Value[];
+    toObject(): Record<string, LixNativeValue>;
+    toValueMap(): Record<string, Value>;
+    private availableColumns;
+}
 export type TransactionBeginMode = "read" | "write" | "deferred";
 export type KvScanRange = {
     kind: "prefix";
@@ -47,9 +63,13 @@ export type OpenLixOptions = {
 export type CreateVersionOptions = {
     id?: string;
     name: string;
+    fromCommitId?: string;
 };
 export type CreateVersionResult = {
-    versionId: string;
+    id: string;
+    name: string;
+    hidden: boolean;
+    commitId: string;
 };
 export type SwitchVersionOptions = {
     versionId: string;
@@ -60,7 +80,7 @@ export type SwitchVersionResult = {
 export type MergeVersionOptions = {
     sourceVersionId: string;
 };
-export type MergeVersionOutcome = "alreadyUpToDate" | "mergeCommitted";
+export type MergeVersionOutcome = "alreadyUpToDate" | "fastForward" | "mergeCommitted";
 export type MergeVersionResult = {
     outcome: MergeVersionOutcome;
     targetVersionId: string;
@@ -73,6 +93,14 @@ export type MergeVersionResult = {
     appliedChangeCount: number;
 };
 export type Lix = {
+    /**
+     * Executes one DataFusion SQL statement against this Lix session.
+     *
+     * This is not SQLite SQL. Use the DataFusion SQL dialect; positional
+     * placeholders are `$1`, `$2`, and so on. SQLite-specific catalog tables and
+     * transaction statements such as `sqlite_master`, `BEGIN`, and `COMMIT` are
+     * not available. Use `information_schema` for catalog inspection.
+     */
     execute(sql: string, params?: ReadonlyArray<LixRuntimeValue>): Promise<ExecuteResult>;
     activeVersionId(): Promise<string>;
     createVersion(options: CreateVersionOptions): Promise<CreateVersionResult>;

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,155 @@ 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 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/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@lix-js/sdk",
   "type": "module",
-  "version": "0.6.0-preview.0",
+  "version": "0.6.0-preview.1",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "SKILL.md"
   ],
   "exports": {
     ".": {