@loradb/lora-wasm 0.6.0 → 0.8.1

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

@@ -5,10 +5,13 @@ 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_executeBuffer: (a: number, b: number, c: number, d: any) => [number, number, number, number];
+export const wasmdatabase_explain: (a: number, b: number, c: number, d: any) => [number, number, number];
 export const wasmdatabase_loadSnapshot: (a: number, b: number, c: number, d: any) => [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_profile: (a: number, b: number, c: number, d: any) => [number, number, number];
 export const wasmdatabase_relationshipCount: (a: number) => number;
 export const wasmdatabase_saveSnapshot: (a: number, b: any) => [number, number, number, number];
 export const wasmdatabase_transaction: (a: number, b: any, c: number, d: number) => [number, number, number];

package/pkg-bundler/package.json

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

package/pkg-node/README.md

@@ -1,17 +1,17 @@
 # lora-wasm
 
-WebAssembly bindings for the [Lora](../../README.md) in-memory graph
+WebAssembly bindings for the [Lora](../../../README.md) in-memory graph
 database. The package is designed for browsers and Node.js and exposes a
 **strongly typed, async-facing API** that keeps the main thread responsive:
 heavy query work can run inside a Web Worker while your UI code simply awaits
 the result.
 
-> **Status:** prototype / feasibility check. Not published to npm.
+> **Package:** `@loradb/lora-wasm`.
 
 ## Build
 
 ```bash
-cd crates/lora-wasm
+cd crates/bindings/lora-wasm
 npm install
 npm run build              # wasm-pack (node + bundler) + tsc
 npm test                   # vitest
@@ -52,7 +52,7 @@ 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";
+import { createDatabase, isNode } from "@loradb/lora-wasm";
 
 const db = await createDatabase(); // Worker-backed in browsers when possible
 await db.execute("CREATE (:Person {name: $n})", { n: "Alice" });
@@ -63,6 +63,37 @@ for (const row of r.rows) {
 }
 ```
 
+### Explain & Profile
+
+`db.explain()` and `db.profile()` are first-class methods alongside
+`db.execute()`. They are intentionally *separate calls*, not a flag
+on `execute()`, so plan inspection and runtime metrics must be
+requested explicitly.
+
+```ts
+const plan = await db.explain(
+  "MATCH (p:Person) WHERE p.name = $name RETURN p",
+  { name: "Alice" },
+);
+console.log(plan.shape);          // "readOnly"
+console.log(plan.tree.operator);
+
+const profile = await db.profile(
+  "MATCH (p:Person) WHERE p.name = $name RETURN p",
+  { name: "Alice" },
+);
+console.log(profile.metrics.totalElapsedNs);
+console.log(profile.metrics.perOperator); // per-step inclusive timing
+```
+
+`explain()` never invokes the executor — calling it on a mutating
+query (`CREATE`, `MERGE`, `SET`, `DELETE`, `REMOVE`) leaves the graph
+untouched.
+
+> **`profile()` executes the query for real.** Mutating queries
+> produce the same side effects as `execute()`. Use `explain()` to
+> inspect a mutating plan without running it.
+
 To force the in-process engine:
 
 ```ts
@@ -84,7 +115,7 @@ const db = await createDatabase({ warnOnFallback: false });
 ### 2. Explicit main-thread WASM
 
 ```ts
-import { createMainThreadDatabase } from "lora-wasm";
+import { createMainThreadDatabase } from "@loradb/lora-wasm";
 
 const db = await createMainThreadDatabase();
 ```
@@ -122,14 +153,14 @@ WASM has no filesystem access, so snapshots never accept string paths.
 accepts `URL`, `Uint8Array`, `ArrayBuffer`, `Blob`, `Response`, and web
 `ReadableStream<Uint8Array | ArrayBuffer>`. The bytes use the database
 snapshot codec (`LORACOL1`) and can be loaded by native LoraDB. Older store
-snapshots (`LORASNAP`) are still accepted by `loadSnapshot` for compatibility.
+snapshots use the current `LORACOL1` columnar format.
 Snapshot bytes are uncompressed by default; pass `{ compression: "gzip" }` or
 `{ compression: { format: "gzip", level: 1 } }` to save smaller
 WASM-portable snapshots. Gzip levels `0..9` are supported; level `1` is the
 fast default.
 
 ```ts
-import { createDatabase } from "lora-wasm";
+import { createDatabase } from "@loradb/lora-wasm";
 
 const db = await createDatabase();
 await db.execute("CREATE (:Person {name: 'Alice'})");
@@ -172,31 +203,42 @@ Helper constructors: `date`, `time`, `datetime`, `localtime`, `localdatetime`,
 `isNode`, `isRelationship`, `isPath`, `isPoint`, `isTemporal`.
 
 > `distance()` on WGS-84-3D points ignores `height`. See
-> [functions reference](../../apps/loradb.com/docs/functions/overview.md) for the spatial
+> [functions reference](../../../apps/loradb.com/docs/functions/overview.md) for the spatial
 > reference and out-of-scope operations.
 
 ## Errors
 
-`db.execute(...)` and the worker client throw `LoraError` with a narrowed
-`code`:
+`db.execute(...)` and the worker client throw `LoraError` with a
+narrowed `code` from the `LoraErrorCode` union — these mirror
+`lora_database::LoraErrorCode` 1:1, plus `WORKER_ERROR` and `UNKNOWN`.
 
-- `LORA_ERROR` — parse / analyze / execute failure
-- `INVALID_PARAMS` — a param value could not be mapped to a Lora value
+Common ones:
+
+- `LORA_PARSE` — Cypher syntax could not be parsed
+- `LORA_SEMANTIC` — analysis failure (unknown variable, label, type mismatch, …)
+- `LORA_INVALID_PARAMS` — a parameter value could not be coerced to a `LoraValue`
+- `LORA_INVALID_VECTOR` — vector value failed dimension / coordinate-type validation
+- `LORA_TIMEOUT` — query exceeded its cooperative deadline
+- `LORA_IO`, `LORA_SNAPSHOT_CODEC`, `LORA_SNAPSHOT_CRYPTO` — storage / snapshot failures
+- `LORA_INTERNAL` — last-resort fallback when the engine cannot classify the failure
 - `WORKER_ERROR` — worker transport / lifecycle failure (worker client only)
 
+See `ts/types.ts` (`LoraErrorCode`) for the full list.
+
 ## Shared type contract
 
 The public TypeScript value model (`LoraValue`, `LoraNode`, …,
 `QueryResult`, `LoraError`) lives in a single canonical file at
-`crates/shared-ts/types.ts` and is copied into each consumer package by
+`crates/bindings/shared-ts/types.ts` and is copied into each consumer package by
 its `sync:types` npm script. CI runs `verify:types` to fail on drift.
 That keeps `lora-node` and `lora-wasm` locked to one identical
 public surface — consumers can swap backends without rewriting types.
 
 ## Known limitations
 
-- The wasm module is single-threaded. Parallel queries inside one worker
-  serialise; spawn more workers for true parallelism.
+- The wasm module runs inside one JavaScript runtime. Auto-commit reads can
+  overlap on engine snapshots; write commits serialize. Use more Workers for
+  separate graphs or stronger UI isolation.
 - I64 values are delivered as JS `number` and lose precision above 2^53.
   Applications that need bigint precision should use the native
   `lora-node` binding instead.
@@ -228,7 +270,7 @@ public surface — consumers can swap backends without rewriting types.
   forms, parameter validation errors, and concurrent queries across the
   worker message protocol.
 - The TypeScript public contract is shared verbatim with `lora-node`
-  via `crates/shared-ts/types.ts`, enforced by `verify:types` in CI.
+  via `crates/bindings/shared-ts/types.ts`, enforced by `verify:types` in CI.
 - `npm pack --dry-run` produces a 45-file, 6.6 MB tarball containing
   all three wasm bundles plus the compiled TS wrapper. No `file:` deps,
   no postinstall scripts.
@@ -245,9 +287,8 @@ public surface — consumers can swap backends without rewriting types.
 - I64 precision is capped at `Number.MAX_SAFE_INTEGER`. For larger
   integer properties we need a `bigint`-aware serializer on the wasm
   boundary.
-- The engine is synchronous inside wasm — a single Worker serialises
-  queries. Multi-tenant workloads need either multiple Workers (already
-  possible), or an engine-level cooperative scheduler.
+- The engine is synchronous inside wasm once a call enters the module. A slow
+  query blocks that Worker until completion.
 - No query cancellation or progress streaming crosses the Worker
   boundary; a slow query blocks that Worker until completion.
 

package/pkg-node/lora_wasm.d.ts

@@ -39,6 +39,16 @@ export class WasmDatabase {
    * Returns the serialized bytes as a `Uint8Array`.
    */
   saveSnapshot(options: any): Uint8Array;
+  /**
+   * Execute a Lora query and return the result as a binary buffer.
+   *
+   * Wire format is the shared `lora_binding_buffer` layout. The TS
+   * wrapper decodes it once into the same `{ columns, rows }` shape
+   * `execute()` returns, but in a tight V8 loop instead of going
+   * through `serde_wasm_bindgen` value-by-value. Materially faster
+   * on bulk reads.
+   */
+  executeBuffer(query: string, params: any): Uint8Array;
   relationshipCount(): number;
   constructor();
   clear(): void;
@@ -50,6 +60,21 @@ export class WasmDatabase {
    * as a plain JS object (structured-clonable).
    */
   execute(query: string, params: any): any;
+  /**
+   * Compile a query and return its plan without executing it.
+   *
+   * Mutating queries (CREATE / MERGE / SET / DELETE / REMOVE) leave
+   * the graph untouched — this method never runs the executor.
+   */
+  explain(query: string, params: any): any;
+  /**
+   * Execute a query and return the plan plus runtime metrics.
+   *
+   * **PROFILE executes the query for real.** Mutating queries are
+   * persisted exactly as in `execute()`. Use `explain()` to inspect
+   * a mutating plan without running it.
+   */
+  profile(query: string, params: any): any;
 }
 export class WasmQueryStream {
   private constructor();

package/pkg-node/lora_wasm.js

@@ -293,6 +293,29 @@ class WasmDatabase {
         wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
         return v1;
     }
+    /**
+     * Execute a Lora query and return the result as a binary buffer.
+     *
+     * Wire format is the shared `lora_binding_buffer` layout. The TS
+     * wrapper decodes it once into the same `{ columns, rows }` shape
+     * `execute()` returns, but in a tight V8 loop instead of going
+     * through `serde_wasm_bindgen` value-by-value. Materially faster
+     * on bulk reads.
+     * @param {string} query
+     * @param {any} params
+     * @returns {Uint8Array}
+     */
+    executeBuffer(query, params) {
+        const ptr0 = passStringToWasm0(query, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmdatabase_executeBuffer(this.__wbg_ptr, ptr0, len0, params);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        var v2 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+        wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+        return v2;
+    }
     /**
      * @returns {number}
      */
@@ -328,6 +351,43 @@ class WasmDatabase {
         }
         return takeFromExternrefTable0(ret[0]);
     }
+    /**
+     * Compile a query and return its plan without executing it.
+     *
+     * Mutating queries (CREATE / MERGE / SET / DELETE / REMOVE) leave
+     * the graph untouched — this method never runs the executor.
+     * @param {string} query
+     * @param {any} params
+     * @returns {any}
+     */
+    explain(query, params) {
+        const ptr0 = passStringToWasm0(query, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmdatabase_explain(this.__wbg_ptr, ptr0, len0, params);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+    /**
+     * Execute a query and return the plan plus runtime metrics.
+     *
+     * **PROFILE executes the query for real.** Mutating queries are
+     * persisted exactly as in `execute()`. Use `explain()` to inspect
+     * a mutating plan without running it.
+     * @param {string} query
+     * @param {any} params
+     * @returns {any}
+     */
+    profile(query, params) {
+        const ptr0 = passStringToWasm0(query, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmdatabase_profile(this.__wbg_ptr, ptr0, len0, params);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
 }
 module.exports.WasmDatabase = WasmDatabase;
 

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

@@ -5,10 +5,13 @@ 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_executeBuffer: (a: number, b: number, c: number, d: any) => [number, number, number, number];
+export const wasmdatabase_explain: (a: number, b: number, c: number, d: any) => [number, number, number];
 export const wasmdatabase_loadSnapshot: (a: number, b: number, c: number, d: any) => [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_profile: (a: number, b: number, c: number, d: any) => [number, number, number];
 export const wasmdatabase_relationshipCount: (a: number) => number;
 export const wasmdatabase_saveSnapshot: (a: number, b: any) => [number, number, number, number];
 export const wasmdatabase_transaction: (a: number, b: any, c: number, d: number) => [number, 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.6.0",
+  "version": "0.8.1",
   "license": "BUSL-1.1",
   "files": [
     "lora_wasm_bg.wasm",

package/pkg-web/README.md

@@ -1,17 +1,17 @@
 # lora-wasm
 
-WebAssembly bindings for the [Lora](../../README.md) in-memory graph
+WebAssembly bindings for the [Lora](../../../README.md) in-memory graph
 database. The package is designed for browsers and Node.js and exposes a
 **strongly typed, async-facing API** that keeps the main thread responsive:
 heavy query work can run inside a Web Worker while your UI code simply awaits
 the result.
 
-> **Status:** prototype / feasibility check. Not published to npm.
+> **Package:** `@loradb/lora-wasm`.
 
 ## Build
 
 ```bash
-cd crates/lora-wasm
+cd crates/bindings/lora-wasm
 npm install
 npm run build              # wasm-pack (node + bundler) + tsc
 npm test                   # vitest
@@ -52,7 +52,7 @@ 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";
+import { createDatabase, isNode } from "@loradb/lora-wasm";
 
 const db = await createDatabase(); // Worker-backed in browsers when possible
 await db.execute("CREATE (:Person {name: $n})", { n: "Alice" });
@@ -63,6 +63,37 @@ for (const row of r.rows) {
 }
 ```
 
+### Explain & Profile
+
+`db.explain()` and `db.profile()` are first-class methods alongside
+`db.execute()`. They are intentionally *separate calls*, not a flag
+on `execute()`, so plan inspection and runtime metrics must be
+requested explicitly.
+
+```ts
+const plan = await db.explain(
+  "MATCH (p:Person) WHERE p.name = $name RETURN p",
+  { name: "Alice" },
+);
+console.log(plan.shape);          // "readOnly"
+console.log(plan.tree.operator);
+
+const profile = await db.profile(
+  "MATCH (p:Person) WHERE p.name = $name RETURN p",
+  { name: "Alice" },
+);
+console.log(profile.metrics.totalElapsedNs);
+console.log(profile.metrics.perOperator); // per-step inclusive timing
+```
+
+`explain()` never invokes the executor — calling it on a mutating
+query (`CREATE`, `MERGE`, `SET`, `DELETE`, `REMOVE`) leaves the graph
+untouched.
+
+> **`profile()` executes the query for real.** Mutating queries
+> produce the same side effects as `execute()`. Use `explain()` to
+> inspect a mutating plan without running it.
+
 To force the in-process engine:
 
 ```ts
@@ -84,7 +115,7 @@ const db = await createDatabase({ warnOnFallback: false });
 ### 2. Explicit main-thread WASM
 
 ```ts
-import { createMainThreadDatabase } from "lora-wasm";
+import { createMainThreadDatabase } from "@loradb/lora-wasm";
 
 const db = await createMainThreadDatabase();
 ```
@@ -122,14 +153,14 @@ WASM has no filesystem access, so snapshots never accept string paths.
 accepts `URL`, `Uint8Array`, `ArrayBuffer`, `Blob`, `Response`, and web
 `ReadableStream<Uint8Array | ArrayBuffer>`. The bytes use the database
 snapshot codec (`LORACOL1`) and can be loaded by native LoraDB. Older store
-snapshots (`LORASNAP`) are still accepted by `loadSnapshot` for compatibility.
+snapshots use the current `LORACOL1` columnar format.
 Snapshot bytes are uncompressed by default; pass `{ compression: "gzip" }` or
 `{ compression: { format: "gzip", level: 1 } }` to save smaller
 WASM-portable snapshots. Gzip levels `0..9` are supported; level `1` is the
 fast default.
 
 ```ts
-import { createDatabase } from "lora-wasm";
+import { createDatabase } from "@loradb/lora-wasm";
 
 const db = await createDatabase();
 await db.execute("CREATE (:Person {name: 'Alice'})");
@@ -172,31 +203,42 @@ Helper constructors: `date`, `time`, `datetime`, `localtime`, `localdatetime`,
 `isNode`, `isRelationship`, `isPath`, `isPoint`, `isTemporal`.
 
 > `distance()` on WGS-84-3D points ignores `height`. See
-> [functions reference](../../apps/loradb.com/docs/functions/overview.md) for the spatial
+> [functions reference](../../../apps/loradb.com/docs/functions/overview.md) for the spatial
 > reference and out-of-scope operations.
 
 ## Errors
 
-`db.execute(...)` and the worker client throw `LoraError` with a narrowed
-`code`:
+`db.execute(...)` and the worker client throw `LoraError` with a
+narrowed `code` from the `LoraErrorCode` union — these mirror
+`lora_database::LoraErrorCode` 1:1, plus `WORKER_ERROR` and `UNKNOWN`.
 
-- `LORA_ERROR` — parse / analyze / execute failure
-- `INVALID_PARAMS` — a param value could not be mapped to a Lora value
+Common ones:
+
+- `LORA_PARSE` — Cypher syntax could not be parsed
+- `LORA_SEMANTIC` — analysis failure (unknown variable, label, type mismatch, …)
+- `LORA_INVALID_PARAMS` — a parameter value could not be coerced to a `LoraValue`
+- `LORA_INVALID_VECTOR` — vector value failed dimension / coordinate-type validation
+- `LORA_TIMEOUT` — query exceeded its cooperative deadline
+- `LORA_IO`, `LORA_SNAPSHOT_CODEC`, `LORA_SNAPSHOT_CRYPTO` — storage / snapshot failures
+- `LORA_INTERNAL` — last-resort fallback when the engine cannot classify the failure
 - `WORKER_ERROR` — worker transport / lifecycle failure (worker client only)
 
+See `ts/types.ts` (`LoraErrorCode`) for the full list.
+
 ## Shared type contract
 
 The public TypeScript value model (`LoraValue`, `LoraNode`, …,
 `QueryResult`, `LoraError`) lives in a single canonical file at
-`crates/shared-ts/types.ts` and is copied into each consumer package by
+`crates/bindings/shared-ts/types.ts` and is copied into each consumer package by
 its `sync:types` npm script. CI runs `verify:types` to fail on drift.
 That keeps `lora-node` and `lora-wasm` locked to one identical
 public surface — consumers can swap backends without rewriting types.
 
 ## Known limitations
 
-- The wasm module is single-threaded. Parallel queries inside one worker
-  serialise; spawn more workers for true parallelism.
+- The wasm module runs inside one JavaScript runtime. Auto-commit reads can
+  overlap on engine snapshots; write commits serialize. Use more Workers for
+  separate graphs or stronger UI isolation.
 - I64 values are delivered as JS `number` and lose precision above 2^53.
   Applications that need bigint precision should use the native
   `lora-node` binding instead.
@@ -228,7 +270,7 @@ public surface — consumers can swap backends without rewriting types.
   forms, parameter validation errors, and concurrent queries across the
   worker message protocol.
 - The TypeScript public contract is shared verbatim with `lora-node`
-  via `crates/shared-ts/types.ts`, enforced by `verify:types` in CI.
+  via `crates/bindings/shared-ts/types.ts`, enforced by `verify:types` in CI.
 - `npm pack --dry-run` produces a 45-file, 6.6 MB tarball containing
   all three wasm bundles plus the compiled TS wrapper. No `file:` deps,
   no postinstall scripts.
@@ -245,9 +287,8 @@ public surface — consumers can swap backends without rewriting types.
 - I64 precision is capped at `Number.MAX_SAFE_INTEGER`. For larger
   integer properties we need a `bigint`-aware serializer on the wasm
   boundary.
-- The engine is synchronous inside wasm — a single Worker serialises
-  queries. Multi-tenant workloads need either multiple Workers (already
-  possible), or an engine-level cooperative scheduler.
+- The engine is synchronous inside wasm once a call enters the module. A slow
+  query blocks that Worker until completion.
 - No query cancellation or progress streaming crosses the Worker
   boundary; a slow query blocks that Worker until completion.
 

package/pkg-web/lora_wasm.d.ts

@@ -39,6 +39,16 @@ export class WasmDatabase {
    * Returns the serialized bytes as a `Uint8Array`.
    */
   saveSnapshot(options: any): Uint8Array;
+  /**
+   * Execute a Lora query and return the result as a binary buffer.
+   *
+   * Wire format is the shared `lora_binding_buffer` layout. The TS
+   * wrapper decodes it once into the same `{ columns, rows }` shape
+   * `execute()` returns, but in a tight V8 loop instead of going
+   * through `serde_wasm_bindgen` value-by-value. Materially faster
+   * on bulk reads.
+   */
+  executeBuffer(query: string, params: any): Uint8Array;
   relationshipCount(): number;
   constructor();
   clear(): void;
@@ -50,6 +60,21 @@ export class WasmDatabase {
    * as a plain JS object (structured-clonable).
    */
   execute(query: string, params: any): any;
+  /**
+   * Compile a query and return its plan without executing it.
+   *
+   * Mutating queries (CREATE / MERGE / SET / DELETE / REMOVE) leave
+   * the graph untouched — this method never runs the executor.
+   */
+  explain(query: string, params: any): any;
+  /**
+   * Execute a query and return the plan plus runtime metrics.
+   *
+   * **PROFILE executes the query for real.** Mutating queries are
+   * persisted exactly as in `execute()`. Use `explain()` to inspect
+   * a mutating plan without running it.
+   */
+  profile(query: string, params: any): any;
 }
 export class WasmQueryStream {
   private constructor();
@@ -67,10 +92,13 @@ export interface InitOutput {
   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_executeBuffer: (a: number, b: number, c: number, d: any) => [number, number, number, number];
+  readonly wasmdatabase_explain: (a: number, b: number, c: number, d: any) => [number, number, number];
   readonly wasmdatabase_loadSnapshot: (a: number, b: number, c: number, d: any) => [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_profile: (a: number, b: number, c: number, d: any) => [number, number, number];
   readonly wasmdatabase_relationshipCount: (a: number) => number;
   readonly wasmdatabase_saveSnapshot: (a: number, b: any) => [number, number, number, number];
   readonly wasmdatabase_transaction: (a: number, b: any, c: number, d: number) => [number, number, number];

package/pkg-web/lora_wasm.js

@@ -289,6 +289,29 @@ export class WasmDatabase {
         wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
         return v1;
     }
+    /**
+     * Execute a Lora query and return the result as a binary buffer.
+     *
+     * Wire format is the shared `lora_binding_buffer` layout. The TS
+     * wrapper decodes it once into the same `{ columns, rows }` shape
+     * `execute()` returns, but in a tight V8 loop instead of going
+     * through `serde_wasm_bindgen` value-by-value. Materially faster
+     * on bulk reads.
+     * @param {string} query
+     * @param {any} params
+     * @returns {Uint8Array}
+     */
+    executeBuffer(query, params) {
+        const ptr0 = passStringToWasm0(query, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmdatabase_executeBuffer(this.__wbg_ptr, ptr0, len0, params);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        var v2 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+        wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+        return v2;
+    }
     /**
      * @returns {number}
      */
@@ -324,6 +347,43 @@ export class WasmDatabase {
         }
         return takeFromExternrefTable0(ret[0]);
     }
+    /**
+     * Compile a query and return its plan without executing it.
+     *
+     * Mutating queries (CREATE / MERGE / SET / DELETE / REMOVE) leave
+     * the graph untouched — this method never runs the executor.
+     * @param {string} query
+     * @param {any} params
+     * @returns {any}
+     */
+    explain(query, params) {
+        const ptr0 = passStringToWasm0(query, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmdatabase_explain(this.__wbg_ptr, ptr0, len0, params);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+    /**
+     * Execute a query and return the plan plus runtime metrics.
+     *
+     * **PROFILE executes the query for real.** Mutating queries are
+     * persisted exactly as in `execute()`. Use `explain()` to inspect
+     * a mutating plan without running it.
+     * @param {string} query
+     * @param {any} params
+     * @returns {any}
+     */
+    profile(query, params) {
+        const ptr0 = passStringToWasm0(query, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmdatabase_profile(this.__wbg_ptr, ptr0, len0, params);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
 }
 
 const WasmQueryStreamFinalization = (typeof FinalizationRegistry === 'undefined')

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

@@ -5,10 +5,13 @@ 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_executeBuffer: (a: number, b: number, c: number, d: any) => [number, number, number, number];
+export const wasmdatabase_explain: (a: number, b: number, c: number, d: any) => [number, number, number];
 export const wasmdatabase_loadSnapshot: (a: number, b: number, c: number, d: any) => [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_profile: (a: number, b: number, c: number, d: any) => [number, number, number];
 export const wasmdatabase_relationshipCount: (a: number) => number;
 export const wasmdatabase_saveSnapshot: (a: number, b: any) => [number, number, number, number];
 export const wasmdatabase_transaction: (a: number, b: any, c: number, d: number) => [number, 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.6.0",
+  "version": "0.8.1",
   "license": "BUSL-1.1",
   "files": [
     "lora_wasm_bg.wasm",