@lix-js/sdk 0.6.2 → 0.7.0

package/README.md

@@ -17,9 +17,15 @@ const lix = await openLix({
   backend: new SqliteBackend({ path: "app.lix" }),
 });
 
-await lix.fs.writeFile("/hello.txt", new TextEncoder().encode("world"));
+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")],
+);
 
-const bytes = await lix.fs.readFile("/hello.txt");
+const result = await lix.execute("SELECT data FROM lix_file WHERE path = $1", [
+  "/hello.txt",
+]);
+const bytes = result.rows[0]?.value("data").asBytes();
 
 console.log(bytes && new TextDecoder().decode(bytes));
 
@@ -33,7 +39,10 @@ const main = await lix.activeBranchId();
 const draft = await lix.createBranch({ name: "Draft" });
 
 await lix.switchBranch({ branchId: draft.id });
-await lix.fs.writeFile("/status.txt", new TextEncoder().encode("draft"));
+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")],
+);
 
 await lix.switchBranch({ branchId: main });
 const preview = await lix.mergeBranchPreview({ sourceBranchId: draft.id });
@@ -46,8 +55,14 @@ const merge = await lix.mergeBranch({ sourceBranchId: draft.id });
 const tx = await lix.beginTransaction();
 
 try {
-  await tx.fs.writeFile("/a.txt", new TextEncoder().encode("1"));
-  await tx.fs.writeFile("/b.txt", new TextEncoder().encode("2"));
+  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();
@@ -57,7 +72,7 @@ try {
 
 ## Notes
 
-- `openLix()` opens a fresh in-memory Lix. Pass `new SqliteBackend({ path })` to persist to disk.
+- `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.
 - The package is ESM-only.
 - The native addon is built from Rust and loaded by the TypeScript wrapper.

package/dist/bundled-plugins.d.ts

@@ -0,0 +1,6 @@
+export type BundledPluginArchive = {
+    key: string;
+    fileName: string;
+    archiveBytes: Uint8Array;
+};
+export declare function bundledPluginArchives(): Promise<BundledPluginArchive[]>;

package/dist/bundled-plugins.js

@@ -0,0 +1,33 @@
+import { readFile } from "node:fs/promises";
+const BUNDLED_PLUGIN_MANIFEST = [
+    {
+        key: "plugin_md_v2",
+        fileName: "plugin_md_v2.lixplugin",
+    },
+    {
+        key: "plugin_csv",
+        fileName: "plugin_csv.lixplugin",
+    },
+];
+export async function bundledPluginArchives() {
+    return await Promise.all(BUNDLED_PLUGIN_MANIFEST.map(async (plugin) => ({
+        key: plugin.key,
+        fileName: plugin.fileName,
+        archiveBytes: await readBundledArchive(plugin.fileName),
+    })));
+}
+async function readBundledArchive(fileName) {
+    const urls = [
+        new URL(`./bundled-plugins/${fileName}`, import.meta.url),
+        new URL(`../dist/bundled-plugins/${fileName}`, import.meta.url),
+    ];
+    for (const url of urls) {
+        try {
+            return new Uint8Array(await readFile(url));
+        }
+        catch {
+            // Try the next build/source layout.
+        }
+    }
+    return new Uint8Array(await readFile(urls[0]));
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,3 +1,4 @@
-export { Lix, LixTransaction, openLix, SqliteBackend } from "./open-lix.js";
+export { FsBackend, Lix, LixTransaction, ObserveEvents, openLix, SqliteBackend, } 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,10 +1,16 @@
 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";
+import type { CreateBranchOptions, CreateBranchReceipt, ExecuteResult, FsBackendOptions, MergeBranchOptions, MergeBranchPreview, MergeBranchReceipt, ObserveEvent, OpenLixOptions, SqlParam, SqliteBackendOptions, SwitchBranchOptions, SwitchBranchReceipt } from "./types.js";
 type NativeExecuteResult = Parameters<typeof wrapExecuteResult>[0];
+type NativeObserveEvent = {
+    sequence: number;
+    mutationSequence: number;
+    rows: NativeExecuteResult;
+};
 type NativeParam = ReturnType<typeof toNativeValue>;
 type NativeLix = {
     execute(sql: string, params: NativeParam[]): NativeExecuteResult;
+    observe(sql: string, params: NativeParam[]): NativeObserveEvents;
     beginTransaction(): NativeLixTransaction;
     activeBranchId(): string;
     createBranch(options: CreateBranchOptions): CreateBranchReceipt;
@@ -18,15 +24,24 @@ type NativeLixTransaction = {
     commit(): void;
     rollback(): void;
 };
+type NativeObserveEvents = {
+    next(): Promise<NativeObserveEvent | null | undefined>;
+    close(): void;
+};
 export declare class SqliteBackend {
     readonly path: string;
     constructor(options: SqliteBackendOptions);
 }
+export declare class FsBackend {
+    readonly path: string;
+    constructor(options: FsBackendOptions);
+}
 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>;
+    observe(sql: string, params?: SqlParam[]): ObserveEvents;
     beginTransaction(): Promise<LixTransaction>;
     activeBranchId(): Promise<string>;
     createBranch(options: CreateBranchOptions): Promise<CreateBranchReceipt>;
@@ -35,6 +50,12 @@ export declare class Lix {
     mergeBranch(options: MergeBranchOptions): Promise<MergeBranchReceipt>;
     close(): Promise<void>;
 }
+export declare class ObserveEvents {
+    private readonly native;
+    constructor(native: NativeObserveEvents);
+    next(): Promise<ObserveEvent | undefined>;
+    close(): void;
+}
 export declare class LixTransaction {
     private readonly native;
     constructor(native: NativeLixTransaction);

package/dist/open-lix.js

@@ -5,12 +5,25 @@ import { normalizeParam, toNativeValue } from "./value.js";
 export class SqliteBackend {
     path;
     constructor(options) {
-        if (!options || typeof options.path !== "string" || options.path.length === 0) {
+        if (!options ||
+            typeof options.path !== "string" ||
+            options.path.length === 0) {
             throw new TypeError("SqliteBackend requires a non-empty path");
         }
         this.path = options.path;
     }
 }
+export class FsBackend {
+    path;
+    constructor(options) {
+        if (!options ||
+            typeof options.path !== "string" ||
+            options.path.length === 0) {
+            throw new TypeError("FsBackend requires a non-empty path");
+        }
+        this.path = options.path;
+    }
+}
 export async function openLix(options = {}) {
     if (!options || typeof options !== "object") {
         throw new TypeError("openLix() options must be an object");
@@ -18,10 +31,13 @@ export async function openLix(options = {}) {
     if (options.backend === undefined) {
         return new Lix(addon.Lix.openMemory());
     }
-    if (!(options.backend instanceof SqliteBackend)) {
-        throw new TypeError("openLix() requires { backend: new SqliteBackend({ path }) }");
+    if (options.backend instanceof SqliteBackend) {
+        return new Lix(addon.Lix.openSqlite(options.backend.path));
+    }
+    if (options.backend instanceof FsBackend) {
+        return new Lix(addon.Lix.openFs(options.backend.path));
     }
-    return new Lix(addon.Lix.openSqlite(options.backend.path));
+    throw new TypeError("openLix() requires { backend: new SqliteBackend({ path }) } or { backend: new FsBackend({ path }) }");
 }
 export class Lix {
     native;
@@ -32,6 +48,10 @@ export class Lix {
         assertExecuteArgs("lix", sql, params);
         return wrapExecuteResult(this.native.execute(sql, params.map((param, index) => toNativeValue(normalizeParam(param, index)))));
     }
+    observe(sql, params = []) {
+        assertSqlArgs("observe", "lix", sql, params);
+        return new ObserveEvents(this.native.observe(sql, params.map((param, index) => toNativeValue(normalizeParam(param, index)))));
+    }
     async beginTransaction() {
         return new LixTransaction(this.native.beginTransaction());
     }
@@ -56,6 +76,26 @@ export class Lix {
         return this.native.close();
     }
 }
+export class ObserveEvents {
+    native;
+    constructor(native) {
+        this.native = native;
+    }
+    async next() {
+        const event = await this.native.next();
+        if (event == null) {
+            return undefined;
+        }
+        return {
+            sequence: event.sequence,
+            mutationSequence: event.mutationSequence,
+            result: wrapExecuteResult(event.rows),
+        };
+    }
+    close() {
+        this.native.close();
+    }
+}
 export class LixTransaction {
     native;
     constructor(native) {
@@ -73,10 +113,13 @@ export class LixTransaction {
     }
 }
 function assertExecuteArgs(receiver, sql, params) {
+    assertSqlArgs("execute", receiver, sql, params);
+}
+function assertSqlArgs(operation, receiver, sql, params) {
     if (typeof sql !== "string") {
-        throw invalidArgument("execute", "sql", "string", typeof sql, receiver);
+        throw invalidArgument(operation, "sql", "string", typeof sql, receiver);
     }
     if (!Array.isArray(params)) {
-        throw invalidArgument("execute", "params", "array", typeof params, receiver);
+        throw invalidArgument(operation, "params", "array", typeof params, receiver);
     }
 }

package/dist/types.d.ts

@@ -1,8 +1,11 @@
 export type SqliteBackendOptions = {
     path: string;
 };
+export type FsBackendOptions = {
+    path: string;
+};
 export type OpenLixOptions = {
-    backend?: import("./open-lix.js").SqliteBackend;
+    backend?: import("./open-lix.js").SqliteBackend | import("./open-lix.js").FsBackend;
 };
 export type LixValue = {
     kind: "null";
@@ -40,6 +43,11 @@ export type ExecuteResult = {
         hint?: string;
     }>;
 };
+export type ObserveEvent = {
+    sequence: number;
+    mutationSequence: number;
+    result: ExecuteResult;
+};
 export type RowLike = {
     get(column: string): unknown;
     value(column: string): ValueLike;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@lix-js/sdk",
 	"type": "module",
-	"version": "0.6.2",
+	"version": "0.7.0",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",
 	"repository": {
@@ -18,22 +18,26 @@
 		"dist"
 	],
 	"scripts": {
-		"build": "npm run build:native && npm run build:ts",
+		"build": "npm run build:native && npm run build:ts && npm run build:plugins",
 		"build:native": "node ./scripts/build-native.js",
+		"build:plugins": "node ./scripts/build-bundled-plugins.js",
 		"prepare:native-package": "node ./scripts/prepare-native-package.js",
 		"build:ts": "tsc -p tsconfig.json",
 		"test": "npm run build && vitest run",
 		"typecheck": "tsc -p tsconfig.test.json --noEmit"
 	},
 	"optionalDependencies": {
-		"@lix-js/sdk-darwin-arm64": "0.6.2",
-		"@lix-js/sdk-linux-arm64": "0.6.2",
-		"@lix-js/sdk-linux-x64": "0.6.2",
-		"@lix-js/sdk-win32-x64": "0.6.2"
+		"@lix-js/sdk-darwin-arm64": "0.7.0",
+		"@lix-js/sdk-linux-arm64": "0.7.0",
+		"@lix-js/sdk-linux-x64": "0.7.0",
+		"@lix-js/sdk-win32-x64": "0.7.0"
 	},
 	"devDependencies": {
 		"@types/node": "^24.10.2",
 		"typescript": "^5.5.4",
 		"vitest": "^4.0.18"
+	},
+	"dependencies": {
+		"fflate": "^0.8.3"
 	}
 }