@loradb/lora-node 0.3.0 → 0.5.0

package/README.md

@@ -1,7 +1,7 @@
 # lora-node
 
-Node.js / TypeScript bindings for the [Lora](../../README.md) in-memory
-graph engine. The package exposes a first-class typed API: query results are
+Node.js / TypeScript bindings for the [Lora](../../README.md) graph
+engine. The package exposes a first-class typed API: query results are
 modelled as discriminated unions, temporal values carry `kind` tags, and the
 `Database` class is strongly typed in both directions (params and rows).
 
@@ -29,13 +29,13 @@ to `package.json`.
 ## Usage
 
 `lora-node` is **async-only** — the sole initialization pattern is
-`createDatabase()`. There is no synchronous constructor and no
+`createDatabase(...)`. There is no synchronous constructor and no
 `Database.create()` static; `Database` is a type-only export.
 
 ```ts
 import { createDatabase, isNode, type LoraNode } from "lora-node";
 
-const db = await createDatabase();
+const db = await createDatabase(); // in-memory by default
 await db.execute("CREATE (:Person {name: $n, age: $a})", { n: "Alice", a: 30 });
 
 const res = await db.execute<{ n: LoraNode }>("MATCH (n:Person) RETURN n");
@@ -46,9 +46,66 @@ for (const row of res.rows) {
 }
 ```
 
-The API matches `lora-wasm` verbatim — same shared types, same
-`createDatabase()` entry point, same async method signatures — so
-switching backends is a single import change.
+The initialization rule is:
+
+```ts
+import { createDatabase } from "lora-node";
+
+const inMemory = await createDatabase();            // in-memory only
+const persistent = await createDatabase("./app");  // persistent: pass a directory string
+```
+
+If you want persistence, pass a **directory string** to `createDatabase(...)`.
+
+Node also has a WAL-backed convenience overload:
+
+```ts
+import { createDatabase } from "lora-node";
+
+const db = await createDatabase("./.lora-wal"); // persistent: directory string
+```
+
+The string is treated as the WAL directory path verbatim. Relative
+paths resolve from the current working directory. This is a Node-only
+initialization convenience; the query surface, shared types, and async
+method signatures still match `lora-wasm`.
+
+Call `db.dispose()` when you need to release the native handle eagerly,
+especially before reopening the same WAL directory in the same process.
+
+## Snapshots
+
+`saveSnapshot(path)` writes the current graph to a local file. It also accepts
+typed formats: `"binary"` returns a Node `Buffer`, `"base64"` returns base64
+text, and `{ format: "path", path }` accepts either a path string or `file:`
+URL.
+
+`loadSnapshot` accepts a `NodeSnapshotSource`: a filesystem path, `file:` URL,
+HTTP(S) or `data:` URL, `Buffer`, `Uint8Array`, `ArrayBuffer`, Node
+`Readable`, web `ReadableStream`, or async iterable of byte chunks.
+
+```ts
+import { readFile } from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { createDatabase } from "lora-node";
+
+const db = await createDatabase();
+await db.execute("CREATE (:Person {name: 'Alice'})");
+await db.saveSnapshot("./graph.lorasnap");
+const bytes = await db.saveSnapshot("binary");
+const base64 = await db.saveSnapshot({ format: "base64" });
+
+await db.loadSnapshot("./graph.lorasnap");
+await db.loadSnapshot(pathToFileURL("./graph.lorasnap"));
+await db.loadSnapshot(await readFile("./graph.lorasnap"));
+await db.loadSnapshot(createReadStream("./graph.lorasnap"));
+await db.loadSnapshot(bytes);
+await db.loadSnapshot(new URL("https://example.com/graph.lorasnap"));
+```
+
+Use `loadSnapshotFromBytes(bytes)` when you already have in-memory bytes and
+want to make that intent explicit.
 
 ## Typed value model
 
@@ -116,15 +173,20 @@ identical to `lora-wasm`.
 
 ## Known limitations
 
-- **Concurrent writes.** Each `execute()` hops through the threadpool and
-  serialises on the store mutex inside Rust, so concurrent read/read and
-  read/write traffic works. Firing many concurrent write queries against
-  the same `Database` (e.g. 2 000 parallel `CREATE`s via `Promise.all`)
-  can expose races in the underlying engine — treat the mutex as
-  per-operation, not per-query. Prefer `await`-in-a-loop or a single
-  batched query for heavy write workloads.
+- **Concurrent writes.** Each `execute()` hops through the threadpool; read
+  queries can share the store read lock, while writes serialize on the store
+  write lock. Firing many concurrent write queries against the same
+  `Database` (e.g. 2 000 parallel `CREATE`s via `Promise.all`) works but
+  queues behind that write lock. Prefer `await`-in-a-loop or a single batched
+  query for heavy write workloads.
 - **I64 precision.** Integer values above `Number.MAX_SAFE_INTEGER`
   (2^53) are returned as JS `number` and lose precision. A `bigint`-aware
   path would require extending the value serializer.
 - **Cancellation.** The napi `Task` abstraction does not support
   cancellation once dispatched; a runaway query runs to completion.
+- **WAL surface.** This first Node persistence slice only exposes
+  WAL-backed initialization via `createDatabase(walDir)`. Checkpoint,
+  truncate, status, and sync-mode controls are not exposed yet.
+- **WAL directory ownership.** A WAL directory can only be open by one
+  live handle at a time. Dispose the first handle before reopening the
+  same directory.

package/dist/index.d.ts

@@ -7,10 +7,13 @@
  * native surface into the strongly-typed `QueryResult<T>` / `LoraParams`
  * shapes defined in the shared TS contract (`crates/shared-ts/types.ts`).
  *
- * **Initialization is async-only.** The one canonical entry point is
- * `createDatabase()`; there is no synchronous constructor. See the docs at
+ * **Initialization is async-only.** The canonical entry point is
+ * `createDatabase(...)`, optionally with a WAL directory path. There is no
+ * synchronous constructor. See the docs at
  * https://loradb.com/docs/getting-started/node for the full rationale.
  */
+import { Buffer } from "node:buffer";
+import { Readable } from "node:stream";
 import type { LoraParams, LoraValue, QueryResult } from "./types.js";
 declare const NativeDatabase: typeof import("./native.js").Database;
 export * from "./types.js";
@@ -26,17 +29,40 @@ export interface SnapshotMeta {
     relationshipCount: number;
     walLsn: number | null;
 }
+export type NodeSnapshotChunk = string | Uint8Array | ArrayBuffer | Buffer;
+export type NodeSnapshotSource = string | URL | Uint8Array | ArrayBuffer | Buffer | Readable | ReadableStream<NodeSnapshotChunk> | AsyncIterable<NodeSnapshotChunk>;
+export type NodeSnapshotSaveFormat = "binary" | "base64";
+export type NodeSnapshotSaveOptions = {
+    format: "path";
+    path: string | URL;
+} | {
+    format: NodeSnapshotSaveFormat;
+};
+export type NodeSnapshotSaveTarget = string | URL | NodeSnapshotSaveFormat | NodeSnapshotSaveOptions;
+export interface CreateDatabaseOptions {
+    databaseDir?: string;
+}
+export type TransactionMode = "read_write" | "read_only" | "readwrite" | "readonly" | "rw" | "ro";
+export interface TransactionStatement {
+    query: string;
+    params?: LoraParams | null;
+}
+export interface RowStream<T extends Record<string, LoraValue> = Record<string, LoraValue>> extends AsyncIterableIterator<T> {
+    columns(): string[];
+    toArray(): Promise<T[]>;
+    close(): void;
+}
 /**
- * In-memory Lora graph database instance.
+ * Lora graph database instance.
  *
- * Obtained exclusively via `createDatabase()`. There is no public constructor
- * and no synchronous factory — the async entry point lets the binding
- * extend initialization later (lazy native loading, warmup, schema
- * preflight) without breaking callers.
+ * Obtained exclusively via `createDatabase()`. There is no public
+ * constructor and no synchronous factory. With no args the instance is
+ * purely in-memory; with a WAL directory path it replays committed WAL
+ * state from disk before serving queries.
  *
  * Instances are independent — each owns its own in-memory graph. Multiple
- * concurrent `execute()` calls against one instance run one at a time
- * (serialised on the store mutex) but none of them block the event loop.
+ * concurrent read-only `execute()` calls against one instance can share
+ * the store read lock; writes serialize without blocking the event loop.
  */
 declare class DatabaseImpl {
     #private;
@@ -47,6 +73,24 @@ declare class DatabaseImpl {
      * with a narrowed `code` (`LORA_ERROR` / `INVALID_PARAMS`).
      */
     execute<T extends Record<string, LoraValue> = Record<string, LoraValue>>(query: string, params?: LoraParams): Promise<QueryResult<T>>;
+    /**
+     * Return an async row iterator for a query.
+     *
+     * The binding exposes the same `for await` shape as the Rust stream API.
+     * Rows are materialized by the native `execute()` promise today, then
+     * yielded one at a time to JS consumers.
+     */
+    stream<T extends Record<string, LoraValue> = Record<string, LoraValue>>(query: string, params?: LoraParams): RowStream<T>;
+    /** Alias for `stream()`, useful when naming the row-level API explicitly. */
+    rows<T extends Record<string, LoraValue> = Record<string, LoraValue>>(query: string, params?: LoraParams): RowStream<T>;
+    /**
+     * Execute a statement batch inside one native transaction.
+     *
+     * Results are returned in statement order. If any statement fails, the
+     * native transaction is dropped before commit and all prior writes in the
+     * batch are rolled back.
+     */
+    transaction<T extends Record<string, LoraValue> = Record<string, LoraValue>>(statements: TransactionStatement[], mode?: TransactionMode): Promise<Array<QueryResult<T>>>;
     /** Drop every node and relationship. Constant-time under the hood. */
     clear(): Promise<void>;
     /** Number of nodes currently in the graph. */
@@ -54,21 +98,33 @@ declare class DatabaseImpl {
     /** Number of relationships currently in the graph. */
     relationshipCount(): Promise<number>;
     /**
-     * Save the graph to a snapshot file. Writes atomically via a `.tmp` +
-     * rename dance — the target path is only replaced once the full payload
-     * has been written and fsync'd.
+     * Release the native database handle. Idempotent.
      *
-     * Synchronous in the native layer (point-in-time consistency requires
-     * holding the store mutex for the duration of the save); the returned
-     * Promise resolves immediately once the save returns.
+     * Call this when a WAL-backed database needs to be reopened in the same
+     * process. New operations after disposal reject with `database is closed`.
      */
-    saveSnapshot(path: string): Promise<SnapshotMeta>;
+    dispose(): void;
+    saveSnapshot(format: "binary"): Promise<Buffer>;
+    saveSnapshot(format: "base64"): Promise<string>;
+    saveSnapshot(path: string | URL): Promise<SnapshotMeta>;
+    saveSnapshot(options: {
+        format: "binary";
+    }): Promise<Buffer>;
+    saveSnapshot(options: {
+        format: "base64";
+    }): Promise<string>;
+    saveSnapshot(options: {
+        format: "path";
+        path: string | URL;
+    }): Promise<SnapshotMeta>;
+    saveSnapshotToBytes(): Promise<Buffer>;
     /**
      * Replace the current graph state with a snapshot loaded from `path`.
-     * Concurrent `execute()` calls block on the store mutex until the load
-     * completes.
+     * Concurrent `execute()` calls block on the store write lock until the
+     * load completes.
      */
-    loadSnapshot(path: string): Promise<SnapshotMeta>;
+    loadSnapshot(source: NodeSnapshotSource): Promise<SnapshotMeta>;
+    loadSnapshotFromBytes(bytes: Uint8Array | ArrayBuffer | Buffer): Promise<SnapshotMeta>;
 }
 /**
  * Public type for a LoraDB instance.
@@ -84,24 +140,36 @@ declare class DatabaseImpl {
  */
 export type Database = DatabaseImpl;
 /**
- * Create and initialize a new in-memory LoraDB instance.
+ * Create and initialize a new LoraDB instance.
  *
  * **This is the only supported initialization pattern** for `lora-node`.
  * Synchronous construction is not available — the async factory guarantees
- * the native layer is ready before the first query dispatches and keeps
- * the Node and WASM surfaces symmetric.
+ * the native layer is ready before the first query dispatches.
  *
  * ```ts
  * import { createDatabase } from "lora-node";
  *
- * const db = await createDatabase();
+ * const db = await createDatabase(); // in-memory by default
  * const res = await db.execute(
  *   "CREATE (n:Person {name: $name}) RETURN n",
  *   { name: "Alice" },
  * );
  * ```
  *
+ * Optional Node-only persistence convenience:
+ *
+ * ```ts
+ * import { createDatabase } from "lora-node";
+ *
+ * const inMemory = await createDatabase();            // in-memory
+ * const persistent = await createDatabase("./app");  // persistent: pass a directory string
+ * ```
+ *
+ * If you want persistence, pass a directory string. The string is treated
+ * as a WAL directory path verbatim. Relative paths resolve from the
+ * current working directory.
+ *
  * Each call returns an independent graph — no shared state between instances.
  */
-export declare function createDatabase(): Promise<Database>;
+export declare function createDatabase(databaseName?: string, options?: CreateDatabaseOptions): Promise<Database>;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../ts/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,SAAS,EACT,WAAW,EACZ,MAAM,YAAY,CAAC;AAOpB,QAAA,MAAM,cAAc,EAAE,cAAc,aAAa,EAAE,QAA0B,CAAC;AAE9E,cAAc,YAAY,CAAC;AAE3B;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;;;;;;;;;GAWG;AACH,cAAM,YAAY;;gBAGJ,KAAK,EAAE,YAAY,CAAC,OAAO,cAAc,CAAC;IAItD;;;;OAIG;IACG,OAAO,CACX,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAC/D,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAS9D,sEAAsE;IAChE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,8CAA8C;IACxC,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC;IAIlC,sDAAsD;IAChD,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC;IAI1C;;;;;;;;OAQG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAQvD;;;;OAIG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;CAOxD;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,QAAQ,GAAG,YAAY,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,QAAQ,CAAC,CAExD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../ts/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -8,8 +8,9 @@
  * native surface into the strongly-typed `QueryResult<T>` / `LoraParams`
  * shapes defined in the shared TS contract (`crates/shared-ts/types.ts`).
  *
- * **Initialization is async-only.** The one canonical entry point is
- * `createDatabase()`; there is no synchronous constructor. See the docs at
+ * **Initialization is async-only.** The canonical entry point is
+ * `createDatabase(...)`, optionally with a WAL directory path. There is no
+ * synchronous constructor. See the docs at
  * https://loradb.com/docs/getting-started/node for the full rationale.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
@@ -31,23 +32,189 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createDatabase = createDatabase;
+const node_buffer_1 = require("node:buffer");
+const node_stream_1 = require("node:stream");
+const node_url_1 = require("node:url");
 const types_js_1 = require("./types.js");
 // eslint-disable-next-line @typescript-eslint/ban-ts-comment
 // @ts-ignore - resolved at runtime via native.js loader
 const native_js_1 = __importDefault(require("./native.js"));
 const NativeDatabase = native_js_1.default.Database;
 __exportStar(require("./types.js"), exports);
+class NativeRowStream {
+    #inner;
+    #streamId;
+    #closed = false;
+    constructor(inner, streamId) {
+        this.#inner = inner;
+        this.#streamId = streamId;
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    columns() {
+        try {
+            return this.#inner.streamColumns(this.#streamId);
+        }
+        catch (err) {
+            throw (0, types_js_1.wrapError)(err);
+        }
+    }
+    async next() {
+        if (this.#closed) {
+            return { done: true, value: undefined };
+        }
+        try {
+            const row = this.#inner.streamNext(this.#streamId);
+            if (row === null) {
+                this.#closed = true;
+                return { done: true, value: undefined };
+            }
+            return { done: false, value: row };
+        }
+        catch (err) {
+            this.#closed = true;
+            throw (0, types_js_1.wrapError)(err);
+        }
+    }
+    async return() {
+        this.close();
+        return { done: true, value: undefined };
+    }
+    async toArray() {
+        const rows = [];
+        for (;;) {
+            const next = await this.next();
+            if (next.done) {
+                return rows;
+            }
+            rows.push(next.value);
+        }
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        try {
+            this.#inner.streamClose(this.#streamId);
+        }
+        catch (err) {
+            throw (0, types_js_1.wrapError)(err);
+        }
+    }
+}
+function isFetchUrl(url) {
+    return url.protocol === "http:" || url.protocol === "https:" || url.protocol === "data:";
+}
+function stringToUrl(value) {
+    try {
+        return new URL(value);
+    }
+    catch {
+        return null;
+    }
+}
+function bytesToUint8Array(bytes) {
+    if (bytes instanceof Uint8Array) {
+        return bytes;
+    }
+    return new Uint8Array(bytes);
+}
+function snapshotChunkToBuffer(chunk) {
+    return typeof chunk === "string"
+        ? node_buffer_1.Buffer.from(chunk)
+        : node_buffer_1.Buffer.from(bytesToUint8Array(chunk));
+}
+function resolveNodeSnapshotPath(path) {
+    if (path instanceof URL) {
+        if (path.protocol !== "file:") {
+            throw new Error(`LORA_ERROR: unsupported snapshot save URL protocol '${path.protocol}'`);
+        }
+        return (0, node_url_1.fileURLToPath)(path);
+    }
+    return path;
+}
+async function fetchSnapshotBytes(url) {
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`LORA_ERROR: snapshot fetch failed (${res.status} ${res.statusText})`);
+    }
+    return node_buffer_1.Buffer.from(await res.arrayBuffer());
+}
+function isReadableStream(source) {
+    return typeof source.getReader === "function";
+}
+function isAsyncIterable(source) {
+    return typeof source[Symbol.asyncIterator] === "function";
+}
+async function readableStreamToBuffer(stream) {
+    const reader = stream.getReader();
+    const chunks = [];
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) {
+                return node_buffer_1.Buffer.concat(chunks);
+            }
+            chunks.push(snapshotChunkToBuffer(value));
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+async function asyncIterableToBuffer(stream) {
+    const chunks = [];
+    for await (const chunk of stream) {
+        chunks.push(snapshotChunkToBuffer(chunk));
+    }
+    return node_buffer_1.Buffer.concat(chunks);
+}
+async function resolveNodeSnapshotSource(source) {
+    if (source instanceof URL) {
+        if (source.protocol === "file:") {
+            return (0, node_url_1.fileURLToPath)(source);
+        }
+        if (isFetchUrl(source)) {
+            return fetchSnapshotBytes(source);
+        }
+        throw new Error(`LORA_ERROR: unsupported snapshot URL protocol '${source.protocol}'`);
+    }
+    if (typeof source === "string") {
+        const url = stringToUrl(source);
+        if (!url) {
+            return source;
+        }
+        if (url.protocol === "file:") {
+            return (0, node_url_1.fileURLToPath)(url);
+        }
+        if (isFetchUrl(url)) {
+            return fetchSnapshotBytes(url);
+        }
+        return source;
+    }
+    if (isReadableStream(source)) {
+        return readableStreamToBuffer(source);
+    }
+    if (source instanceof node_stream_1.Readable) {
+        return asyncIterableToBuffer(source);
+    }
+    if (isAsyncIterable(source)) {
+        return asyncIterableToBuffer(source);
+    }
+    return node_buffer_1.Buffer.from(bytesToUint8Array(source));
+}
 /**
- * In-memory Lora graph database instance.
+ * Lora graph database instance.
  *
- * Obtained exclusively via `createDatabase()`. There is no public constructor
- * and no synchronous factory — the async entry point lets the binding
- * extend initialization later (lazy native loading, warmup, schema
- * preflight) without breaking callers.
+ * Obtained exclusively via `createDatabase()`. There is no public
+ * constructor and no synchronous factory. With no args the instance is
+ * purely in-memory; with a WAL directory path it replays committed WAL
+ * state from disk before serving queries.
  *
  * Instances are independent — each owns its own in-memory graph. Multiple
- * concurrent `execute()` calls against one instance run one at a time
- * (serialised on the store mutex) but none of them block the event loop.
+ * concurrent read-only `execute()` calls against one instance can share
+ * the store read lock; writes serialize without blocking the event loop.
  */
 class DatabaseImpl {
     #inner;
@@ -68,30 +235,121 @@ class DatabaseImpl {
             throw (0, types_js_1.wrapError)(err);
         }
     }
+    /**
+     * Return an async row iterator for a query.
+     *
+     * The binding exposes the same `for await` shape as the Rust stream API.
+     * Rows are materialized by the native `execute()` promise today, then
+     * yielded one at a time to JS consumers.
+     */
+    stream(query, params) {
+        try {
+            const streamId = this.#inner.openStream(query, params ?? null);
+            return new NativeRowStream(this.#inner, streamId);
+        }
+        catch (err) {
+            throw (0, types_js_1.wrapError)(err);
+        }
+    }
+    /** Alias for `stream()`, useful when naming the row-level API explicitly. */
+    rows(query, params) {
+        return this.stream(query, params);
+    }
+    /**
+     * Execute a statement batch inside one native transaction.
+     *
+     * Results are returned in statement order. If any statement fails, the
+     * native transaction is dropped before commit and all prior writes in the
+     * batch are rolled back.
+     */
+    async transaction(statements, mode = "read_write") {
+        try {
+            return (await this.#inner.transaction(statements, mode));
+        }
+        catch (err) {
+            throw (0, types_js_1.wrapError)(err);
+        }
+    }
     /** Drop every node and relationship. Constant-time under the hood. */
     async clear() {
-        this.#inner.clear();
+        try {
+            this.#inner.clear();
+        }
+        catch (err) {
+            throw (0, types_js_1.wrapError)(err);
+        }
     }
     /** Number of nodes currently in the graph. */
     async nodeCount() {
-        return this.#inner.nodeCount();
+        try {
+            return this.#inner.nodeCount();
+        }
+        catch (err) {
+            throw (0, types_js_1.wrapError)(err);
+        }
     }
     /** Number of relationships currently in the graph. */
     async relationshipCount() {
-        return this.#inner.relationshipCount();
+        try {
+            return this.#inner.relationshipCount();
+        }
+        catch (err) {
+            throw (0, types_js_1.wrapError)(err);
+        }
     }
     /**
-     * Save the graph to a snapshot file. Writes atomically via a `.tmp` +
-     * rename dance — the target path is only replaced once the full payload
-     * has been written and fsync'd.
+     * Release the native database handle. Idempotent.
      *
-     * Synchronous in the native layer (point-in-time consistency requires
-     * holding the store mutex for the duration of the save); the returned
-     * Promise resolves immediately once the save returns.
+     * Call this when a WAL-backed database needs to be reopened in the same
+     * process. New operations after disposal reject with `database is closed`.
      */
-    async saveSnapshot(path) {
+    dispose() {
         try {
-            return this.#inner.saveSnapshot(path);
+            this.#inner.dispose();
+        }
+        catch (err) {
+            throw (0, types_js_1.wrapError)(err);
+        }
+    }
+    /**
+     * Save the graph as a snapshot.
+     *
+     * - `saveSnapshot(path)` and `saveSnapshot({ format: "path", path })`
+     *   write atomically to a local file and return `SnapshotMeta`.
+     * - `saveSnapshot("binary")` / `{ format: "binary" }` return a `Buffer`.
+     * - `saveSnapshot("base64")` / `{ format: "base64" }` return base64 text.
+     */
+    async saveSnapshot(target) {
+        try {
+            if (target === "binary" || (typeof target === "object"
+                && !(target instanceof URL)
+                && target.format === "binary")) {
+                return this.saveSnapshotToBytes();
+            }
+            if (target === "base64" || (typeof target === "object"
+                && !(target instanceof URL)
+                && target.format === "base64")) {
+                return (await this.saveSnapshotToBytes()).toString("base64");
+            }
+            let path;
+            if (typeof target === "object" && !(target instanceof URL)) {
+                if (target.format !== "path") {
+                    throw new Error(`LORA_ERROR: unsupported snapshot save format '${target.format}'`);
+                }
+                path = target.path;
+            }
+            else {
+                path = target;
+            }
+            return this.#inner.saveSnapshot(resolveNodeSnapshotPath(path));
+        }
+        catch (err) {
+            throw (0, types_js_1.wrapError)(err);
+        }
+    }
+    async saveSnapshotToBytes() {
+        try {
+            return this.#inner.saveSnapshotToBytes();
         }
         catch (err) {
             throw (0, types_js_1.wrapError)(err);
@@ -99,12 +357,24 @@ class DatabaseImpl {
     }
     /**
      * Replace the current graph state with a snapshot loaded from `path`.
-     * Concurrent `execute()` calls block on the store mutex until the load
-     * completes.
+     * Concurrent `execute()` calls block on the store write lock until the
+     * load completes.
      */
-    async loadSnapshot(path) {
+    async loadSnapshot(source) {
         try {
-            return this.#inner.loadSnapshot(path);
+            const resolved = await resolveNodeSnapshotSource(source);
+            if (typeof resolved === "string") {
+                return this.#inner.loadSnapshot(resolved);
+            }
+            return this.#inner.loadSnapshotFromBytes(resolved);
+        }
+        catch (err) {
+            throw (0, types_js_1.wrapError)(err);
+        }
+    }
+    async loadSnapshotFromBytes(bytes) {
+        try {
+            return this.#inner.loadSnapshotFromBytes(node_buffer_1.Buffer.from(bytesToUint8Array(bytes)));
         }
         catch (err) {
             throw (0, types_js_1.wrapError)(err);
@@ -112,26 +382,45 @@ class DatabaseImpl {
     }
 }
 /**
- * Create and initialize a new in-memory LoraDB instance.
+ * Create and initialize a new LoraDB instance.
  *
  * **This is the only supported initialization pattern** for `lora-node`.
  * Synchronous construction is not available — the async factory guarantees
- * the native layer is ready before the first query dispatches and keeps
- * the Node and WASM surfaces symmetric.
+ * the native layer is ready before the first query dispatches.
  *
  * ```ts
  * import { createDatabase } from "lora-node";
  *
- * const db = await createDatabase();
+ * const db = await createDatabase(); // in-memory by default
  * const res = await db.execute(
  *   "CREATE (n:Person {name: $name}) RETURN n",
  *   { name: "Alice" },
  * );
  * ```
  *
+ * Optional Node-only persistence convenience:
+ *
+ * ```ts
+ * import { createDatabase } from "lora-node";
+ *
+ * const inMemory = await createDatabase();            // in-memory
+ * const persistent = await createDatabase("./app");  // persistent: pass a directory string
+ * ```
+ *
+ * If you want persistence, pass a directory string. The string is treated
+ * as a WAL directory path verbatim. Relative paths resolve from the
+ * current working directory.
+ *
  * Each call returns an independent graph — no shared state between instances.
  */
-async function createDatabase() {
-    return new DatabaseImpl(new NativeDatabase());
+async function createDatabase(databaseName, options = {}) {
+    try {
+        return new DatabaseImpl(databaseName === undefined
+            ? new NativeDatabase()
+            : new NativeDatabase(databaseName, options.databaseDir ?? null));
+    }
+    catch (err) {
+        throw (0, types_js_1.wrapError)(err);
+    }
 }
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../ts/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;;;;;;;;;;;;;;;;;AAiJH,wCAEC;AA5ID,yCAAuC;AAEvC,6DAA6D;AAC7D,wDAAwD;AACxD,4DAAiC;AAEjC,MAAM,cAAc,GAA0C,mBAAM,CAAC,QAAQ,CAAC;AAE9E,6CAA2B;AAe3B;;;;;;;;;;;GAWG;AACH,MAAM,YAAY;IACP,MAAM,CAAsC;IAErD,YAAY,KAA0C;QACpD,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,OAAO,CAEX,KAAa,EAAE,MAAmB;QAClC,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,IAAI,IAAI,CAAC,CAAC;YAC7D,OAAO,GAAqB,CAAC;QAC/B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAA,oBAAS,EAAC,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,sEAAsE;IACtE,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IAED,8CAA8C;IAC9C,KAAK,CAAC,SAAS;QACb,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;IACjC,CAAC;IAED,sDAAsD;IACtD,KAAK,CAAC,iBAAiB;QACrB,OAAO,IAAI,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC;IACzC,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,YAAY,CAAC,IAAY;QAC7B,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAiB,CAAC;QACxD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAA,oBAAS,EAAC,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,YAAY,CAAC,IAAY;QAC7B,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAiB,CAAC;QACxD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAA,oBAAS,EAAC,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;CACF;AAgBD;;;;;;;;;;;;;;;;;;;GAmBG;AACI,KAAK,UAAU,cAAc;IAClC,OAAO,IAAI,YAAY,CAAC,IAAI,cAAc,EAAE,CAAC,CAAC;AAChD,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../ts/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;;;;;;;;;;;;;;;;;AAwgBH,wCAaC;AAnhBD,6CAAqC;AACrC,6CAAuC;AACvC,uCAAyC;AAOzC,yCAAuC;AAEvC,6DAA6D;AAC7D,wDAAwD;AACxD,4DAAiC;AAEjC,MAAM,cAAc,GAA0C,mBAAM,CAAC,QAAQ,CAAC;AAE9E,6CAA2B;AA4D3B,MAAM,eAAe;IAGV,MAAM,CAAsC;IAC5C,SAAS,CAAS;IAC3B,OAAO,GAAG,KAAK,CAAC;IAEhB,YAAY,KAA0C,EAAE,QAAgB;QACtE,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;IAC5B,CAAC;IAED,CAAC,MAAM,CAAC,aAAa,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO;QACL,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACnD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAA,oBAAS,EAAC,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI;QACR,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;QAC1C,CAAC;QACD,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAa,CAAC;YAC/D,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;gBACjB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;gBACpB,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;YAC1C,CAAC;YACD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;QACrC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;YACpB,MAAM,IAAA,oBAAS,EAAC,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,KAAK,CAAC,MAAM;QACV,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IAC1C,CAAC;IAED,KAAK,CAAC,OAAO;QACX,MAAM,IAAI,GAAQ,EAAE,CAAC;QACrB,SAAS,CAAC;YACR,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;YAC/B,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;gBACd,OAAO,IAAI,CAAC;YACd,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IAED,KAAK;QACH,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACzB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC1C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAA,oBAAS,EAAC,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;CACF;AAED,SAAS,UAAU,CAAC,GAAQ;IAC1B,OAAO,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,CAAC;AAC3F,CAAC;AAED,SAAS,WAAW,CAAC,KAAa;IAChC,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAwC;IACjE,IAAI,KAAK,YAAY,UAAU,EAAE,CAAC;QAChC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED,SAAS,qBAAqB,CAAC,KAAwB;IACrD,OAAO,OAAO,KAAK,KAAK,QAAQ;QAC9B,CAAC,CAAC,oBAAM,CAAC,IAAI,CAAC,KAAK,CAAC;QACpB,CAAC,CAAC,oBAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC;AAC5C,CAAC;AAED,SAAS,uBAAuB,CAAC,IAAkB;IACjD,IAAI,IAAI,YAAY,GAAG,EAAE,CAAC;QACxB,IAAI,IAAI,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,uDAAuD,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;QAC3F,CAAC;QACD,OAAO,IAAA,wBAAa,EAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,KAAK,UAAU,kBAAkB,CAAC,GAAQ;IACxC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,sCAAsC,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,UAAU,GAAG,CAAC,CAAC;IACzF,CAAC;IACD,OAAO,oBAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED,SAAS,gBAAgB,CAAC,MAAe;IACvC,OAAO,OAAQ,MAAkC,CAAC,SAAS,KAAK,UAAU,CAAC;AAC7E,CAAC;AAED,SAAS,eAAe,CAAC,MAAe;IACtC,OAAO,OAAQ,MAA+C,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,UAAU,CAAC;AACtG,CAAC;AAED,KAAK,UAAU,sBAAsB,CACnC,MAAyC;IAEzC,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,EAAE,CAAC;IAClC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,CAAC;QACH,SAAS,CAAC;YACR,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YAC5C,IAAI,IAAI,EAAE,CAAC;gBACT,OAAO,oBAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAC/B,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,qBAAqB,CAAC,KAAK,CAAC,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,WAAW,EAAE,CAAC;IACvB,CAAC;AACH,CAAC;AAED,KAAK,UAAU,qBAAqB,CAClC,MAAwC;IAExC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QACjC,MAAM,CAAC,IAAI,CAAC,qBAAqB,CAAC,KAAK,CAAC,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,oBAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAC/B,CAAC;AAED,KAAK,UAAU,yBAAyB,CACtC,MAA0B;IAE1B,IAAI,MAAM,YAAY,GAAG,EAAE,CAAC;QAC1B,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;YAChC,OAAO,IAAA,wBAAa,EAAC,MAAM,CAAC,CAAC;QAC/B,CAAC;QACD,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YACvB,OAAO,kBAAkB,CAAC,MAAM,CAAC,CAAC;QACpC,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,kDAAkD,MAAM,CAAC,QAAQ,GAAG,CAAC,CAAC;IACxF,CAAC;IAED,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,GAAG,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;QAChC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;YAC7B,OAAO,IAAA,wBAAa,EAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;QACD,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACpB,OAAO,kBAAkB,CAAC,GAAG,CAAC,CAAC;QACjC,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,IAAI,gBAAgB,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7B,OAAO,sBAAsB,CAAC,MAAM,CAAC,CAAC;IACxC,CAAC;IAED,IAAI,MAAM,YAAY,sBAAQ,EAAE,CAAC;QAC/B,OAAO,qBAAqB,CAAC,MAA0C,CAAC,CAAC;IAC3E,CAAC;IAED,IAAI,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5B,OAAO,qBAAqB,CAAC,MAAM,CAAC,CAAC;IACvC,CAAC;IAED,OAAO,oBAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,YAAY;IACP,MAAM,CAAsC;IAErD,YAAY,KAA0C;QACpD,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,OAAO,CAEX,KAAa,EAAE,MAAmB;QAClC,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,IAAI,IAAI,CAAC,CAAC;YAC7D,OAAO,GAAqB,CAAC;QAC/B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAA,oBAAS,EAAC,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CACJ,KAAa,EACb,MAAmB;QAEnB,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,IAAI,IAAI,CAAC,CAAC;YAC/D,OAAO,IAAI,eAAe,CAAI,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QACvD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAA,oBAAS,EAAC,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,6EAA6E;IAC7E,IAAI,CACF,KAAa,EACb,MAAmB;QAEnB,OAAO,IAAI,CAAC,MAAM,CAAI,KAAK,EAAE,MAAM,CAAC,CAAC;IACvC,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,WAAW,CAGf,UAAkC,EAClC,OAAwB,YAAY;QAEpC,IAAI,CAAC;YACH,OAAO,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,UAAU,EAAE,IAAI,CAAC,CAA0B,CAAC;QACpF,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAA,oBAAS,EAAC,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,sEAAsE;IACtE,KAAK,CAAC,KAAK;QACT,IAAI,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACtB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAA,oBAAS,EAAC,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,8CAA8C;IAC9C,KAAK,CAAC,SAAS;QACb,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;QACjC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAA,oBAAS,EAAC,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,sDAAsD;IACtD,KAAK,CAAC,iBAAiB;QACrB,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC;QACzC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAA,oBAAS,EAAC,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,OAAO;QACL,IAAI,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACxB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAA,oBAAS,EAAC,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAQD;;;;;;;OAOG;IACH,KAAK,CAAC,YAAY,CAChB,MAA8B;QAE9B,IAAI,CAAC;YACH,IAAI,MAAM,KAAK,QAAQ,IAAI,CAAC,OAAO,MAAM,KAAK,QAAQ;mBACjD,CAAC,CAAC,MAAM,YAAY,GAAG,CAAC;mBACxB,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,EAAE,CAAC;gBACjC,OAAO,IAAI,CAAC,mBAAmB,EAAE,CAAC;YACpC,CAAC;YAED,IAAI,MAAM,KAAK,QAAQ,IAAI,CAAC,OAAO,MAAM,KAAK,QAAQ;mBACjD,CAAC,CAAC,MAAM,YAAY,GAAG,CAAC;mBACxB,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,EAAE,CAAC;gBACjC,OAAO,CAAC,MAAM,IAAI,CAAC,mBAAmB,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAC/D,CAAC;YAED,IAAI,IAAkB,CAAC;YACvB,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,YAAY,GAAG,CAAC,EAAE,CAAC;gBAC3D,IAAI,MAAM,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;oBAC7B,MAAM,IAAI,KAAK,CAAC,iDAAiD,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;gBACrF,CAAC;gBACD,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;YACrB,CAAC;iBAAM,CAAC;gBACN,IAAI,GAAG,MAAM,CAAC;YAChB,CAAC;YACD,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,uBAAuB,CAAC,IAAI,CAAC,CAAiB,CAAC;QACjF,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAA,oBAAS,EAAC,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,KAAK,CAAC,mBAAmB;QACvB,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,MAAM,CAAC,mBAAmB,EAAE,CAAC;QAC3C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAA,oBAAS,EAAC,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,YAAY,CAAC,MAA0B;QAC3C,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,yBAAyB,CAAC,MAAM,CAAC,CAAC;YACzD,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;gBACjC,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAiB,CAAC;YAC5D,CAAC;YACD,OAAO,IAAI,CAAC,MAAM,CAAC,qBAAqB,CAAC,QAAQ,CAAiB,CAAC;QACrE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAA,oBAAS,EAAC,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,KAAK,CAAC,qBAAqB,CACzB,KAAwC;QAExC,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,MAAM,CAAC,qBAAqB,CACtC,oBAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC,CACtB,CAAC;QACpB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAA,oBAAS,EAAC,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;CACF;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACI,KAAK,UAAU,cAAc,CAClC,YAAqB,EACrB,UAAiC,EAAE;IAEnC,IAAI,CAAC;QACH,OAAO,IAAI,YAAY,CACrB,YAAY,KAAK,SAAS;YACxB,CAAC,CAAC,IAAI,cAAc,EAAE;YACtB,CAAC,CAAC,IAAI,cAAc,CAAC,YAAY,EAAE,OAAO,CAAC,WAAW,IAAI,IAAI,CAAC,CAClE,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAA,oBAAS,EAAC,GAAG,CAAC,CAAC;IACvB,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loradb/lora-node",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Node.js / TypeScript bindings for the Lora in-memory graph database",
   "license": "BUSL-1.1",
   "author": "LoraDB, Inc.",
@@ -89,10 +89,10 @@
     "vitest": "^2.1.1"
   },
   "optionalDependencies": {
-    "@loradb/lora-node-linux-x64-gnu": "0.3.0",
-    "@loradb/lora-node-linux-arm64-gnu": "0.3.0",
-    "@loradb/lora-node-darwin-x64": "0.3.0",
-    "@loradb/lora-node-darwin-arm64": "0.3.0",
-    "@loradb/lora-node-win32-x64-msvc": "0.3.0"
+    "@loradb/lora-node-linux-x64-gnu": "0.5.0",
+    "@loradb/lora-node-linux-arm64-gnu": "0.5.0",
+    "@loradb/lora-node-darwin-x64": "0.5.0",
+    "@loradb/lora-node-darwin-arm64": "0.5.0",
+    "@loradb/lora-node-win32-x64-msvc": "0.5.0"
   }
 }

package/ts/native.d.ts

@@ -19,17 +19,33 @@ export interface NativeSnapshotMeta {
 }
 
 export declare class Database {
-  constructor();
+  constructor(databaseName?: string | null, databaseDir?: string | null);
   /** Non-blocking: runs on the libuv threadpool, returns a Promise. */
   execute(
     query: string,
     params?: Record<string, unknown> | null,
   ): Promise<NativeQueryResult>;
+  openStream(
+    query: string,
+    params?: Record<string, unknown> | null,
+  ): number;
+  streamColumns(streamId: number): string[];
+  streamNext(streamId: number): Record<string, unknown> | null;
+  streamClose(streamId: number): void;
+  transaction(
+    statements: Array<{ query: string; params?: Record<string, unknown> | null }>,
+    mode?: "read_write" | "read_only" | "readwrite" | "readonly" | "rw" | "ro" | null,
+  ): Promise<NativeQueryResult[]>;
   clear(): void;
   nodeCount(): number;
   relationshipCount(): number;
-  /** Atomic save. Synchronous under the store mutex. */
+  dispose(): void;
+  /** Atomic save. Synchronous under the store read lock. */
   saveSnapshot(path: string): NativeSnapshotMeta;
+  /** Serialize the current graph into snapshot bytes. */
+  saveSnapshotToBytes(): Buffer;
   /** Replace the current graph with the snapshot at `path`. */
   loadSnapshot(path: string): NativeSnapshotMeta;
+  /** Replace the current graph with snapshot bytes. */
+  loadSnapshotFromBytes(bytes: Uint8Array | Buffer): NativeSnapshotMeta;
 }