@moltendb-web/core 1.0.0-rc.3 → 1.0.0-rc.5

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/index.d.ts

@@ -1,34 +1,34 @@
-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;
+    private initPromise;
     private pendingRequests;
     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>;
     private startAsLeader;
     private startAsFollower;

package/dist/index.js

@@ -1,8 +1,9 @@
 import { mapToObj } from "./helpers";
-export class MoltenDB {
+export class MoltenDb {
     dbName;
     workerUrl;
     worker = null;
+    initPromise = null;
     pendingRequests = new Map();
     // Multi-tab Sync State
     isLeader = false;
@@ -34,18 +35,18 @@ export class MoltenDB {
                 listener(event);
             }
             catch (err) {
-                console.error('[MoltenDB] Error in subscribed listener', err);
+                console.error('[MoltenDb] Error in subscribed listener', err);
             }
         }
     }
     // ───────────────────────────────────────────────────────────────────────────
-    initialized = false;
-    async init() {
-        if (this.initialized)
-            return;
-        this.initialized = true;
-        this.bc = new BroadcastChannel(`moltendb_channel_${this.dbName}`);
-        return new Promise((resolveInit, rejectInit) => {
+    init() {
+        // 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
+        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) => {
                 if (lock) {
                     try {
@@ -60,14 +61,16 @@ export class MoltenDB {
                 else {
                     this.startAsFollower();
                     resolveInit();
+                    // Wait in the background to become leader if the current leader dies
                     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
                     });
                 }
             });
         });
+        return this.initPromise;
     }
     async startAsLeader() {
         // Guard: OPFS is required
@@ -75,7 +78,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;
@@ -139,21 +142,33 @@ export class MoltenDB {
         };
     }
     async sendMessage(action, payload) {
-        // Generate a unique ID (random fallback for test environments without crypto.randomUUID)
+        //  Wait for the engine to boot before routing the message.
+        // If the DB is already initialized, this resolves instantly.
+        if (action !== 'init') {
+            if (this.initPromise) {
+                await this.initPromise;
+            }
+            else {
+                throw new Error('[MoltenDb] You must call db.init() before querying the database.');
+            }
+        }
+        // 2. Generate a unique ID
         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));
+            // 3. We are now GUARANTEED that isLeader, worker, and bc are accurately set
             if (this.isLeader && this.worker) {
                 this.pendingRequests.set(id, { resolve: successHandler, reject });
                 this.worker.postMessage({ id, action, ...payload });
             }
             else {
+                // Follower routing via BroadcastChannel
                 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 after 10s.`));
                     }
                 }, 10000);
                 this.pendingRequests.set(id, {
@@ -163,8 +178,7 @@ export class MoltenDB {
                 this.bc.postMessage({ type: 'query', id, action, payload });
             }
         });
-    }
-    // ── Convenience CRUD helpers ───────────────────────────────────────────────
+    } // ── Convenience CRUD helpers ───────────────────────────────────────────────
     async set(collection, key, value) {
         await this.sendMessage('set', { collection, data: { [key]: value } });
     }

package/dist/moltendb-worker.js

@@ -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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@moltendb-web/core",
-  "version": "1.0.0-rc.3",
-  "description": "MoltenDB WASM runtime — the database engine, Web Worker, and main-thread client in one package.",
+  "version": "1.0.0-rc.5",
+  "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",