mumpixfe

React package for the Mumpix frontend runtime.

mumpixfe ships three layers so you can adopt it incrementally:

• Full UI app: MumpixFE
• React hooks/runtime: useMumpix, usePrefix
• Core DB engine: MumpixDB

The Mumpix Family

• MumpixDB — Mumpix Database
• MumpixFS — Mumpix File System
• MumpixFE — Mumpix Frontend
• MumpixSL — Mumpix System Level

Install

npm install mumpixfe

Requirements

• React >=18
• ReactDOM >=18
• Browser runtime for hooks/app (indexedDB, WebSocket)
• Works in local-only mode when WebSocket is unavailable

Package Entry Points

import { MumpixFE, useMumpix, usePrefix, MumpixDB } from "mumpixfe";

import { MumpixFE } from "mumpixfe/app";
import { useMumpix, usePrefix } from "mumpixfe/hooks";
import { MumpixDB } from "mumpixfe/core";

Quick Start (Full App)

import { MumpixFE } from "mumpixfe";

export default function Page() {
  return <MumpixFE />;
}

Hook Runtime

useMumpix()

Returns:

• db: active MumpixDB singleton
• ready: runtime bootstrap state
• syncState: connecting | connected | synced | disconnected | local-only
• api.set(key, value): writes key and pushes sync delta
• api.del(key): deletes key and pushes sync delta

import { useMumpix } from "mumpixfe";

export function Controls() {
  const { ready, syncState, api } = useMumpix();
  if (!ready) return <div>Booting...</div>;

  return (
    <button onClick={() => api.set("memory^user^name", "Carrera")}>
      write key ({syncState})
    </button>
  );
}

usePrefix(db, ready, prefix)

Reactive prefix scanner backed by watchPrefix.

import { useMumpix, usePrefix } from "mumpixfe";

export function Inspector() {
  const { db, ready } = useMumpix();
  const entries = usePrefix(db, ready, "memory^");
  return <pre>{JSON.stringify(entries, null, 2)}</pre>;
}

Core Engine (MumpixDB)

MumpixDB is fully usable without React.

import { MumpixDB } from "mumpixfe/core";

const db = new MumpixDB({ name: "local" });
db.set("memory^user^name", "Carrera");
console.log(db.get("memory^user^name"));

Core Methods

• set(key, value)
• get(key)
• delete(key)
• scan(prefix?, options?)
• children(prefix?)
• watch(key, callback)
• watchPrefix(prefix, callback)
• batch(ops)
• merge(prefix, obj)
• export(prefix?)
• delta(sinceGeneration?)
• applyDelta(delta)
• serialize() / MumpixDB.deserialize(serialized)
• stats()

Sync Model

useMumpix() includes a built-in sync client:

• local hostnames use /ws
• non-local hostnames use /benchmark/ws
• sends HELLO { generation }
• receives SNAPSHOT and DELTA
• pushes local DELTA after writes

If connection fails, state transitions to disconnected and auto-reconnects.

Persistence Model

By default the runtime persists into IndexedDB:

• DB name: mumpixdb-client
• Store: kv

Startup flow:

1. open IndexedDB adapter
2. load all persisted keys
3. hydrate in-memory MumpixDB
4. start sync bridge

Troubleshooting

• indexedDB is not defined: render hooks only on the client.
• syncState never reaches synced: verify WS endpoint and proxy path.
• UI updates missing: ensure writes hit the same prefix being watched.

License

BUSL-1.1