@plures/unum

Reactive PluresDB bindings for Svelte — backend-agnostic, TypeScript-first, Svelte 5 runes-ready.

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• API Reference
• Custom Adapters
• Examples
• Migration Guide
• Contributing
• Changelog
• License

Features

• Svelte 4 & 5 Compatible — store protocol and runes ($state, $derived, $effect)
• TypeScript-first — fully typed generics throughout
• Backend-agnostic — swap databases via the DbAdapter interface
• Real-time — subscription-based reactivity, no polling
• P2P — optional Hyperswarm adapter for peer-to-peer graph sync
• Graph & Collection APIs — purpose-built primitives for complex data

Requirements

| Requirement | Version | |---|---| | Node.js | ≥ 18 | | Svelte | 4.x or 5.x | | TypeScript | ≥ 5.0 (optional but recommended) |

Peer dependencies (install as needed):

| Package | Required for | |---|---| | svelte | All usage | | pluresdb | createPluresDbAdapter() | | hyperswarm | createHyperswarmAdapter() | | @plures/praxis | Praxis rule-engine modules |

Installation

npm install @plures/unum

Quick Start

import { initDb, createMemoryAdapter, createCollection } from '@plures/unum';

// 1. Initialize with an adapter once at app startup
initDb(createMemoryAdapter());

// 2. Use reactive APIs anywhere
interface Task { title: string; done: boolean }
const tasks = createCollection<Task>('tasks');

const id = tasks.add({ title: 'Buy milk', done: false });
tasks.update(id, { done: true });
tasks.remove(id);

API Reference

See docs/API.md for the complete exported API surface.

Adapter Setup

initDb(adapter)

Initialize unum with a database adapter. Call once at app startup before using any data bindings.

import { initDb, createPluresDbAdapter } from '@plures/unum';
import PluresDB from 'pluresdb';

initDb(createPluresDbAdapter(new PluresDB({ localStorage: true })));

destroyDb()

Tear down the current adapter and reset the context.

getAdapter()

Return the current DbAdapter (throws if initDb() has not been called).

getRoot()

Return a root ChainNode from the current adapter.

db

Svelte-compatible readable store containing the current DbAdapter | null. Useful for lazy-init patterns.

Collections — createCollection<T>(path)

Create a reactive typed collection binding backed by PluresDB.

<script>
  import { createCollection } from '@plures/unum';

  interface Task { title: string; done: boolean }
  const tasks = createCollection<Task>('tasks');

  const pending = tasks.query(items => items.filter(i => !i.data.done));
</script>

{#each tasks.items as task}
  <p class:done={task.data.done}>{task.data.title}</p>
{/each}

CollectionRef<T> properties & methods

| Member | Description | |---|---| | items | Current items as Array<CollectionItem<T>> | | size | Number of items | | add(data) | Add an item; returns generated ID | | update(id, data) | Merge partial data into an item | | remove(id) | Delete an item | | get(id) | Retrieve a single item (or undefined) | | query(selector) | Create a derived reactive query (returns CollectionQuery<R>) | | subscribe(cb) | Svelte 4 store protocol | | destroy() | Tear down subscriptions |

Graph — useGraph<N, E>(path)

Create a reactive typed graph binding backed by PluresDB.

<script>
  import { useGraph } from '@plures/unum';

  const graph = useGraph<{ label: string }, { weight: number }>('my-graph');

  const heavy = graph.query(
    (nodes, edges) => edges.filter(e => e.data.weight > 10)
  );
</script>

{#each graph.nodes as node}
  <p>{node.data.label}</p>
{/each}

GraphRef<N, E> properties & methods

| Member | Description | |---|---| | nodes | Current nodes as Array<GraphNode<N>> | | edges | Current edges as Array<GraphEdge<E>> | | state | Full GraphState<N, E> snapshot | | addNode(data) | Add a node; returns generated ID | | updateNode(id, data) | Merge partial data into a node | | removeNode(id) | Remove a node and all its incident edges | | addEdge(source, target, data?) | Add a directed edge; returns generated ID | | updateEdge(id, data) | Merge partial data into an edge | | removeEdge(id) | Remove an edge | | query(selector) | Create a derived reactive query (returns GraphQuery<T>) | | findPath(fromId, toId) | BFS shortest path between two nodes | | subscribe(cb) | Svelte 4 store protocol | | destroy() | Tear down subscriptions |

Reactive Data — pluresData<T>(path, id?)

Low-level reactive binding to a PluresDB path. Suitable for single-document or collection bindings without the typed Collection API.

<script>
  import { pluresData } from '@plures/unum';
  const todos = pluresData('todos');
</script>

{#each todos.list() as todo}
  <p>{todo.text}</p>
{/each}

DataRef<T> properties & methods

| Member | Description | |---|---| | state | Current raw state snapshot | | value | Single item (id-bound) or item array (collection) | | list() | Items as an array (collections only) | | add(data) | Add an item to the collection | | update(idOrUpdater, updater?) | Update item(s) | | remove(id?) | Remove an item (or the bound item) | | subscribe(cb) | Svelte store protocol | | destroy() | Tear down subscriptions |

Derived & Bind — pluresDerived / pluresBind

import { pluresData, pluresDerived, pluresBind } from '@plures/unum';

const todos  = pluresData('todos');
const done   = pluresDerived(todos, items => items.filter(i => i.done));
const title  = pluresBind(todos, 'title');   // two-way binding for a field

Store — PluresStore<T> / createPluresStore<T>

A Svelte-compatible writable store that syncs a single scalar value with PluresDB. Implements the full store contract (subscribe / set / update).

import { initDb, createMemoryAdapter, createPluresStore } from '@plures/unum';

initDb(createMemoryAdapter());

const theme = createPluresStore<'light' | 'dark'>('settings/theme', 'light');
theme.set('dark');
theme.update(t => t === 'dark' ? 'light' : 'dark');
theme.destroy();

Adapters

createMemoryAdapter()

Fully in-memory adapter. Data is not persisted. Ideal for unit tests and server-side rendering.

import { initDb, createMemoryAdapter } from '@plures/unum';
initDb(createMemoryAdapter());

createPluresDbAdapter(db)

Wrap a PluresDB instance.

import PluresDB from 'pluresdb';
import { initDb, createPluresDbAdapter } from '@plures/unum';

initDb(createPluresDbAdapter(new PluresDB({ localStorage: true })));

createGunAdapter(gun)

Wrap an existing Gun.js instance for migration scenarios.

import Gun from 'gun';
import { initDb } from '@plures/unum';
import { createGunAdapter } from '@plures/unum/adapters';

initDb(createGunAdapter(Gun({ peers: ['http://localhost:8765/gun'] })));

createHyperswarmAdapter(swarm, inner)

Add P2P sync to any inner adapter via Hyperswarm.

import Hyperswarm from 'hyperswarm';
import { createHash } from 'node:crypto';
import { initDb, createMemoryAdapter } from '@plures/unum';
import { createHyperswarmAdapter } from '@plures/unum/adapters';

const swarm = new Hyperswarm();
swarm.join(createHash('sha256').update('my-topic').digest());

initDb(createHyperswarmAdapter(swarm, createMemoryAdapter()));

Praxis Modules (@plures/unum/praxis)

Logic modules for the @plures/praxis rule engine.

| Module | Factory | Description | |---|---|---| | Merge Policy | mergePolicyModule(config) | Conflict resolution for multi-source data | | Schema Unification | schemaUnificationModule(config) | Schema compatibility & coercion rules | | Subscription Policy | subscriptionPolicyModule(config) | Stream routing & auth gate | | Freshness | freshnessModule(config) | TTL / cache-invalidation rules |

import { PraxisRegistry } from '@plures/praxis';
import {
  mergePolicyModule,
  schemaUnificationModule,
  subscriptionPolicyModule,
  freshnessModule,
} from '@plures/unum/praxis';

const registry = new PraxisRegistry();
registry.registerModule(mergePolicyModule({ priorities: { remote: 10, local: 5 } }));
registry.registerModule(schemaUnificationModule());
registry.registerModule(subscriptionPolicyModule({ requireAuth: true }));
registry.registerModule(freshnessModule({ defaultTtlMs: 60_000 }));

Utility Helpers

These helpers are exported from the main package entry point.

| Helper | Description | |---|---| | isPluresAvailable(adapter) | Type guard — returns true when adapter is non-null | | safeGet(obj, path, default?) | Read a deeply nested property via dot-path | | safeMap(dbData, callback, filter?) | Transform a DB record object into an array | | safeChain(adapter, path?) | Build a ChainNode from a dot-separated path string |

Custom Adapters

Implement the DbAdapter interface to connect any backend:

import type { DbAdapter, ChainNode } from '@plures/unum';

export function createMyAdapter(): DbAdapter {
  return {
    root(): ChainNode {
      // return a ChainNode bound to your backend
    },
    destroy?(): void {
      // optional cleanup
    },
  };
}

Examples

Runnable examples are in the examples/ directory:

| Example | Description | |---|---| | examples/svelte-kit-demo | Full SvelteKit app using createCollection and useGraph | | examples/deno-svelte-demo | Deno + Svelte demo with the memory adapter |

Migration Guide

Migrating from the PluresStore/pluresData (Svelte 4) API to the useGraph()/createCollection() runes API? See MIGRATION.md for a step-by-step guide.

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository and create a feature branch (git checkout -b feat/my-feature).
2. Install dependencies: npm install.
3. Make your changes; add or update tests in tests/.
4. Run the full test suite: npm test.
5. Run the type-checker: npm run lint.
6. Commit using Conventional Commits (feat:, fix:, chore:, docs:, etc.).
7. Open a pull request against main.

Note: All public API functions must have JSDoc comments with @param and @example tags. The README must stay in sync with exports in src/index.ts.

Changelog

See CHANGELOG.md for a full history of notable changes.

License

MIT