@bhooai/nexus-fusion

A from-scratch embedded database for the Nexus framework: a Firebase-style API over a Rust engine implementing a branched decomposition tree, write-ahead journal, Mongo-style query compiler, and an inbuilt LRU cache. No Firebase/Mongo/Redis dependency in the core — those remain optional adapters.

Architecture

TypeScript (this package)          Firebase-style API, onSnapshot, offline
  collection()/doc()/where()       queue, security rules, schemas
        │ napi-rs
Rust core (nexus-fusion-core)      tree engine, WAL + crash recovery,
                                   query compiler, L1 LRU cache, sortable ids

• Branched decomposition tree: root → database → branch → collection → document. Every node addressable by path (main/prod/users/u1); branches are isolated namespaces (prod/staging/feature).
• Durability: append-only WAL with replay-on-open and auto-compaction; pure in-memory mode when no dir is given.
• Inbuilt cache: L1 LRU with TTL inside the engine; every read is cache-through, every write invalidates.
• Versioning: every write bumps a per-document version; optimistic concurrency via setIfVersion.

Quick start

import { fusion } from '@bhooai/nexus-fusion';

// In-memory (dev/test):
const db = fusion('main', 'prod');
// Durable (WAL on disk):
const disk = fusion('main', 'prod', { dir: './data/fusion' });

// Firebase-style writes
const ref = await db.collection('users').add({ name: 'alice', age: 30 });
await db.collection('users').doc('u1').set({ name: 'bob' });
await db.collection('users').doc('u1').update({ age: increment(1) });

// Mongo-style querying
const snap = await db.collection('users')
  .where('age', '>=', 18)
  .orderByField('age', 'desc')
  .limit(10)
  .get();

// Live queries
const unsub = db.collection('users').onSnapshot((snap) => {
  console.log(snap.size, snap.docs);
});
unsub();

// Offline queue (optimistic writes, flushed on sync)
db.queueUpdate('users', 'u1', { status: 'paid' });
await db.sync();

// Security rules
db.security.match('main/prod/users/{uid}', {
  read: (doc, ctx) => ctx.auth?.uid === doc.id,
  write: (_doc, ctx) => ctx.auth?.role === 'admin',
});
db.setRuleContext({ auth: { uid: 'u1', role: 'user' }, params: {} });
await db.checkPermission('read', 'users', 'u1', { id: 'u1', data: {} });

Predefined schemas

import { usersSchema, postsSchema, ordersSchema, validate } from '@bhooai/nexus-fusion/schemas' — auth (users/sessions/audit), CMS (posts/comments/categories/media), e-commerce (products/orders/carts/inventory).

Optional adapters (peer deps, lazy-loaded)

• MongoMirror — async best-effort write mirror to MongoDB (mongodb)
• RedisBridge — cross-instance onSnapshot fan-out via Redis pub/sub (redis)

Building the native core

Requires Rust (rustup, stable-msvc or platform equivalent):

cd packages/nexus-fusion
npm run build:native     # napi build --release into nexus-fusion-core/

The loader finds nexus-fusion-core/fusion.<platform>-<arch>-<abi>.node by walking up from the package, or a published @bhooai/nexus-fusion-<platform>-<arch>-<abi> package via optionalDependencies.

Tests

• Rust: cargo test in packages/nexus-fusion-core (22 unit tests: tree, WAL recovery/compaction, query ops, cache eviction, idgen, events)
• TS: npx vitest run --root packages/nexus-fusion (19 tests: CRUD, transforms, queries, onSnapshot, offline queue, rules, durability)