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

package/README.md

@@ -1,9 +1,81 @@
 # @lix-js/sdk
 
-WASM-backed JavaScript SDK for Lix.
+JavaScript SDK for Lix, backed by the native Rust SDK.
 
-## Agent Guidance
+## Install
 
-If you are an AI coding agent using this package, read [`SKILL.md`](./SKILL.md) before building examples, demos, tests, or applications with `@lix-js/sdk`.
+```bash
+npm install @lix-js/sdk
+```
 
-The skill documents the current preview API, recommended SQLite backend setup, schema registration flow, entity-table writes, branch workflows, merge behavior, and known sharp edges.
+## Usage
+
+```ts
+import { openLix, SqliteBackend } from "@lix-js/sdk";
+
+const lix = await openLix({
+	backend: new SqliteBackend({ path: "app.lix" }),
+});
+
+await lix.execute(
+	"INSERT INTO lix_key_value (key, value) VALUES ($1, $2)",
+	["hello", "world"],
+);
+
+const result = await lix.execute(
+	"SELECT value FROM lix_key_value WHERE key = $1",
+	["hello"],
+);
+
+console.log(result.rows[0]?.get("value"));
+
+await lix.close();
+```
+
+## Branches
+
+```ts
+const main = await lix.activeBranchId();
+const draft = await lix.createBranch({ name: "Draft" });
+
+await lix.switchBranch({ branchId: draft.id });
+await lix.execute(
+	"INSERT INTO lix_key_value (key, value) VALUES ($1, $2)",
+	["status", "draft"],
+);
+
+await lix.switchBranch({ branchId: main });
+const preview = await lix.mergeBranchPreview({ sourceBranchId: draft.id });
+const merge = await lix.mergeBranch({ sourceBranchId: draft.id });
+```
+
+## Transactions
+
+```ts
+const tx = await lix.beginTransaction();
+
+try {
+	await tx.execute(
+		"INSERT INTO lix_key_value (key, value) VALUES ($1, $2)",
+		["a", "1"],
+	);
+	await tx.execute(
+		"INSERT INTO lix_key_value (key, value) VALUES ($1, $2)",
+		["b", "2"],
+	);
+	await tx.commit();
+} catch (error) {
+	await tx.rollback();
+	throw error;
+}
+```
+
+## Notes
+
+- `openLix()` opens a fresh in-memory Lix. Pass `new SqliteBackend({ path })` to persist to disk.
+- The SDK is Node/native only right now; it is not browser-compatible.
+- The package is ESM-only.
+- The native addon is built from Rust and loaded by the TypeScript wrapper.
+- The public API is promise-based, but the current native implementation performs local SQLite work synchronously under the hood.
+- SQL parameters use normal JavaScript values: `string`, finite `number`, `boolean`, `Uint8Array`, `null`, JSON-compatible arrays, and JSON-compatible plain objects.
+- Use `Value.integer(...)`, `Value.real(...)`, `Value.text(...)`, `Value.json(...)`, or `Value.blob(...)` only when you need to pass an explicit native Lix value.

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+export type LixJsError = Error & {
+    code?: string;
+    details?: unknown;
+    hint?: string;
+};
+export declare function invalidArgument(operation: string, argument: string, expected: string, actual: string, receiver?: string): LixJsError;
+export declare function invalidParam(index: number, message: string, actual: string): LixJsError;

package/dist/errors.js

@@ -0,0 +1,19 @@
+export function invalidArgument(operation, argument, expected, actual, receiver = "lix") {
+    const error = new Error(`${receiver}.${operation}() expected ${argument} to be a ${expected}`);
+    error.name = "LixError";
+    error.code = "LIX_INVALID_ARGUMENT";
+    error.details = { operation, argument, expected, actual };
+    return error;
+}
+export function invalidParam(index, message, actual) {
+    const error = new Error(message);
+    error.name = "LixError";
+    error.code = "LIX_INVALID_PARAM";
+    error.details = {
+        operation: "execute",
+        parameter_index: index + 1,
+        argument: `params[${index}]`,
+        actual,
+    };
+    return error;
+}

package/dist/index.d.ts

@@ -1,5 +1,4 @@
-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";
+export { Lix, LixTransaction, openLix, SqliteBackend } from "./open-lix.js";
+export { Row } from "./result.js";
+export { Value } from "./value.js";
+export type { CreateBranchOptions, CreateBranchReceipt, ExecuteResult, JsonValue, LixValue, MergeBranchOptions, MergeBranchOutcome, MergeBranchPreview, MergeBranchReceipt, MergeChangeStats, MergeConflict, MergeConflictSide, OpenLixOptions, SqlParam, SqliteBackendOptions, SwitchBranchOptions, SwitchBranchReceipt, } from "./types.js";

package/dist/index.js

@@ -1,3 +1,3 @@
-export * from "./open-lix.js";
-export * from "./builtin-schemas.js";
-export { Value, isLixError } from "./engine-wasm/index.js";
+export { Lix, LixTransaction, openLix, SqliteBackend } from "./open-lix.js";
+export { Row } from "./result.js";
+export { Value } from "./value.js";

package/dist/native.d.ts

@@ -0,0 +1 @@
+export declare const addon: Record<string, any>;

package/dist/native.js

@@ -0,0 +1,47 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+const require = createRequire(import.meta.url);
+const localNativePath = fileURLToPath(new URL("../lix_js_sdk.node", import.meta.url));
+const nativePackages = {
+    "linux-x64": "@lix-js/sdk-linux-x64",
+    "linux-arm64": "@lix-js/sdk-linux-arm64",
+    "darwin-arm64": "@lix-js/sdk-darwin-arm64",
+    "win32-x64": "@lix-js/sdk-win32-x64",
+};
+function nativePackageName() {
+    const key = `${process.platform}-${process.arch}`;
+    return nativePackages[key];
+}
+function resolveNativePath() {
+    if (existsSync(localNativePath)) {
+        return localNativePath;
+    }
+    const packageName = nativePackageName();
+    let packageResolutionError;
+    if (packageName) {
+        try {
+            return require.resolve(packageName);
+        }
+        catch (error) {
+            packageResolutionError = error;
+        }
+    }
+    if (!packageName) {
+        throw new Error(`Unsupported platform ${process.platform}-${process.arch}`);
+    }
+    throw packageResolutionError;
+}
+const native = { exports: {} };
+try {
+    const nativePath = resolveNativePath();
+    process.dlopen(native, nativePath);
+}
+catch (cause) {
+    const error = new Error(`Failed to load @lix-js/sdk native addon for ${process.platform}-${process.arch}. ` +
+        "This package requires the matching optional native binary package. " +
+        "Run `npm run build` from packages/js-sdk for local development, or install a release that includes your platform binary.");
+    error.cause = cause;
+    throw error;
+}
+export const addon = native.exports;

package/dist/open-lix.d.ts

@@ -1,214 +1,45 @@
-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 LixNativeValue = JsonValue | Uint8Array;
-export type ExecuteResult = {
-    columns: string[];
-    rows: Row[];
-    rowsAffected: number;
-    notices: LixNotice[];
-};
-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 BackendKvScanRange = {
-    kind: "prefix";
-    prefix: Uint8Array;
-} | {
-    kind: "range";
-    start: Uint8Array;
-    end: Uint8Array;
-};
-export type BackendKvGetRequest = {
-    groups: BackendKvGetGroup[];
-};
-export type BackendKvGetGroup = {
-    namespace: string;
-    keys: Uint8Array[];
-};
-export type BackendKvValueBatch = {
-    groups: BackendKvValueGroup[];
-};
-export type BackendKvValueGroup = {
-    namespace: string;
-    values: Array<Uint8Array | null>;
-};
-export type BackendKvExistsBatch = {
-    groups: BackendKvExistsGroup[];
-};
-export type BackendKvExistsGroup = {
-    namespace: string;
-    exists: boolean[];
-};
-export type BackendKvScanRequest = {
-    namespace: string;
-    range: BackendKvScanRange;
-    after?: Uint8Array | null;
-    limit: number;
-};
-export type BackendKvKeyPage = {
-    keys: Uint8Array[];
-    resumeAfter?: Uint8Array | null;
-};
-export type BackendKvValuePage = {
-    values: Uint8Array[];
-    resumeAfter?: Uint8Array | null;
-};
-export type BackendKvEntryPage = {
-    keys: Uint8Array[];
-    values: Uint8Array[];
-    resumeAfter?: Uint8Array | null;
-};
-export type BackendKvWriteOp = {
-    kind: "put";
-    key: Uint8Array;
-    value: Uint8Array;
-} | {
-    kind: "delete";
-    key: Uint8Array;
-} | {
-    kind: "deleteRange";
-    range: BackendKvScanRange;
-};
-export type BackendKvWriteBatch = {
-    groups: BackendKvWriteGroup[];
-};
-export type BackendKvWriteGroup = {
-    namespace: string;
-    ops: BackendKvWriteOp[];
-};
-export type BackendKvWriteStats = {
-    puts: number;
-    deletes: number;
-    deleteRanges: number;
-    bytesWritten: number;
-};
-export type LixBackendReadTransaction = {
-    getValues(request: BackendKvGetRequest): BackendKvValueBatch;
-    existsMany(request: BackendKvGetRequest): BackendKvExistsBatch;
-    scanKeys(request: BackendKvScanRequest): BackendKvKeyPage;
-    scanValues(request: BackendKvScanRequest): BackendKvValuePage;
-    scanEntries(request: BackendKvScanRequest): BackendKvEntryPage;
-    rollback(): void;
-};
-export type LixBackendWriteTransaction = LixBackendReadTransaction & {
-    writeKvBatch(batch: BackendKvWriteBatch): BackendKvWriteStats;
+import { wrapExecuteResult } from "./result.js";
+import { toNativeValue } from "./value.js";
+import type { CreateBranchOptions, CreateBranchReceipt, ExecuteResult, MergeBranchOptions, MergeBranchPreview, MergeBranchReceipt, OpenLixOptions, SqlParam, SqliteBackendOptions, SwitchBranchOptions, SwitchBranchReceipt } from "./types.js";
+type NativeExecuteResult = Parameters<typeof wrapExecuteResult>[0];
+type NativeParam = ReturnType<typeof toNativeValue>;
+type NativeLix = {
+    execute(sql: string, params: NativeParam[]): NativeExecuteResult;
+    beginTransaction(): NativeLixTransaction;
+    activeBranchId(): string;
+    createBranch(options: CreateBranchOptions): CreateBranchReceipt;
+    switchBranch(options: SwitchBranchOptions): SwitchBranchReceipt;
+    mergeBranchPreview(options: MergeBranchOptions): MergeBranchPreview;
+    mergeBranch(options: MergeBranchOptions): MergeBranchReceipt;
+    close(): void;
+};
+type NativeLixTransaction = {
+    execute(sql: string, params: NativeParam[]): NativeExecuteResult;
     commit(): void;
+    rollback(): void;
 };
-export type LixBackend = {
-    beginReadTransaction(): LixBackendReadTransaction;
-    beginWriteTransaction(): LixBackendWriteTransaction;
-    close?(): void;
-};
-export type OpenLixOptions = {
-    backend?: LixBackend;
-};
-export type CreateBranchOptions = {
-    id?: string;
-    name: string;
-    fromCommitId?: string;
-};
-export type CreateBranchResult = {
-    id: string;
-    name: string;
-    hidden: boolean;
-    commitId: string;
-};
-export type SwitchBranchOptions = {
-    branchId: string;
-};
-export type SwitchBranchResult = {
-    branchId: string;
-};
-export type MergeBranchOptions = {
-    sourceBranchId: string;
-};
-export type MergeBranchOutcome = "alreadyUpToDate" | "fastForward" | "mergeCommitted";
-export type MergeBranchResult = {
-    /**
-     * How the merge was applied. `fastForward` advances the target ref without
-     * creating a merge commit, but can still make source changes visible.
-     */
-    outcome: MergeBranchOutcome;
-    targetBranchId: string;
-    sourceBranchId: string;
-    baseCommitId: string;
-    targetHeadBeforeCommitId: string;
-    sourceHeadBeforeCommitId: string;
-    targetHeadAfterCommitId: string;
-    createdMergeCommitId: string | null;
-    changeStats: MergeChangeStats;
-};
-export type MergeBranchPreviewResult = {
-    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: string[];
-    fileId: string | null;
-    target: MergeConflictSide;
-    source: MergeConflictSide;
-};
-export type MergeConflictSide = {
-    kind: "added" | "modified" | "removed";
-    beforeChangeId: string | null;
-    afterChangeId: string | null;
-};
-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 `?` or `$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. While a
-     * transaction is active, call `execute()` on the transaction handle instead.
-     */
-    execute(sql: string, params?: ReadonlyArray<LixRuntimeValue>): Promise<ExecuteResult>;
+export declare class SqliteBackend {
+    readonly path: string;
+    constructor(options: SqliteBackendOptions);
+}
+export declare function openLix(options?: OpenLixOptions): Promise<Lix>;
+export declare class Lix {
+    private readonly native;
+    constructor(native: NativeLix);
+    execute(sql: string, params?: SqlParam[]): Promise<ExecuteResult>;
     beginTransaction(): Promise<LixTransaction>;
     activeBranchId(): Promise<string>;
-    createBranch(options: CreateBranchOptions): Promise<CreateBranchResult>;
-    switchBranch(options: SwitchBranchOptions): Promise<SwitchBranchResult>;
-    mergeBranchPreview(options: MergeBranchOptions): Promise<MergeBranchPreviewResult>;
-    mergeBranch(options: MergeBranchOptions): Promise<MergeBranchResult>;
+    createBranch(options: CreateBranchOptions): Promise<CreateBranchReceipt>;
+    switchBranch(options: SwitchBranchOptions): Promise<SwitchBranchReceipt>;
+    mergeBranchPreview(options: MergeBranchOptions): Promise<MergeBranchPreview>;
+    mergeBranch(options: MergeBranchOptions): Promise<MergeBranchReceipt>;
     close(): Promise<void>;
-};
-export type LixTransaction = {
-    execute(sql: string, params?: ReadonlyArray<LixRuntimeValue>): Promise<ExecuteResult>;
+}
+export declare class LixTransaction {
+    private readonly native;
+    constructor(native: NativeLixTransaction);
+    execute(sql: string, params?: SqlParam[]): Promise<ExecuteResult>;
     commit(): Promise<void>;
     rollback(): Promise<void>;
-};
-export declare function openLix(options?: OpenLixOptions): Promise<Lix>;
+}
+export {};