@taladb/web 0.6.0 → 0.7.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taladb/web",
-  "version": "0.6.0",
+  "version": "0.7.3",
   "description": "TalaDB WASM bindings — document queries and vector search in the browser",
   "main": "pkg/taladb_web.js",
   "types": "pkg/taladb_web.d.ts",

package/pkg/package.json

@@ -4,8 +4,8 @@
   "collaborators": [
     "thinkgrid-labs"
   ],
-  "description": "TalaDB browser WASM bindings (wasm-bindgen + OPFS)",
-  "version": "0.6.0",
+  "description": "TalaDB browser WASM bindings (wasm-bindgen + OPFS) and Cloudflare Workers",
+  "version": "0.7.3",
   "license": "MIT",
   "files": [
     "taladb_web_bg.wasm",

package/pkg/taladb_web.d.ts

@@ -16,11 +16,11 @@ export class CollectionWasm {
     /**
      * Create a vector index on `field`.
      *
-     * `dimensions`           — expected vector length.
-     * `metric`               — optional: `"cosine"` (default), `"dot"`, or `"euclidean"`.
-     * `index_type`           — optional: `"flat"` (default) or `"hnsw"`.
-     * `hnsw_m`               — HNSW connectivity (default 16).
-     * `hnsw_ef_construction` — build quality (default 200).
+     * `dimensions`           - expected vector length.
+     * `metric`               - optional: `"cosine"` (default), `"dot"`, or `"euclidean"`.
+     * `index_type`           - optional: `"flat"` (default) or `"hnsw"`.
+     * `hnsw_m`               - HNSW connectivity (default 16).
+     * `hnsw_ef_construction` - build quality (default 200).
      */
     createVectorIndex(field: string, dimensions: number, metric?: string | null, index_type?: string | null, hnsw_m?: number | null, hnsw_ef_construction?: number | null): void;
     /**
@@ -46,7 +46,7 @@ export class CollectionWasm {
     /**
      * Find the `top_k` nearest documents to `query` on a vector index.
      *
-     * `filter` — optional pre-filter (same format as `find`). Pass `null` to
+     * `filter` - optional pre-filter (same format as `find`). Pass `null` to
      *            search across all documents that have the vector field.
      *
      * Returns a JSON array of `{ document: {...}, score: number }` objects.
@@ -108,7 +108,7 @@ export class TalaDBWasm {
      * ```js
      * const bytes = await opfs_load_snapshot('myapp.db');   // null on first open
      * const db = TalaDBWasm.openWithSnapshot(bytes);
-     * // … mutations …
+     * // ... mutations ...
      * await opfs_flush_snapshot('myapp.db', db.exportSnapshot());
      * ```
      */
@@ -119,6 +119,32 @@ export class WorkerDB {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * Compact the underlying OPFS / redb storage file, reclaiming space freed
+     * by deletes and updates.
+     *
+     * Call this during idle periods (e.g. once on app startup after tombstone
+     * compaction). No-op on in-memory (IDB-fallback) databases.
+     *
+     * ```js
+     * db.compact();
+     * ```
+     */
+    compact(): void;
+    /**
+     * Remove tombstones older than `before_ms` from the given collection.
+     *
+     * Call periodically (e.g. on app startup) after your sync retention window
+     * has elapsed so deleted document IDs no longer accumulate indefinitely.
+     * Returns the number of tombstones removed.
+     *
+     * ```js
+     * // Prune tombstones older than 30 days
+     * const cutoff = Date.now() - 30 * 24 * 60 * 60 * 1000;
+     * const pruned = db.compactTombstones('users', cutoff);
+     * ```
+     */
+    compactTombstones(collection: string, before_ms: number): number;
     /**
      * Count matching documents.
      */
@@ -148,6 +174,18 @@ export class WorkerDB {
      * Drop a vector index (and its HNSW graph if present).
      */
     dropVectorIndex(collection: string, field: string): void;
+    /**
+     * Export a changeset for the given collections since `since_ms`.
+     *
+     * Returns a JSON string representing `Vec<Change>` that can be sent
+     * to a remote peer via fetch, WebSocket, or SSE.
+     *
+     * ```js
+     * const json = db.exportChangeset(JSON.stringify(['users', 'posts']), 0);
+     * await fetch('/sync', { method: 'POST', body: json });
+     * ```
+     */
+    exportChangeset(collections_json: string, since_ms: number): string;
     /**
      * Serialize the entire in-memory database to bytes for persistence.
      *
@@ -167,6 +205,19 @@ export class WorkerDB {
      * Find one document. Returns a JSON object or `"null"`.
      */
     findOne(collection: string, filter_json: string): string;
+    /**
+     * Import a remote changeset and merge it into the local database using
+     * Last-Write-Wins conflict resolution.
+     *
+     * Returns the number of documents actually changed.
+     *
+     * ```js
+     * const resp = await fetch('/sync?since=' + lastSync);
+     * const applied = db.importChangeset(await resp.text());
+     * if (applied > 0) { rerender(); }
+     * ```
+     */
+    importChangeset(changeset_json: string): number;
     /**
      * Insert a document. Returns the new ULID as a string.
      */
@@ -175,6 +226,11 @@ export class WorkerDB {
      * Insert many documents. Returns a JSON array of ULID strings.
      */
     insertMany(collection: string, docs_json: string): string;
+    /**
+     * Returns a JSON array of all collection names in the database.
+     * Used by the Worker to build the collections list for exportChangeset.
+     */
+    listCollections(): string;
     /**
      * Returns a JSON string `{ btree: string[], fts: string[], vector: string[] }`
      * listing all indexes on the given collection.
@@ -187,7 +243,9 @@ export class WorkerDB {
     /**
      * Open a database backed by OPFS with HTTP push sync config.
      *
-     * `config_json` — JSON-serialised `TalaDbConfig`, or `null` to open without sync.
+     * Not available when compiled with the `cf-workers` feature.
+     *
+     * `config_json` - JSON-serialised `TalaDbConfig`, or `null` to open without sync.
      *
      * ```js
      * const handle = await file_handle.createSyncAccessHandle();
@@ -198,7 +256,7 @@ export class WorkerDB {
     /**
      * Open a database from an optional snapshot with HTTP push sync config.
      *
-     * `config_json` — JSON-serialised `TalaDbConfig`, or `null` to open without sync.
+     * `config_json` - JSON-serialised `TalaDbConfig`, or `null` to open without sync.
      *
      * ```js
      * const db = WorkerDB.openWithConfigAndSnapshot(snapshot, JSON.stringify(config));
@@ -208,6 +266,8 @@ export class WorkerDB {
     /**
      * Open a database backed by an OPFS `FileSystemSyncAccessHandle`.
      *
+     * Not available when compiled with the `cf-workers` feature.
+     *
      * Call sequence in the SharedWorker:
      * ```js
      * const handle = await file_handle.createSyncAccessHandle();
@@ -298,6 +358,8 @@ export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembl
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
     readonly __wbg_workerdb_free: (a: number, b: number) => void;
+    readonly workerdb_compact: (a: number) => [number, number];
+    readonly workerdb_compactTombstones: (a: number, b: number, c: number, d: number) => [number, number, number];
     readonly workerdb_count: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
     readonly workerdb_createFtsIndex: (a: number, b: number, c: number, d: number, e: number) => [number, number];
     readonly workerdb_createIndex: (a: number, b: number, c: number, d: number, e: number) => [number, number];
@@ -307,12 +369,15 @@ export interface InitOutput {
     readonly workerdb_dropFtsIndex: (a: number, b: number, c: number, d: number, e: number) => [number, number];
     readonly workerdb_dropIndex: (a: number, b: number, c: number, d: number, e: number) => [number, number];
     readonly workerdb_dropVectorIndex: (a: number, b: number, c: number, d: number, e: number) => [number, number];
+    readonly workerdb_exportChangeset: (a: number, b: number, c: number, d: number) => [number, number, number, number];
     readonly workerdb_exportSnapshot: (a: number) => [number, number, number, number];
     readonly workerdb_find: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
     readonly workerdb_findNearest: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number) => [number, number, number, number];
     readonly workerdb_findOne: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
+    readonly workerdb_importChangeset: (a: number, b: number, c: number) => [number, number, number];
     readonly workerdb_insert: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
     readonly workerdb_insertMany: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
+    readonly workerdb_listCollections: (a: number) => [number, number, number, number];
     readonly workerdb_listIndexes: (a: number, b: number, c: number) => [number, number, number, number];
     readonly workerdb_openInMemory: () => [number, number, number];
     readonly workerdb_openWithConfigAndOpfs: (a: any, b: number, c: number) => [number, number, number];
@@ -339,25 +404,25 @@ export interface InitOutput {
     readonly collectionwasm_updateMany: (a: number, b: any, c: any) => [number, number, number];
     readonly collectionwasm_updateOne: (a: number, b: any, c: any) => [number, number, number];
     readonly collectionwasm_upgradeVectorIndex: (a: number, b: number, c: number) => [number, number];
-    readonly taladbwasm_collection: (a: number, b: number, c: number) => number;
+    readonly taladbwasm_collection: (a: number, b: number, c: number) => [number, number, number];
     readonly taladbwasm_exportSnapshot: (a: number) => [number, number, number, number];
     readonly taladbwasm_openInMemory: () => [number, number, number];
     readonly taladbwasm_openWithSnapshot: (a: number, b: number) => [number, number, number];
     readonly init: () => void;
-    readonly idb_load_snapshot: (a: number, b: number) => any;
-    readonly idb_save_snapshot: (a: number, b: number, c: number, d: number) => any;
     readonly is_opfs_available: () => any;
     readonly opfs_delete_snapshot: (a: number, b: number) => any;
     readonly opfs_flush_snapshot: (a: number, b: number, c: number, d: number) => any;
     readonly opfs_load_snapshot: (a: number, b: number) => any;
+    readonly idb_load_snapshot: (a: number, b: number) => any;
+    readonly idb_save_snapshot: (a: number, b: number, c: number, d: number) => any;
     readonly opfs_open_backend: (a: number, b: number) => any;
-    readonly wasm_bindgen__closure__destroy__hf3c3b5f99d903397: (a: number, b: number) => void;
-    readonly wasm_bindgen__closure__destroy__h478053cb26acc43f: (a: number, b: number) => void;
-    readonly wasm_bindgen__closure__destroy__h1febc128ce23ccd1: (a: number, b: number) => void;
-    readonly wasm_bindgen__convert__closures_____invoke__h3022e61d849d0b12: (a: number, b: number, c: any) => [number, number];
-    readonly wasm_bindgen__convert__closures_____invoke__h470c93d8a24e0015: (a: number, b: number, c: any, d: any) => void;
-    readonly wasm_bindgen__convert__closures_____invoke__h524ec4525bd0d07f: (a: number, b: number, c: any) => void;
-    readonly wasm_bindgen__convert__closures_____invoke__h325a87e086f6f78c: (a: number, b: number) => void;
+    readonly wasm_bindgen__closure__destroy__hf5d71bc2d02a6064: (a: number, b: number) => void;
+    readonly wasm_bindgen__closure__destroy__h48e8a8f67ee293c6: (a: number, b: number) => void;
+    readonly wasm_bindgen__closure__destroy__h8b8dc50e88fa67bc: (a: number, b: number) => void;
+    readonly wasm_bindgen__convert__closures_____invoke__hfb64ebab929241fc: (a: number, b: number, c: any) => [number, number];
+    readonly wasm_bindgen__convert__closures_____invoke__h31b79bb0cf86afae: (a: number, b: number, c: any, d: any) => void;
+    readonly wasm_bindgen__convert__closures_____invoke__h57a4f572d4d576bf: (a: number, b: number, c: any) => void;
+    readonly wasm_bindgen__convert__closures_____invoke__had96e062ebd712a6: (a: number, b: number) => void;
     readonly __wbindgen_malloc: (a: number, b: number) => number;
     readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_exn_store: (a: number) => void;

package/pkg/taladb_web.js

@@ -45,11 +45,11 @@ export class CollectionWasm {
     /**
      * Create a vector index on `field`.
      *
-     * `dimensions`           — expected vector length.
-     * `metric`               — optional: `"cosine"` (default), `"dot"`, or `"euclidean"`.
-     * `index_type`           — optional: `"flat"` (default) or `"hnsw"`.
-     * `hnsw_m`               — HNSW connectivity (default 16).
-     * `hnsw_ef_construction` — build quality (default 200).
+     * `dimensions`           - expected vector length.
+     * `metric`               - optional: `"cosine"` (default), `"dot"`, or `"euclidean"`.
+     * `index_type`           - optional: `"flat"` (default) or `"hnsw"`.
+     * `hnsw_m`               - HNSW connectivity (default 16).
+     * `hnsw_ef_construction` - build quality (default 200).
      * @param {string} field
      * @param {number} dimensions
      * @param {string | null} [metric]
@@ -132,7 +132,7 @@ export class CollectionWasm {
     /**
      * Find the `top_k` nearest documents to `query` on a vector index.
      *
-     * `filter` — optional pre-filter (same format as `find`). Pass `null` to
+     * `filter` - optional pre-filter (same format as `find`). Pass `null` to
      *            search across all documents that have the vector field.
      *
      * Returns a JSON array of `{ document: {...}, score: number }` objects.
@@ -268,7 +268,10 @@ export class TalaDBWasm {
         const ptr0 = passStringToWasm0(name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         const len0 = WASM_VECTOR_LEN;
         const ret = wasm.taladbwasm_collection(this.__wbg_ptr, ptr0, len0);
-        return CollectionWasm.__wrap(ret);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return CollectionWasm.__wrap(ret[0]);
     }
     /**
      * Serialize the entire in-memory database to bytes.
@@ -308,7 +311,7 @@ export class TalaDBWasm {
      * ```js
      * const bytes = await opfs_load_snapshot('myapp.db');   // null on first open
      * const db = TalaDBWasm.openWithSnapshot(bytes);
-     * // … mutations …
+     * // ... mutations ...
      * await opfs_flush_snapshot('myapp.db', db.exportSnapshot());
      * ```
      * @param {Uint8Array | null} [snapshot]
@@ -344,6 +347,48 @@ export class WorkerDB {
         const ptr = this.__destroy_into_raw();
         wasm.__wbg_workerdb_free(ptr, 0);
     }
+    /**
+     * Compact the underlying OPFS / redb storage file, reclaiming space freed
+     * by deletes and updates.
+     *
+     * Call this during idle periods (e.g. once on app startup after tombstone
+     * compaction). No-op on in-memory (IDB-fallback) databases.
+     *
+     * ```js
+     * db.compact();
+     * ```
+     */
+    compact() {
+        const ret = wasm.workerdb_compact(this.__wbg_ptr);
+        if (ret[1]) {
+            throw takeFromExternrefTable0(ret[0]);
+        }
+    }
+    /**
+     * Remove tombstones older than `before_ms` from the given collection.
+     *
+     * Call periodically (e.g. on app startup) after your sync retention window
+     * has elapsed so deleted document IDs no longer accumulate indefinitely.
+     * Returns the number of tombstones removed.
+     *
+     * ```js
+     * // Prune tombstones older than 30 days
+     * const cutoff = Date.now() - 30 * 24 * 60 * 60 * 1000;
+     * const pruned = db.compactTombstones('users', cutoff);
+     * ```
+     * @param {string} collection
+     * @param {number} before_ms
+     * @returns {number}
+     */
+    compactTombstones(collection, before_ms) {
+        const ptr0 = passStringToWasm0(collection, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.workerdb_compactTombstones(this.__wbg_ptr, ptr0, len0, before_ms);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] >>> 0;
+    }
     /**
      * Count matching documents.
      * @param {string} collection
@@ -495,6 +540,40 @@ export class WorkerDB {
             throw takeFromExternrefTable0(ret[0]);
         }
     }
+    /**
+     * Export a changeset for the given collections since `since_ms`.
+     *
+     * Returns a JSON string representing `Vec<Change>` that can be sent
+     * to a remote peer via fetch, WebSocket, or SSE.
+     *
+     * ```js
+     * const json = db.exportChangeset(JSON.stringify(['users', 'posts']), 0);
+     * await fetch('/sync', { method: 'POST', body: json });
+     * ```
+     * @param {string} collections_json
+     * @param {number} since_ms
+     * @returns {string}
+     */
+    exportChangeset(collections_json, since_ms) {
+        let deferred3_0;
+        let deferred3_1;
+        try {
+            const ptr0 = passStringToWasm0(collections_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            const len0 = WASM_VECTOR_LEN;
+            const ret = wasm.workerdb_exportChangeset(this.__wbg_ptr, ptr0, len0, since_ms);
+            var ptr2 = ret[0];
+            var len2 = ret[1];
+            if (ret[3]) {
+                ptr2 = 0; len2 = 0;
+                throw takeFromExternrefTable0(ret[2]);
+            }
+            deferred3_0 = ptr2;
+            deferred3_1 = len2;
+            return getStringFromWasm0(ptr2, len2);
+        } finally {
+            wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+        }
+    }
     /**
      * Serialize the entire in-memory database to bytes for persistence.
      *
@@ -602,6 +681,29 @@ export class WorkerDB {
             wasm.__wbindgen_free(deferred4_0, deferred4_1, 1);
         }
     }
+    /**
+     * Import a remote changeset and merge it into the local database using
+     * Last-Write-Wins conflict resolution.
+     *
+     * Returns the number of documents actually changed.
+     *
+     * ```js
+     * const resp = await fetch('/sync?since=' + lastSync);
+     * const applied = db.importChangeset(await resp.text());
+     * if (applied > 0) { rerender(); }
+     * ```
+     * @param {string} changeset_json
+     * @returns {number}
+     */
+    importChangeset(changeset_json) {
+        const ptr0 = passStringToWasm0(changeset_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.workerdb_importChangeset(this.__wbg_ptr, ptr0, len0);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] >>> 0;
+    }
     /**
      * Insert a document. Returns the new ULID as a string.
      * @param {string} collection
@@ -658,6 +760,29 @@ export class WorkerDB {
             wasm.__wbindgen_free(deferred4_0, deferred4_1, 1);
         }
     }
+    /**
+     * Returns a JSON array of all collection names in the database.
+     * Used by the Worker to build the collections list for exportChangeset.
+     * @returns {string}
+     */
+    listCollections() {
+        let deferred2_0;
+        let deferred2_1;
+        try {
+            const ret = wasm.workerdb_listCollections(this.__wbg_ptr);
+            var ptr1 = ret[0];
+            var len1 = ret[1];
+            if (ret[3]) {
+                ptr1 = 0; len1 = 0;
+                throw takeFromExternrefTable0(ret[2]);
+            }
+            deferred2_0 = ptr1;
+            deferred2_1 = len1;
+            return getStringFromWasm0(ptr1, len1);
+        } finally {
+            wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+        }
+    }
     /**
      * Returns a JSON string `{ btree: string[], fts: string[], vector: string[] }`
      * listing all indexes on the given collection.
@@ -698,7 +823,9 @@ export class WorkerDB {
     /**
      * Open a database backed by OPFS with HTTP push sync config.
      *
-     * `config_json` — JSON-serialised `TalaDbConfig`, or `null` to open without sync.
+     * Not available when compiled with the `cf-workers` feature.
+     *
+     * `config_json` - JSON-serialised `TalaDbConfig`, or `null` to open without sync.
      *
      * ```js
      * const handle = await file_handle.createSyncAccessHandle();
@@ -720,7 +847,7 @@ export class WorkerDB {
     /**
      * Open a database from an optional snapshot with HTTP push sync config.
      *
-     * `config_json` — JSON-serialised `TalaDbConfig`, or `null` to open without sync.
+     * `config_json` - JSON-serialised `TalaDbConfig`, or `null` to open without sync.
      *
      * ```js
      * const db = WorkerDB.openWithConfigAndSnapshot(snapshot, JSON.stringify(config));
@@ -743,6 +870,8 @@ export class WorkerDB {
     /**
      * Open a database backed by an OPFS `FileSystemSyncAccessHandle`.
      *
+     * Not available when compiled with the `cf-workers` feature.
+     *
      * Call sequence in the SharedWorker:
      * ```js
      * const handle = await file_handle.createSyncAccessHandle();
@@ -1324,7 +1453,7 @@ function __wbg_get_imports() {
                     const a = state0.a;
                     state0.a = 0;
                     try {
-                        return wasm_bindgen__convert__closures_____invoke__h470c93d8a24e0015(a, state0.b, arg0, arg1);
+                        return wasm_bindgen__convert__closures_____invoke__h31b79bb0cf86afae(a, state0.b, arg0, arg1);
                     } finally {
                         state0.a = a;
                     }
@@ -1346,7 +1475,7 @@ function __wbg_get_imports() {
                     const a = state0.a;
                     state0.a = 0;
                     try {
-                        return wasm_bindgen__convert__closures_____invoke__h470c93d8a24e0015(a, state0.b, arg0, arg1);
+                        return wasm_bindgen__convert__closures_____invoke__h31b79bb0cf86afae(a, state0.b, arg0, arg1);
                     } finally {
                         state0.a = a;
                     }
@@ -1507,18 +1636,18 @@ function __wbg_get_imports() {
             return ret;
         },
         __wbindgen_cast_0000000000000001: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { dtor_idx: 156, function: Function { arguments: [Externref], shim_idx: 157, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm.wasm_bindgen__closure__destroy__hf3c3b5f99d903397, wasm_bindgen__convert__closures_____invoke__h524ec4525bd0d07f);
+            // Cast intrinsic for `Closure(Closure { dtor_idx: 137, function: Function { arguments: [Externref], shim_idx: 138, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, wasm.wasm_bindgen__closure__destroy__hf5d71bc2d02a6064, wasm_bindgen__convert__closures_____invoke__h57a4f572d4d576bf);
             return ret;
         },
         __wbindgen_cast_0000000000000002: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { dtor_idx: 170, function: Function { arguments: [], shim_idx: 171, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm.wasm_bindgen__closure__destroy__h478053cb26acc43f, wasm_bindgen__convert__closures_____invoke__h325a87e086f6f78c);
+            // Cast intrinsic for `Closure(Closure { dtor_idx: 187, function: Function { arguments: [], shim_idx: 188, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, wasm.wasm_bindgen__closure__destroy__h48e8a8f67ee293c6, wasm_bindgen__convert__closures_____invoke__had96e062ebd712a6);
             return ret;
         },
         __wbindgen_cast_0000000000000003: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { dtor_idx: 575, function: Function { arguments: [Externref], shim_idx: 576, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm.wasm_bindgen__closure__destroy__h1febc128ce23ccd1, wasm_bindgen__convert__closures_____invoke__h3022e61d849d0b12);
+            // Cast intrinsic for `Closure(Closure { dtor_idx: 629, function: Function { arguments: [Externref], shim_idx: 630, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, wasm.wasm_bindgen__closure__destroy__h8b8dc50e88fa67bc, wasm_bindgen__convert__closures_____invoke__hfb64ebab929241fc);
             return ret;
         },
         __wbindgen_cast_0000000000000004: function(arg0) {
@@ -1564,23 +1693,23 @@ function __wbg_get_imports() {
     };
 }
 
-function wasm_bindgen__convert__closures_____invoke__h325a87e086f6f78c(arg0, arg1) {
-    wasm.wasm_bindgen__convert__closures_____invoke__h325a87e086f6f78c(arg0, arg1);
+function wasm_bindgen__convert__closures_____invoke__had96e062ebd712a6(arg0, arg1) {
+    wasm.wasm_bindgen__convert__closures_____invoke__had96e062ebd712a6(arg0, arg1);
 }
 
-function wasm_bindgen__convert__closures_____invoke__h524ec4525bd0d07f(arg0, arg1, arg2) {
-    wasm.wasm_bindgen__convert__closures_____invoke__h524ec4525bd0d07f(arg0, arg1, arg2);
+function wasm_bindgen__convert__closures_____invoke__h57a4f572d4d576bf(arg0, arg1, arg2) {
+    wasm.wasm_bindgen__convert__closures_____invoke__h57a4f572d4d576bf(arg0, arg1, arg2);
 }
 
-function wasm_bindgen__convert__closures_____invoke__h3022e61d849d0b12(arg0, arg1, arg2) {
-    const ret = wasm.wasm_bindgen__convert__closures_____invoke__h3022e61d849d0b12(arg0, arg1, arg2);
+function wasm_bindgen__convert__closures_____invoke__hfb64ebab929241fc(arg0, arg1, arg2) {
+    const ret = wasm.wasm_bindgen__convert__closures_____invoke__hfb64ebab929241fc(arg0, arg1, arg2);
     if (ret[1]) {
         throw takeFromExternrefTable0(ret[0]);
     }
 }
 
-function wasm_bindgen__convert__closures_____invoke__h470c93d8a24e0015(arg0, arg1, arg2, arg3) {
-    wasm.wasm_bindgen__convert__closures_____invoke__h470c93d8a24e0015(arg0, arg1, arg2, arg3);
+function wasm_bindgen__convert__closures_____invoke__h31b79bb0cf86afae(arg0, arg1, arg2, arg3) {
+    wasm.wasm_bindgen__convert__closures_____invoke__h31b79bb0cf86afae(arg0, arg1, arg2, arg3);
 }
 
 

package/pkg/taladb_web_bg.wasm.d.ts

@@ -2,6 +2,8 @@
 /* eslint-disable */
 export const memory: WebAssembly.Memory;
 export const __wbg_workerdb_free: (a: number, b: number) => void;
+export const workerdb_compact: (a: number) => [number, number];
+export const workerdb_compactTombstones: (a: number, b: number, c: number, d: number) => [number, number, number];
 export const workerdb_count: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
 export const workerdb_createFtsIndex: (a: number, b: number, c: number, d: number, e: number) => [number, number];
 export const workerdb_createIndex: (a: number, b: number, c: number, d: number, e: number) => [number, number];
@@ -11,12 +13,15 @@ export const workerdb_deleteOne: (a: number, b: number, c: number, d: number, e:
 export const workerdb_dropFtsIndex: (a: number, b: number, c: number, d: number, e: number) => [number, number];
 export const workerdb_dropIndex: (a: number, b: number, c: number, d: number, e: number) => [number, number];
 export const workerdb_dropVectorIndex: (a: number, b: number, c: number, d: number, e: number) => [number, number];
+export const workerdb_exportChangeset: (a: number, b: number, c: number, d: number) => [number, number, number, number];
 export const workerdb_exportSnapshot: (a: number) => [number, number, number, number];
 export const workerdb_find: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
 export const workerdb_findNearest: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number) => [number, number, number, number];
 export const workerdb_findOne: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
+export const workerdb_importChangeset: (a: number, b: number, c: number) => [number, number, number];
 export const workerdb_insert: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
 export const workerdb_insertMany: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
+export const workerdb_listCollections: (a: number) => [number, number, number, number];
 export const workerdb_listIndexes: (a: number, b: number, c: number) => [number, number, number, number];
 export const workerdb_openInMemory: () => [number, number, number];
 export const workerdb_openWithConfigAndOpfs: (a: any, b: number, c: number) => [number, number, number];
@@ -43,25 +48,25 @@ export const collectionwasm_insertMany: (a: number, b: any) => [number, number,
 export const collectionwasm_updateMany: (a: number, b: any, c: any) => [number, number, number];
 export const collectionwasm_updateOne: (a: number, b: any, c: any) => [number, number, number];
 export const collectionwasm_upgradeVectorIndex: (a: number, b: number, c: number) => [number, number];
-export const taladbwasm_collection: (a: number, b: number, c: number) => number;
+export const taladbwasm_collection: (a: number, b: number, c: number) => [number, number, number];
 export const taladbwasm_exportSnapshot: (a: number) => [number, number, number, number];
 export const taladbwasm_openInMemory: () => [number, number, number];
 export const taladbwasm_openWithSnapshot: (a: number, b: number) => [number, number, number];
 export const init: () => void;
-export const idb_load_snapshot: (a: number, b: number) => any;
-export const idb_save_snapshot: (a: number, b: number, c: number, d: number) => any;
 export const is_opfs_available: () => any;
 export const opfs_delete_snapshot: (a: number, b: number) => any;
 export const opfs_flush_snapshot: (a: number, b: number, c: number, d: number) => any;
 export const opfs_load_snapshot: (a: number, b: number) => any;
+export const idb_load_snapshot: (a: number, b: number) => any;
+export const idb_save_snapshot: (a: number, b: number, c: number, d: number) => any;
 export const opfs_open_backend: (a: number, b: number) => any;
-export const wasm_bindgen__closure__destroy__hf3c3b5f99d903397: (a: number, b: number) => void;
-export const wasm_bindgen__closure__destroy__h478053cb26acc43f: (a: number, b: number) => void;
-export const wasm_bindgen__closure__destroy__h1febc128ce23ccd1: (a: number, b: number) => void;
-export const wasm_bindgen__convert__closures_____invoke__h3022e61d849d0b12: (a: number, b: number, c: any) => [number, number];
-export const wasm_bindgen__convert__closures_____invoke__h470c93d8a24e0015: (a: number, b: number, c: any, d: any) => void;
-export const wasm_bindgen__convert__closures_____invoke__h524ec4525bd0d07f: (a: number, b: number, c: any) => void;
-export const wasm_bindgen__convert__closures_____invoke__h325a87e086f6f78c: (a: number, b: number) => void;
+export const wasm_bindgen__closure__destroy__hf5d71bc2d02a6064: (a: number, b: number) => void;
+export const wasm_bindgen__closure__destroy__h48e8a8f67ee293c6: (a: number, b: number) => void;
+export const wasm_bindgen__closure__destroy__h8b8dc50e88fa67bc: (a: number, b: number) => void;
+export const wasm_bindgen__convert__closures_____invoke__hfb64ebab929241fc: (a: number, b: number, c: any) => [number, number];
+export const wasm_bindgen__convert__closures_____invoke__h31b79bb0cf86afae: (a: number, b: number, c: any, d: any) => void;
+export const wasm_bindgen__convert__closures_____invoke__h57a4f572d4d576bf: (a: number, b: number, c: any) => void;
+export const wasm_bindgen__convert__closures_____invoke__had96e062ebd712a6: (a: number, b: number) => void;
 export const __wbindgen_malloc: (a: number, b: number) => number;
 export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
 export const __wbindgen_exn_store: (a: number) => void;

package/worker/taladb.worker.js

@@ -48,6 +48,11 @@
  * dropVectorIndex   { collection, field }
  * upgradeVectorIndex { collection, field }
  * findNearest       { collection, field, queryJson, topK, filterJson? }
+ * listCollections   {}                             → JSON string[]
+ * compact           {}                             → null
+ * compactTombstones { collection, beforeMs }       → number pruned
+ * exportChangeset   { collectionsJson, sinceMs? }  → JSON changeset string
+ * importChangeset   { changesetJson }              → number of applied changes
  * close             {}
  *
  * Multi-tab live queries (BroadcastChannel)
@@ -57,6 +62,16 @@
  * `"taladb:<dbName>"`.  Other tabs listening on the same channel re-trigger
  * their active `subscribe()` pollers immediately, bypassing the 300 ms tick.
  *
+ * Secondary-tab write propagation
+ * --------------------------------
+ * Fallback (non-OPFS) tabs can also make writes that need to reach the primary
+ * tab's OPFS-backed database.  After every mutating op a fallback tab exports a
+ * mini-changeset (all collections, since the previous sync point) and posts it
+ * as `{ type: 'taladb:secondary-write', changeset }` on the BroadcastChannel.
+ * The primary (OPFS) tab receives it, calls importChangeset(), and runs the
+ * normal onWriteCommitted() path — so all other tabs are notified and the OPFS
+ * file stays authoritative.  LWW merge handles any concurrent edits.
+ *
  * IndexedDB fallback (no OPFS)
  * ----------------------------
  * When OPFS is unavailable (cross-origin iframes, Firefox without storage
@@ -130,6 +145,14 @@ let broadcastChannel = null;
  */
 let idbFallback = false;
 
+/**
+ * Timestamp (ms) of the last changeset we exported and broadcast to the
+ * primary tab.  Used as `sinceMs` for the next export so we only send the
+ * delta, not the entire database on every write.
+ * @type {number}
+ */
+let lastSecondaryPushMs = 0;
+
 // ---------------------------------------------------------------------------
 // IndexedDB helpers (used only when OPFS is unavailable)
 // ---------------------------------------------------------------------------
@@ -193,20 +216,97 @@ async function idbSaveSnapshot(dbName, bytes) {
   } catch { /* best-effort persistence — ignore failures */ }
 }
 
+// ---------------------------------------------------------------------------
+// Debounced IDB snapshot
+// ---------------------------------------------------------------------------
+
 /**
- * Notify sibling tabs of a write and, when in IDB-fallback mode, flush the
- * updated snapshot to IndexedDB.  Must be called after every mutating op.
+ * Debounce + max-interval parameters for IDB snapshot persistence.
+ *
+ * On every write we notify sibling tabs immediately via BroadcastChannel,
+ * but we defer the actual IDB persistence so that bulk inserts (insertMany,
+ * rapid sequential inserts) only produce a single IDB write rather than one
+ * per document.  A max-interval cap ensures data is never more than 5 s stale
+ * in IDB even under continuous write load.
  */
-function onWriteCommitted() {
-  broadcastChannel?.postMessage('taladb:changed');
-  // Always flush a snapshot to IDB after every write — this keeps other tabs'
-  // IDB-fallback instances in sync via BroadcastChannel + snapshotDirty reload.
+const SNAPSHOT_DEBOUNCE_MS = 500;
+const SNAPSHOT_MAX_INTERVAL_MS = 5000;
+
+/** setTimeout handle for the pending debounced flush. */
+let snapshotTimer = null;
+
+/** Timestamp of the last completed IDB flush (ms since epoch). */
+let lastSnapshotMs = 0;
+
+/** Perform the IDB snapshot write and reset state. */
+async function flushSnapshot() {
+  clearTimeout(snapshotTimer);
+  snapshotTimer = null;
+  lastSnapshotMs = Date.now();
   if (db && activeDbName) {
     try {
       const bytes = db.exportSnapshot();
-      idbSaveSnapshot(activeDbName, bytes).catch(() => {});
-    } catch { /* ignore snapshot export errors */ }
+      await idbSaveSnapshot(activeDbName, bytes);
+    } catch { /* best-effort — ignore failures */ }
+  }
+}
+
+/**
+ * Schedule (or immediately trigger) an IDB snapshot write.
+ *
+ * - If the last flush was more than SNAPSHOT_MAX_INTERVAL_MS ago, flush now.
+ * - Otherwise debounce: reset the timer to fire SNAPSHOT_DEBOUNCE_MS from now.
+ */
+function scheduleSnapshot() {
+  const now = Date.now();
+  if (now - lastSnapshotMs > SNAPSHOT_MAX_INTERVAL_MS) {
+    // Overdue — flush synchronously in the microtask queue.
+    flushSnapshot().catch(() => {});
+    return;
   }
+  clearTimeout(snapshotTimer);
+  snapshotTimer = setTimeout(() => { flushSnapshot().catch(() => {}); }, SNAPSHOT_DEBOUNCE_MS);
+}
+
+/**
+ * When running as a fallback (non-OPFS) tab, export the changes made since
+ * the last push and broadcast them to the primary tab for merging into OPFS.
+ *
+ * Uses exportChangeset with all known collections to keep the delta small.
+ * The primary tab's BroadcastChannel handler calls importChangeset() and runs
+ * its own onWriteCommitted(), which notifies all tabs (including this one) via
+ * taladb:changed so reads stay consistent.
+ */
+function pushChangesetToPrimary() {
+  if (!idbFallback || !db || !broadcastChannel || !activeDbName) return;
+  try {
+    // Collect all collection names from the current in-memory state.
+    // exportChangeset accepts a JSON array of collection names.
+    const collections = db.listCollections();
+    const changeset = db.exportChangeset(collections, lastSecondaryPushMs);
+    // Only broadcast if there is actually something to send.
+    const parsed = JSON.parse(changeset);
+    if (parsed.length === 0) return;
+    lastSecondaryPushMs = Date.now();
+    broadcastChannel.postMessage({ type: 'taladb:secondary-write', changeset });
+    log(`Broadcast ${parsed.length} change(s) to primary tab`);
+  } catch (err) {
+    warn('Failed to export changeset for primary tab:', err);
+  }
+}
+
+/**
+ * Notify sibling tabs of a write and schedule IDB persistence.
+ * Must be called after every mutating op.
+ */
+function onWriteCommitted() {
+  broadcastChannel?.postMessage('taladb:changed');
+  // Fallback tab: push local changes to the primary (OPFS) tab so they are
+  // merged into the authoritative database file.
+  pushChangesetToPrimary();
+  // Debounced IDB flush — keeps other tabs' fallback instances in sync via
+  // BroadcastChannel + snapshotDirty reload without writing to IDB on every op.
+  scheduleSnapshot();
 }
 
 // ---------------------------------------------------------------------------
@@ -357,7 +457,36 @@ async function dispatch(op, args) {
         args.filterJson ?? 'null',
       );
 
+    case 'listCollections':
+      return db.listCollections();
+
+    case 'compact':
+      // Compact the storage file, reclaiming freed space. No-op on IDB fallback.
+      db.compact();
+      return null;
+
+    case 'compactTombstones':
+      // Prune tombstones older than beforeMs from a collection.
+      // Returns the count of tombstones removed.
+      return db.compactTombstones(args.collection, args.beforeMs ?? 0);
+
+    case 'exportChangeset':
+      // Export a LWW changeset for the given collections since sinceMs.
+      // Returns a JSON string the caller can POST to a sync server.
+      return db.exportChangeset(args.collectionsJson, args.sinceMs ?? 0);
+
+    case 'importChangeset': {
+      // Apply a remote changeset (JSON string from sync server) using LWW.
+      // Triggers onWriteCommitted so multi-tab peers get notified.
+      const applied = db.importChangeset(args.changesetJson);
+      if (applied > 0) onWriteCommitted();
+      return applied;
+    }
+
     case 'close':
+      // Flush any pending debounced snapshot before releasing the lock so
+      // no writes are lost when the tab closes or navigates away.
+      await flushSnapshot();
       // Release the Web Lock and close the sync handle gracefully.
       if (releaseLock) { releaseLock(); releaseLock = null; }
       broadcastChannel?.close();
@@ -376,7 +505,7 @@ async function dispatch(op, args) {
 // ---------------------------------------------------------------------------
 
 async function doInit(dbName, configJson) {
-  const wasm = await import('../pkg/taladb_web.js');
+  const wasm = await import(/* @vite-ignore */ '../pkg/taladb_web.js');
   await wasm.default();
 
   // Hoist to module scope so snapshot reloads in dispatch() can use it.
@@ -402,6 +531,17 @@ async function doInit(dbName, configJson) {
         const resolve = pendingSnapshotResolve;
         pendingSnapshotResolve = null;
         resolve();
+      } else if (e.data?.type === 'taladb:secondary-write' && !idbFallback && db) {
+        // Primary (OPFS) tab: a secondary tab made a write — merge it in via LWW.
+        try {
+          const applied = db.importChangeset(e.data.changeset);
+          if (applied > 0) {
+            log(`Merged ${applied} change(s) from secondary tab`);
+            onWriteCommitted();
+          }
+        } catch (err) {
+          warn('Failed to import secondary-tab changeset:', err);
+        }
       }
     };
     log('BroadcastChannel opened:', `taladb:${dbName}`);