@moltendb-web/core 0.1.0-alpha.21 → 0.1.0-beta.1

package/README.md

@@ -243,7 +243,7 @@ This monorepo contains the following packages:
 
 ## Roadmap
 
-- [ ] **Multi-Tab Sync:** Leader election for multiple tabs to share a single OPFS instance.
+- [ ] ~~**Multi-Tab Sync:** Leader election for multiple tabs to share a single OPFS instance.~~ ✅
 - [ ] **Delta Sync:** Automatic two-way sync with the MoltenDB Rust server.
 - [ ] **Analytics functionality:** Run analytics queries straight in the browser. 
 
@@ -256,6 +256,4 @@ MoltenDB is licensed under the **Business Source License 1.1**.
 
 For commercial licensing or questions: [maximilian.both27@outlook.com](mailto:maximilian.both27@outlook.com)
 
----
 
-Created with 🌋 by Maximilian Both. Coming to the world on the Equinox.

package/dist/index.d.ts

@@ -1,56 +1,55 @@
 export interface MoltenDBOptions {
-  /** URL or path to moltendb-worker.js. Defaults to './moltendb-worker.js'. */
-  workerUrl?: string | URL;
-  /** Enable WebSocket sync with a MoltenDB server. Default: false. */
-  syncEnabled?: boolean;
-  /** WebSocket server URL. Default: 'wss://localhost:3000/ws'. */
-  serverUrl?: string;
-  /** Sync batch flush interval in ms. Default: 5000. */
-  syncIntervalMs?: number;
-  /** JWT token for WebSocket authentication. */
-  authToken?: string;
+    /** 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;
 }
-
 export type SyncCallback = (update: {
-  event: 'change' | 'delete' | 'drop';
-  collection: string;
-  key: string;
-  new_v: number | null;
+    event: 'change' | 'delete' | 'drop';
+    collection: string;
+    key: string;
+    new_v: number | null;
 }) => void;
-
-export class MoltenDB {
-  readonly dbName: string;
-  readonly worker: Worker | null;
-
-  constructor(dbName?: string, options?: MoltenDBOptions);
-
-  /** Initialise the Web Worker and open the OPFS database. */
-  init(): Promise<void>;
-
-  /** Send a raw message to the worker. */
-  sendMessage(action: string, params?: Record<string, unknown>): Promise<unknown>;
-
-  /** Insert / upsert one document. */
-  set(collection: string, key: string, value: Record<string, unknown>, options?: { skipSync?: boolean }): Promise<void>;
-
-  /** Fetch a single document by key. */
-  get(collection: string, key: string): Promise<unknown>;
-
-  /** Fetch all documents in a collection. */
-  getAll(collection: string): Promise<unknown>;
-
-  /** Delete a document by key. */
-  delete(collection: string, key: string, options?: { skipSync?: boolean }): Promise<void>;
-
-  /** Compact the OPFS log file. */
-  compact(): Promise<unknown>;
-
-  /** Subscribe to real-time server push events. Returns an unsubscribe function. */
-  onSync(callback: SyncCallback): () => void;
-
-  /** Close the WebSocket connection and stop the sync timer. */
-  disconnect(): void;
-
-  /** Terminate the Web Worker (and disconnect sync). */
-  terminate(): void;
+export declare class MoltenDB {
+    readonly dbName: string;
+    readonly workerUrl: string | URL;
+    worker: Worker | null;
+    private messageId;
+    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) */
+    onEvent?: (event: any) => void;
+    constructor(dbName?: string, options?: MoltenDBOptions);
+    init(): Promise<void>;
+    private startAsLeader;
+    private startAsFollower;
+    sendMessage(action: string, payload?: Record<string, unknown>): Promise<any>;
+    set(collection: string, key: string, value: Record<string, unknown>, options?: {
+        skipSync?: boolean;
+    }): Promise<void>;
+    get(collection: string, key: string): Promise<unknown>;
+    getAll(collection: string): Promise<unknown>;
+    delete(collection: string, key: string, options?: {
+        skipSync?: boolean;
+    }): Promise<void>;
+    compact(): Promise<unknown>;
+    private startSync;
+    onSyncEvent(callback: SyncCallback): void;
+    disconnect(): void;
+    terminate(): void;
 }

package/dist/index.js

@@ -1,176 +1,214 @@
-/**
- * MoltenDB main-thread client.
- *
- * Usage:
- *   import { MoltenDB } from 'moltendb-wasm';
- *
- *   const db = new MoltenDB('my-db', {
- *     // Required: URL or path to the moltendb-worker.js file.
- *     // With a bundler:  new URL('moltendb-wasm/worker', import.meta.url)
- *     // Plain script:    '/node_modules/moltendb-wasm/dist/moltendb-worker.js'
- *     workerUrl: new URL('moltendb-wasm/worker', import.meta.url),
- *   });
- *   await db.init();
- */
 export class MoltenDB {
-    /**
-     * @param {string} dbName - OPFS file name (unique per database).
-     * @param {object} [options]
-     * @param {string|URL} [options.workerUrl] - URL to moltendb-worker.js.
-     *   Defaults to './moltendb-worker.js' (works when served from the same directory).
-     * @param {boolean} [options.syncEnabled=false] - Enable WebSocket sync.
-     * @param {string}  [options.serverUrl='wss://localhost:3000/ws'] - WS server URL.
-     * @param {number}  [options.syncIntervalMs=5000] - Sync batch flush interval.
-     * @param {string}  [options.authToken] - JWT token for WS authentication.
-     */
+    dbName;
+    workerUrl;
+    worker = null;
+    messageId = 0;
+    pendingRequests = new Map();
+    // 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) */
+    onEvent;
     constructor(dbName = 'moltendb', options = {}) {
-        this.dbName         = dbName;
-        this.workerUrl      = options.workerUrl ?? './moltendb-worker.js';
-        this.worker         = null;
-        this.messageId      = 0;
-        this.pendingRequests = new Map();
-
-        this.syncEnabled    = options.syncEnabled    ?? false;
-        this.serverUrl      = options.serverUrl      ?? 'wss://localhost:3000/ws';
+        this.dbName = dbName;
+        // Zero-config default worker resolution
+        this.workerUrl = options.workerUrl ?? new URL('./moltendb-worker.js', import.meta.url).href;
+        this.syncEnabled = options.syncEnabled ?? false;
+        this.serverUrl = options.serverUrl ?? 'wss://localhost:3000/ws';
         this.syncIntervalMs = options.syncIntervalMs ?? 5000;
-        this.authToken      = options.authToken      ?? null;
-
-        this.ws             = null;
-        this.syncCallbacks  = new Set();
-        this.syncQueue      = [];
-        this.syncTimer      = null;
+        this.authToken = options.authToken;
     }
-
-    /** Initialise the Web Worker and open the OPFS database. */
     async init() {
-        return new Promise((resolve, reject) => {
-            this.worker = new Worker(this.workerUrl, { type: 'module' });
-
-            this.worker.onmessage = (event) => {
-                const { id, result, error } = event.data;
-                const pending = this.pendingRequests.get(id);
-                if (!pending) return;
-                this.pendingRequests.delete(id);
-                if (error) pending.reject(new Error(error));
-                else       pending.resolve(result);
-            };
-
-            this.worker.onerror = (err) => {
-                console.error('[MoltenDB] Worker error:', err);
-                reject(err);
-            };
-
-            this.sendMessage('init', { dbName: this.dbName })
-                .then(() => this.syncEnabled ? this.connectSync() : undefined)
-                .then(resolve)
-                .catch(reject);
+        this.bc = new BroadcastChannel(`moltendb_channel_${this.dbName}`);
+        return new Promise((resolveInit) => {
+            // 1. Try to grab the lock immediately (Leader Election)
+            navigator.locks.request(`moltendb_lock_${this.dbName}`, { ifAvailable: true }, async (lock) => {
+                if (lock) {
+                    // We got the lock! We are the active DB host.
+                    await this.startAsLeader();
+                    resolveInit();
+                    // Return a promise that never resolves to hold the lock until the tab closes
+                    return new Promise(() => { });
+                }
+                else {
+                    // Lock is taken. We are a proxy follower.
+                    this.startAsFollower();
+                    resolveInit();
+                    // 2. Queue up in the background. If the Leader tab closes, this lock resolves!
+                    navigator.locks.request(`moltendb_lock_${this.dbName}`, async (fallbackLock) => {
+                        console.log(`[MoltenDB] Previous leader disconnected. Promoting this tab to Leader.`);
+                        await this.startAsLeader();
+                        return new Promise(() => { }); // Hold lock
+                    });
+                }
+            });
         });
     }
-
-    /**
-     * Send a raw message to the worker and return a Promise for the result.
-     * @param {string} action
-     * @param {object} [params]
-     */
-    sendMessage(action, params = {}) {
-        return new Promise((resolve, reject) => {
+    async startAsLeader() {
+        this.isLeader = true;
+        if (this.worker)
+            this.worker.terminate(); // Clean slate if promoted
+        this.worker = new Worker(this.workerUrl, { type: 'module', name: `moltendb-${this.dbName}-leader` });
+        // Handle messages strictly from our local Worker
+        this.worker.onmessage = (e) => {
+            const data = e.data;
+            if (data.type === 'event') {
+                // Trigger local UI hook
+                if (this.onEvent)
+                    this.onEvent(data);
+                // Broadcast the native event to all Follower tabs
+                this.bc.postMessage(data);
+                return;
+            }
+            // Resolve pending local promises
+            const req = this.pendingRequests.get(data.id);
+            if (req) {
+                if (data.error)
+                    req.reject(new Error(data.error));
+                else
+                    req.resolve(data.result);
+                this.pendingRequests.delete(data.id);
+            }
+        };
+        // Initialize the WASM Engine
+        await new Promise((resolve, reject) => {
             const id = this.messageId++;
             this.pendingRequests.set(id, { resolve, reject });
-            this.worker.postMessage({ id, action, ...params });
+            this.worker.postMessage({ id, action: 'init', dbName: this.dbName, workerUrl: this.workerUrl });
         });
-    }
-
-    // ── WebSocket sync ────────────────────────────────────────────────────────
-
-    connectSync() {
-        return new Promise((resolve, reject) => {
-            this.ws = new WebSocket(this.serverUrl);
-
-            this.ws.onopen = () => {
-                if (this.authToken) {
-                    this.ws.send(JSON.stringify({ action: 'AUTH', token: this.authToken }));
+        // Listen to the BroadcastChannel for queries coming from Follower tabs
+        this.bc.onmessage = async (e) => {
+            const msg = e.data;
+            if (msg.type === 'query' && msg.action) {
+                try {
+                    const result = await this.sendMessage(msg.action, msg.payload);
+                    this.bc.postMessage({ type: 'response', id: msg.id, result });
                 }
-                if (this.syncTimer) clearInterval(this.syncTimer);
-                this.syncTimer = setInterval(() => this.flushSyncQueue(), this.syncIntervalMs);
-                resolve();
-            };
-
-            this.ws.onmessage = (event) => {
-                try { this.handleServerUpdate(JSON.parse(event.data)); }
-                catch (e) { console.error('[MoltenDB] Failed to parse server message:', e); }
-            };
-
-            this.ws.onclose = () => {
-                if (this.syncTimer) clearInterval(this.syncTimer);
-                setTimeout(() => this.connectSync(), 3000);
-            };
-
-            this.ws.onerror = (err) => reject(err);
-        });
-    }
-
-    handleServerUpdate(update) {
-        if (update.event === 'change' && update.collection && update.key) {
-            // Re-fetch the updated document from the server and apply locally.
-            // (The WS push only carries the key + new _v, not the full document.)
+                catch (err) {
+                    this.bc.postMessage({ type: 'response', id: msg.id, error: err.message });
+                }
+            }
+        };
+        // If backend sync is enabled, only the Leader manages the WebSocket
+        if (this.syncEnabled) {
+            this.startSync();
         }
-        this.syncCallbacks.forEach(cb => cb(update));
     }
-
-    /** Subscribe to real-time server push events. Returns an unsubscribe fn. */
-    onSync(callback) {
-        this.syncCallbacks.add(callback);
-        return () => this.syncCallbacks.delete(callback);
+    startAsFollower() {
+        this.isLeader = false;
+        // We don't need a worker, we rely on the Leader.
+        if (this.worker) {
+            this.worker.terminate();
+            this.worker = null;
+        }
+        // Listen to the BroadcastChannel for answers from the Leader
+        this.bc.onmessage = (e) => {
+            const data = e.data;
+            if (data.type === 'event') {
+                // Trigger local UI hook as if it happened in this tab
+                if (this.onEvent)
+                    this.onEvent(data);
+                return;
+            }
+            if (data.type === 'response') {
+                // Resolve our proxied promises
+                const req = this.pendingRequests.get(data.id);
+                if (req) {
+                    if (data.error)
+                        req.reject(new Error(data.error));
+                    else
+                        req.resolve(data.result);
+                    this.pendingRequests.delete(data.id);
+                }
+            }
+        };
     }
-
-    flushSyncQueue() {
-        if (!this.syncQueue.length || !this.ws || this.ws.readyState !== WebSocket.OPEN) return;
-        const batch = this.syncQueue.splice(0);
-        this.ws.send(JSON.stringify({ action: 'set', operations: batch }));
+    async sendMessage(action, payload) {
+        const id = this.messageId++;
+        return new Promise((resolve, reject) => {
+            this.pendingRequests.set(id, { resolve, reject });
+            if (this.isLeader && this.worker) {
+                // Direct execution on the local Worker
+                this.worker.postMessage({ id, action, ...payload });
+            }
+            else {
+                // Proxy the request to the Leader tab
+                this.bc.postMessage({ type: 'query', id, action, payload });
+            }
+        });
     }
-
     // ── Convenience CRUD helpers ──────────────────────────────────────────────
-
-    /** Insert / upsert one document. */
     async set(collection, key, value, options = {}) {
         await this.sendMessage('set', { collection, data: { [key]: value } });
-        if (this.syncEnabled && !options.skipSync) {
+        if (this.syncEnabled && !options.skipSync && this.isLeader) {
             this.syncQueue.push({ action: 'set', collection, data: { [key]: value } });
         }
     }
-
-    /** Fetch a single document by key. */
     get(collection, key) {
         return this.sendMessage('get', { collection, keys: key });
     }
-
-    /** Fetch all documents in a collection. */
     getAll(collection) {
         return this.sendMessage('get', { collection });
     }
-
-    /** Delete a document by key. */
     async delete(collection, key, options = {}) {
         await this.sendMessage('delete', { collection, keys: key });
-        if (this.syncEnabled && !options.skipSync) {
+        if (this.syncEnabled && !options.skipSync && this.isLeader) {
             this.syncQueue.push({ action: 'delete', collection, keys: key });
         }
     }
-
-    /** Compact the OPFS log file. */
     compact() {
         return this.sendMessage('compact');
     }
-
-    /** Close the WebSocket connection and stop the sync timer. */
+    // ── 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.syncTimer)
+            clearInterval(this.syncTimer);
+        if (this.ws)
+            this.ws.close();
+        if (this.bc)
+            this.bc.close();
     }
-
-    /** Terminate the Web Worker (and disconnect sync). */
     terminate() {
         this.disconnect();
-        if (this.worker) this.worker.terminate();
+        if (this.worker)
+            this.worker.terminate();
     }
 }

package/dist/moltendb-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/moltendb-worker.js

@@ -1,39 +1,36 @@
 import init, { WorkerDb } from './moltendb.js';
-
 let db;
-
 self.onmessage = async (e) => {
     const { id, action, ...payload } = e.data;
-
     // --- Initialization Phase ---
     if (action === 'init') {
         try {
-            await init(payload.workerUrl);
+            await init();
             db = await new WorkerDb(payload.dbName);
-
             // THE NATIVE FEED: Listen to Rust and broadcast to the main thread
             db.subscribe((eventStr) => {
                 try {
                     const eventData = JSON.parse(eventStr);
                     // Use type: 'event' so the transport knows it's an unsolicited broadcast
                     self.postMessage({ type: 'event', ...eventData });
-                } catch (err) {
-                    console.error("[MoltenDB Worker] Failed to parse event", err);
+                }
+                catch (err) {
+                    console.error('[MoltenDB Worker] Failed to parse event', err);
                 }
             });
-
             self.postMessage({ id, result: { status: 'ok' } });
-        } catch (error) {
+        }
+        catch (error) {
             self.postMessage({ id, error: String(error) });
         }
         return;
     }
-
     // --- Standard Request/Response Phase ---
     try {
         const result = db.handle_message({ action, ...payload });
         self.postMessage({ id, result });
-    } catch (error) {
+    }
+    catch (error) {
         self.postMessage({ id, error: String(error) });
     }
-};
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moltendb-web/core",
-  "version": "0.1.0-alpha.21",
+  "version": "0.1.0-beta.1",
   "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>",
@@ -25,6 +25,11 @@
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  },
   "devDependencies": {
     "typescript": "^6.0.1-rc"
   },
@@ -38,4 +43,4 @@
     "indexeddb",
     "embedded"
   ]
-}
+}