@moltendb-web/core 1.5.0 → 1.6.0

package/README.md

@@ -11,7 +11,7 @@
   [![NPM Version](https://img.shields.io/npm/v/@moltendb-web/core?style=flat-square&color=orange)](https://www.npmjs.com/package/@moltendb-web/core)
   [![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE.md)
   [![WASM](https://img.shields.io/badge/wasm-optimized-magenta?style=flat-square)](https://webassembly.org/)
-  [![Status](https://img.shields.io/badge/status-release%20candidate-brightgreen?style=flat-square)]()
+  [![Status](https://img.shields.io/badge/status-stable-brightgreen?style=flat-square)]()
 
 </div>
 
@@ -23,7 +23,7 @@ MoltenDb is a JSON document database written in Rust that runs directly in your
 
 Beyond being a full-featured embedded database, MoltenDb can also serve as a **persistent state manager** for your application. Because all data is written to OPFS, your app's state survives page reloads, browser crashes, and unexpected connection loss — your users will never lose their work.
 
-> **🚀 Release Candidate 2** — The core engine, multi-tab sync, storage layer, and **transparent at-rest encryption** are feature-complete and stabilised. Server sync and analytics are planned for a future release.
+> **✅ Stable** — The core engine, multi-tab sync, storage layer, and **transparent at-rest encryption** are feature-complete and stabilised. Server sync and analytics are planned for a future release.
 
 ### 🎮 Explore the Full Functionality
 
@@ -220,6 +220,8 @@ MoltenDb supports a variety of operators in the `where` clause:
 | `$contains` | `$ct` | Substring check (string) or membership check (array) |
 | `$in` | `$oneOf` | Field value is one of a list |
 | `$nin` | `$notIn` | Field value is not in a list |
+| `$or` | | At least one of the sub-conditions must match (array of where-style objects) |
+| `$and` | | All sub-conditions must match (array of where-style objects) |
 
 // Inline reference embedding (`extends`)
 
@@ -266,15 +268,15 @@ await db.init();
 
 ### Options Reference
 
-| Property | Type | Default | Description |
-| :--- | :--- | :--- | :--- |
-| `hotThreshold` | `number` | `50000` | **Hybrid Bitcask Limit:** Maximum documents per collection to keep in RAM. When exceeded, the oldest documents are paged out to OPFS to save memory. |
-| `encryptionKey` | `string` | `undefined` | **At-Rest Encryption:** If provided, all data written to OPFS is encrypted using XChaCha20-Poly1305. If omitted, data is stored as plain JSON. |
+| Property | Type | Default | Description                                                                                                                                                                                                                                                      |
+| :--- | :--- | :--- |:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `hotThreshold` | `number` | `50000` | **Hybrid Bitcask Limit:** Maximum documents per collection to keep in RAM. When exceeded, the oldest documents are paged out to OPFS to save memory.                                                                                                             |
+| `encryptionKey` | `string` | `undefined` | **At-Rest Encryption:** If provided, all data written to OPFS is encrypted using XChaCha20-Poly1305. If omitted, data is stored as plain JSON.                                                                                                                   |
 | `writeMode` | `'async' \| 'sync'` | `'async'` | **Durability vs Speed:** `'async'` is blazing fast (high throughput), while `'sync'` ensures every write is flushed to disk before returning (safer but slower). **Note:** `async` is recommended for most web apps to avoid blocking during heavy write bursts. |
-| `workerUrl` | `string \| URL` | `undefined` | Custom path to the Web Worker script. |
-| `maxBodySize` | `number` | `10485760` | **Payload Limit:** Max body size in bytes. Prevents memory spikes from large messages. |
-| `rateLimitRequests`| `number` | `100` | (Server Parity/Safety) Max requests allowed per rate-limit window. |
-| `rateLimitWindow` | `number` | `60` | (Server Parity/Safety) Size of the rate-limit window in seconds. |
+| `workerUrl` | `string \| URL` | `undefined` | Custom path to the Web Worker script.                                                                                                                                                                                                                            |
+| `maxBodySize` | `number` | `10485760` | **Payload Limit:** Max body size in bytes. Prevents memory spikes from large messages.                                                                                                                                                                           |
+| `maxKeysPerRequest` | `number` | `1000` | **Batch Limit:** Maximum number of keys allowed per JSON request.                                                                                                                                                                                                |
+| `inMemory` | `boolean` | `false` | **Ephemeral Mode:** Run entirely in RAM — no OPFS writes, no WAL. All data is lost when **any** tab refreshes or closes. Ideal for CI environments and ephemeral caches.                                                                                         |
 
 ---
 ## Storage Architecture
@@ -394,16 +396,16 @@ This monorepo contains the following packages:
 
 ## Roadmap
 
-- [x] **Multi-Tab Sync:** Leader election for multiple tabs to share a single OPFS instance — **stabilised in RC1**.
-- [x] **Automatic Compaction:** Log compacts automatically at 500 entries or 5 MB — **stabilised in RC1**.
-- [x] **Rich Test Suite:** 50 unit, integration, and stress tests via Vitest — **stabilised in RC1**.
+- [x] **Multi-Tab Sync:** Leader election for multiple tabs to share a single OPFS instance.
+- [x] **Automatic Compaction:** Log compacts automatically at 500 entries or 5 MB.
+- [x] **Rich Test Suite:** 50 unit, integration, and stress tests via Vitest.
 - [ ] **React Adapter:** Official `@moltendb-web/react` package with `useQuery` hooks and real-time context providers.
 - [x] **Angular Adapter:** Official `@moltendb-web/angular` package featuring Signal-based data fetching.
 - [ ] **Delta Sync:** Automatic two-way sync with the MoltenDb Rust server.
-- [x] **Data Encryption:** Transparent encryption-at-rest using hardware-backed keys (Argon2id + XChaCha20) — **stabilised in RC2**.
-- [x] **Hybrid Bitcask:** Seamlessly handle datasets larger than RAM by paging docs to OPFS — **stabilised in RC2**.
+- [x] **Data Encryption:** Transparent encryption-at-rest using hardware-backed keys (Argon2id + XChaCha20).
+- [x] **Hybrid Bitcask:** Seamlessly handle datasets larger than RAM by paging docs to OPFS.
 - [ ] **Analytics Functionality:** Run complex analytics queries straight in the browser without blocking the UI.
-- [x] **Configurable Limits:** User-defined RAM thresholds and request body sizes for edge and browser environments — **stabilised in RC2**.
+- [x] **Configurable Limits:** User-defined RAM thresholds and request body sizes for edge and browser environments.
 
 
 ## Contributing & Feedback

package/dist/index.d.ts

@@ -7,12 +7,20 @@ export interface MoltenDbOptions {
     encryptionKey?: string;
     /** Storage write mode: 'async' (default, high throughput) or 'sync' (durable). */
     writeMode?: 'async' | 'sync';
-    /** (Server only) Max requests per IP per rate-limit window. */
-    rateLimitRequests?: number;
-    /** (Server only) Rate-limit window size in seconds. */
-    rateLimitWindow?: number;
-    /** (Server only) Maximum request body size in bytes. */
+    /**  Maximum request body size in bytes. */
     maxBodySize?: number;
+    /** Maximum number of keys allowed per JSON request. Default: 1000. */
+    maxKeysPerRequest?: number;
+    /**
+     * Run entirely in RAM — no OPFS writes.
+     *
+     * All tabs share a single in-memory store via the leader/follower election.
+     * Data persists as long as at least one tab is open.
+     * When **any** tab refreshes or closes, the shared RAM store is wiped for all tabs.
+     *
+     * Default: false.
+     */
+    inMemory?: boolean;
 }
 export interface DbEvent {
     type: 'event';

package/dist/index.js

@@ -46,7 +46,17 @@ export class MoltenDb {
         // 1. If initialization has already started or finished, return the existing promise
         if (this.initPromise)
             return this.initPromise;
-        // 2. Otherwise, start the initialization and store the promise
+        // 2. When running in-memory, any tab refresh should wipe the shared RAM store.
+        //    Broadcast a clear_all signal on beforeunload so the leader can wipe the Rust DashMap.
+        if (this.options.inMemory) {
+            window.addEventListener('beforeunload', () => {
+                try {
+                    this.bc?.postMessage({ type: 'clear_all' });
+                }
+                catch { }
+            });
+        }
+        // 3. Otherwise, start the initialization and store the promise
         this.initPromise = new Promise((resolveInit, rejectInit) => {
             this.bc = new BroadcastChannel(`moltendb_channel_${this.dbName}`);
             navigator.locks.request(`moltendb_lock_${this.dbName}`, { ifAvailable: true }, async (lock) => {
@@ -76,12 +86,14 @@ export class MoltenDb {
     }
     async startAsLeader() {
         // Guard: OPFS is required
-        try {
-            await navigator.storage.getDirectory();
-        }
-        catch {
-            throw new Error('[MoltenDb] Origin Private File System (OPFS) is not available in this browser context. ' +
-                'Try a non-private window or a browser that supports OPFS (Chrome 102+, Firefox 111+, Safari 15.2+).');
+        if (!this.options.inMemory) {
+            try {
+                await navigator.storage.getDirectory();
+            }
+            catch {
+                throw new Error('[MoltenDb] Origin Private File System (OPFS) is not available in this browser context. ' +
+                    'Try a non-private window or a browser that supports OPFS (Chrome 102+, Firefox 111+, Safari 15.2+).');
+            }
         }
         this.isLeader = true;
         if (this.worker)
@@ -107,15 +119,27 @@ export class MoltenDb {
         // Wait for worker to boot
         await this.sendMessage('init', {
             dbName: this.dbName,
-            hotThreshold: this.options.hotThreshold,
             encryptionKey: this.options.encryptionKey,
-            writeMode: this.options.writeMode,
-            rateLimitRequests: this.options.rateLimitRequests,
-            rateLimitWindow: this.options.rateLimitWindow,
+            hotThreshold: this.options.hotThreshold,
+            inMemory: this.options.inMemory,
             maxBodySize: this.options.maxBodySize,
+            maxKeysPerRequest: this.options.maxKeysPerRequest,
+            writeMode: this.options.writeMode,
         });
         this.bc.onmessage = async (e) => {
             const msg = e.data;
+            // Any tab unloading in in-memory mode broadcasts this — wipe the shared RAM store.
+            if (msg.type === 'clear_all') {
+                try {
+                    await this.sendMessage('clear', {});
+                    this.bc.postMessage({ type: 'cleared' });
+                    console.log('[MoltenDb] In-memory store wiped (tab unloaded).');
+                }
+                catch (err) {
+                    console.warn('[MoltenDb] Failed to clear in-memory store:', err);
+                }
+                return;
+            }
             if (msg.type === 'query' && msg.action) {
                 try {
                     const result = await this.sendMessage(msg.action, msg.payload);
@@ -139,6 +163,15 @@ export class MoltenDb {
                 this.dispatchEvent(data); // ⬅️ Trigger new dispatcher
                 return;
             }
+            // In-memory wipe notification from leader — reject all in-flight requests.
+            if (data.type === 'cleared') {
+                console.log('[MoltenDb] In-memory store was wiped by another tab.');
+                for (const [id, req] of this.pendingRequests) {
+                    req.reject(new Error('[MoltenDb] In-memory store was cleared by a tab reload.'));
+                    this.pendingRequests.delete(id);
+                }
+                return;
+            }
             if (data.type === 'response') {
                 const req = this.pendingRequests.get(data.id);
                 if (req) {

package/dist/moltendb-worker.js

@@ -9,7 +9,7 @@ self.onmessage = async (e) => {
             initPromise = (async () => {
                 await init();
                 // Pass all config flags to Rust
-                const instance = await WorkerDb.create(payload.dbName, payload.hotThreshold, payload.encryptionKey, payload.writeMode, payload.rateLimitRequests, payload.rateLimitWindow, payload.maxBodySize);
+                const instance = await WorkerDb.create(payload.dbName, payload.hotThreshold, payload.encryptionKey, payload.writeMode, payload.maxBodySize, payload.maxKeysPerRequest, payload.inMemory);
                 // Listen to Rust and broadcast events
                 instance.subscribe((eventStr) => {
                     try {

package/dist/wasm/moltendb_core.d.ts

@@ -59,11 +59,13 @@ export class WorkerDb {
      * * `hot_threshold` — Optional maximum documents per collection to keep in RAM (default: 50,000).
      * * `encryption_key` — Optional password for at-rest encryption.
      * * `write_mode` — Optional write mode: "async" (default) or "sync".
-     * * `rate_limit_requests` — Optional max requests per window (default: 100).
-     * * `rate_limit_window` — Optional window size in seconds (default: 60).
      * * `max_body_size` — Optional maximum request body size in bytes (default: 10MB).
+     * * `max_keys_per_request` — Optional maximum keys allowed per request (default: 1000).
+     * * `in_memory` — Optional flag to run entirely in RAM with no OPFS writes (default: false).
+     *   When `true`, all data is lost when the worker is terminated — useful for ephemeral
+     *   session caches or testing without touching OPFS storage.
      */
-    static create(db_name: string, hot_threshold?: number | null, encryption_key?: string | null, write_mode?: string | null, rate_limit_requests?: number | null, rate_limit_window?: bigint | null, max_body_size?: number | null): Promise<WorkerDb>;
+    static create(db_name: string, hot_threshold?: number | null, encryption_key?: string | null, write_mode?: string | null, max_body_size?: number | null, max_keys_per_request?: number | null, in_memory?: boolean | null): Promise<WorkerDb>;
     /**
      * Route an incoming message from the JavaScript worker to the correct handler.
      *
@@ -80,6 +82,7 @@ export class WorkerDb {
      *   - "delete"   → delete documents or drop:   { collection, keys: ... } or { drop: true }
      *   - "compact"  → compact the OPFS log file
      *   - "get_size" → return current OPFS file size in bytes
+     *   - "clear"    → wipe all in-memory state (in-memory mode only)
      *
      * Returns a JsValue result on success, or a JsValue error string on failure.
      */
@@ -98,11 +101,11 @@ export interface InitOutput {
     readonly memory: WebAssembly.Memory;
     readonly __wbg_workerdb_free: (a: number, b: number) => void;
     readonly workerdb_analytics: (a: number, b: number, c: number, d: number) => void;
-    readonly workerdb_create: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: bigint, k: number) => number;
+    readonly workerdb_create: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number) => number;
     readonly workerdb_handle_message: (a: number, b: number, c: number) => void;
     readonly workerdb_subscribe: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_4053: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_4065: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_4220: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_4230: (a: number, b: number, c: number, d: number) => void;
     readonly __wbindgen_export: (a: number, b: number) => number;
     readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_export3: (a: number) => void;

package/dist/wasm/moltendb_core.js

@@ -91,26 +91,28 @@ export class WorkerDb {
      * * `hot_threshold` — Optional maximum documents per collection to keep in RAM (default: 50,000).
      * * `encryption_key` — Optional password for at-rest encryption.
      * * `write_mode` — Optional write mode: "async" (default) or "sync".
-     * * `rate_limit_requests` — Optional max requests per window (default: 100).
-     * * `rate_limit_window` — Optional window size in seconds (default: 60).
      * * `max_body_size` — Optional maximum request body size in bytes (default: 10MB).
+     * * `max_keys_per_request` — Optional maximum keys allowed per request (default: 1000).
+     * * `in_memory` — Optional flag to run entirely in RAM with no OPFS writes (default: false).
+     *   When `true`, all data is lost when the worker is terminated — useful for ephemeral
+     *   session caches or testing without touching OPFS storage.
      * @param {string} db_name
      * @param {number | null} [hot_threshold]
      * @param {string | null} [encryption_key]
      * @param {string | null} [write_mode]
-     * @param {number | null} [rate_limit_requests]
-     * @param {bigint | null} [rate_limit_window]
      * @param {number | null} [max_body_size]
+     * @param {number | null} [max_keys_per_request]
+     * @param {boolean | null} [in_memory]
      * @returns {Promise<WorkerDb>}
      */
-    static create(db_name, hot_threshold, encryption_key, write_mode, rate_limit_requests, rate_limit_window, max_body_size) {
+    static create(db_name, hot_threshold, encryption_key, write_mode, max_body_size, max_keys_per_request, in_memory) {
         const ptr0 = passStringToWasm0(db_name, wasm.__wbindgen_export, wasm.__wbindgen_export2);
         const len0 = WASM_VECTOR_LEN;
         var ptr1 = isLikeNone(encryption_key) ? 0 : passStringToWasm0(encryption_key, wasm.__wbindgen_export, wasm.__wbindgen_export2);
         var len1 = WASM_VECTOR_LEN;
         var ptr2 = isLikeNone(write_mode) ? 0 : passStringToWasm0(write_mode, wasm.__wbindgen_export, wasm.__wbindgen_export2);
         var len2 = WASM_VECTOR_LEN;
-        const ret = wasm.workerdb_create(ptr0, len0, isLikeNone(hot_threshold) ? 0x100000001 : (hot_threshold) >>> 0, ptr1, len1, ptr2, len2, isLikeNone(rate_limit_requests) ? 0x100000001 : (rate_limit_requests) >>> 0, !isLikeNone(rate_limit_window), isLikeNone(rate_limit_window) ? BigInt(0) : rate_limit_window, isLikeNone(max_body_size) ? 0x100000001 : (max_body_size) >>> 0);
+        const ret = wasm.workerdb_create(ptr0, len0, isLikeNone(hot_threshold) ? 0x100000001 : (hot_threshold) >>> 0, ptr1, len1, ptr2, len2, isLikeNone(max_body_size) ? 0x100000001 : (max_body_size) >>> 0, isLikeNone(max_keys_per_request) ? 0x100000001 : (max_keys_per_request) >>> 0, isLikeNone(in_memory) ? 0xFFFFFF : in_memory ? 1 : 0);
         return takeObject(ret);
     }
     /**
@@ -129,6 +131,7 @@ export class WorkerDb {
      *   - "delete"   → delete documents or drop:   { collection, keys: ... } or { drop: true }
      *   - "compact"  → compact the OPFS log file
      *   - "get_size" → return current OPFS file size in bytes
+     *   - "clear"    → wipe all in-memory state (in-memory mode only)
      *
      * Returns a JsValue result on success, or a JsValue error string on failure.
      * @param {any} data
@@ -417,7 +420,7 @@ function __wbg_get_imports() {
                     const a = state0.a;
                     state0.a = 0;
                     try {
-                        return __wasm_bindgen_func_elem_4065(a, state0.b, arg0, arg1);
+                        return __wasm_bindgen_func_elem_4230(a, state0.b, arg0, arg1);
                     } finally {
                         state0.a = a;
                     }
@@ -564,8 +567,8 @@ function __wbg_get_imports() {
             return ret;
         }, arguments); },
         __wbindgen_cast_0000000000000001: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 733, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_4053);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 774, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_4220);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000002: function(arg0) {
@@ -607,10 +610,10 @@ function __wbg_get_imports() {
     };
 }
 
-function __wasm_bindgen_func_elem_4053(arg0, arg1, arg2) {
+function __wasm_bindgen_func_elem_4220(arg0, arg1, arg2) {
     try {
         const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-        wasm.__wasm_bindgen_func_elem_4053(retptr, arg0, arg1, addHeapObject(arg2));
+        wasm.__wasm_bindgen_func_elem_4220(retptr, arg0, arg1, addHeapObject(arg2));
         var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
         var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
         if (r1) {
@@ -621,8 +624,8 @@ function __wasm_bindgen_func_elem_4053(arg0, arg1, arg2) {
     }
 }
 
-function __wasm_bindgen_func_elem_4065(arg0, arg1, arg2, arg3) {
-    wasm.__wasm_bindgen_func_elem_4065(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
+function __wasm_bindgen_func_elem_4230(arg0, arg1, arg2, arg3) {
+    wasm.__wasm_bindgen_func_elem_4230(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
 }
 
 const WorkerDbFinalization = (typeof FinalizationRegistry === 'undefined')

package/dist/wasm/moltendb_core_bg.wasm.d.ts

@@ -3,11 +3,11 @@
 export const memory: WebAssembly.Memory;
 export const __wbg_workerdb_free: (a: number, b: number) => void;
 export const workerdb_analytics: (a: number, b: number, c: number, d: number) => void;
-export const workerdb_create: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: bigint, k: number) => number;
+export const workerdb_create: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number) => number;
 export const workerdb_handle_message: (a: number, b: number, c: number) => void;
 export const workerdb_subscribe: (a: number, b: number) => void;
-export const __wasm_bindgen_func_elem_4053: (a: number, b: number, c: number, d: number) => void;
-export const __wasm_bindgen_func_elem_4065: (a: number, b: number, c: number, d: number) => void;
+export const __wasm_bindgen_func_elem_4220: (a: number, b: number, c: number, d: number) => void;
+export const __wasm_bindgen_func_elem_4230: (a: number, b: number, c: number, d: number) => void;
 export const __wbindgen_export: (a: number, b: number) => number;
 export const __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
 export const __wbindgen_export3: (a: number) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moltendb-web/core",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "MoltenDb WASM runtime — the database engine, Web Worker, and main-thread client in one package.",
   "type": "module",
   "author": "Maximilian Both <maximilian.both27@outlook.com>",