@lix-js/sdk 0.7.0 → 0.8.0

package/README.md

@@ -1,6 +1,7 @@
 # @lix-js/sdk
 
-JavaScript SDK for Lix, backed by the native Rust SDK.
+JavaScript SDK for Lix. It uses the native Rust addon in Node.js and the same
+Rust SDK compiled to WebAssembly in browsers.
 
 ## Install
 
@@ -10,20 +11,36 @@ npm install @lix-js/sdk
 
 ## Usage
 
+The default in-memory backend works in browsers and Node.js:
+
+```ts
+import { openLix } from "@lix-js/sdk";
+
+const lix = await openLix();
+const result = await lix.execute("SELECT $1 AS message", ["hello"]);
+console.log(result.rows[0]?.get("message"));
+await lix.close();
+```
+
+Filesystem and SQLite backends use native Node.js dependencies:
+
 ```ts
-import { openLix, SqliteBackend } from "@lix-js/sdk";
+import { FsBackend, openLix } from "@lix-js/sdk";
 
 const lix = await openLix({
-  backend: new SqliteBackend({ path: "app.lix" }),
+	backend: new FsBackend({
+		path: "./workspace",
+		syncAllFiles: true,
+	}),
 });
 
 await lix.execute(
-  "INSERT INTO lix_file (path, data) VALUES ($1, $2) ON CONFLICT (path) DO UPDATE SET data = excluded.data",
-  ["/hello.txt", new TextEncoder().encode("world")],
+	"INSERT INTO lix_file (path, data) VALUES ($1, $2) ON CONFLICT (path) DO UPDATE SET data = excluded.data",
+	["/hello.txt", new TextEncoder().encode("world")],
 );
 
 const result = await lix.execute("SELECT data FROM lix_file WHERE path = $1", [
-  "/hello.txt",
+	"/hello.txt",
 ]);
 const bytes = result.rows[0]?.value("data").asBytes();
 
@@ -40,8 +57,8 @@ const draft = await lix.createBranch({ name: "Draft" });
 
 await lix.switchBranch({ branchId: draft.id });
 await lix.execute(
-  "INSERT INTO lix_file (path, data) VALUES ($1, $2) ON CONFLICT (path) DO UPDATE SET data = excluded.data",
-  ["/status.txt", new TextEncoder().encode("draft")],
+	"INSERT INTO lix_file (path, data) VALUES ($1, $2) ON CONFLICT (path) DO UPDATE SET data = excluded.data",
+	["/status.txt", new TextEncoder().encode("draft")],
 );
 
 await lix.switchBranch({ branchId: main });
@@ -55,26 +72,77 @@ const merge = await lix.mergeBranch({ sourceBranchId: draft.id });
 const tx = await lix.beginTransaction();
 
 try {
-  await tx.execute(
-    "INSERT INTO lix_file (path, data) VALUES ($1, $2) ON CONFLICT (path) DO UPDATE SET data = excluded.data",
-    ["/a.txt", new TextEncoder().encode("1")],
-  );
-  await tx.execute(
-    "INSERT INTO lix_file (path, data) VALUES ($1, $2) ON CONFLICT (path) DO UPDATE SET data = excluded.data",
-    ["/b.txt", new TextEncoder().encode("2")],
-  );
-  await tx.commit();
+	await tx.execute(
+		"INSERT INTO lix_file (path, data) VALUES ($1, $2) ON CONFLICT (path) DO UPDATE SET data = excluded.data",
+		["/a.txt", new TextEncoder().encode("1")],
+	);
+	await tx.execute(
+		"INSERT INTO lix_file (path, data) VALUES ($1, $2) ON CONFLICT (path) DO UPDATE SET data = excluded.data",
+		["/b.txt", new TextEncoder().encode("2")],
+	);
+	await tx.commit();
 } catch (error) {
-  await tx.rollback();
-  throw error;
+	await tx.rollback();
+	throw error;
 }
 ```
 
 ## Notes
 
-- `openLix()` opens a fresh in-memory Lix. Pass `new SqliteBackend({ path })` for a raw SQLite `.lix` file, or `new FsBackend({ path })` for a filesystem workspace directory backed by `<path>/.lix/.internal/db.sqlite`.
-- The SDK is Node/native only right now; it is not browser-compatible.
+- `openLix()` opens a fresh in-memory Lix. Pass `new FsBackend({ path, syncAllFiles: true })` for a filesystem workspace directory backed by `<path>/.lix/.internal/rocksdb`.
+- Pass `new FsBackend({ path, lixDir, syncAllFiles: true })` for filesystem sync with repository metadata in an external `.lix` directory and no workspace `.lix` directory.
+- Pass `syncAllFiles: false` to start filesystem sync with no regular workspace files, then call `backend.importPaths(["notes/today.md"])` on the `FsBackend` instance to sync selected files. Imported paths are exact workspace-relative file paths, not directories or globs.
+- Use `new SqliteBackend({ path })` when a single SQLite-backed `.lix` file is the application document itself, for example when defining a new file format and using Lix as the application's file format.
+- In browsers, `openLix()` loads the Rust engine as WebAssembly and uses the
+  in-memory backend.
+- `FsBackend` and `SqliteBackend` are Node.js-only. Constructing them is safe in
+  shared code, but passing one to `openLix()` in a browser throws an error.
 - The package is ESM-only.
-- The native addon is built from Rust and loaded by the TypeScript wrapper.
+- The package uses conditional ESM imports internally: Node.js resolves the
+  native N-API binding, while browsers and other runtimes resolve the portable
+  WebAssembly binding. Vite follows this split without consumer configuration.
+- Every `openLix()` owns one dedicated worker. The engine, storage backend, and
+  installed WASM plugin components all run in that worker in both Node.js and
+  browsers, so database and plugin work does not block the page's main thread.
+- Installed WASM plugin components are transpiled with JCO and executed by the
+  worker's WebAssembly runtime in both environments. Plugin execution does not
+  yet enforce the declared fuel, timeout, or memory limits, so only install
+  trusted plugins.
+- A page Content Security Policy only needs to permit the package's same-origin
+  worker. WebAssembly compilation and JCO's generated `data:` module imports
+  happen inside that worker, so they can be scoped to the worker script's HTTP
+  response instead of being allowed by the document:
+
+  ```http
+  # HTML document response
+  Content-Security-Policy: default-src 'self'; script-src 'self'; worker-src 'self'
+
+  # Lix worker response (Vite emits assets/entry.browser-<hash>.js)
+  Content-Security-Policy: default-src 'none'; script-src 'self' data: 'wasm-unsafe-eval'; connect-src 'self'
+  ```
+
+  Hosts that apply one policy to every response can use
+  `script-src 'self' data: 'wasm-unsafe-eval'; worker-src 'self'` globally
+  instead. Worker-scoped headers keep those permissions out of the page.
 - 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.
+
+## Browser development
+
+The browser suite runs the published package shape in a real headless Chromium
+page through Vite/Vitest Browser Mode:
+
+```bash
+rustup target add wasm32-unknown-unknown
+cargo install wasm-bindgen-cli --version 0.2.122 --locked
+npx playwright install chromium
+npm run test:browser
+```
+
+`npm run test:browser:production` additionally packs the SDK, installs the
+tarball into a minimal Vite app, makes a production build, and exercises SQL
+plus both bundled plugins in Chromium. It runs with both worker-scoped and
+global strict CSP headers.
+
+Use `npm run build:wasm:dev` while iterating on the Rust bridge when release
+optimization is unnecessary.

package/dist/binding-types.d.ts

@@ -0,0 +1,52 @@
+import type { CreateBranchOptions, CreateBranchReceipt, ExecuteOptions, MergeBranchOptions, MergeBranchPreview, MergeBranchReceipt, SwitchBranchOptions, SwitchBranchReceipt } from "./types.js";
+import type { NativeLixValue } from "./value.js";
+export type BindingExecuteResult = {
+    columns: string[];
+    rows: NativeLixValue[][];
+    rowsAffected: number;
+    notices: Array<{
+        code: string;
+        message: string;
+        hint?: string;
+    }>;
+};
+export type BindingObserveEvent = {
+    sequence: number;
+    mutationSequence: number;
+    rows: BindingExecuteResult;
+};
+export type BindingParam = NativeLixValue;
+export type LixBinding = {
+    execute(sql: string, params: BindingParam[], options?: ExecuteOptions): Promise<BindingExecuteResult>;
+    observe(sql: string, params: BindingParam[]): Promise<ObserveEventsBinding>;
+    beginTransaction(): Promise<LixTransactionBinding>;
+    activeBranchId(): Promise<string>;
+    createBranch(options: CreateBranchOptions): Promise<CreateBranchReceipt>;
+    switchBranch(options: SwitchBranchOptions): Promise<SwitchBranchReceipt>;
+    importFilesystemPaths(paths: string[]): Promise<void>;
+    mergeBranchPreview(options: MergeBranchOptions): Promise<MergeBranchPreview>;
+    mergeBranch(options: MergeBranchOptions): Promise<MergeBranchReceipt>;
+    syncDiskToLix(): Promise<void>;
+    close(): Promise<void>;
+};
+export type LixTransactionBinding = {
+    execute(sql: string, params: BindingParam[], options?: ExecuteOptions): Promise<BindingExecuteResult>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+};
+export type ObserveEventsBinding = {
+    next(): Promise<BindingObserveEvent | null | undefined>;
+    close(): void;
+};
+export type PluginRuntimeDispatch = (request: unknown) => Promise<unknown>;
+export type LixBackendConfig = {
+    kind: "memory";
+} | {
+    kind: "sqlite";
+    path: string;
+} | {
+    kind: "fs";
+    path: string;
+    lixDir?: string;
+    syncAllFiles: boolean;
+};

package/dist/binding-types.js

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

package/dist/binding.browser.d.ts

@@ -0,0 +1,2 @@
+import type { LixBackendConfig, LixBinding, PluginRuntimeDispatch } from "./binding-types.js";
+export declare function openLixBinding(backend: LixBackendConfig, dispatch: PluginRuntimeDispatch): Promise<LixBinding>;

package/dist/binding.browser.js

@@ -0,0 +1,14 @@
+// Generated before TypeScript compilation and emitted beside this module.
+// @ts-expect-error Generated by build:wasm.
+import initWasm, { openMemory } from "./wasm/lix_js_sdk.js";
+let wasmInitialized;
+function initializeWasm() {
+    return (wasmInitialized ??= initWasm());
+}
+export async function openLixBinding(backend, dispatch) {
+    if (backend.kind !== "memory") {
+        throw new Error(`${backend.kind === "fs" ? "FsBackend" : "SqliteBackend"} is only available in Node.js`);
+    }
+    await initializeWasm();
+    return openMemory(dispatch);
+}

package/dist/binding.node.d.ts

@@ -0,0 +1,2 @@
+import type { LixBackendConfig, LixBinding, PluginRuntimeDispatch } from "./binding-types.js";
+export declare function openLixBinding(backend: LixBackendConfig, dispatch: PluginRuntimeDispatch): Promise<LixBinding>;

package/dist/{native.js → binding.node.js}

@@ -9,15 +9,11 @@ const nativePackages = {
     "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)) {
+    if (existsSync(localNativePath))
         return localNativePath;
-    }
-    const packageName = nativePackageName();
+    const key = `${process.platform}-${process.arch}`;
+    const packageName = nativePackages[key];
     let packageResolutionError;
     if (packageName) {
         try {
@@ -32,10 +28,9 @@ function resolveNativePath() {
     }
     throw packageResolutionError;
 }
-const native = { exports: {} };
+let addon;
 try {
-    const nativePath = resolveNativePath();
-    process.dlopen(native, nativePath);
+    addon = require(resolveNativePath());
 }
 catch (cause) {
     const error = new Error(`Failed to load @lix-js/sdk native addon for ${process.platform}-${process.arch}. ` +
@@ -44,4 +39,13 @@ catch (cause) {
     error.cause = cause;
     throw error;
 }
-export const addon = native.exports;
+export function openLixBinding(backend, dispatch) {
+    switch (backend.kind) {
+        case "memory":
+            return addon.Lix.openMemory(dispatch);
+        case "sqlite":
+            return addon.Lix.openSqlite(backend.path, dispatch);
+        case "fs":
+            return addon.Lix.openFs(backend.path, backend.lixDir, backend.syncAllFiles, dispatch);
+    }
+}

package/dist/bundled-plugins.js

@@ -1,4 +1,3 @@
-import { readFile } from "node:fs/promises";
 const BUNDLED_PLUGIN_MANIFEST = [
     {
         key: "plugin_md_v2",
@@ -23,11 +22,20 @@ async function readBundledArchive(fileName) {
     ];
     for (const url of urls) {
         try {
+            if (url.protocol !== "file:") {
+                const response = await fetch(url);
+                if (response.ok) {
+                    return new Uint8Array(await response.arrayBuffer());
+                }
+                continue;
+            }
+            const moduleName = "node:fs/promises";
+            const { readFile } = await import(/* @vite-ignore */ moduleName);
             return new Uint8Array(await readFile(url));
         }
         catch {
             // Try the next build/source layout.
         }
     }
-    return new Uint8Array(await readFile(urls[0]));
+    throw new Error(`Could not load bundled plugin archive ${fileName}`);
 }

package/dist/errors.d.ts

@@ -5,3 +5,5 @@ export type LixJsError = Error & {
 };
 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;
+export declare function fsBackendNotOpen(operation: string): LixJsError;
+export declare function fsBackendAlreadyOpen(): LixJsError;

package/dist/errors.js

@@ -17,3 +17,16 @@ export function invalidParam(index, message, actual) {
     };
     return error;
 }
+export function fsBackendNotOpen(operation) {
+    const error = new Error(`FsBackend.${operation}() requires the backend to be opened with openLix() first`);
+    error.name = "LixError";
+    error.code = "LIX_FS_BACKEND_NOT_OPEN";
+    error.details = { operation };
+    return error;
+}
+export function fsBackendAlreadyOpen() {
+    const error = new Error("openLix() FsBackend is already open; close the existing Lix or create a new FsBackend");
+    error.name = "LixError";
+    error.code = "LIX_FS_BACKEND_IN_USE";
+    return error;
+}

package/dist/index.d.ts

@@ -2,4 +2,4 @@ export { FsBackend, Lix, LixTransaction, ObserveEvents, openLix, SqliteBackend,
 export { bundledPluginArchives, type BundledPluginArchive, } from "./bundled-plugins.js";
 export { Row } from "./result.js";
 export { Value } from "./value.js";
-export type { CreateBranchOptions, CreateBranchReceipt, ExecuteResult, FsBackendOptions, JsonValue, LixValue, MergeBranchOptions, MergeBranchOutcome, MergeBranchPreview, MergeBranchReceipt, MergeChangeStats, MergeConflict, MergeConflictSide, ObserveEvent, OpenLixOptions, SqlParam, SqliteBackendOptions, SwitchBranchOptions, SwitchBranchReceipt, } from "./types.js";
+export type { CreateBranchOptions, CreateBranchReceipt, ExecuteOptions, ExecuteResult, FsBackendOptions, JsonValue, LixValue, MergeBranchOptions, MergeBranchOutcome, MergeBranchPreview, MergeBranchReceipt, MergeChangeStats, MergeConflict, MergeConflictSide, ObserveEvent, OpenLixOptions, SqlParam, SqliteBackendOptions, SwitchBranchOptions, SwitchBranchReceipt, } from "./types.js";