@moltendb-web/core 1.0.0-rc.1 → 1.0.0-rc.4

package/README.md

@@ -1,12 +1,12 @@
-# MoltenDB Web
+# MoltenDb Web
 
 <div align="center">
-  <img src="../../assets/logo.png" alt="MoltenDB Logo" width="64"/>
+  <img src="../../assets/logo.png" alt="MoltenDb Logo" width="64"/>
 
   ### 🌋 The Embedded Database for the Modern Web
   **High-performance Rust engine compiled to WASM. Persistent storage via OPFS.**
 
-  [Interactive Demo](https://stackblitz.com/~/github.com/maximilian27/moltendb-wasm-demo?file=package.json) • [Core Engine](https://www.npmjs.com/package/@moltendb-web/core) • [Query Builder](https://www.npmjs.com/package/@moltendb-web/query) • [Original Repository](https://github.com/maximilian27/MoltenDB) • [License](LICENSE.md)
+  [Interactive Demo](https://stackblitz.com/~/github.com/maximilian27/moltendb-wasm-demo?file=package.json) • [Core Engine](https://www.npmjs.com/package/@moltendb-web/core) • [Query Builder](https://www.npmjs.com/package/@moltendb-web/query) • [Original Repository](https://github.com/maximilian27/MoltenDb) • [License](LICENSE.md)
 
   [![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)
@@ -17,15 +17,15 @@
 
 ---
 
-## What is MoltenDB Web?
+## What is MoltenDb Web?
 
-MoltenDB is a JSON document database written in Rust that runs directly in your browser. Unlike traditional browser databases limited by `localStorage` quotas or IndexedDB's complex API, MoltenDB leverages the **Origin Private File System (OPFS)** to provide a high-performance, append-only storage engine.
+MoltenDb is a JSON document database written in Rust that runs directly in your browser. Unlike traditional browser databases limited by `localStorage` quotas or IndexedDB's complex API, MoltenDb leverages the **Origin Private File System (OPFS)** to provide a high-performance, append-only storage engine.
 
 > **🚀 Release Candidate** — The core engine, multi-tab sync, and storage layer are feature-complete and stabilised for v1. Server sync, encryption and analytics are planned for a future release.
 
 ### 🎮 Explore the Full Functionality
 
-The best way to experience MoltenDB is through the **[Interactive Demo on StackBlitz](https://stackblitz.com/~/github.com/maximilian27/moltendb-wasm-demo?file=package.json)**. It provides a complete, live environment where you can test query builder expressions, perform mutations, and see real-time events with zero local setup.
+The best way to experience MoltenDb is through the **[Interactive Demo on StackBlitz](https://stackblitz.com/~/github.com/maximilian27/moltendb-wasm-demo?file=package.json)**. It provides a complete, live environment where you can test query builder expressions, perform mutations, and see real-time events with zero local setup.
 
 Prefer to run it in your own environment? You can **[clone the demo repository](https://github.com/maximilian27/moltendb-wasm-demo)** to inspect the source code, run the explorers locally, and experiment with your own schema.
 
@@ -37,7 +37,7 @@ Prefer to run it in your own environment? You can **[clone the demo repository](
 - **Worker-Threaded:** The database runs entirely inside a Web Worker—zero impact on your UI thread.
 - **Multi-Tab Sync (stabilised):** Leader election via the Web Locks API ensures only one tab owns the OPFS handle. All other tabs proxy reads and writes through a `BroadcastChannel`. Seamless leader promotion when the active tab closes.
 - **Automatic Compaction:** The engine automatically compacts the append-only log when it exceeds **500 entries or 5 MB**, keeping storage lean without any manual intervention.
-- **Real-Time Pub/Sub:** Every write and delete emits a typed `DBEvent` to all open tabs instantly. The `subscribe()` pattern supports multiple independent listeners per tab — perfect for modern UI frameworks like React and Angular.
+- **Real-Time Pub/Sub:** Every write and delete emits a typed `DbEvent` to all open tabs instantly. The `subscribe()` pattern supports multiple independent listeners per tab — perfect for modern UI frameworks like React and Angular.
 - **GraphQL-style Selection:** Request only the fields you need (even deeply nested ones) to save memory and CPU.
 - **Auto-Indexing:** The engine monitors your queries and automatically creates indexes for frequently filtered fields.
 - **Conflict Resolution:** Incoming writes with `_v ≤ stored _v` are silently skipped.
@@ -47,7 +47,7 @@ Prefer to run it in your own environment? You can **[clone the demo repository](
 
 ## Installation
 
-MoltenDB is split into two packages: the core engine and the type-safe, chainable query builder.
+MoltenDb is split into two packages: the core engine and the type-safe, chainable query builder.
 
 ```bash
 # Install the core engine and WASM artifacts
@@ -58,7 +58,7 @@ npm install @moltendb-web/query
 ```
 📦 **Bundler Setup**
 
-MoltenDB handles its own Web Workers and WASM loading automatically. However, depending on your build tool, you may need a tiny config tweak to ensure it serves the static files correctly.
+MoltenDb handles its own Web Workers and WASM loading automatically. However, depending on your build tool, you may need a tiny config tweak to ensure it serves the static files correctly.
 
 **For Vite:**
 Exclude the core package from pre-bundling in your vite.config.js:
@@ -85,17 +85,17 @@ module.exports = {
 # Quick Start
 1. Initialize the Client
 
-MoltenDB handles the Web Worker and WASM instantiation for you.
+MoltenDb handles the Web Worker and WASM instantiation for you.
 TypeScript
 ```ts
-import { MoltenDB } from '@moltendb-web/core';
-import { MoltenDBClient, WorkerTransport } from '@moltendb-web/query';
+import { MoltenDb } from '@moltendb-web/core';
+import { MoltenDbClient, WorkerTransport } from '@moltendb-web/query';
 
-const db = new MoltenDB('moltendb_demo');
+const db = new MoltenDb('moltendb_demo');
 await db.init();
 
 // Connect the query builder to the WASM worker
-const client = new MoltenDBClient(db);
+const client = new MoltenDbClient(db);
 
 // 2. Insert and Query
 
@@ -200,7 +200,7 @@ await client.collection('laptops')
 
 // Supported Query Operators
 
-MoltenDB supports a variety of operators in the `where` clause:
+MoltenDb supports a variety of operators in the `where` clause:
 
 | Operator | Aliases | Description |
 |---|---|---|
@@ -248,14 +248,14 @@ await client.collection('laptops')
 
 ### How the Log Works
 
-MoltenDB uses an append-only JSON log. Every write is a new line, ensuring your data is safe even if the tab is closed unexpectedly.
+MoltenDb uses an append-only JSON log. Every write is a new line, ensuring your data is safe even if the tab is closed unexpectedly.
 
 - **Automatic Compaction:** When the log exceeds **500 entries or 5 MB**, the engine automatically "squashes" the log, removing superseded document versions to reclaim space. No manual `compact()` calls are needed in normal operation.
 - **Persistence:** All data is stored in the Origin Private File System (OPFS). This is a special file system for web apps that provides much higher performance than IndexedDB.
 
 ### Multi-Tab Sync
 
-MoltenDB uses the **Web Locks API** for leader election. The first tab to acquire the lock becomes the *leader* and owns the OPFS file handle directly. Every subsequent tab becomes a *follower* and proxies all reads and writes through a `BroadcastChannel` to the leader.
+MoltenDb uses the **Web Locks API** for leader election. The first tab to acquire the lock becomes the *leader* and owns the OPFS file handle directly. Every subsequent tab becomes a *follower* and proxies all reads and writes through a `BroadcastChannel` to the leader.
 
 When the leader tab is closed, the next queued follower automatically acquires the lock and promotes itself to leader — no data loss, no manual reconnection required.
 
@@ -268,12 +268,12 @@ Tab 1 (Leader) ──owns──▶ Web Worker ──▶ WASM Engine ──▶ OP
 
 ### Real-Time Events (Pub/Sub)
 
-MoltenDB has a built-in pub/sub system that automatically notifies **all open tabs** whenever a document is created, updated, or deleted — no polling required.
+MoltenDb has a built-in pub/sub system that automatically notifies **all open tabs** whenever a document is created, updated, or deleted — no polling required.
 
 You can attach multiple independent listeners using the subscribe() method, making it trivial to keep different UI components (like React hooks or Angular signals) in sync without memory leaks:
 
 ```ts
-const db = new MoltenDB('my-app');
+const db = new MoltenDb('my-app');
 await db.init();
 
 // Attach a listener (Returns an unsubscribe function)
@@ -298,21 +298,21 @@ db.subscribe(({ event, collection, key }) => {
 });
 ```
 
-The `DBEvent` type is exported from the package for full TypeScript support:
+The `DbEvent` type is exported from the package for full TypeScript support:
 
 ```ts
-import { MoltenDB, DBEvent } from '@moltendb-web/core';
+import { MoltenDb, DbEvent } from '@moltendb-web/core';
 
-const db = new MoltenDB('my-app');
+const db = new MoltenDb('my-app');
 await db.init();
 
-db.subscribe((e: DBEvent) => { /* fully typed */ });```
+db.subscribe((e: DbEvent) => { /* fully typed */ });```
 
 ---
 
 ### Performance Note
 
-Because MoltenDB uses OPFS, your browser must support `SharedArrayBuffer`. Most modern browsers support this, but your server must send the following headers:
+Because MoltenDb uses OPFS, your browser must support `SharedArrayBuffer`. Most modern browsers support this, but your server must send the following headers:
 
 ```http
 Cross-Origin-Opener-Policy: same-origin
@@ -356,7 +356,7 @@ npm run test:coverage # with coverage report
 
 This monorepo contains the following packages:
 
-- **`packages/core`:** The core WASM engine, Web Worker logic, and the MoltenDB main client.
+- **`packages/core`:** The core WASM engine, Web Worker logic, and the MoltenDb main client.
 - **`packages/query`:** The type-safe, chainable Query Builder.
 
 ## Roadmap
@@ -366,7 +366,7 @@ This monorepo contains the following packages:
 - [x] **Rich Test Suite:** 50 unit, integration, and stress tests via Vitest — **stabilised in RC1**.
 - [ ] **React Adapter:** Official `@moltendb-web/react` package with `useQuery` hooks and real-time context providers.
 - [ ] **Angular Adapter:** Official `@moltendb-web/angular` package featuring RxJS observables and Signal-based data fetching.
-- [ ] **Delta Sync:** Automatic two-way sync with the MoltenDB Rust server.
+- [ ] **Delta Sync:** Automatic two-way sync with the MoltenDb Rust server.
 - [ ] **Data Encryption:** Transparent encryption-at-rest using hardware-backed keys (Web Crypto API).
 - [ ] **Analytics Functionality:** Run complex analytics queries straight in the browser without blocking the UI.
 
@@ -379,8 +379,8 @@ Found a bug or have a feature request? Please open an issue on the [GitHub issue
 
 ## License
 
-The MoltenDB Web packages (`@moltendb-web/core` and `@moltendb-web/query`) are licensed under the MIT License.
+The MoltenDb Web packages (`@moltendb-web/core` and `@moltendb-web/query`) are licensed under the MIT License.
 
-The **MoltenDB Server** (Rust backend) remains under the Business Source License 1.1 (Free for organizations under $5M revenue, requires a license for managed services).
+The **MoltenDb Server** (Rust backend) remains under the Business Source License 1.1 (Free for organizations under $5M revenue, requires a license for managed services).
 
 For commercial licensing or questions: [maximilian.both27@outlook.com](mailto:maximilian.both27@outlook.com)

package/dist/helpers.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Recursively converts JS Maps (WASM default) into Plain Objects.
+ */
+export declare function mapToObj(data: any): any;

package/dist/helpers.js

@@ -0,0 +1,16 @@
+/**
+ * Recursively converts JS Maps (WASM default) into Plain Objects.
+ */
+export function mapToObj(data) {
+    if (data instanceof Map) {
+        const obj = {};
+        data.forEach((value, key) => {
+            obj[key] = mapToObj(value);
+        });
+        return obj;
+    }
+    if (Array.isArray(data)) {
+        return data.map(mapToObj);
+    }
+    return data;
+}

package/dist/index.d.ts

@@ -1,15 +1,15 @@
-export interface MoltenDBOptions {
+export interface MoltenDbOptions {
     /** URL or path to moltendb-worker.js. */
     workerUrl?: string | URL;
 }
-export interface DBEvent {
+export interface DbEvent {
     type: 'event';
     event: 'change' | 'delete' | 'drop';
     collection: string;
     key: string;
     new_v: number | null;
 }
-export declare class MoltenDB {
+export declare class MoltenDb {
     readonly dbName: string;
     readonly workerUrl?: string | URL;
     worker: Worker | null;
@@ -17,16 +17,16 @@ export declare class MoltenDB {
     isLeader: boolean;
     private bc;
     /** Legacy global hook. Use `subscribe()` for multi-component listeners. */
-    onEvent?: (event: DBEvent) => void;
+    onEvent?: (event: DbEvent) => void;
     private eventListeners;
-    constructor(dbName?: string, options?: MoltenDBOptions);
+    constructor(dbName?: string, options?: MoltenDbOptions);
     /**
      * ⚡ Subscribe to real-time DB mutations.
      * @returns An unsubscribe function to prevent memory leaks in UI frameworks.
      */
-    subscribe(listener: (event: DBEvent) => void): () => void;
+    subscribe(listener: (event: DbEvent) => void): () => void;
     /** Manually remove a specific listener */
-    unsubscribe(listener: (event: DBEvent) => void): void;
+    unsubscribe(listener: (event: DbEvent) => void): void;
     private dispatchEvent;
     private initialized;
     init(): Promise<void>;

package/dist/index.js

@@ -1,4 +1,5 @@
-export class MoltenDB {
+import { mapToObj } from "./helpers";
+export class MoltenDb {
     dbName;
     workerUrl;
     worker = null;
@@ -33,7 +34,7 @@ export class MoltenDB {
                 listener(event);
             }
             catch (err) {
-                console.error('[MoltenDB] Error in subscribed listener', err);
+                console.error('[MoltenDb] Error in subscribed listener', err);
             }
         }
     }
@@ -60,7 +61,7 @@ export class MoltenDB {
                     this.startAsFollower();
                     resolveInit();
                     navigator.locks.request(`moltendb_lock_${this.dbName}`, async () => {
-                        console.log(`[MoltenDB] Promoting this tab to Leader.`);
+                        console.log(`[MoltenDb] Promoting this tab to Leader.`);
                         await this.startAsLeader();
                         return new Promise(() => { }); // Hold lock
                     });
@@ -74,7 +75,7 @@ export class MoltenDB {
             await navigator.storage.getDirectory();
         }
         catch {
-            throw new Error('[MoltenDB] Origin Private File System (OPFS) is not available in this browser context. ' +
+            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;
@@ -138,21 +139,25 @@ export class MoltenDB {
         };
     }
     async sendMessage(action, payload) {
-        const id = crypto.randomUUID();
+        // Generate a unique ID (random fallback for test environments without crypto.randomUUID)
+        const id = (typeof crypto !== 'undefined' && crypto.randomUUID)
+            ? crypto.randomUUID()
+            : Math.random().toString(36).substring(2, 9);
         return new Promise((resolve, reject) => {
+            const successHandler = (res) => resolve(mapToObj(res));
             if (this.isLeader && this.worker) {
-                this.pendingRequests.set(id, { resolve, reject });
+                this.pendingRequests.set(id, { resolve: successHandler, reject });
                 this.worker.postMessage({ id, action, ...payload });
             }
             else {
                 const timer = setTimeout(() => {
                     if (this.pendingRequests.has(id)) {
                         this.pendingRequests.delete(id);
-                        reject(new Error(`[MoltenDB] Request "${action}" timed out.`));
+                        reject(new Error(`[MoltenDb] Request "${action}" timed out.`));
                     }
                 }, 10000);
                 this.pendingRequests.set(id, {
-                    resolve: (v) => { clearTimeout(timer); resolve(v); },
+                    resolve: (res) => { clearTimeout(timer); successHandler(res); },
                     reject: (e) => { clearTimeout(timer); reject(e); }
                 });
                 this.bc.postMessage({ type: 'query', id, action, payload });

package/dist/moltendb-worker.js

@@ -1,4 +1,4 @@
-import init, { WorkerDb } from './moltendb.js';
+import init, { WorkerDb } from './wasm/moltendb.js';
 let db = null;
 let initPromise = null;
 self.onmessage = async (e) => {
@@ -17,7 +17,7 @@ self.onmessage = async (e) => {
                         self.postMessage({ type: 'event', ...eventData });
                     }
                     catch (err) {
-                        console.error('[MoltenDB Worker] Event parse error', err);
+                        console.error('[MoltenDb Worker] Event parse error', err);
                     }
                 });
                 db = instance;

package/dist/{moltendb.d.ts → wasm/moltendb.d.ts}

@@ -93,9 +93,9 @@ export interface InitOutput {
     readonly workerdb_handle_message: (a: number, b: number, c: number) => void;
     readonly workerdb_new: (a: number, b: number) => number;
     readonly workerdb_subscribe: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_3613: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_3697: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_3702: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_3628: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_3707: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_3718: (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/{moltendb.js → wasm/moltendb.js}

@@ -389,7 +389,7 @@ function __wbg_get_imports() {
                     const a = state0.a;
                     state0.a = 0;
                     try {
-                        return __wasm_bindgen_func_elem_3702(a, state0.b, arg0, arg1);
+                        return __wasm_bindgen_func_elem_3718(a, state0.b, arg0, arg1);
                     } finally {
                         state0.a = a;
                     }
@@ -509,8 +509,8 @@ function __wbg_get_imports() {
             return ret;
         }, arguments); },
         __wbindgen_cast_0000000000000001: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { dtor_idx: 664, function: Function { arguments: [Externref], shim_idx: 677, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm.__wasm_bindgen_func_elem_3613, __wasm_bindgen_func_elem_3697);
+            // Cast intrinsic for `Closure(Closure { dtor_idx: 664, function: Function { arguments: [Externref], shim_idx: 675, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, wasm.__wasm_bindgen_func_elem_3628, __wasm_bindgen_func_elem_3707);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000002: function(arg0) {
@@ -547,10 +547,10 @@ function __wbg_get_imports() {
     };
 }
 
-function __wasm_bindgen_func_elem_3697(arg0, arg1, arg2) {
+function __wasm_bindgen_func_elem_3707(arg0, arg1, arg2) {
     try {
         const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-        wasm.__wasm_bindgen_func_elem_3697(retptr, arg0, arg1, addHeapObject(arg2));
+        wasm.__wasm_bindgen_func_elem_3707(retptr, arg0, arg1, addHeapObject(arg2));
         var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
         var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
         if (r1) {
@@ -561,8 +561,8 @@ function __wasm_bindgen_func_elem_3697(arg0, arg1, arg2) {
     }
 }
 
-function __wasm_bindgen_func_elem_3702(arg0, arg1, arg2, arg3) {
-    wasm.__wasm_bindgen_func_elem_3702(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
+function __wasm_bindgen_func_elem_3718(arg0, arg1, arg2, arg3) {
+    wasm.__wasm_bindgen_func_elem_3718(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
 }
 
 const WorkerDbFinalization = (typeof FinalizationRegistry === 'undefined')

package/dist/{moltendb_bg.wasm.d.ts → wasm/moltendb_bg.wasm.d.ts}

@@ -6,9 +6,9 @@ export const workerdb_analytics: (a: number, b: number, c: number, d: number) =>
 export const workerdb_handle_message: (a: number, b: number, c: number) => void;
 export const workerdb_new: (a: number, b: number) => number;
 export const workerdb_subscribe: (a: number, b: number) => void;
-export const __wasm_bindgen_func_elem_3613: (a: number, b: number) => void;
-export const __wasm_bindgen_func_elem_3697: (a: number, b: number, c: number, d: number) => void;
-export const __wasm_bindgen_func_elem_3702: (a: number, b: number, c: number, d: number) => void;
+export const __wasm_bindgen_func_elem_3628: (a: number, b: number) => void;
+export const __wasm_bindgen_func_elem_3707: (a: number, b: number, c: number, d: number) => void;
+export const __wasm_bindgen_func_elem_3718: (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,7 +1,7 @@
 {
   "name": "@moltendb-web/core",
-  "version": "1.0.0-rc.1",
-  "description": "MoltenDB WASM runtime — the database engine, Web Worker, and main-thread client in one package.",
+  "version": "1.0.0-rc.4",
+  "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>",
   "license": "MIT",
@@ -23,14 +23,16 @@
       "import": "./dist/moltendb-worker.js",
       "types": "./dist/moltendb-worker.d.ts"
     },
-    "./wasm": "./dist/moltendb.js",
-    "./wasm-bg": "./dist/moltendb_bg.wasm"
+    "./wasm": "./dist/wasm/moltendb.js",
+    "./wasm-bg": "./dist/wasm/moltendb_bg.wasm"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
+    "build": "tsc && npm run copy-wasm",
+    "copy-wasm": "copyfiles -u 1 \"src/wasm/**/*\" dist/",
+    "dev": "tsc --watch & npm run watch-wasm",
+    "watch-wasm": "copyfiles -u 1 -w \"src/wasm/**/*\" dist/",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -41,6 +43,7 @@
   "devDependencies": {
     "@playwright/test": "^1.58.2",
     "@vitest/coverage-v8": "^4.1.1",
+    "copyfiles": "^2.4.1",
     "happy-dom": "^20.8.7",
     "typescript": "^6.0.2",
     "vite": "^8.0.2",