@moltendb-web/react 1.7.0

package/README.md

@@ -0,0 +1,290 @@
+# @moltendb-web/react
+
+Official React hooks wrapper for [MoltenDb](https://github.com/maximilian27/moltendb-web).
+
+## React Version Support
+
+| React Version | Supported |
+|---|---|
+| 16.8+ | ✅ |
+| 17.x | ✅ |
+| 18.x | ✅ |
+| 19.x | ✅ |
+
+The package uses only stable React hooks (`useState`, `useEffect`, `useRef`, `useContext`, `createContext`) available since React 16.8. No concurrent features or React 18+ APIs are used in the library itself.
+
+## Installation
+
+```bash
+npm install @moltendb-web/react
+```
+
+`@moltendb-web/core` and `@moltendb-web/query` are automatically installed as dependencies — no need to install them separately.
+
+## Setup
+
+### Root-level provider (recommended)
+
+Wrap your entire app with `MoltenDbProvider` so all components share a single database instance:
+
+**React 18+ (`createRoot`)**
+```tsx
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { MoltenDbProvider } from '@moltendb-web/react';
+import App from './App';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <MoltenDbProvider config={{ name: 'mydb' }}>
+      <App />
+    </MoltenDbProvider>
+  </React.StrictMode>
+);
+```
+
+**React 16/17 (`ReactDOM.render`)**
+```tsx
+import React from 'react';
+import ReactDOM from 'react-dom';
+import { MoltenDbProvider } from '@moltendb-web/react';
+import App from './App';
+
+ReactDOM.render(
+  <React.StrictMode>
+    <MoltenDbProvider config={{ name: 'mydb' }}>
+      <App />
+    </MoltenDbProvider>
+  </React.StrictMode>,
+  document.getElementById('root')
+);
+```
+
+### Component-level provider
+
+You can also scope a `MoltenDbProvider` to a specific subtree or feature area. Each provider creates its own isolated database instance:
+
+```tsx
+import { MoltenDbProvider } from '@moltendb-web/react';
+
+function InventoryFeature() {
+  return (
+    <MoltenDbProvider config={{ name: 'inventory_db', inMemory: false }}>
+      <InventoryList />
+      <InventoryStats />
+    </MoltenDbProvider>
+  );
+}
+```
+
+This is useful for:
+- **Lazy-loaded routes** — only initialise the DB when the route is visited
+- **Isolated feature modules** — each feature uses its own database
+- **Testing** — wrap individual components in a provider with `inMemory: true`
+
+```tsx
+// Lazy-loaded route example
+import { lazy, Suspense } from 'react';
+import { MoltenDbProvider } from '@moltendb-web/react';
+
+const Dashboard = lazy(() => import('./Dashboard'));
+
+function App() {
+  return (
+    <Suspense fallback={<p>Loading…</p>}>
+      <MoltenDbProvider config={{ name: 'dashboard_db' }}>
+        <Dashboard />
+      </MoltenDbProvider>
+    </Suspense>
+  );
+}
+```
+
+## Hooks
+
+### `useMoltenDb()`
+
+Returns the `MoltenDbClient` instance for manual queries and mutations. Must be used inside `<MoltenDbProvider>`.
+
+```tsx
+import { useMoltenDb } from '@moltendb-web/react';
+
+function AddTodoButton() {
+  const client = useMoltenDb();
+
+  const handleClick = async () => {
+    await client.collection('todos').set({
+      todo_1: { text: 'Hello MoltenDb!', done: false }
+    }).exec();
+  };
+
+  return <button onClick={handleClick}>Add Todo</button>;
+}
+```
+
+### `useMoltenDbResource<T>(collection, queryFn)`
+
+Reactively fetches data from a collection. Automatically re-fetches whenever the collection is mutated. Returns `{ value, isLoading, error }`.
+
+```tsx
+import { useMoltenDbResource } from '@moltendb-web/react';
+
+interface Todo {
+  text: string;
+  done: boolean;
+}
+
+function TodoList() {
+  const { value: todos, isLoading, error } = useMoltenDbResource<Record<string, Todo>>(
+    'todos',
+    (col) => col.get().exec()
+  );
+
+  if (isLoading) return <p>Loading…</p>;
+  if (error) return <p>Error: {error.message}</p>;
+  if (!todos) return <p>No todos yet.</p>;
+
+  return (
+    <ul>
+      {Object.entries(todos).map(([id, todo]) => (
+        <li key={id} style={{ textDecoration: todo.done ? 'line-through' : 'none' }}>
+          {todo.text}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+#### With query builder options
+
+```tsx
+const { value: expensiveLaptops } = useMoltenDbResource(
+  'laptops',
+  (col) => col.get()
+    .where({ price: { $gt: 2000 }, in_stock: true })
+    .sort([{ field: 'price', order: 'asc' }])
+    .exec()
+);
+```
+
+### `useMoltenDbReady()`
+
+Returns `true` once MoltenDb has finished initialising. Useful for gating UI until the database is ready. Must be used inside `<MoltenDbProvider>`.
+
+```tsx
+import { useMoltenDbReady } from '@moltendb-web/react';
+
+function AppShell({ children }: { children: React.ReactNode }) {
+  const isReady = useMoltenDbReady();
+
+  if (!isReady) return <p>⚙ Initialising database…</p>;
+
+  return <>{children}</>;
+}
+```
+
+### `useMoltenDbIsLeader()`
+
+Returns `true` if the current tab is the **Leader** — the tab running the WASM worker and performing actual writes. Other tabs act as follower proxies that forward operations to the leader. Must be used inside `<MoltenDbProvider>`.
+
+```tsx
+import { useMoltenDbIsLeader } from '@moltendb-web/react';
+
+function TabBadge() {
+  const isLeader = useMoltenDbIsLeader();
+
+  return (
+    <span className="badge">
+      {isLeader ? '👑 Leader' : '🔗 Follower'}
+    </span>
+  );
+}
+```
+
+### `useMoltenDbTerminate()`
+
+Returns a function that terminates the MoltenDb worker. You must call this before clearing OPFS storage to avoid file-lock conflicts. Must be used inside `<MoltenDbProvider>`.
+
+```tsx
+import { useMoltenDbTerminate } from '@moltendb-web/react';
+
+function ResetButton() {
+  const terminate = useMoltenDbTerminate();
+
+  const handleReset = async () => {
+    if (!confirm('Delete all local data?')) return;
+    terminate();
+    const root = await navigator.storage.getDirectory();
+    await root.removeEntry('mydb', { recursive: true });
+    location.reload();
+  };
+
+  return <button onClick={handleReset}>🗑 Reset All Data</button>;
+}
+```
+
+### `useMoltenDbEvents(listener)`
+
+Subscribes to real-time mutation events from the database. The `listener` is called with a `DbEvent` whenever any document is created, updated, deleted, or a collection is dropped. Must be used inside `<MoltenDbProvider>`.
+
+```tsx
+import { useCallback, useState } from 'react';
+import { useMoltenDbEvents } from '@moltendb-web/react';
+import type { DbEvent } from '@moltendb-web/react';
+
+function LiveFeed() {
+  const [events, setEvents] = useState<DbEvent[]>([]);
+
+  useMoltenDbEvents(useCallback((evt: DbEvent) => {
+    setEvents((prev) => [evt, ...prev].slice(0, 50));
+  }, []));
+
+  return (
+    <ul>
+      {events.map((e, i) => (
+        <li key={i}>{e.event} — {e.collection}/{e.key}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+> **Tip:** Wrap the listener in `useCallback` with an empty dependency array to keep it stable and avoid re-subscribing on every render.
+
+## API Reference
+
+| Export | Type | Description |
+|---|---|---|
+| `MoltenDbProvider` | Component | Context provider — initializes MoltenDb and exposes the client to the subtree |
+| `useMoltenDb()` | Hook | Returns the `MoltenDbClient` instance |
+| `useMoltenDbReady()` | Hook | Returns `true` once MoltenDb has finished initialising |
+| `useMoltenDbIsLeader()` | Hook | Returns `true` if the current tab is the Leader (running the WASM worker) |
+| `useMoltenDbTerminate()` | Hook | Returns a function that terminates the MoltenDb worker — call before clearing OPFS storage |
+| `useMoltenDbResource(collection, queryFn)` | Hook | Reactive data fetching with `value`, `isLoading`, `error` and auto-refresh on mutations |
+| `useMoltenDbEvents(listener)` | Hook | Subscribe to real-time `DbEvent` mutation events |
+| `DbEvent` | Type | Event object emitted on mutations: `{ event, collection, key, new_v }` |
+| `MoltenDbProviderProps` | Interface | Props for `MoltenDbProvider`: `{ config: ReactMoltenDbOptions, children }` |
+| `ReactMoltenDbOptions` | Interface | Config passed to the provider — extends `MoltenDbOptions` with a required `name` field |
+| `MoltenDbResourceResult<T>` | Interface | Return type of `useMoltenDbResource`: `{ value, isLoading, error }` |
+
+## Configuration
+
+`ReactMoltenDbOptions` extends the core `MoltenDbOptions` with one required field:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `name` | `string` | **required** | Database name (used as the OPFS directory name) |
+| `inMemory` | `boolean` | `false` | Run entirely in RAM — no OPFS writes. Data persists as long as at least one tab is open; any tab refresh or close wipes the shared store for all tabs |
+| `encryptionKey` | `string` | `undefined` | Password for at-rest encryption. If omitted, data is stored as plain JSON |
+| `writeMode` | `'async' \| 'sync'` | `'async'` | Storage write mode: `'async'` for high throughput or `'sync'` for durable writes |
+| `hotThreshold` | `number` | `50000` | Maximum documents per collection to keep in RAM |
+| `maxBodySize` | `number` | `undefined` | Maximum request body size in bytes |
+| `maxKeysPerRequest` | `number` | `1000` | Maximum number of keys allowed per JSON request |
+| `workerUrl` | `string \| URL` | `undefined` | Custom URL or path to `moltendb-worker.js` |
+
+## Notes
+
+- `MoltenDbProvider` initialises the database asynchronously. Hooks will not return data until `isReady` is `true` — `useMoltenDbResource` handles this automatically by waiting before fetching.
+- Multiple `MoltenDbProvider` instances with the **same `name`** will share the same underlying OPFS storage but maintain separate in-memory instances. Use the same `name` across tabs for cross-tab sync via the built-in leader/follower mechanism.
+- The library ships both **ESM** (`dist/index.js`) and **CommonJS** (`dist/index.cjs`) builds with full TypeScript declarations.

package/dist/MoltenDbContext.d.ts

@@ -0,0 +1,18 @@
+import React from 'react';
+import { MoltenDb, MoltenDbOptions } from '@moltendb-web/core';
+import { MoltenDbClient } from '@moltendb-web/query';
+export interface ReactMoltenDbOptions extends MoltenDbOptions {
+    name: string;
+}
+export interface MoltenDbContextValue {
+    db: MoltenDb;
+    client: MoltenDbClient;
+    isReady: boolean;
+}
+export declare const MoltenDbContext: React.Context<MoltenDbContextValue | null>;
+export interface MoltenDbProviderProps {
+    config: ReactMoltenDbOptions;
+    children: React.ReactNode;
+}
+export declare function MoltenDbProvider({ config, children }: MoltenDbProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function useMoltenDbContext(): MoltenDbContextValue;

package/dist/index.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,a)=>(a=n==null?{}:e(i(n)),o(r||!n||!n.__esModule?t(a,`default`,{value:n,enumerable:!0}):a,n));let c=require(`react`);c=s(c,1);let l=require(`@moltendb-web/core`),u=require(`@moltendb-web/query`),d=require(`react/jsx-runtime`);var f=(0,c.createContext)(null);function p({config:e,children:t}){let[n,r]=(0,c.useState)(!1),i=(0,c.useRef)(null),a=(0,c.useRef)(null);return i.current||(i.current=new l.MoltenDb(e.name,e),a.current=new u.MoltenDbClient(i.current)),(0,c.useEffect)(()=>{i.current.init().then(()=>r(!0)).catch(e=>console.error(`[MoltenDb] Failed to initialize`,e))},[]),(0,d.jsx)(f.Provider,{value:{db:i.current,client:a.current,isReady:n},children:t})}function m(){let e=(0,c.useContext)(f);if(!e)throw Error(`[MoltenDb] useMoltenDbContext must be used inside <MoltenDbProvider>`);return e}function h(){return m().client}function g(){return m().isReady}function _(){return m().db.isLeader}function v(){let{db:e}=m();return()=>e.terminate()}function y(e){let{db:t,isReady:n}=m();(0,c.useEffect)(()=>{if(n)return t.subscribe(e)},[t,n,e])}function b(e,t){let{db:n,client:r,isReady:i}=m(),[a,o]=(0,c.useState)(void 0),[s,l]=(0,c.useState)(!1),[u,d]=(0,c.useState)(null),f=(0,c.useRef)(t);return f.current=t,(0,c.useEffect)(()=>{if(!i)return;let t=!1,a=async()=>{l(!0);try{let n=await f.current(r.collection(e),r);t||(o(n),d(null))}catch(e){t||(e.message?.includes(`404`)?(o([]),d(null)):d(e))}finally{t||l(!1)}};a();let s=n.subscribe(t=>{t.collection===e&&a()});return()=>{t=!0,s()}},[i,e,n,r]),{value:a,isLoading:s,error:u}}exports.MoltenDbProvider=p,exports.useMoltenDb=h,exports.useMoltenDbEvents=y,exports.useMoltenDbIsLeader=_,exports.useMoltenDbReady=g,exports.useMoltenDbResource=b,exports.useMoltenDbTerminate=v;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { MoltenDbProvider } from './MoltenDbContext';
+export type { ReactMoltenDbOptions, MoltenDbProviderProps } from './MoltenDbContext';
+export { useMoltenDb, useMoltenDbReady, useMoltenDbIsLeader, useMoltenDbTerminate, useMoltenDbEvents } from './useMoltenDb';
+export type { DbEvent } from '@moltendb-web/core';
+export { useMoltenDbResource } from './useMoltenDbResource';
+export type { MoltenDbResourceResult } from './useMoltenDbResource';

package/dist/index.js

@@ -0,0 +1,86 @@
+import { createContext as e, useContext as t, useEffect as n, useRef as r, useState as i } from "react";
+import { MoltenDb as a } from "@moltendb-web/core";
+import { MoltenDbClient as o } from "@moltendb-web/query";
+import { jsx as s } from "react/jsx-runtime";
+//#region src/MoltenDbContext.tsx
+var c = e(null);
+function l({ config: e, children: t }) {
+	let [l, u] = i(!1), d = r(null), f = r(null);
+	return d.current || (d.current = new a(e.name, e), f.current = new o(d.current)), n(() => {
+		d.current.init().then(() => u(!0)).catch((e) => console.error("[MoltenDb] Failed to initialize", e));
+	}, []), /* @__PURE__ */ s(c.Provider, {
+		value: {
+			db: d.current,
+			client: f.current,
+			isReady: l
+		},
+		children: t
+	});
+}
+function u() {
+	let e = t(c);
+	if (!e) throw Error("[MoltenDb] useMoltenDbContext must be used inside <MoltenDbProvider>");
+	return e;
+}
+//#endregion
+//#region src/useMoltenDb.ts
+function d() {
+	return u().client;
+}
+function f() {
+	return u().isReady;
+}
+function p() {
+	return u().db.isLeader;
+}
+function m() {
+	let { db: e } = u();
+	return () => e.terminate();
+}
+function h(e) {
+	let { db: t, isReady: r } = u();
+	n(() => {
+		if (r) return t.subscribe(e);
+	}, [
+		t,
+		r,
+		e
+	]);
+}
+//#endregion
+//#region src/useMoltenDbResource.ts
+function g(e, t) {
+	let { db: a, client: o, isReady: s } = u(), [c, l] = i(void 0), [d, f] = i(!1), [p, m] = i(null), h = r(t);
+	return h.current = t, n(() => {
+		if (!s) return;
+		let t = !1, n = async () => {
+			f(!0);
+			try {
+				let n = await h.current(o.collection(e), o);
+				t || (l(n), m(null));
+			} catch (e) {
+				t || (e.message?.includes("404") ? (l([]), m(null)) : m(e));
+			} finally {
+				t || f(!1);
+			}
+		};
+		n();
+		let r = a.subscribe((t) => {
+			t.collection === e && n();
+		});
+		return () => {
+			t = !0, r();
+		};
+	}, [
+		s,
+		e,
+		a,
+		o
+	]), {
+		value: c,
+		isLoading: d,
+		error: p
+	};
+}
+//#endregion
+export { l as MoltenDbProvider, d as useMoltenDb, h as useMoltenDbEvents, p as useMoltenDbIsLeader, f as useMoltenDbReady, g as useMoltenDbResource, m as useMoltenDbTerminate };

package/dist/useMoltenDb.d.ts

@@ -0,0 +1,16 @@
+import { DbEvent } from '@moltendb-web/core';
+import { MoltenDbClient } from '@moltendb-web/query';
+/** Hook to access the MoltenDb Query Client directly. Must be used inside <MoltenDbProvider>. */
+export declare function useMoltenDb(): MoltenDbClient;
+/** Returns true once MoltenDb has finished initialising. Must be used inside <MoltenDbProvider>. */
+export declare function useMoltenDbReady(): boolean;
+/** Returns true if this tab is the Leader (running the WASM worker). Must be used inside <MoltenDbProvider>. */
+export declare function useMoltenDbIsLeader(): boolean;
+/** Returns a function that terminates the MoltenDb worker. Call before clearing OPFS storage. Must be used inside <MoltenDbProvider>. */
+export declare function useMoltenDbTerminate(): () => void;
+/**
+ * Hook to subscribe to real-time MoltenDb mutation events.
+ * The callback is called whenever any document in the database changes.
+ * Must be used inside <MoltenDbProvider>.
+ */
+export declare function useMoltenDbEvents(listener: (event: DbEvent) => void): void;

package/dist/useMoltenDbResource.d.ts

@@ -0,0 +1,15 @@
+import { MoltenDbClient } from '@moltendb-web/query';
+export interface MoltenDbResourceResult<T> {
+    value: T | undefined;
+    isLoading: boolean;
+    error: any | null;
+}
+/**
+ * Hook to reactively fetch data from a MoltenDb collection.
+ * Automatically re-fetches when the collection changes.
+ * Must be used inside <MoltenDbProvider>.
+ *
+ * @param collection - The collection name to query.
+ * @param queryFn - A function receiving the pre-bound collection accessor and the full client.
+ */
+export declare function useMoltenDbResource<T>(collection: string, queryFn: (collection: ReturnType<MoltenDbClient['collection']>, client: MoltenDbClient) => Promise<T>): MoltenDbResourceResult<T>;

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@moltendb-web/react",
+  "version": "1.7.0",
+  "description": "Official React hooks wrapper for MoltenDb",
+  "type": "module",
+  "author": "Maximilian Both <maximilian.both27@outlook.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/maximilian27/moltendb-web/tree/master/packages/react"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build && tsc --emitDeclarationOnly --declaration --declarationDir dist",
+    "dev": "vite build --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "dependencies": {
+    "@moltendb-web/core": "^1.7.0",
+    "@moltendb-web/query": "^1.7.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "react": "^19.2.5",
+    "typescript": "^5.5.3",
+    "vite": "^8.0.10",
+    "vite-plugin-dts": "^3.0.0"
+  }
+}