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

package/dist/index.d.ts

@@ -1,28 +1,5 @@
-export * from "./account/index.js";
-export * from "./change/index.js";
-export * from "./change-author/index.js";
-export * from "./environment/index.js";
-export * from "./change-set/index.js";
-export * from "./commit/index.js";
-export * from "./database/index.js";
-export * from "./engine/functions/index.js";
-export * from "./entity/index.js";
-export * from "./engine/entity-views/index.js";
-export * from "./filesystem/index.js";
-export * from "./hooks/create-hooks.js";
-export * from "./key-value/index.js";
-export * from "./label/index.js";
-export * from "./lix/index.js";
-export * from "./log/index.js";
-export * from "./observe/index.js";
-export * from "./plugin/index.js";
-export * from "./query-filter/index.js";
-export * from "./schema-definition/index.js";
-export * from "./state/index.js";
-export * from "./stored-schema/index.js";
-export * from "./server-protocol-handler/index.js";
-export * from "./conversation/index.js";
-export * from "./change-proposal/index.js";
-export * from "./version/index.js";
-export * from "./diff/index.js";
-//# sourceMappingURL=index.d.ts.map
+export * from "./open-lix.js";
+export * from "./builtin-schemas.js";
+export { Value, isLixError } from "./engine-wasm/index.js";
+export type { LixError, LixValue } from "./engine-wasm/index.js";
+export type { JsonValue, LixRuntimeValue } from "./types.js";

package/dist/index.js

@@ -1,28 +1,3 @@
-export * from "./account/index.js";
-export * from "./change/index.js";
-export * from "./change-author/index.js";
-export * from "./environment/index.js";
-export * from "./change-set/index.js";
-export * from "./commit/index.js";
-export * from "./database/index.js";
-export * from "./engine/functions/index.js";
-export * from "./entity/index.js";
-export * from "./engine/entity-views/index.js";
-export * from "./filesystem/index.js";
-export * from "./hooks/create-hooks.js";
-export * from "./key-value/index.js";
-export * from "./label/index.js";
-export * from "./lix/index.js";
-export * from "./log/index.js";
-export * from "./observe/index.js";
-export * from "./plugin/index.js";
-export * from "./query-filter/index.js";
-export * from "./schema-definition/index.js";
-export * from "./state/index.js";
-export * from "./stored-schema/index.js";
-export * from "./server-protocol-handler/index.js";
-export * from "./conversation/index.js";
-export * from "./change-proposal/index.js";
-export * from "./version/index.js";
-export * from "./diff/index.js";
-//# sourceMappingURL=index.js.map
+export * from "./open-lix.js";
+export * from "./builtin-schemas.js";
+export { Value, isLixError } from "./engine-wasm/index.js";

package/dist/open-lix.d.ts

@@ -0,0 +1,83 @@
+import { Value } from "./engine-wasm/index.js";
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type LixRuntimeValue = JsonValue | Uint8Array | ArrayBuffer | Value;
+export type RowSet = {
+    columns: string[];
+    rows: Value[][];
+};
+export type ExecuteResult = {
+    kind: "rows";
+    rows: RowSet;
+} | {
+    kind: "affectedRows";
+    affectedRows: number;
+};
+export type TransactionBeginMode = "read" | "write" | "deferred";
+export type KvScanRange = {
+    kind: "prefix";
+    prefix: Uint8Array;
+} | {
+    kind: "range";
+    start: Uint8Array;
+    end: Uint8Array;
+};
+export type KvPair = {
+    key: Uint8Array;
+    value: Uint8Array;
+};
+export type LixBackendTransaction = {
+    kvGet(namespace: string, key: Uint8Array): Uint8Array | null | undefined;
+    kvScan(namespace: string, range: KvScanRange, limit?: number | null): KvPair[];
+    kvPut(namespace: string, key: Uint8Array, value: Uint8Array): void;
+    kvDelete(namespace: string, key: Uint8Array): void;
+    commit(): void;
+    rollback(): void;
+};
+export type LixBackend = {
+    beginTransaction(mode: TransactionBeginMode): LixBackendTransaction;
+    kvGet?(namespace: string, key: Uint8Array): Uint8Array | null | undefined;
+    kvScan?(namespace: string, range: KvScanRange, limit?: number | null): KvPair[];
+    close?(): void;
+};
+export type OpenLixOptions = {
+    backend?: LixBackend;
+};
+export type CreateVersionOptions = {
+    id?: string;
+    name: string;
+};
+export type CreateVersionResult = {
+    versionId: string;
+};
+export type SwitchVersionOptions = {
+    versionId: string;
+};
+export type SwitchVersionResult = {
+    versionId: string;
+};
+export type MergeVersionOptions = {
+    sourceVersionId: string;
+};
+export type MergeVersionOutcome = "alreadyUpToDate" | "mergeCommitted";
+export type MergeVersionResult = {
+    outcome: MergeVersionOutcome;
+    targetVersionId: string;
+    sourceVersionId: string;
+    mergeBaseCommitId: string | null;
+    targetHeadBeforeCommitId: string;
+    sourceHeadBeforeCommitId: string;
+    targetHeadAfterCommitId: string;
+    createdMergeCommitId: string | null;
+    appliedChangeCount: number;
+};
+export type Lix = {
+    execute(sql: string, params?: ReadonlyArray<LixRuntimeValue>): Promise<ExecuteResult>;
+    activeVersionId(): Promise<string>;
+    createVersion(options: CreateVersionOptions): Promise<CreateVersionResult>;
+    switchVersion(options: SwitchVersionOptions): Promise<SwitchVersionResult>;
+    mergeVersion(options: MergeVersionOptions): Promise<MergeVersionResult>;
+    close(): Promise<void>;
+};
+export declare function openLix(options?: OpenLixOptions): Promise<Lix>;

package/dist/open-lix.js

@@ -0,0 +1,104 @@
+import init, { resolveEngineWasmModuleOrPath, Value, } from "./engine-wasm/index.js";
+import * as wasmModule from "./engine-wasm/index.js";
+let wasmReady = null;
+async function ensureWasmReady() {
+    if (!wasmReady) {
+        wasmReady = resolveEngineWasmModuleOrPath()
+            .then((module_or_path) => init({ module_or_path }))
+            .then(() => undefined);
+    }
+    await wasmReady;
+}
+export async function openLix(options = {}) {
+    await ensureWasmReady();
+    try {
+        const wasmLix = (await wasmModule.openLix(options));
+        return createLixHandle(wasmLix, options.backend);
+    }
+    catch (error) {
+        try {
+            options.backend?.close?.();
+        }
+        catch {
+            // Preserve the original open failure.
+        }
+        throw error;
+    }
+}
+function createLixHandle(wasmLix, backend) {
+    let closed = false;
+    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;
+        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();
+        }
+        finally {
+            release();
+        }
+    };
+    return {
+        async execute(sql, params = []) {
+            ensureOpen("execute");
+            const result = await runQueued(() => wasmLix.execute(sql, params.map((param) => Value.from(param))));
+            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;
+            }
+        },
+    };
+}
+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))),
+            },
+        };
+    }
+    return {
+        kind: "affectedRows",
+        affectedRows: result.affectedRows,
+    };
+}

package/dist/sqlite/index.d.ts

@@ -0,0 +1,12 @@
+import type { LixBackend } from "../open-lix.js";
+export type BetterSqlite3BackendOptions = {
+    path: string;
+    databaseOptions?: BetterSqlite3DatabaseOptions;
+};
+export type BetterSqlite3DatabaseOptions = {
+    readonly?: boolean;
+    fileMustExist?: boolean;
+    timeout?: number;
+    verbose?: (message?: unknown, ...additional: unknown[]) => void;
+};
+export declare function createBetterSqlite3Backend(options: BetterSqlite3BackendOptions): LixBackend;

package/dist/sqlite/index.js

@@ -0,0 +1,226 @@
+import DatabaseConstructor from "better-sqlite3";
+const openFileHandles = new Set();
+export function createBetterSqlite3Backend(options) {
+    if (!options.path) {
+        throw new Error("createBetterSqlite3Backend() requires a non-empty path");
+    }
+    const registryKey = registryKeyForPath(options.path);
+    if (registryKey && openFileHandles.has(registryKey)) {
+        throw doubleOpenError(options.path);
+    }
+    let activeRegistryKey = registryKey;
+    let db;
+    if (activeRegistryKey) {
+        openFileHandles.add(activeRegistryKey);
+    }
+    try {
+        db = new DatabaseConstructor(options.path, options.databaseOptions);
+        initializeDatabase(db);
+        return new BetterSqlite3Backend(db, activeRegistryKey);
+    }
+    catch (error) {
+        if (activeRegistryKey) {
+            openFileHandles.delete(activeRegistryKey);
+        }
+        if (db) {
+            try {
+                db.close();
+            }
+            catch {
+                // Ignore close errors while preserving the original open failure.
+            }
+        }
+        throw error;
+    }
+}
+function initializeDatabase(db) {
+    db.exec(`
+		CREATE TABLE IF NOT EXISTS lix_kv (
+			namespace TEXT NOT NULL,
+			key BLOB NOT NULL,
+			value BLOB NOT NULL,
+			PRIMARY KEY (namespace, key)
+		) WITHOUT ROWID
+	`);
+}
+class BetterSqlite3Backend {
+    #db;
+    #registryKey;
+    #closed = false;
+    constructor(db, registryKey) {
+        this.#db = db;
+        this.#registryKey = registryKey;
+    }
+    beginTransaction(mode) {
+        this.#ensureOpen();
+        if (this.#db.inTransaction) {
+            throw new Error("cannot open nested Lix backend transaction");
+        }
+        this.#db.exec(mode === "write" ? "BEGIN IMMEDIATE" : "BEGIN DEFERRED");
+        return new BetterSqlite3Transaction(this.#db);
+    }
+    kvGet(namespace, key) {
+        this.#ensureOpen();
+        return kvGet(this.#db, namespace, key);
+    }
+    kvScan(namespace, range, limit) {
+        this.#ensureOpen();
+        return kvScan(this.#db, namespace, range, limit);
+    }
+    close() {
+        if (this.#closed)
+            return;
+        try {
+            this.#db.close();
+        }
+        finally {
+            this.#closed = true;
+            if (this.#registryKey) {
+                openFileHandles.delete(this.#registryKey);
+            }
+        }
+    }
+    #ensureOpen() {
+        if (this.#closed) {
+            throw new Error("better-sqlite3 Lix backend is closed");
+        }
+    }
+}
+class BetterSqlite3Transaction {
+    #db;
+    #closed = false;
+    constructor(db) {
+        this.#db = db;
+    }
+    kvGet(namespace, key) {
+        this.#ensureOpen();
+        return kvGet(this.#db, namespace, key);
+    }
+    kvScan(namespace, range, limit) {
+        this.#ensureOpen();
+        return kvScan(this.#db, namespace, range, limit);
+    }
+    kvPut(namespace, key, value) {
+        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));
+    }
+    kvDelete(namespace, key) {
+        this.#ensureOpen();
+        this.#db
+            .prepare("DELETE FROM lix_kv WHERE namespace = ? AND key = ?")
+            .run(namespace, sqliteBytes(key));
+    }
+    commit() {
+        this.#ensureOpen();
+        this.#db.exec("COMMIT");
+        this.#closed = true;
+    }
+    rollback() {
+        this.#ensureOpen();
+        this.#db.exec("ROLLBACK");
+        this.#closed = true;
+    }
+    #ensureOpen() {
+        if (this.#closed) {
+            throw new Error("Lix backend transaction is closed");
+        }
+    }
+}
+function kvGet(db, namespace, key) {
+    const row = db
+        .prepare("SELECT value FROM lix_kv WHERE namespace = ? AND key = ?")
+        .get(namespace, sqliteBytes(key));
+    if (!isObject(row) || !("value" in row)) {
+        return null;
+    }
+    return bytesFromUnknown(row.value, "lix_kv.value");
+}
+function kvScan(db, namespace, range, limit) {
+    const { sql, params } = scanQuery(namespace, range, limit);
+    return db.prepare(sql).all(...params).map((row) => {
+        if (!isObject(row) || !("key" in row) || !("value" in row)) {
+            throw new Error("invalid lix_kv scan row");
+        }
+        return {
+            key: bytesFromUnknown(row.key, "lix_kv.key"),
+            value: bytesFromUnknown(row.value, "lix_kv.value"),
+        };
+    });
+}
+function scanQuery(namespace, range, limit) {
+    const params = [namespace];
+    const clauses = ["namespace = ?"];
+    if (range.kind === "prefix") {
+        clauses.push("key >= ?");
+        params.push(sqliteBytes(range.prefix));
+        const end = prefixUpperBound(range.prefix);
+        if (end) {
+            clauses.push("key < ?");
+            params.push(sqliteBytes(end));
+        }
+    }
+    else {
+        clauses.push("key >= ?", "key < ?");
+        params.push(sqliteBytes(range.start), sqliteBytes(range.end));
+    }
+    let sql = `SELECT key, value FROM lix_kv WHERE ${clauses.join(" AND ")} ORDER BY key`;
+    if (limit != null) {
+        sql += " LIMIT ?";
+        params.push(limit);
+    }
+    return { sql, params };
+}
+function prefixUpperBound(prefix) {
+    const end = new Uint8Array(prefix);
+    for (let index = end.length - 1; index >= 0; index--) {
+        if (end[index] !== 0xff) {
+            end[index] += 1;
+            return end.slice(0, index + 1);
+        }
+    }
+    return null;
+}
+function bytesFromUnknown(value, context) {
+    if (value instanceof Uint8Array) {
+        return new Uint8Array(value);
+    }
+    throw new Error(`${context} must be bytes`);
+}
+function sqliteBytes(bytes) {
+    const buffer = globalThis.Buffer;
+    return buffer ? buffer.from(bytes) : bytes;
+}
+function registryKeyForPath(filename) {
+    if (filename === ":memory:") {
+        return null;
+    }
+    if (filename.startsWith("/")) {
+        return normalizeAbsolutePath(filename);
+    }
+    const cwd = globalThis.process?.cwd?.() ?? "/";
+    return normalizeAbsolutePath(`${cwd}/${filename}`);
+}
+function normalizeAbsolutePath(filename) {
+    const segments = [];
+    for (const segment of filename.split("/")) {
+        if (!segment || segment === ".") {
+            continue;
+        }
+        if (segment === "..") {
+            segments.pop();
+            continue;
+        }
+        segments.push(segment);
+    }
+    return `/${segments.join("/")}`;
+}
+function doubleOpenError(filename) {
+    return new Error(`createBetterSqlite3Backend() already has an open handle for ${filename}; close the existing Lix handle before opening this file again`);
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null;
+}

package/dist/types.d.ts

@@ -0,0 +1 @@
+export type { JsonValue, LixRuntimeValue } from "./open-lix.js";

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,82 +1,64 @@
 {
   "name": "@lix-js/sdk",
   "type": "module",
-  "publishConfig": {
-    "access": "public"
-  },
-  "version": "0.5.0",
-  "description": "SDK for change control. Enable Git-like capabilities like versioning, history, and blame in apps and AI agents.",
-  "keywords": [
-    "change control",
-    "version control",
-    "git",
-    "versioning",
-    "history",
-    "blame",
-    "branching",
-    "ai-agents",
-    "sdk",
-    "browser",
-    "wasm",
-    "json",
-    "csv",
-    "markdown"
-  ],
-  "license": "Apache-2.0",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/opral/lix-sdk"
-  },
-  "homepage": "https://lix.dev/",
+  "version": "0.6.0-preview.0",
+  "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "exports": {
-    ".": "./dist/index.js",
-    "./dependency/kysely": "./dist/dependency/kysely/index.js",
-    "./dependency/kysely/helpers/sqlite": "./dist/dependency/kysely/helpers/sqlite.js",
-    "./dependency/zettel-ast": "./dist/dependency/zettel-ast/index.js"
-  },
-  "_filesComment": "Shipping src for better debugging experience",
   "files": [
-    "dist",
-    "src"
+    "dist"
   ],
-  "_comment": "Required for tree-shaking https://webpack.js.org/guides/tree-shaking/#mark-the-file-as-side-effect-free",
-  "sideEffects": false,
-  "engines": {
-    "node": ">=22"
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./sqlite": {
+      "types": "./dist/sqlite/index.d.ts",
+      "default": "./dist/sqlite/index.js"
+    }
   },
-  "dependencies": {
-    "@marcbachmann/cel-js": "^2.5.2",
-    "@sqlite.org/sqlite-wasm": "^3.50.4-build1",
-    "ajv": "^8.17.1",
-    "chevrotain": "^11.0.3",
-    "kysely": "^0.28.7",
-    "uuid": "^11.1.0",
-    "@opral/zettel-ast": "0.1.0",
-    "@lix-js/server-protocol-schema": "0.1.1"
+  "description": "WASM-backed JS SDK wrapper for Lix",
+  "peerDependencies": {
+    "better-sqlite3": "^12.9.0"
+  },
+  "peerDependenciesMeta": {
+    "better-sqlite3": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "@codspeed/vitest-plugin": "^4.0.1",
-    "@vitest/browser-playwright": "4.0.6",
-    "@vitest/coverage-v8": "4.0.6",
-    "json-schema-to-ts": "^3.1.1",
-    "oxlint": "^1.14.0",
-    "playwright": "^1.55.0",
-    "prettier": "^3.3.3",
+    "better-sqlite3": "^12.9.0",
     "typescript": "^5.5.4",
-    "vitest": "4.0.6",
-    "@opral/tsconfig": "1.1.0"
+    "vitest": "^4.0.18"
+  },
+  "nx": {
+    "targets": {
+      "build": {
+        "inputs": [
+          "default",
+          "^default",
+          "publicEnv",
+          "nodeVersion",
+          "platform",
+          "{workspaceRoot}/Cargo.toml",
+          "{workspaceRoot}/Cargo.lock",
+          "{workspaceRoot}/packages/engine/**/*",
+          "{workspaceRoot}/packages/rs-sdk/**/*",
+          "{workspaceRoot}/packages/js-sdk/Cargo.toml",
+          "{workspaceRoot}/packages/js-sdk/wasm-bindgen.rs"
+        ],
+        "outputs": [
+          "{projectRoot}/dist",
+          "{projectRoot}/src/engine-wasm/wasm"
+        ]
+      }
+    }
   },
   "scripts": {
     "build": "node ./scripts/build.js",
-    "typecheck": "tsc --noEmit -p tsconfig.json",
-    "pretest": "playwright install --with-deps",
-    "test": "node ./scripts/build.js --setup-only && vitest run --typecheck",
-    "test:watch": "node ./scripts/build.js --setup-only && vitest --typecheck",
-    "bench": "vitest bench",
-    "lint": "oxlint --config .oxlintrc.json \"src/**/*.{js,ts}\" --fix",
-    "dev": "node ./scripts/build.js --watch",
-    "format": "prettier ./src --write",
-    "clean": "rm -rf ./dist ./node_modules"
+    "sync:builtin-schemas": "node ./scripts/sync-builtin-schemas.js",
+    "typecheck": "pnpm run sync:builtin-schemas && tsc -p tsconfig.json --noEmit",
+    "test": "node ./scripts/build.js && vitest run",
+    "test:watch": "node ./scripts/build.js && vitest"
   }
 }

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2024 Opral US Inc.
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.