@lix-js/sdk 0.6.2 → 0.8.0

package/dist/jco-transpile.browser.d.ts

@@ -0,0 +1,14 @@
+type TranspileOptions = {
+    name?: string;
+    emitTypescriptDeclarations?: boolean;
+    instantiation?: "async" | "sync";
+    nodejsCompat?: boolean;
+    base64Cutoff?: number;
+};
+type TranspileResult = {
+    files: Record<string, Uint8Array>;
+    imports: string[];
+    exports: [string, "function" | "instance"][];
+};
+export declare function transpileBytes(component: Uint8Array, options?: TranspileOptions): Promise<TranspileResult>;
+export {};

package/dist/jco-transpile.browser.js

@@ -0,0 +1,22 @@
+// This module is copied from the pinned JCO package by build:jco-browser. Using
+// its browser-native generator avoids pulling JCO's CLI-only Node imports and
+// optional minifier into application bundles.
+// @ts-expect-error The generated module is copied into dist after tsc runs.
+import { $init, generate } from "./jco/js-component-bindgen-component.js";
+export async function transpileBytes(component, options = {}) {
+    await $init;
+    const generated = generate(component, {
+        name: options.name ?? "component",
+        noTypescript: options.emitTypescriptDeclarations === false,
+        instantiation: options.instantiation
+            ? { tag: options.instantiation }
+            : undefined,
+        noNodejsCompat: options.nodejsCompat === false,
+        base64Cutoff: options.base64Cutoff ?? 5000,
+    });
+    return {
+        files: Object.fromEntries(generated.files),
+        imports: generated.imports,
+        exports: generated.exports,
+    };
+}

package/dist/open-lix.d.ts

@@ -1,32 +1,25 @@
-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;
-};
+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 {
     readonly path: string;
     constructor(options: SqliteBackendOptions);
 }
+export declare class FsBackend {
+    readonly path: string;
+    readonly lixDir: string | undefined;
+    readonly syncAllFiles: boolean;
+    constructor(options: FsBackendOptions);
+    importPaths(paths: readonly string[]): Promise<void>;
+    syncDiskToLix(): Promise<void>;
+    private client;
+}
 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>;
+    private readonly client;
+    private closePromise;
+    constructor(client: LixWorkerClient);
+    execute(sql: string, params?: SqlParam[], options?: ExecuteOptions): Promise<ExecuteResult>;
+    observe(sql: string, params?: SqlParam[]): ObserveEvents;
     beginTransaction(): Promise<LixTransaction>;
     activeBranchId(): Promise<string>;
     createBranch(options: CreateBranchOptions): Promise<CreateBranchReceipt>;
@@ -35,11 +28,21 @@ export declare class Lix {
     mergeBranch(options: MergeBranchOptions): Promise<MergeBranchReceipt>;
     close(): Promise<void>;
 }
+export declare class ObserveEvents {
+    private readonly client;
+    private readonly setup;
+    private closed;
+    private readonly observeId;
+    constructor(client: LixWorkerClient, observeId: Promise<number>);
+    next(): Promise<ObserveEvent | undefined>;
+    close(): void;
+}
 export declare class LixTransaction {
-    private readonly native;
-    constructor(native: NativeLixTransaction);
-    execute(sql: string, params?: SqlParam[]): Promise<ExecuteResult>;
+    private readonly client;
+    private readonly transactionId;
+    constructor(client: LixWorkerClient, transactionId: number);
+    execute(sql: string, params?: SqlParam[], options?: ExecuteOptions): Promise<ExecuteResult>;
     commit(): Promise<void>;
     rollback(): Promise<void>;
+    private finish;
 }
-export {};

package/dist/open-lix.js

@@ -1,82 +1,263 @@
-import { invalidArgument } from "./errors.js";
-import { addon } from "./native.js";
+import { fsBackendAlreadyOpen, fsBackendNotOpen, invalidArgument, } from "./errors.js";
 import { normalizeOptionals, wrapExecuteResult } from "./result.js";
 import { normalizeParam, toNativeValue } from "./value.js";
+import { openLixWorker } from "./worker/client.js";
+const transactionFinalizer = new FinalizationRegistry(({ client, transactionId }) => {
+    client.notify({ kind: "transaction.abandon", transactionId });
+});
+const observeFinalizer = new FinalizationRegistry(({ client, observeId }) => {
+    void observeId.then((id) => {
+        if (id !== undefined)
+            client.notify({ kind: "observe.close", observeId: id });
+    });
+});
 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;
     }
 }
+const openFsBackends = new WeakMap();
+export class FsBackend {
+    path;
+    lixDir;
+    syncAllFiles;
+    constructor(options) {
+        if (!options ||
+            typeof options.path !== "string" ||
+            options.path.length === 0) {
+            throw new TypeError("FsBackend 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");
+        }
+        if (typeof options.syncAllFiles !== "boolean") {
+            throw new TypeError("FsBackend syncAllFiles must be a boolean");
+        }
+        this.path = options.path;
+        this.lixDir = options.lixDir;
+        this.syncAllFiles = options.syncAllFiles;
+    }
+    async importPaths(paths) {
+        if (!Array.isArray(paths)) {
+            throw new TypeError("importPaths() paths must be an array");
+        }
+        for (const path of paths) {
+            if (typeof path !== "string" || path.length === 0) {
+                throw new TypeError("importPaths() paths must contain non-empty strings");
+            }
+            if (path.endsWith("/")) {
+                throw new TypeError("importPaths() paths must contain file paths, not directory paths");
+            }
+        }
+        await this.client("importPaths").request({
+            kind: "importFilesystemPaths",
+            paths: [...paths],
+        });
+    }
+    async syncDiskToLix() {
+        return this.client("syncDiskToLix").request({ kind: "syncDiskToLix" });
+    }
+    client(operation) {
+        const client = openFsBackends.get(this);
+        if (!client) {
+            throw fsBackendNotOpen(operation);
+        }
+        return client;
+    }
+}
 export async function openLix(options = {}) {
     if (!options || typeof options !== "object") {
         throw new TypeError("openLix() options must be an object");
     }
     if (options.backend === undefined) {
-        return new Lix(addon.Lix.openMemory());
+        return new Lix(await openLixWorker({ kind: "memory" }));
     }
-    if (!(options.backend instanceof SqliteBackend)) {
-        throw new TypeError("openLix() requires { backend: new SqliteBackend({ path }) }");
+    if (options.backend instanceof SqliteBackend) {
+        return new Lix(await openLixWorker({ kind: "sqlite", path: options.backend.path }));
+    }
+    if (options.backend instanceof FsBackend) {
+        const backend = options.backend;
+        if (openFsBackends.has(backend)) {
+            throw fsBackendAlreadyOpen();
+        }
+        openFsBackends.set(backend, null);
+        try {
+            const client = await openLixWorker({
+                kind: "fs",
+                path: backend.path,
+                lixDir: backend.lixDir,
+                syncAllFiles: backend.syncAllFiles,
+            }, () => openFsBackends.delete(backend));
+            openFsBackends.set(backend, client);
+            return new Lix(client);
+        }
+        catch (error) {
+            openFsBackends.delete(backend);
+            throw error;
+        }
     }
-    return new Lix(addon.Lix.openSqlite(options.backend.path));
+    throw new TypeError("openLix() requires backend to be SqliteBackend or FsBackend");
 }
 export class Lix {
-    native;
-    constructor(native) {
-        this.native = native;
+    client;
+    closePromise;
+    constructor(client) {
+        this.client = client;
     }
-    async execute(sql, params = []) {
-        assertExecuteArgs("lix", sql, params);
-        return wrapExecuteResult(this.native.execute(sql, params.map((param, index) => toNativeValue(normalizeParam(param, index)))));
+    async execute(sql, params = [], options) {
+        assertExecuteArgs("lix", sql, params, options);
+        return wrapExecuteResult(await this.client.request({
+            kind: "execute",
+            sql,
+            params: params.map((param, index) => toNativeValue(normalizeParam(param, index))),
+            options,
+        }));
+    }
+    observe(sql, params = []) {
+        assertSqlArgs("observe", "lix", sql, params);
+        return new ObserveEvents(this.client, this.client.request({
+            kind: "observe",
+            sql,
+            params: params.map((param, index) => toNativeValue(normalizeParam(param, index))),
+        }));
     }
     async beginTransaction() {
-        return new LixTransaction(this.native.beginTransaction());
+        const transactionId = await this.client.request({
+            kind: "beginTransaction",
+        });
+        return new LixTransaction(this.client, transactionId);
     }
     async activeBranchId() {
-        return this.native.activeBranchId();
+        return this.client.request({ kind: "activeBranchId" });
     }
     async createBranch(options) {
-        return this.native.createBranch(options);
+        return this.client.request({ kind: "createBranch", options });
     }
     async switchBranch(options) {
-        return this.native.switchBranch(options);
+        return this.client.request({ kind: "switchBranch", options });
     }
     async mergeBranchPreview(options) {
-        return normalizeOptionals(this.native.mergeBranchPreview(options));
+        return normalizeOptionals(await this.client.request({ kind: "mergeBranchPreview", options }));
     }
     async mergeBranch(options) {
-        const receipt = normalizeOptionals(this.native.mergeBranch(options));
+        const receipt = normalizeOptionals(await this.client.request({ kind: "mergeBranch", options }));
         receipt.createdMergeCommitId ??= null;
         return receipt;
     }
     async close() {
-        return this.native.close();
+        this.closePromise ??= (async () => {
+            await this.client.request({ kind: "close" });
+            await this.client.terminate();
+        })();
+        try {
+            await this.closePromise;
+        }
+        catch (error) {
+            this.closePromise = undefined;
+            throw error;
+        }
+    }
+}
+export class ObserveEvents {
+    client;
+    setup = {};
+    closed = false;
+    observeId;
+    constructor(client, observeId) {
+        this.client = client;
+        const setup = this.setup;
+        this.observeId = observeId.catch((error) => {
+            setup.error = error;
+            return undefined;
+        });
+        observeFinalizer.register(this, { client, observeId: this.observeId }, this);
+    }
+    async next() {
+        if (this.closed)
+            return undefined;
+        const observeId = await this.observeId;
+        if (observeId === undefined) {
+            throw this.setup.error;
+        }
+        const event = await this.client.request({
+            kind: "observe.next",
+            observeId,
+        });
+        if (event == null) {
+            return undefined;
+        }
+        return {
+            sequence: event.sequence,
+            mutationSequence: event.mutationSequence,
+            result: wrapExecuteResult(event.rows),
+        };
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        observeFinalizer.unregister(this);
+        void this.observeId.then((observeId) => {
+            if (observeId !== undefined) {
+                this.client.notify({ kind: "observe.close", observeId });
+            }
+        });
     }
 }
 export class LixTransaction {
-    native;
-    constructor(native) {
-        this.native = native;
+    client;
+    transactionId;
+    constructor(client, transactionId) {
+        this.client = client;
+        this.transactionId = transactionId;
+        transactionFinalizer.register(this, { client, transactionId }, this);
     }
-    async execute(sql, params = []) {
-        assertExecuteArgs("lixTransaction", sql, params);
-        return wrapExecuteResult(this.native.execute(sql, params.map((param, index) => toNativeValue(normalizeParam(param, index)))));
+    async execute(sql, params = [], options) {
+        assertExecuteArgs("lixTransaction", sql, params, options);
+        return wrapExecuteResult(await this.client.request({
+            kind: "transaction.execute",
+            transactionId: this.transactionId,
+            sql,
+            params: params.map((param, index) => toNativeValue(normalizeParam(param, index))),
+            options,
+        }));
     }
     async commit() {
-        return this.native.commit();
+        return this.finish("transaction.commit");
     }
     async rollback() {
-        return this.native.rollback();
+        return this.finish("transaction.rollback");
+    }
+    async finish(kind) {
+        transactionFinalizer.unregister(this);
+        return this.client.request({ kind, transactionId: this.transactionId });
+    }
+}
+function assertExecuteArgs(receiver, sql, params, options) {
+    assertSqlArgs("execute", receiver, sql, params);
+    if (options === undefined) {
+        return;
+    }
+    if (!options || typeof options !== "object" || Array.isArray(options)) {
+        throw invalidArgument("execute", "options", "object", typeof options, receiver);
+    }
+    if (options.originKey !== undefined &&
+        typeof options.originKey !== "string") {
+        throw invalidArgument("execute", "options.originKey", "string", typeof options.originKey, receiver);
     }
 }
-function assertExecuteArgs(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/plugin-runtime.d.ts

@@ -0,0 +1,45 @@
+type PluginRuntimeOperation = "initComponent" | "detectChanges" | "render" | "closeComponent";
+export type PluginRuntimeRequest = {
+    operation: PluginRuntimeOperation;
+    componentId?: number;
+    componentBytes?: Uint8Array;
+    maxMemoryBytes?: string;
+    maxFuel?: string;
+    timeoutMs?: string;
+    state?: PluginEntityState[];
+    file?: PluginFile;
+};
+export type PluginRuntimeResponse = {
+    componentId?: number;
+    changes?: PluginDetectedChange[];
+    bytes?: Uint8Array;
+    errorMessage?: string;
+};
+type PluginFile = {
+    filename?: string;
+    data: Uint8Array;
+};
+type PluginEntityState = {
+    entityPk: string[];
+    schemaKey: string;
+    snapshotContent: string;
+    metadata?: string;
+};
+type PluginDetectedChange = {
+    entityPk: string[];
+    schemaKey: string;
+    snapshotContent?: string;
+    metadata?: string;
+};
+declare class WasmPluginRuntime {
+    private nextComponentId;
+    private readonly components;
+    readonly dispatch: (request: PluginRuntimeRequest) => Promise<PluginRuntimeResponse>;
+    private initComponent;
+    private detectChanges;
+    private render;
+    private closeComponent;
+    private requiredComponent;
+}
+export declare function createPluginRuntimeDispatch(): WasmPluginRuntime["dispatch"];
+export {};

package/dist/plugin-runtime.js

@@ -0,0 +1,124 @@
+import { WASIShim } from "@bytecodealliance/preview2-shim/instantiation";
+import { transpileBytes } from "#jco-transpile";
+const webAssembly = globalThis.WebAssembly;
+class WasmPluginRuntime {
+    nextComponentId = 1;
+    components = new Map();
+    dispatch = async (request) => {
+        try {
+            switch (request.operation) {
+                case "initComponent":
+                    return await this.initComponent(request);
+                case "detectChanges":
+                    return this.detectChanges(request);
+                case "render":
+                    return this.render(request);
+                case "closeComponent":
+                    return this.closeComponent(request);
+            }
+        }
+        catch (cause) {
+            return {
+                errorMessage: `Lix plugin runtime ${request.operation} failed: ${errorMessage(cause)}`,
+            };
+        }
+    };
+    async initComponent(request) {
+        if (!request.componentBytes) {
+            throw new TypeError("initComponent requires componentBytes");
+        }
+        const componentId = this.nextComponentId;
+        this.nextComponentId += 1;
+        const name = "lix_plugin";
+        const transpiled = await transpileBytes(request.componentBytes, {
+            name,
+            emitTypescriptDeclarations: false,
+            instantiation: "async",
+            nodejsCompat: false,
+        });
+        const files = new Map(Object.entries(transpiled.files));
+        const moduleSource = requiredFile(files, `${name}.js`);
+        const moduleUrl = `data:text/javascript;base64,${bytesToBase64(moduleSource)}`;
+        const generatedModule = (await import(
+        /* @vite-ignore */ moduleUrl));
+        const wasi = new WASIShim({
+            sandbox: {
+                preopens: {},
+                env: {},
+                args: ["lix-plugin"],
+                enableNetwork: false,
+            },
+        });
+        const instance = await generatedModule.instantiate(async (path) => await webAssembly.compile(copyArrayBuffer(requiredFile(files, path))), wasi.getImportObject());
+        if (!instance.api) {
+            throw new Error("component does not export lix:plugin/api");
+        }
+        this.components.set(componentId, instance.api);
+        return { componentId };
+    }
+    detectChanges(request) {
+        const component = this.requiredComponent(request.componentId);
+        if (!request.file) {
+            throw new TypeError("detectChanges requires file");
+        }
+        return {
+            changes: component.detectChanges(request.state ?? [], request.file),
+        };
+    }
+    render(request) {
+        const component = this.requiredComponent(request.componentId);
+        return { bytes: component.render(request.state ?? []) };
+    }
+    closeComponent(request) {
+        if (request.componentId !== undefined) {
+            this.components.delete(request.componentId);
+        }
+        return {};
+    }
+    requiredComponent(componentId) {
+        if (componentId === undefined) {
+            throw new TypeError("plugin runtime operation requires componentId");
+        }
+        const component = this.components.get(componentId);
+        if (!component) {
+            throw new Error(`unknown plugin component ${componentId}`);
+        }
+        return component;
+    }
+}
+export function createPluginRuntimeDispatch() {
+    return new WasmPluginRuntime().dispatch;
+}
+function bytesToBase64(bytes) {
+    let binary = "";
+    const chunkSize = 0x8000;
+    for (let index = 0; index < bytes.length; index += chunkSize) {
+        binary += String.fromCharCode(...bytes.subarray(index, index + chunkSize));
+    }
+    return btoa(binary);
+}
+function requiredFile(files, path) {
+    const file = files.get(path);
+    if (!file) {
+        throw new Error(`JCO output is missing ${path}`);
+    }
+    return file;
+}
+function copyArrayBuffer(bytes) {
+    const copy = new Uint8Array(bytes.byteLength);
+    copy.set(bytes);
+    return copy.buffer;
+}
+function errorMessage(cause) {
+    if (cause instanceof Error) {
+        return cause.message;
+    }
+    if (cause && typeof cause === "object") {
+        const tag = "tag" in cause ? String(cause.tag) : undefined;
+        const value = "val" in cause ? String(cause.val) : undefined;
+        if (tag || value) {
+            return [tag, value].filter(Boolean).join(": ");
+        }
+    }
+    return String(cause);
+}

package/dist/types.d.ts

@@ -1,8 +1,13 @@
 export type SqliteBackendOptions = {
     path: string;
 };
+export type FsBackendOptions = {
+    path: string;
+    lixDir?: string;
+    syncAllFiles: boolean;
+};
 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";
@@ -30,6 +35,9 @@ export type JsonValue = null | boolean | number | string | readonly JsonValue[]
     readonly [key: string]: JsonValue;
 };
 export type SqlParam = JsonValue | Uint8Array | import("./value.js").Value;
+export type ExecuteOptions = {
+    originKey?: string;
+};
 export type ExecuteResult = {
     columns: string[];
     rows: RowLike[];
@@ -40,6 +48,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;