@moltendb-web/core 0.1.0-rc.1 → 1.0.0-rc.3

package/README.md

@@ -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 (`onEvent`):** Every write and delete emits a typed `DBEvent` to all open tabs instantly — no polling, no extra infrastructure.
+- **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.
@@ -270,28 +270,32 @@ Tab 1 (Leader) ──owns──▶ Web Worker ──▶ WASM Engine ──▶ OP
 
 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.
 
-Assign a callback to `onEvent` after calling `init()`:
+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');
 await db.init();
 
-db.onEvent = (event) => {
+// Attach a listener (Returns an unsubscribe function)
+const unsubscribe = db.subscribe((event) => {
   console.log(event.event);      // 'change' | 'delete' | 'drop'
   console.log(event.collection); // e.g. 'laptops'
   console.log(event.key);        // e.g. 'lp1'
   console.log(event.new_v);      // new version number, or null on delete
-};
+});
+
+// Later, when the UI component unmounts:
+unsubscribe();
 ```
 
 The event fires on the **leader tab** (directly from the WASM engine) and is automatically broadcast over the `BroadcastChannel` so every **follower tab** receives it too. This makes it trivial to keep your UI in sync across tabs without any extra infrastructure:
 
 ```ts
-db.onEvent = ({ event, collection, key }) => {
+db.subscribe(({ event, collection, key }) => {
   if (collection === 'laptops') {
     refreshLaptopList(); // re-query and re-render
   }
-};
+});
 ```
 
 The `DBEvent` type is exported from the package for full TypeScript support:
@@ -302,8 +306,7 @@ import { MoltenDB, DBEvent } from '@moltendb-web/core';
 const db = new MoltenDB('my-app');
 await db.init();
 
-db.onEvent = (e: DBEvent) => { /* fully typed */ };
-```
+db.subscribe((e: DBEvent) => { /* fully typed */ });```
 
 ---
 
@@ -337,7 +340,7 @@ npm run test:coverage # with coverage report
 | CRUD — follower | 3 | BroadcastChannel proxy path for all mutations |
 | Worker error handling | 3 | Transient errors, unknown actions, request isolation |
 | Leader promotion | 2 | Follower takes over when leader tab closes |
-| `onEvent` hook | 2 | Real-time event delivery to leader and followers |
+| `Pub/Sub (subscribe)`  | 2 | Multi-subscriber event delivery across tabs |
 | Follower timeout | 1 | Pending requests reject after 10 s if leader disappears |
 | `terminate` / `disconnect` | 3 | Worker cleanup, timer teardown |
 | Stress — rapid writes | 3 | 100 sequential, 50 concurrent, interleaved set/delete |

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,23 +1,7 @@
 export interface MoltenDBOptions {
     /** URL or path to moltendb-worker.js. */
     workerUrl?: string | URL;
-    /** Enable WebSocket sync with a MoltenDB server. Default: false. */
-    syncEnabled?: boolean;
-    /** WebSocket server URL. Default: 'wss://localhost:1538/ws'. */
-    serverUrl?: string;
-    /** Sync batch flush interval in ms. Default: 5000. */
-    syncIntervalMs?: number;
-    /** JWT token for WebSocket authentication. */
-    authToken?: string;
-    /** Called whenever a DB mutation event is broadcast (all tabs). */
-    onEvent?: (event: DBEvent) => void;
 }
-export type SyncCallback = (update: {
-    event: 'change' | 'delete' | 'drop';
-    collection: string;
-    key: string;
-    new_v: number | null;
-}) => void;
 export interface DBEvent {
     type: 'event';
     event: 'change' | 'delete' | 'drop';
@@ -32,33 +16,28 @@ export declare class MoltenDB {
     private pendingRequests;
     isLeader: boolean;
     private bc;
-    private syncEnabled;
-    private serverUrl;
-    private syncIntervalMs;
-    private authToken?;
-    private ws;
-    private syncCallbacks;
-    private syncQueue;
-    private syncTimer;
-    /** ⚡ Hook to listen to native real-time DB mutations (works on all tabs) */
+    /** Legacy global hook. Use `subscribe()` for multi-component listeners. */
     onEvent?: (event: DBEvent) => void;
+    private eventListeners;
     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;
+    /** Manually remove a specific listener */
+    unsubscribe(listener: (event: DBEvent) => void): void;
+    private dispatchEvent;
     private initialized;
     init(): Promise<void>;
     private startAsLeader;
     private startAsFollower;
     sendMessage(action: string, payload?: Record<string, unknown>): Promise<any>;
-    set(collection: string, key: string, value: any, options?: {
-        skipSync?: boolean;
-    }): Promise<void>;
+    set(collection: string, key: string, value: any): Promise<void>;
     get(collection: string, key: string): Promise<unknown>;
     getAll(collection: string): Promise<unknown[]>;
-    delete(collection: string, key: string, options?: {
-        skipSync?: boolean;
-    }): Promise<void>;
+    delete(collection: string, key: string): Promise<void>;
     compact(): Promise<unknown>;
-    private startSync;
-    onSyncEvent(callback: SyncCallback): void;
     disconnect(): void;
     terminate(): void;
 }

package/dist/index.js

@@ -1,3 +1,4 @@
+import { mapToObj } from "./helpers";
 export class MoltenDB {
     dbName;
     workerUrl;
@@ -6,27 +7,38 @@ export class MoltenDB {
     // Multi-tab Sync State
     isLeader = false;
     bc;
-    // Server Sync State
-    syncEnabled;
-    serverUrl;
-    syncIntervalMs;
-    authToken;
-    ws = null;
-    syncCallbacks = [];
-    syncQueue = [];
-    syncTimer = null;
-    /** ⚡ Hook to listen to native real-time DB mutations (works on all tabs) */
+    /** Legacy global hook. Use `subscribe()` for multi-component listeners. */
     onEvent;
+    // ── Multi-Subscriber Event System ──────────────────────────────────────────
+    eventListeners = new Set();
     constructor(dbName = 'moltendb', options = {}) {
         this.dbName = dbName;
         this.workerUrl = options.workerUrl;
-        this.syncEnabled = options.syncEnabled ?? false;
-        this.serverUrl = options.serverUrl ?? 'wss://localhost:3000/ws';
-        this.syncIntervalMs = options.syncIntervalMs ?? 5000;
-        this.authToken = options.authToken;
-        if (options.onEvent)
-            this.onEvent = options.onEvent;
     }
+    /**
+     * ⚡ Subscribe to real-time DB mutations.
+     * @returns An unsubscribe function to prevent memory leaks in UI frameworks.
+     */
+    subscribe(listener) {
+        this.eventListeners.add(listener);
+        return () => this.eventListeners.delete(listener);
+    }
+    /** Manually remove a specific listener */
+    unsubscribe(listener) {
+        this.eventListeners.delete(listener);
+    }
+    dispatchEvent(event) {
+        // Fire all subscribed component handlers
+        for (const listener of this.eventListeners) {
+            try {
+                listener(event);
+            }
+            catch (err) {
+                console.error('[MoltenDB] Error in subscribed listener', err);
+            }
+        }
+    }
+    // ───────────────────────────────────────────────────────────────────────────
     initialized = false;
     async init() {
         if (this.initialized)
@@ -74,8 +86,7 @@ export class MoltenDB {
         this.worker.onmessage = (e) => {
             const data = e.data;
             if (data.type === 'event') {
-                if (this.onEvent)
-                    this.onEvent(data);
+                this.dispatchEvent(data); // ⬅️ Trigger new dispatcher
                 this.bc.postMessage(data);
                 return;
             }
@@ -102,8 +113,6 @@ export class MoltenDB {
                 }
             }
         };
-        if (this.syncEnabled)
-            this.startSync();
     }
     startAsFollower() {
         this.isLeader = false;
@@ -114,8 +123,7 @@ export class MoltenDB {
         this.bc.onmessage = (e) => {
             const data = e.data;
             if (data.type === 'event') {
-                if (this.onEvent)
-                    this.onEvent(data);
+                this.dispatchEvent(data); // ⬅️ Trigger new dispatcher
                 return;
             }
             if (data.type === 'response') {
@@ -131,11 +139,14 @@ export class MoltenDB {
         };
     }
     async sendMessage(action, payload) {
-        // FIX: Use random UUIDs so tabs don't collide on message IDs
-        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 {
@@ -146,19 +157,16 @@ export class MoltenDB {
                     }
                 }, 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 });
             }
         });
     }
-    // ── Convenience CRUD helpers (CLEANED - NO DUPLICATES) ─────────────────────
-    async set(collection, key, value, options = {}) {
+    // ── Convenience CRUD helpers ───────────────────────────────────────────────
+    async set(collection, key, value) {
         await this.sendMessage('set', { collection, data: { [key]: value } });
-        if (this.syncEnabled && !options.skipSync && this.isLeader) {
-            this.syncQueue.push({ action: 'set', collection, data: { [key]: value } });
-        }
     }
     async get(collection, key) {
         try {
@@ -189,51 +197,13 @@ export class MoltenDB {
             throw err;
         }
     }
-    async delete(collection, key, options = {}) {
+    async delete(collection, key) {
         await this.sendMessage('delete', { collection, keys: key });
-        if (this.syncEnabled && !options.skipSync && this.isLeader) {
-            this.syncQueue.push({ action: 'delete', collection, keys: key });
-        }
     }
     compact() {
         return this.sendMessage('compact');
     }
-    // ── Server Sync Implementation (Leader Only) ──────────────────────────────
-    startSync() {
-        this.ws = new WebSocket(this.serverUrl);
-        this.ws.onopen = () => {
-            if (this.authToken) {
-                this.ws?.send(JSON.stringify({ type: 'auth', token: this.authToken }));
-            }
-        };
-        this.ws.onmessage = (e) => {
-            try {
-                const msg = JSON.parse(e.data);
-                if (msg.event) {
-                    for (const cb of this.syncCallbacks)
-                        cb(msg);
-                }
-            }
-            catch (err) {
-            }
-        };
-        this.syncTimer = setInterval(async () => {
-            if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
-                return;
-            if (this.syncQueue.length === 0)
-                return;
-            const batch = this.syncQueue.splice(0, this.syncQueue.length);
-            this.ws.send(JSON.stringify({ type: 'batch', operations: batch }));
-        }, this.syncIntervalMs);
-    }
-    onSyncEvent(callback) {
-        this.syncCallbacks.push(callback);
-    }
     disconnect() {
-        if (this.syncTimer)
-            clearInterval(this.syncTimer);
-        if (this.ws)
-            this.ws.close();
         if (this.bc)
             this.bc.close();
     }

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) => {

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_3624: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_3703: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_3716: (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}

@@ -251,6 +251,9 @@ function __wbg_get_imports() {
             const ret = Object.entries(getObject(arg0));
             return addHeapObject(ret);
         },
+        __wbg_error_8d9a8e04cd1d3588: function(arg0) {
+            console.error(getObject(arg0));
+        },
         __wbg_error_a6fa202b58aa1cd3: function(arg0, arg1) {
             let deferred0_0;
             let deferred0_1;
@@ -386,7 +389,7 @@ function __wbg_get_imports() {
                     const a = state0.a;
                     state0.a = 0;
                     try {
-                        return __wasm_bindgen_func_elem_3716(a, state0.b, arg0, arg1);
+                        return __wasm_bindgen_func_elem_3718(a, state0.b, arg0, arg1);
                     } finally {
                         state0.a = a;
                     }
@@ -506,8 +509,8 @@ function __wbg_get_imports() {
             return ret;
         }, arguments); },
         __wbindgen_cast_0000000000000001: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { dtor_idx: 663, function: Function { arguments: [Externref], shim_idx: 674, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm.__wasm_bindgen_func_elem_3624, __wasm_bindgen_func_elem_3703);
+            // 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) {
@@ -544,10 +547,10 @@ function __wbg_get_imports() {
     };
 }
 
-function __wasm_bindgen_func_elem_3703(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_3703(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) {
@@ -558,8 +561,8 @@ function __wasm_bindgen_func_elem_3703(arg0, arg1, arg2) {
     }
 }
 
-function __wasm_bindgen_func_elem_3716(arg0, arg1, arg2, arg3) {
-    wasm.__wasm_bindgen_func_elem_3716(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_3624: (a: number, b: number) => void;
-export const __wasm_bindgen_func_elem_3703: (a: number, b: number, c: number, d: number) => void;
-export const __wasm_bindgen_func_elem_3716: (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,6 +1,6 @@
 {
   "name": "@moltendb-web/core",
-  "version": "0.1.0-rc.1",
+  "version": "1.0.0-rc.3",
   "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>",
@@ -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",