@lix-js/sdk 0.8.1 → 0.8.3

package/README.md

@@ -11,7 +11,7 @@ npm install @lix-js/sdk
 
 ## Usage
 
-The default in-memory backend works in browsers and Node.js:
+The default in-memory storage works in browsers and Node.js:
 
 ```ts
 import { openLix } from "@lix-js/sdk";
@@ -22,13 +22,13 @@ console.log(result.rows[0]?.get("message"));
 await lix.close();
 ```
 
-Filesystem and SQLite backends use native Node.js dependencies:
+Filesystem sync and SQLite persistence use native Node.js dependencies:
 
 ```ts
-import { FsBackend, openLix } from "@lix-js/sdk";
+import { LocalFilesystem, openLix } from "@lix-js/sdk";
 
 const lix = await openLix({
-	backend: new FsBackend({
+	storage: new LocalFilesystem({
 		path: "./workspace",
 		syncAllFiles: true,
 	}),
@@ -89,19 +89,19 @@ try {
 
 ## Notes
 
-- `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.
+- `openLix()` opens a fresh in-memory Lix. Pass `new LocalFilesystem({ path, syncAllFiles: true })` for a filesystem workspace directory backed by `<path>/.lix/.internal/rocksdb`.
+- Pass `new LocalFilesystem({ 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 `storage.importPaths(["notes/today.md"])` on the `LocalFilesystem` instance to sync selected files. Imported paths are exact workspace-relative file paths, not directories or globs.
+- Use `new SQLite({ 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
+  in-memory storage.
+- `LocalFilesystem` and `SQLite` 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 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
+- Every `openLix()` owns one dedicated worker. The engine, storage, 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

package/dist/binding-types.d.ts

@@ -39,13 +39,13 @@ export type ObserveEventsBinding = {
     close(): void;
 };
 export type PluginRuntimeDispatch = (request: unknown) => Promise<unknown>;
-export type LixBackendConfig = {
+export type LixStorageConfig = {
     kind: "memory";
 } | {
     kind: "sqlite";
     path: string;
 } | {
-    kind: "fs";
+    kind: "localFilesystem";
     path: string;
     lixDir?: string;
     syncAllFiles: boolean;

package/dist/binding.browser.d.ts

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

package/dist/binding.browser.js

@@ -5,9 +5,9 @@ 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`);
+export async function openLixBinding(storage, dispatch) {
+    if (storage.kind !== "memory") {
+        throw new Error(`${storage.kind === "localFilesystem" ? "LocalFilesystem" : "SQLite"} is only available in Node.js`);
     }
     await initializeWasm();
     return openMemory(dispatch);

package/dist/binding.node.d.ts

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

package/dist/binding.node.js

@@ -39,13 +39,13 @@ catch (cause) {
     error.cause = cause;
     throw error;
 }
-export function openLixBinding(backend, dispatch) {
-    switch (backend.kind) {
+export function openLixBinding(storage, dispatch) {
+    switch (storage.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);
+            return addon.Lix.openSQLite(storage.path, dispatch);
+        case "localFilesystem":
+            return addon.Lix.openLocalFilesystem(storage.path, storage.lixDir, storage.syncAllFiles, dispatch);
     }
 }

package/dist/errors.d.ts

@@ -5,5 +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;
+export declare function localFilesystemNotOpen(operation: string): LixJsError;
+export declare function localFilesystemAlreadyOpen(): LixJsError;

package/dist/errors.js

@@ -17,16 +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`);
+export function localFilesystemNotOpen(operation) {
+    const error = new Error(`LocalFilesystem.${operation}() requires the storage to be opened with openLix() first`);
     error.name = "LixError";
-    error.code = "LIX_FS_BACKEND_NOT_OPEN";
+    error.code = "LIX_LOCAL_FILESYSTEM_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");
+export function localFilesystemAlreadyOpen() {
+    const error = new Error("openLix() LocalFilesystem is already open; close the existing Lix or create a new LocalFilesystem");
     error.name = "LixError";
-    error.code = "LIX_FS_BACKEND_IN_USE";
+    error.code = "LIX_LOCAL_FILESYSTEM_IN_USE";
     return error;
 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { FsBackend, Lix, LixTransaction, ObserveEvents, openLix, SqliteBackend, } from "./open-lix.js";
+export { LocalFilesystem, Lix, LixTransaction, ObserveEvents, openLix, SQLite, } from "./open-lix.js";
 export { bundledPluginArchives, type BundledPluginArchive, } from "./bundled-plugins.js";
 export { Row } from "./result.js";
 export { Value } from "./value.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";
+export type { CreateBranchOptions, CreateBranchReceipt, ExecuteOptions, ExecuteResult, LocalFilesystemOptions, JsonValue, LixValue, MergeBranchOptions, MergeBranchOutcome, MergeBranchPreview, MergeBranchReceipt, MergeChangeStats, MergeConflict, MergeConflictSide, ObserveEvent, OpenLixOptions, SqlParam, SQLiteOptions, SwitchBranchOptions, SwitchBranchReceipt, } from "./types.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export { FsBackend, Lix, LixTransaction, ObserveEvents, openLix, SqliteBackend, } from "./open-lix.js";
+export { LocalFilesystem, Lix, LixTransaction, ObserveEvents, openLix, SQLite, } from "./open-lix.js";
 export { bundledPluginArchives, } from "./bundled-plugins.js";
 export { Row } from "./result.js";
 export { Value } from "./value.js";

package/dist/open-lix.d.ts

@@ -1,14 +1,14 @@
 import { LixWorkerClient } from "./worker/client.js";
-import type { CreateBranchOptions, CreateBranchReceipt, ExecuteOptions, ExecuteResult, FsBackendOptions, MergeBranchOptions, MergeBranchPreview, MergeBranchReceipt, ObserveEvent, OpenLixOptions, SqlParam, SqliteBackendOptions, SwitchBranchOptions, SwitchBranchReceipt } from "./types.js";
-export declare class SqliteBackend {
+import type { CreateBranchOptions, CreateBranchReceipt, ExecuteOptions, ExecuteResult, LocalFilesystemOptions, MergeBranchOptions, MergeBranchPreview, MergeBranchReceipt, ObserveEvent, OpenLixOptions, SqlParam, SQLiteOptions, SwitchBranchOptions, SwitchBranchReceipt } from "./types.js";
+export declare class SQLite {
     readonly path: string;
-    constructor(options: SqliteBackendOptions);
+    constructor(options: SQLiteOptions);
 }
-export declare class FsBackend {
+export declare class LocalFilesystem {
     readonly path: string;
     readonly lixDir: string | undefined;
     readonly syncAllFiles: boolean;
-    constructor(options: FsBackendOptions);
+    constructor(options: LocalFilesystemOptions);
     importPaths(paths: readonly string[]): Promise<void>;
     syncDiskToLix(): Promise<void>;
     private client;

package/dist/open-lix.js

@@ -1,4 +1,4 @@
-import { fsBackendAlreadyOpen, fsBackendNotOpen, invalidArgument, } from "./errors.js";
+import { localFilesystemAlreadyOpen, localFilesystemNotOpen, invalidArgument, } from "./errors.js";
 import { normalizeOptionals, wrapExecuteResult } from "./result.js";
 import { normalizeParam, toNativeValue } from "./value.js";
 import { openLixWorker } from "./worker/client.js";
@@ -11,19 +11,19 @@ const observeFinalizer = new FinalizationRegistry(({ client, observeId }) => {
             client.notify({ kind: "observe.close", observeId: id });
     });
 });
-export class SqliteBackend {
+export class SQLite {
     path;
     constructor(options) {
         if (!options ||
             typeof options.path !== "string" ||
             options.path.length === 0) {
-            throw new TypeError("SqliteBackend requires a non-empty path");
+            throw new TypeError("SQLite requires a non-empty path");
         }
         this.path = options.path;
     }
 }
-const openFsBackends = new WeakMap();
-export class FsBackend {
+const openLocalFilesystems = new WeakMap();
+export class LocalFilesystem {
     path;
     lixDir;
     syncAllFiles;
@@ -31,14 +31,14 @@ export class FsBackend {
         if (!options ||
             typeof options.path !== "string" ||
             options.path.length === 0) {
-            throw new TypeError("FsBackend requires a non-empty path");
+            throw new TypeError("LocalFilesystem requires a non-empty path");
         }
         if (options.lixDir !== undefined &&
             (typeof options.lixDir !== "string" || options.lixDir.length === 0)) {
-            throw new TypeError("FsBackend lixDir must be a non-empty string");
+            throw new TypeError("LocalFilesystem lixDir must be a non-empty string");
         }
         if (typeof options.syncAllFiles !== "boolean") {
-            throw new TypeError("FsBackend syncAllFiles must be a boolean");
+            throw new TypeError("LocalFilesystem syncAllFiles must be a boolean");
         }
         this.path = options.path;
         this.lixDir = options.lixDir;
@@ -65,9 +65,9 @@ export class FsBackend {
         return this.client("syncDiskToLix").request({ kind: "syncDiskToLix" });
     }
     client(operation) {
-        const client = openFsBackends.get(this);
+        const client = openLocalFilesystems.get(this);
         if (!client) {
-            throw fsBackendNotOpen(operation);
+            throw localFilesystemNotOpen(operation);
         }
         return client;
     }
@@ -76,34 +76,37 @@ export async function openLix(options = {}) {
     if (!options || typeof options !== "object") {
         throw new TypeError("openLix() options must be an object");
     }
-    if (options.backend === undefined) {
+    if ("backend" in options) {
+        throw new TypeError("openLix() option 'backend' was removed; use 'storage' instead");
+    }
+    if (options.storage === undefined) {
         return new Lix(await openLixWorker({ kind: "memory" }));
     }
-    if (options.backend instanceof SqliteBackend) {
-        return new Lix(await openLixWorker({ kind: "sqlite", path: options.backend.path }));
+    if (options.storage instanceof SQLite) {
+        return new Lix(await openLixWorker({ kind: "sqlite", path: options.storage.path }));
     }
-    if (options.backend instanceof FsBackend) {
-        const backend = options.backend;
-        if (openFsBackends.has(backend)) {
-            throw fsBackendAlreadyOpen();
+    if (options.storage instanceof LocalFilesystem) {
+        const storage = options.storage;
+        if (openLocalFilesystems.has(storage)) {
+            throw localFilesystemAlreadyOpen();
         }
-        openFsBackends.set(backend, null);
+        openLocalFilesystems.set(storage, null);
         try {
             const client = await openLixWorker({
-                kind: "fs",
-                path: backend.path,
-                lixDir: backend.lixDir,
-                syncAllFiles: backend.syncAllFiles,
-            }, () => openFsBackends.delete(backend));
-            openFsBackends.set(backend, client);
+                kind: "localFilesystem",
+                path: storage.path,
+                lixDir: storage.lixDir,
+                syncAllFiles: storage.syncAllFiles,
+            }, () => openLocalFilesystems.delete(storage));
+            openLocalFilesystems.set(storage, client);
             return new Lix(client);
         }
         catch (error) {
-            openFsBackends.delete(backend);
+            openLocalFilesystems.delete(storage);
             throw error;
         }
     }
-    throw new TypeError("openLix() requires backend to be SqliteBackend or FsBackend");
+    throw new TypeError("openLix() requires storage to be SQLite or LocalFilesystem");
 }
 export class Lix {
     client;

package/dist/types.d.ts

@@ -1,13 +1,13 @@
-export type SqliteBackendOptions = {
+export type SQLiteOptions = {
     path: string;
 };
-export type FsBackendOptions = {
+export type LocalFilesystemOptions = {
     path: string;
     lixDir?: string;
     syncAllFiles: boolean;
 };
 export type OpenLixOptions = {
-    backend?: import("./open-lix.js").SqliteBackend | import("./open-lix.js").FsBackend;
+    storage?: import("./open-lix.js").SQLite | import("./open-lix.js").LocalFilesystem;
 };
 export type LixValue = {
     kind: "null";

package/dist/worker/client.d.ts

@@ -1,6 +1,6 @@
-import type { LixBackendConfig } from "../binding-types.js";
+import type { LixStorageConfig } from "../binding-types.js";
 import { type WorkerConnection, type WorkerNotification, type WorkerOperation } from "./protocol.js";
-export declare function openLixWorker(backend: LixBackendConfig, onDisposed?: () => void): Promise<LixWorkerClient>;
+export declare function openLixWorker(storage: LixStorageConfig, onDisposed?: () => void): Promise<LixWorkerClient>;
 export declare class LixWorkerClient {
     private readonly onDisposed?;
     private readonly connection;

package/dist/worker/client.js

@@ -1,9 +1,9 @@
 import { createWorkerConnection } from "#worker-factory";
 import { deserializeWorkerError, } from "./protocol.js";
-export async function openLixWorker(backend, onDisposed) {
+export async function openLixWorker(storage, onDisposed) {
     const client = new LixWorkerClient(onDisposed);
     try {
-        await client.request({ kind: "open", backend });
+        await client.request({ kind: "open", storage });
         return client;
     }
     catch (error) {

package/dist/worker/host.js

@@ -58,7 +58,7 @@ export function startWorkerHost(endpoint) {
             case "open":
                 if (lix)
                     throw workerStateError("Lix worker is already open");
-                lix = await openLixBinding(operation.backend, createPluginRuntimeDispatch());
+                lix = await openLixBinding(operation.storage, createPluginRuntimeDispatch());
                 return undefined;
             case "execute":
                 return requiredLix().execute(operation.sql, operation.params, operation.options);

package/dist/worker/protocol.d.ts

@@ -1,4 +1,4 @@
-import type { BindingParam, LixBackendConfig } from "../binding-types.js";
+import type { BindingParam, LixStorageConfig } from "../binding-types.js";
 import type { CreateBranchOptions, ExecuteOptions, MergeBranchOptions, SwitchBranchOptions } from "../types.js";
 export type WorkerRequest = {
     id: number;
@@ -6,7 +6,7 @@ export type WorkerRequest = {
 };
 export type WorkerOperation = {
     kind: "open";
-    backend: LixBackendConfig;
+    storage: LixStorageConfig;
 } | {
     kind: "execute";
     sql: string;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@lix-js/sdk",
 	"type": "module",
-	"version": "0.8.1",
+	"version": "0.8.3",
 	"license": "MIT",
 	"repository": {
 		"type": "git",
@@ -53,10 +53,10 @@
 		"typecheck": "tsc -p tsconfig.test.json --noEmit"
 	},
 	"optionalDependencies": {
-		"@lix-js/sdk-darwin-arm64": "0.8.1",
-		"@lix-js/sdk-linux-arm64": "0.8.1",
-		"@lix-js/sdk-linux-x64": "0.8.1",
-		"@lix-js/sdk-win32-x64": "0.8.1"
+		"@lix-js/sdk-darwin-arm64": "0.8.3",
+		"@lix-js/sdk-linux-arm64": "0.8.3",
+		"@lix-js/sdk-linux-x64": "0.8.3",
+		"@lix-js/sdk-win32-x64": "0.8.3"
 	},
 	"devDependencies": {
 		"@vitest/browser-playwright": "4.0.18",