@loradb/lora-wasm 0.4.0 → 0.5.0

package/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/dist/index.d.ts

@@ -1,9 +1,10 @@
 /**
  * lora-wasm — typed WebAssembly bindings for the Lora graph engine.
  *
- * This entry targets Node.js (ESM) and any bundler host whose resolver maps
- * `node:module` through. Browser consumers should prefer the Worker-backed
- * API exposed in `worker-client.ts` to keep the main thread responsive.
+ * This entry targets Node.js (ESM) and browser bundlers. In browser-like
+ * hosts, `createDatabase()` tries to start the packaged Web Worker first so
+ * query work stays off the main thread. If that fails, it warns once and
+ * falls back to the in-process WASM engine.
  *
  * **Initialization is async-only.** The one canonical entry point is
  * `createDatabase()`; the WASM module is bootstrapped inside it before the
@@ -16,8 +17,11 @@
  */
 import type { LoraParams, LoraValue, QueryResult } from "./types.js";
 import { WasmDatabase } from "./loader-node.js";
+import type { WorkerDatabase } from "./worker-client.js";
+import type { WasmSnapshotSource } from "./snapshot.js";
 export * from "./types.js";
-export { createWorkerDatabase, type WorkerDatabase } from "./worker-client.js";
+export { createWorkerDatabase, type WorkerDatabase, type WorkerLike, } from "./worker-client.js";
+export type { WasmSnapshotSaveFormat, WasmSnapshotSaveOptions, WasmSnapshotSource, } from "./snapshot.js";
 /**
  * Metadata returned by `saveSnapshotToBytes` / `loadSnapshotFromBytes`.
  * Mirrors the Rust `SnapshotMeta` struct and matches the shape used by
@@ -30,6 +34,34 @@ export interface SnapshotMeta {
     relationshipCount: number;
     walLsn: number | null;
 }
+export interface CreateDatabaseOptions {
+    /**
+     * Select where the WASM engine runs.
+     *
+     * - `"auto"` tries a Web Worker first when available, then falls back to
+     *   the main thread.
+     * - `"worker"` requires a Web Worker and rejects if startup fails.
+     * - `"main-thread"` skips Worker startup and runs the engine in-process.
+     *
+     * Defaults to `"auto"`.
+     */
+    runtime?: "auto" | "worker" | "main-thread";
+    /**
+     * Emit `console.warn` if worker startup fails and the factory falls back to
+     * the main-thread WASM engine in `"auto"` mode. Defaults to `true`.
+     */
+    warnOnFallback?: boolean;
+}
+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[] | Promise<string[]>;
+    toArray(): Promise<T[]>;
+    close(): void;
+}
 /**
  * In-memory Lora graph database running on the WASM engine.
  *
@@ -42,6 +74,9 @@ declare class DatabaseImpl {
     #private;
     constructor(inner: InstanceType<typeof WasmDatabase>);
     execute<T extends Record<string, LoraValue> = Record<string, LoraValue>>(query: string, params?: LoraParams): Promise<QueryResult<T>>;
+    stream<T extends Record<string, LoraValue> = Record<string, LoraValue>>(query: string, params?: LoraParams): RowStream<T>;
+    rows<T extends Record<string, LoraValue> = Record<string, LoraValue>>(query: string, params?: LoraParams): RowStream<T>;
+    transaction<T extends Record<string, LoraValue> = Record<string, LoraValue>>(statements: TransactionStatement[], mode?: TransactionMode): Promise<Array<QueryResult<T>>>;
     clear(): Promise<void>;
     nodeCount(): Promise<number>;
     relationshipCount(): Promise<number>;
@@ -52,11 +87,32 @@ declare class DatabaseImpl {
      * them back to `loadSnapshotFromBytes` on a future database instance.
      */
     saveSnapshotToBytes(): Promise<Uint8Array>;
+    saveSnapshot(): Promise<Uint8Array>;
+    saveSnapshot(format: "binary"): Promise<Uint8Array>;
+    saveSnapshot(format: "base64"): Promise<string>;
+    saveSnapshot(format: "blob"): Promise<Blob>;
+    saveSnapshot(format: "download"): Promise<void>;
+    saveSnapshot(options: {
+        format: "binary";
+    }): Promise<Uint8Array>;
+    saveSnapshot(options: {
+        format: "base64";
+    }): Promise<string>;
+    saveSnapshot(options: {
+        format: "blob";
+        mimeType?: string;
+    }): Promise<Blob>;
+    saveSnapshot(options: {
+        format: "download";
+        filename?: string;
+        mimeType?: string;
+    }): Promise<void>;
     /**
      * Replace the current graph state with a snapshot decoded from `bytes`.
      * Returns metadata describing the restored snapshot.
      */
     loadSnapshotFromBytes(bytes: Uint8Array): Promise<SnapshotMeta>;
+    loadSnapshot(source: WasmSnapshotSource): Promise<SnapshotMeta>;
     /** Release the underlying wasm handle. Subsequent calls will throw. */
     dispose(): void;
 }
@@ -66,14 +122,15 @@ declare class DatabaseImpl {
  * Exported as a type only — there is no runtime `Database` value. To obtain
  * an instance, always use `createDatabase()`.
  */
-export type Database = DatabaseImpl;
+export type Database = DatabaseImpl | WorkerDatabase;
 /**
  * Create and initialize a new in-memory LoraDB instance on the WASM engine.
  *
- * **This is the only supported initialization pattern** for `lora-wasm`.
- * Synchronous construction is not available — the async factory bootstraps
- * the WASM module on first call and guarantees the engine is ready before
- * the first query.
+ * In browser-like hosts this factory tries the packaged Web Worker first,
+ * pings it, and returns the worker-backed database when startup succeeds.
+ * If worker construction or bootstrap fails it warns once and falls back to
+ * the main-thread WASM engine. Pass `{ runtime: "main-thread" }` to force the
+ * in-process engine, or `{ runtime: "worker" }` to require a Worker.
  *
  * ```ts
  * import { createDatabase } from "lora-wasm";
@@ -82,9 +139,10 @@ export type Database = DatabaseImpl;
  * const res = await db.execute("MATCH (n) RETURN count(n) AS n");
  * ```
  *
- * For heavy browser workloads, use `createWorkerDatabase()` from
- * `lora-wasm/worker-client` instead — it keeps the main thread responsive
- * by running the engine in a Web Worker.
+ * Use `createMainThreadDatabase()` when you explicitly want the in-process
+ * WASM engine, or `createWorkerDatabase(worker)` when you need to supply a
+ * custom Worker instance.
  */
-export declare function createDatabase(): Promise<Database>;
+export declare function createMainThreadDatabase(): Promise<DatabaseImpl>;
+export declare function createDatabase(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;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,SAAS,EACT,WAAW,EACZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,YAAY,EAAoB,MAAM,kBAAkB,CAAC;AAElE,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAE/E;;;;;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;AASD;;;;;;;GAOG;AACH,cAAM,YAAY;;gBAGJ,KAAK,EAAE,YAAY,CAAC,OAAO,YAAY,CAAC;IAI9C,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;IASxD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC;IAI5B,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC;IAI1C;;;;;OAKG;IACG,mBAAmB,IAAI,OAAO,CAAC,UAAU,CAAC;IAQhD;;;OAGG;IACG,qBAAqB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC;IAQrE,uEAAuE;IACvE,OAAO,IAAI,IAAI;CAGhB;AAED;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,YAAY,CAAC;AAEpC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,QAAQ,CAAC,CAGxD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../ts/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,9 +1,10 @@
 /**
  * lora-wasm — typed WebAssembly bindings for the Lora graph engine.
  *
- * This entry targets Node.js (ESM) and any bundler host whose resolver maps
- * `node:module` through. Browser consumers should prefer the Worker-backed
- * API exposed in `worker-client.ts` to keep the main thread responsive.
+ * This entry targets Node.js (ESM) and browser bundlers. In browser-like
+ * hosts, `createDatabase()` tries to start the packaged Web Worker first so
+ * query work stays off the main thread. If that fails, it warns once and
+ * falls back to the in-process WASM engine.
  *
  * **Initialization is async-only.** The one canonical entry point is
  * `createDatabase()`; the WASM module is bootstrapped inside it before the
@@ -16,8 +17,70 @@
  */
 import { wrapError } from "./types.js";
 import { WasmDatabase, init as wasmInit } from "./loader-node.js";
+import { createWorkerDatabase } from "./worker-client.js";
+import { downloadSnapshotBytes, resolveSnapshotSaveFormat, snapshotBytesToBase64, snapshotBytesToBlob, snapshotSourceToBytes, } from "./snapshot.js";
 export * from "./types.js";
-export { createWorkerDatabase } from "./worker-client.js";
+export { createWorkerDatabase, } from "./worker-client.js";
+class NativeRowStream {
+    #inner;
+    #closed = false;
+    constructor(inner) {
+        this.#inner = inner;
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    columns() {
+        try {
+            return this.#inner.columns();
+        }
+        catch (err) {
+            throw wrapError(err);
+        }
+    }
+    async next() {
+        if (this.#closed) {
+            return { done: true, value: undefined };
+        }
+        try {
+            const row = this.#inner.next();
+            if (row === null) {
+                this.#closed = true;
+                return { done: true, value: undefined };
+            }
+            return { done: false, value: row };
+        }
+        catch (err) {
+            this.#closed = true;
+            throw 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.close();
+        }
+        catch (err) {
+            throw wrapError(err);
+        }
+    }
+}
 let bootstrapped = false;
 function ensureBootstrapped() {
     if (bootstrapped)
@@ -47,6 +110,27 @@ class DatabaseImpl {
             throw wrapError(err);
         }
     }
+    stream(query, params) {
+        try {
+            const native = this.#inner;
+            return new NativeRowStream(native.openStream(query, params ?? null));
+        }
+        catch (err) {
+            throw wrapError(err);
+        }
+    }
+    rows(query, params) {
+        return this.stream(query, params);
+    }
+    async transaction(statements, mode = "read_write") {
+        try {
+            const native = this.#inner;
+            return native.transaction(statements, mode);
+        }
+        catch (err) {
+            throw wrapError(err);
+        }
+    }
     async clear() {
         this.#inner.clear();
     }
@@ -70,6 +154,20 @@ class DatabaseImpl {
             throw wrapError(err);
         }
     }
+    async saveSnapshot(target) {
+        const options = resolveSnapshotSaveFormat(target);
+        const bytes = await this.saveSnapshotToBytes();
+        switch (options.format) {
+            case "binary":
+                return bytes;
+            case "base64":
+                return snapshotBytesToBase64(bytes);
+            case "blob":
+                return snapshotBytesToBlob(bytes, options.mimeType);
+            case "download":
+                return downloadSnapshotBytes(bytes, options.filename, options.mimeType);
+        }
+    }
     /**
      * Replace the current graph state with a snapshot decoded from `bytes`.
      * Returns metadata describing the restored snapshot.
@@ -82,18 +180,50 @@ class DatabaseImpl {
             throw wrapError(err);
         }
     }
+    async loadSnapshot(source) {
+        try {
+            return this.#inner.loadSnapshotFromBytes(await snapshotSourceToBytes(source));
+        }
+        catch (err) {
+            throw wrapError(err);
+        }
+    }
     /** Release the underlying wasm handle. Subsequent calls will throw. */
     dispose() {
         this.#inner.free();
     }
 }
+let warnedWorkerFallback = false;
+function requestedRuntime(options) {
+    return options?.runtime ?? "auto";
+}
+function shouldTryDefaultWorker(options) {
+    const runtime = requestedRuntime(options);
+    return runtime !== "main-thread" && typeof Worker !== "undefined";
+}
+function shouldFallbackToMainThread(options) {
+    return requestedRuntime(options) === "auto";
+}
+function warnWorkerFallback(err, options) {
+    if (options?.warnOnFallback === false || warnedWorkerFallback)
+        return;
+    warnedWorkerFallback = true;
+    const detail = err instanceof Error ? err.message : String(err);
+    console.warn(`[lora-wasm] Web Worker startup failed; falling back to main-thread WASM. ${detail}`);
+}
+function createDefaultWorker() {
+    return new Worker(new URL("./worker.js", import.meta.url), {
+        type: "module",
+    });
+}
 /**
  * Create and initialize a new in-memory LoraDB instance on the WASM engine.
  *
- * **This is the only supported initialization pattern** for `lora-wasm`.
- * Synchronous construction is not available — the async factory bootstraps
- * the WASM module on first call and guarantees the engine is ready before
- * the first query.
+ * In browser-like hosts this factory tries the packaged Web Worker first,
+ * pings it, and returns the worker-backed database when startup succeeds.
+ * If worker construction or bootstrap fails it warns once and falls back to
+ * the main-thread WASM engine. Pass `{ runtime: "main-thread" }` to force the
+ * in-process engine, or `{ runtime: "worker" }` to require a Worker.
  *
  * ```ts
  * import { createDatabase } from "lora-wasm";
@@ -102,12 +232,39 @@ class DatabaseImpl {
  * const res = await db.execute("MATCH (n) RETURN count(n) AS n");
  * ```
  *
- * For heavy browser workloads, use `createWorkerDatabase()` from
- * `lora-wasm/worker-client` instead — it keeps the main thread responsive
- * by running the engine in a Web Worker.
+ * Use `createMainThreadDatabase()` when you explicitly want the in-process
+ * WASM engine, or `createWorkerDatabase(worker)` when you need to supply a
+ * custom Worker instance.
  */
-export async function createDatabase() {
+export async function createMainThreadDatabase() {
     ensureBootstrapped();
     return new DatabaseImpl(new WasmDatabase());
 }
+export async function createDatabase(options = {}) {
+    if (shouldTryDefaultWorker(options)) {
+        let worker = null;
+        try {
+            worker = createDefaultWorker();
+            const db = createWorkerDatabase(worker);
+            await db.nodeCount();
+            return db;
+        }
+        catch (err) {
+            try {
+                worker?.terminate();
+            }
+            catch {
+                // best-effort cleanup after a failed worker startup
+            }
+            if (!shouldFallbackToMainThread(options)) {
+                throw wrapError(err);
+            }
+            warnWorkerFallback(err, options);
+        }
+    }
+    if (requestedRuntime(options) === "worker") {
+        throw wrapError(new Error("WORKER_ERROR: Web Worker is not available"));
+    }
+    return createMainThreadDatabase();
+}
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../ts/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,IAAI,IAAI,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAElE,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAuB,MAAM,oBAAoB,CAAC;AAe/E,IAAI,YAAY,GAAG,KAAK,CAAC;AACzB,SAAS,kBAAkB;IACzB,IAAI,YAAY;QAAE,OAAO;IACzB,QAAQ,EAAE,CAAC;IACX,YAAY,GAAG,IAAI,CAAC;AACtB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,YAAY;IACP,MAAM,CAAoC;IAEnD,YAAY,KAAwC;QAClD,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,KAAK,CAAC,OAAO,CAEX,KAAa,EAAE,MAAmB;QAClC,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,MAAM,IAAI,IAAI,CAAY,CAAC,CAAC;YACpE,OAAO,GAAqB,CAAC;QAC/B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,SAAS,CAAC,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IAED,KAAK,CAAC,SAAS;QACb,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,iBAAiB;QACrB,OAAO,IAAI,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC;IACzC,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,mBAAmB;QACvB,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,MAAM,CAAC,mBAAmB,EAAE,CAAC;QAC3C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,SAAS,CAAC,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,qBAAqB,CAAC,KAAiB;QAC3C,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,MAAM,CAAC,qBAAqB,CAAC,KAAK,CAAiB,CAAC;QAClE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,SAAS,CAAC,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,uEAAuE;IACvE,OAAO;QACL,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACrB,CAAC;CACF;AAUD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,kBAAkB,EAAE,CAAC;IACrB,OAAO,IAAI,YAAY,CAAC,IAAI,YAAY,EAAE,CAAC,CAAC;AAC9C,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../ts/index.ts"],"names":[],"mappings":"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"}

package/dist/snapshot.d.ts

@@ -0,0 +1,22 @@
+export type WasmSnapshotSource = string | URL | Uint8Array | ArrayBuffer | Blob | Response | ReadableStream<Uint8Array | ArrayBuffer>;
+export type WasmSnapshotSaveFormat = "binary" | "base64" | "blob" | "download";
+export type WasmSnapshotSaveOptions = {
+    format: "binary";
+} | {
+    format: "base64";
+} | {
+    format: "blob";
+    mimeType?: string;
+} | {
+    format: "download";
+    filename?: string;
+    mimeType?: string;
+};
+export type WasmSnapshotSaveTarget = WasmSnapshotSaveFormat | WasmSnapshotSaveOptions | undefined;
+export declare function bytesToUint8Array(bytes: Uint8Array | ArrayBuffer): Uint8Array;
+export declare function snapshotBytesToBase64(bytes: Uint8Array): string;
+export declare function snapshotBytesToBlob(bytes: Uint8Array, mimeType?: string): Blob;
+export declare function downloadSnapshotBytes(bytes: Uint8Array, filename?: string, mimeType?: string): void;
+export declare function resolveSnapshotSaveFormat(target: WasmSnapshotSaveTarget): WasmSnapshotSaveOptions;
+export declare function snapshotSourceToBytes(source: WasmSnapshotSource): Promise<Uint8Array>;
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../ts/snapshot.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAC1B,MAAM,GACN,GAAG,GACH,UAAU,GACV,WAAW,GACX,IAAI,GACJ,QAAQ,GACR,cAAc,CAAC,UAAU,GAAG,WAAW,CAAC,CAAC;AAC7C,MAAM,MAAM,sBAAsB,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAC/E,MAAM,MAAM,uBAAuB,GAC/B;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,GACpB;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,GACpB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AACjE,MAAM,MAAM,sBAAsB,GAC9B,sBAAsB,GACtB,uBAAuB,GACvB,SAAS,CAAC;AAKd,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,GAAG,UAAU,CAK7E;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAe/D;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,UAAU,EACjB,QAAQ,SAA6B,GACpC,IAAI,CAIN;AAED,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,UAAU,EACjB,QAAQ,SAA4B,EACpC,QAAQ,SAA6B,GACpC,IAAI,CAsCN;AAED,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,sBAAsB,GAC7B,uBAAuB,CAQzB;AAED,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,UAAU,CAAC,CAkBrB"}

package/dist/snapshot.js

@@ -0,0 +1,107 @@
+const DEFAULT_SNAPSHOT_MIME_TYPE = "application/octet-stream";
+const DEFAULT_SNAPSHOT_FILENAME = "lora-snapshot.bin";
+export function bytesToUint8Array(bytes) {
+    if (bytes instanceof Uint8Array) {
+        return bytes;
+    }
+    return new Uint8Array(bytes);
+}
+export function snapshotBytesToBase64(bytes) {
+    const buffer = globalThis.Buffer;
+    if (buffer) {
+        return buffer.from(bytes).toString("base64");
+    }
+    const chunkSize = 0x8000;
+    let binary = "";
+    for (let offset = 0; offset < bytes.byteLength; offset += chunkSize) {
+        const chunk = bytes.subarray(offset, offset + chunkSize);
+        binary += String.fromCharCode(...chunk);
+    }
+    return btoa(binary);
+}
+export function snapshotBytesToBlob(bytes, mimeType = DEFAULT_SNAPSHOT_MIME_TYPE) {
+    const copy = new Uint8Array(bytes.byteLength);
+    copy.set(bytes);
+    return new Blob([copy.buffer], { type: mimeType });
+}
+export function downloadSnapshotBytes(bytes, filename = DEFAULT_SNAPSHOT_FILENAME, mimeType = DEFAULT_SNAPSHOT_MIME_TYPE) {
+    const doc = globalThis.document;
+    const urlApi = globalThis.URL;
+    if (!doc || !urlApi?.createObjectURL) {
+        throw new Error("LORA_ERROR: snapshot download requires a browser document");
+    }
+    const url = urlApi.createObjectURL(snapshotBytesToBlob(bytes, mimeType));
+    const anchor = doc.createElement("a");
+    anchor.href = url;
+    anchor.download = filename;
+    if (anchor.style) {
+        anchor.style.display = "none";
+    }
+    doc.body?.appendChild(anchor);
+    try {
+        anchor.click();
+    }
+    finally {
+        anchor.remove?.();
+        setTimeout(() => urlApi.revokeObjectURL(url), 0);
+    }
+}
+export function resolveSnapshotSaveFormat(target) {
+    if (target === undefined) {
+        return { format: "binary" };
+    }
+    if (typeof target === "string") {
+        return { format: target };
+    }
+    return target;
+}
+export async function snapshotSourceToBytes(source) {
+    if (source instanceof Uint8Array || source instanceof ArrayBuffer) {
+        return bytesToUint8Array(source);
+    }
+    if (typeof Blob !== "undefined" && source instanceof Blob) {
+        return new Uint8Array(await source.arrayBuffer());
+    }
+    if (typeof Response !== "undefined" && source instanceof Response) {
+        return responseToBytes(source);
+    }
+    if (isReadableStream(source)) {
+        return readableStreamToBytes(source);
+    }
+    return responseToBytes(await fetch(source));
+}
+function isReadableStream(source) {
+    return typeof source.getReader === "function";
+}
+async function readableStreamToBytes(stream) {
+    const reader = stream.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) {
+                const merged = new Uint8Array(total);
+                let offset = 0;
+                for (const chunk of chunks) {
+                    merged.set(chunk, offset);
+                    offset += chunk.byteLength;
+                }
+                return merged;
+            }
+            const chunk = bytesToUint8Array(value);
+            chunks.push(chunk);
+            total += chunk.byteLength;
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+async function responseToBytes(response) {
+    if (!response.ok) {
+        throw new Error(`LORA_ERROR: snapshot fetch failed (${response.status} ${response.statusText})`);
+    }
+    return new Uint8Array(await response.arrayBuffer());
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../ts/snapshot.ts"],"names":[],"mappings":"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"}