@loradb/lora-wasm 0.3.0 → 0.5.0

package/pkg-node/README.md

@@ -37,19 +37,24 @@ npm run test:browser
 npm run pack:dry
 ```
 
-## Two execution modes
+## Execution modes
 
-### 1. In-process (Node / scripts)
+### 1. Default: Worker first, main-thread fallback
 
 `lora-wasm` is **async-only** — the sole initialization pattern is
 `createDatabase()`, which bootstraps the WASM module on first call.
 There is no synchronous constructor and no `Database.create()`
 static; `Database` is a type-only export.
 
+In browser-like hosts, `createDatabase()` tries to spawn the packaged module
+Worker first and pings it before returning. If the Worker cannot be created or
+fails during startup, the package emits one `console.warn` and falls back to
+the in-process WASM engine so the app can still run.
+
 ```ts
 import { createDatabase, isNode } from "lora-wasm";
 
-const db = await createDatabase();
+const db = await createDatabase(); // Worker-backed in browsers when possible
 await db.execute("CREATE (:Person {name: $n})", { n: "Alice" });
 
 const r = await db.execute("MATCH (n:Person) RETURN n");
@@ -58,7 +63,36 @@ for (const row of r.rows) {
 }
 ```
 
-### 2. Non-blocking Web Worker (browser)
+To force the in-process engine:
+
+```ts
+const db = await createDatabase({ runtime: "main-thread" });
+```
+
+To require Worker startup instead of falling back:
+
+```ts
+const db = await createDatabase({ runtime: "worker" });
+```
+
+To disable the fallback warning:
+
+```ts
+const db = await createDatabase({ warnOnFallback: false });
+```
+
+### 2. Explicit main-thread WASM
+
+```ts
+import { createMainThreadDatabase } from "lora-wasm";
+
+const db = await createMainThreadDatabase();
+```
+
+### 3. Custom Web Worker
+
+Use this when you need to control the Worker URL, lifecycle, bundler entry, or
+pooling strategy.
 
 ```ts
 import { createWorkerDatabase } from "lora-wasm/worker-client";
@@ -75,11 +109,42 @@ const { rows } = await db.execute("MATCH (n) RETURN n.n AS n");
 The worker entry (`ts/worker.ts`) hosts the WASM module. The main thread only
 posts messages, so long-running queries never block the event loop / UI.
 
-### 3. In-process but typed like the worker (advanced)
+### 4. In-process but typed like the worker (advanced)
 
 The same `createWorkerDatabase` signature accepts any `WorkerLike` object —
 useful for tests and for swapping execution backends behind the same API.
 
+## Snapshots
+
+WASM has no filesystem access, so `saveSnapshot()` defaults to a `Uint8Array`.
+It also accepts typed formats: `"base64"` returns base64 text, `"blob"` returns
+a `Blob`, and `"download"` triggers a browser download from the main thread.
+
+`loadSnapshot` accepts a `WasmSnapshotSource`: `Uint8Array`, `ArrayBuffer`,
+`Blob`/`File`, `Response`, web `ReadableStream`, string URL, or `URL`. It does
+not include Node `Buffer`; use `Uint8Array` bytes when running the WASM package
+from Node.
+
+```ts
+import { createDatabase } from "lora-wasm";
+
+const db = await createDatabase();
+await db.execute("CREATE (:Person {name: 'Alice'})");
+
+const bytes = await db.saveSnapshotToBytes();
+const sameBytes = await db.saveSnapshot("binary");
+const blob = await db.saveSnapshot({ format: "blob" });
+await db.saveSnapshot({ format: "download", filename: "graph.lorasnap" });
+
+await db.loadSnapshot(bytes);
+await db.loadSnapshot(blob);
+await db.loadSnapshot(new Response(bytes).body!);
+await db.loadSnapshot(new URL("/graph.lorasnap", location.href));
+```
+
+`loadSnapshotFromBytes(bytes)` remains available for the narrow
+`Uint8Array`-only path.
+
 ## Typed value model
 
 | TS type                              | Runtime shape                                                               |
@@ -140,8 +205,7 @@ public surface — consumers can swap backends without rewriting types.
   millisecond-granular, so the nanosecond field on returned values is
   zero below the millisecond boundary.
 - Engine errors cross the worker boundary as `LoraError` with a
-  narrowed `code`; the engine does not currently stream query progress
-  or offer cancellation.
+  narrowed `code`; the engine does not currently offer query cancellation.
 
 ## Feasibility assessment
 

package/pkg-node/lora_wasm.d.ts

@@ -11,6 +11,16 @@ export function init(): void;
 export class WasmDatabase {
   free(): void;
   nodeCount(): number;
+  /**
+   * Open a true native row stream. Rows are pulled from the Rust executor
+   * one `next()` call at a time.
+   */
+  openStream(query: string, params: any): WasmQueryStream;
+  /**
+   * Execute an array of `{ query, params? }` statements inside one native
+   * transaction. Returns an array of query results in statement order.
+   */
+  transaction(statements: any, mode?: string | null): any;
   relationshipCount(): number;
   /**
    * Serialize the graph into a byte buffer. The caller is responsible for
@@ -39,3 +49,10 @@ export class WasmDatabase {
    */
   execute(query: string, params: any): any;
 }
+export class WasmQueryStream {
+  private constructor();
+  free(): void;
+  next(): any;
+  close(): void;
+  columns(): any;
+}

package/pkg-node/lora_wasm.js

@@ -222,6 +222,38 @@ class WasmDatabase {
         const ret = wasm.wasmdatabase_nodeCount(this.__wbg_ptr);
         return ret >>> 0;
     }
+    /**
+     * Open a true native row stream. Rows are pulled from the Rust executor
+     * one `next()` call at a time.
+     * @param {string} query
+     * @param {any} params
+     * @returns {WasmQueryStream}
+     */
+    openStream(query, params) {
+        const ptr0 = passStringToWasm0(query, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmdatabase_openStream(this.__wbg_ptr, ptr0, len0, params);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return WasmQueryStream.__wrap(ret[0]);
+    }
+    /**
+     * Execute an array of `{ query, params? }` statements inside one native
+     * transaction. Returns an array of query results in statement order.
+     * @param {any} statements
+     * @param {string | null} [mode]
+     * @returns {any}
+     */
+    transaction(statements, mode) {
+        var ptr0 = isLikeNone(mode) ? 0 : passStringToWasm0(mode, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        var len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmdatabase_transaction(this.__wbg_ptr, statements, ptr0, len0);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
     /**
      * @returns {number}
      */
@@ -295,6 +327,57 @@ class WasmDatabase {
 }
 module.exports.WasmDatabase = WasmDatabase;
 
+const WasmQueryStreamFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_wasmquerystream_free(ptr >>> 0, 1));
+
+class WasmQueryStream {
+
+    static __wrap(ptr) {
+        ptr = ptr >>> 0;
+        const obj = Object.create(WasmQueryStream.prototype);
+        obj.__wbg_ptr = ptr;
+        WasmQueryStreamFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        WasmQueryStreamFinalization.unregister(this);
+        return ptr;
+    }
+
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_wasmquerystream_free(ptr, 0);
+    }
+    /**
+     * @returns {any}
+     */
+    next() {
+        const ret = wasm.wasmquerystream_next(this.__wbg_ptr);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+    close() {
+        wasm.wasmquerystream_close(this.__wbg_ptr);
+    }
+    /**
+     * @returns {any}
+     */
+    columns() {
+        const ret = wasm.wasmquerystream_columns(this.__wbg_ptr);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+}
+module.exports.WasmQueryStream = WasmQueryStream;
+
 module.exports.__wbg_String_8f0eb39a4a4c2f66 = function(arg0, arg1) {
     const ret = String(arg1);
     const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);

package/pkg-node/lora_wasm_bg.wasm.d.ts

@@ -2,13 +2,19 @@
 /* eslint-disable */
 export const memory: WebAssembly.Memory;
 export const __wbg_wasmdatabase_free: (a: number, b: number) => void;
+export const __wbg_wasmquerystream_free: (a: number, b: number) => void;
 export const wasmdatabase_clear: (a: number) => void;
 export const wasmdatabase_execute: (a: number, b: number, c: number, d: any) => [number, number, number];
 export const wasmdatabase_loadSnapshotFromBytes: (a: number, b: number, c: number) => [number, number, number];
 export const wasmdatabase_new: () => number;
 export const wasmdatabase_nodeCount: (a: number) => number;
+export const wasmdatabase_openStream: (a: number, b: number, c: number, d: any) => [number, number, number];
 export const wasmdatabase_relationshipCount: (a: number) => number;
 export const wasmdatabase_saveSnapshotToBytes: (a: number) => [number, number, number, number];
+export const wasmdatabase_transaction: (a: number, b: any, c: number, d: number) => [number, number, number];
+export const wasmquerystream_close: (a: number) => void;
+export const wasmquerystream_columns: (a: number) => [number, number, number];
+export const wasmquerystream_next: (a: number) => [number, number, number];
 export const init: () => void;
 export const __wbindgen_malloc: (a: number, b: number) => number;
 export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;

package/pkg-node/package.json

@@ -4,7 +4,7 @@
     "LoraDB, Inc."
   ],
   "description": "WebAssembly bindings for the Lora in-memory graph database",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "license": "BUSL-1.1",
   "files": [
     "lora_wasm_bg.wasm",

package/pkg-web/README.md

@@ -37,19 +37,24 @@ npm run test:browser
 npm run pack:dry
 ```
 
-## Two execution modes
+## Execution modes
 
-### 1. In-process (Node / scripts)
+### 1. Default: Worker first, main-thread fallback
 
 `lora-wasm` is **async-only** — the sole initialization pattern is
 `createDatabase()`, which bootstraps the WASM module on first call.
 There is no synchronous constructor and no `Database.create()`
 static; `Database` is a type-only export.
 
+In browser-like hosts, `createDatabase()` tries to spawn the packaged module
+Worker first and pings it before returning. If the Worker cannot be created or
+fails during startup, the package emits one `console.warn` and falls back to
+the in-process WASM engine so the app can still run.
+
 ```ts
 import { createDatabase, isNode } from "lora-wasm";
 
-const db = await createDatabase();
+const db = await createDatabase(); // Worker-backed in browsers when possible
 await db.execute("CREATE (:Person {name: $n})", { n: "Alice" });
 
 const r = await db.execute("MATCH (n:Person) RETURN n");
@@ -58,7 +63,36 @@ for (const row of r.rows) {
 }
 ```
 
-### 2. Non-blocking Web Worker (browser)
+To force the in-process engine:
+
+```ts
+const db = await createDatabase({ runtime: "main-thread" });
+```
+
+To require Worker startup instead of falling back:
+
+```ts
+const db = await createDatabase({ runtime: "worker" });
+```
+
+To disable the fallback warning:
+
+```ts
+const db = await createDatabase({ warnOnFallback: false });
+```
+
+### 2. Explicit main-thread WASM
+
+```ts
+import { createMainThreadDatabase } from "lora-wasm";
+
+const db = await createMainThreadDatabase();
+```
+
+### 3. Custom Web Worker
+
+Use this when you need to control the Worker URL, lifecycle, bundler entry, or
+pooling strategy.
 
 ```ts
 import { createWorkerDatabase } from "lora-wasm/worker-client";
@@ -75,11 +109,42 @@ const { rows } = await db.execute("MATCH (n) RETURN n.n AS n");
 The worker entry (`ts/worker.ts`) hosts the WASM module. The main thread only
 posts messages, so long-running queries never block the event loop / UI.
 
-### 3. In-process but typed like the worker (advanced)
+### 4. In-process but typed like the worker (advanced)
 
 The same `createWorkerDatabase` signature accepts any `WorkerLike` object —
 useful for tests and for swapping execution backends behind the same API.
 
+## Snapshots
+
+WASM has no filesystem access, so `saveSnapshot()` defaults to a `Uint8Array`.
+It also accepts typed formats: `"base64"` returns base64 text, `"blob"` returns
+a `Blob`, and `"download"` triggers a browser download from the main thread.
+
+`loadSnapshot` accepts a `WasmSnapshotSource`: `Uint8Array`, `ArrayBuffer`,
+`Blob`/`File`, `Response`, web `ReadableStream`, string URL, or `URL`. It does
+not include Node `Buffer`; use `Uint8Array` bytes when running the WASM package
+from Node.
+
+```ts
+import { createDatabase } from "lora-wasm";
+
+const db = await createDatabase();
+await db.execute("CREATE (:Person {name: 'Alice'})");
+
+const bytes = await db.saveSnapshotToBytes();
+const sameBytes = await db.saveSnapshot("binary");
+const blob = await db.saveSnapshot({ format: "blob" });
+await db.saveSnapshot({ format: "download", filename: "graph.lorasnap" });
+
+await db.loadSnapshot(bytes);
+await db.loadSnapshot(blob);
+await db.loadSnapshot(new Response(bytes).body!);
+await db.loadSnapshot(new URL("/graph.lorasnap", location.href));
+```
+
+`loadSnapshotFromBytes(bytes)` remains available for the narrow
+`Uint8Array`-only path.
+
 ## Typed value model
 
 | TS type                              | Runtime shape                                                               |
@@ -140,8 +205,7 @@ public surface — consumers can swap backends without rewriting types.
   millisecond-granular, so the nanosecond field on returned values is
   zero below the millisecond boundary.
 - Engine errors cross the worker boundary as `LoraError` with a
-  narrowed `code`; the engine does not currently stream query progress
-  or offer cancellation.
+  narrowed `code`; the engine does not currently offer query cancellation.
 
 ## Feasibility assessment
 

package/pkg-web/lora_wasm.d.ts

@@ -11,6 +11,16 @@ export function init(): void;
 export class WasmDatabase {
   free(): void;
   nodeCount(): number;
+  /**
+   * Open a true native row stream. Rows are pulled from the Rust executor
+   * one `next()` call at a time.
+   */
+  openStream(query: string, params: any): WasmQueryStream;
+  /**
+   * Execute an array of `{ query, params? }` statements inside one native
+   * transaction. Returns an array of query results in statement order.
+   */
+  transaction(statements: any, mode?: string | null): any;
   relationshipCount(): number;
   /**
    * Serialize the graph into a byte buffer. The caller is responsible for
@@ -39,19 +49,32 @@ export class WasmDatabase {
    */
   execute(query: string, params: any): any;
 }
+export class WasmQueryStream {
+  private constructor();
+  free(): void;
+  next(): any;
+  close(): void;
+  columns(): any;
+}
 
 export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
 
 export interface InitOutput {
   readonly memory: WebAssembly.Memory;
   readonly __wbg_wasmdatabase_free: (a: number, b: number) => void;
+  readonly __wbg_wasmquerystream_free: (a: number, b: number) => void;
   readonly wasmdatabase_clear: (a: number) => void;
   readonly wasmdatabase_execute: (a: number, b: number, c: number, d: any) => [number, number, number];
   readonly wasmdatabase_loadSnapshotFromBytes: (a: number, b: number, c: number) => [number, number, number];
   readonly wasmdatabase_new: () => number;
   readonly wasmdatabase_nodeCount: (a: number) => number;
+  readonly wasmdatabase_openStream: (a: number, b: number, c: number, d: any) => [number, number, number];
   readonly wasmdatabase_relationshipCount: (a: number) => number;
   readonly wasmdatabase_saveSnapshotToBytes: (a: number) => [number, number, number, number];
+  readonly wasmdatabase_transaction: (a: number, b: any, c: number, d: number) => [number, number, number];
+  readonly wasmquerystream_close: (a: number) => void;
+  readonly wasmquerystream_columns: (a: number) => [number, number, number];
+  readonly wasmquerystream_next: (a: number) => [number, number, number];
   readonly init: () => void;
   readonly __wbindgen_malloc: (a: number, b: number) => number;
   readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;

package/pkg-web/lora_wasm.js

@@ -218,6 +218,38 @@ export class WasmDatabase {
         const ret = wasm.wasmdatabase_nodeCount(this.__wbg_ptr);
         return ret >>> 0;
     }
+    /**
+     * Open a true native row stream. Rows are pulled from the Rust executor
+     * one `next()` call at a time.
+     * @param {string} query
+     * @param {any} params
+     * @returns {WasmQueryStream}
+     */
+    openStream(query, params) {
+        const ptr0 = passStringToWasm0(query, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmdatabase_openStream(this.__wbg_ptr, ptr0, len0, params);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return WasmQueryStream.__wrap(ret[0]);
+    }
+    /**
+     * Execute an array of `{ query, params? }` statements inside one native
+     * transaction. Returns an array of query results in statement order.
+     * @param {any} statements
+     * @param {string | null} [mode]
+     * @returns {any}
+     */
+    transaction(statements, mode) {
+        var ptr0 = isLikeNone(mode) ? 0 : passStringToWasm0(mode, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        var len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmdatabase_transaction(this.__wbg_ptr, statements, ptr0, len0);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
     /**
      * @returns {number}
      */
@@ -290,6 +322,56 @@ export class WasmDatabase {
     }
 }
 
+const WasmQueryStreamFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_wasmquerystream_free(ptr >>> 0, 1));
+
+export class WasmQueryStream {
+
+    static __wrap(ptr) {
+        ptr = ptr >>> 0;
+        const obj = Object.create(WasmQueryStream.prototype);
+        obj.__wbg_ptr = ptr;
+        WasmQueryStreamFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        WasmQueryStreamFinalization.unregister(this);
+        return ptr;
+    }
+
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_wasmquerystream_free(ptr, 0);
+    }
+    /**
+     * @returns {any}
+     */
+    next() {
+        const ret = wasm.wasmquerystream_next(this.__wbg_ptr);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+    close() {
+        wasm.wasmquerystream_close(this.__wbg_ptr);
+    }
+    /**
+     * @returns {any}
+     */
+    columns() {
+        const ret = wasm.wasmquerystream_columns(this.__wbg_ptr);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+}
+
 async function __wbg_load(module, imports) {
     if (typeof Response === 'function' && module instanceof Response) {
         if (typeof WebAssembly.instantiateStreaming === 'function') {

package/pkg-web/lora_wasm_bg.wasm.d.ts

@@ -2,13 +2,19 @@
 /* eslint-disable */
 export const memory: WebAssembly.Memory;
 export const __wbg_wasmdatabase_free: (a: number, b: number) => void;
+export const __wbg_wasmquerystream_free: (a: number, b: number) => void;
 export const wasmdatabase_clear: (a: number) => void;
 export const wasmdatabase_execute: (a: number, b: number, c: number, d: any) => [number, number, number];
 export const wasmdatabase_loadSnapshotFromBytes: (a: number, b: number, c: number) => [number, number, number];
 export const wasmdatabase_new: () => number;
 export const wasmdatabase_nodeCount: (a: number) => number;
+export const wasmdatabase_openStream: (a: number, b: number, c: number, d: any) => [number, number, number];
 export const wasmdatabase_relationshipCount: (a: number) => number;
 export const wasmdatabase_saveSnapshotToBytes: (a: number) => [number, number, number, number];
+export const wasmdatabase_transaction: (a: number, b: any, c: number, d: number) => [number, number, number];
+export const wasmquerystream_close: (a: number) => void;
+export const wasmquerystream_columns: (a: number) => [number, number, number];
+export const wasmquerystream_next: (a: number) => [number, number, number];
 export const init: () => void;
 export const __wbindgen_malloc: (a: number, b: number) => number;
 export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;

package/pkg-web/package.json

@@ -5,7 +5,7 @@
     "LoraDB, Inc."
   ],
   "description": "WebAssembly bindings for the Lora in-memory graph database",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "license": "BUSL-1.1",
   "files": [
     "lora_wasm_bg.wasm",