OIMDB
OIMDB is state management for applications that outgrew a basic store: a wide toolkit at close to the cost of a hand-written implementation. It ships signals (computed values and effects), granular subscriptions down to one column of one entity, and memory management that releases whatever nothing holds or watches, under a policy you pick; general-purpose stores keep everything until you delete it yourself. It holds every entity of your application once, keeps groups, sorted views and derived values in sync with it, and tells subscribers what changed. It does so once per frame, the delivery of every write made since the previous one (see the glossary), however many writes landed.
It is for applications built on collections: cards, messages, tasks, anything with an id that shows up in more than one list or screen. It covers what a bare store leaves to you: normalised storage, grouping by a column, sorted views, per-entity and per-column subscriptions, batching, and releasing what nobody holds. It is not worth it for a few global values with no collections behind them, where a signal library or a bare store is enough. Why OIMDB works through the same task with zustand and with OIMDB.
npm install @oimdb/core
These pages describe @oimdb/core 4.x. See
Installation for the other packages.
The one idea
A key is resolved to an identity once. From then on, every read, write and subscription goes through that identity. A bucket holds the slots themselves, each one the identity of an entity; a subscription is a handler hanging on an identity; a bucket is an identity whose content is other identities.
That is why a write goes through the identity (slot.updateEntity(patch),
slot.clearSlotContent()). The one write that takes a key, writeSlotContentByKey, hands the
identity back so you keep it; a caller holding
only a key resolves it first with getSlotByKey, so the lookup is a call you can see.
'c1'content: slot.entitytitlerank'spades'content: the entity slots filed under that key'spades'its value is derived from its source slots, refreshed by the read that asks for itThree sentences carry the rest:
- Four doors mint an identity: writing a value, subscribing, taking a
hold, and
getSlotByKey, whose mint the unused-slot collector holds for the turn.peekSlotByKeyandhasSlotContentByKeyread without minting. - A slot goes when nothing refers to it, and whatever took a reference gives it back.
- Where a trade-off has two defensible strategies, both ship and you pick one at construction, so no branch is left on a hot path.
See The model.
A small example
import { OIMDB, OIMEffectService, type TOIMEntitySlot, createOIMEntityContentService, createOIMSlotCollectionService, OIMPositionalArrayBucketContentService, OIMBucketCommands } from '@oimdb/core';
type Card = { id: string; deck: string; title: string };
const db = new OIMDB();
const effectService = OIMEffectService.INSTANCE;
const cardService = createOIMSlotCollectionService({ slotContentService: createOIMEntityContentService<Card>() });
const cards = cardService.createStoreSlot(db);
const byDeckService = createOIMSlotCollectionService({ slotContentService: new OIMPositionalArrayBucketContentService<TOIMEntitySlot<Card>>({ bucketCommands: new OIMBucketCommands({ maxCommandsPerSlot: undefined }) }) });
const byDeck = byDeckService.createStoreSlot(db);
const first = cardService.writeSlotContentByKey(cards, 'c1', { id: 'c1', deck: 'd1', title: 'alpha' });
const deckOne = byDeckService.holdSlotByKey(byDeck, 'd1');
deckOne.writeSlotContent([first]);
db.flush();
const effect = effectService.createEffect(db, () => {
console.log('deck d1 now has', deckOne.getBucketMemberSlotCount(), 'card(s)');
}, [deckOne]);
const second = cardService.writeSlotContentByKey(cards, 'c2', { id: 'c2', deck: 'd1', title: 'beta' });
deckOne.writeSlotContent([first, second]);
db.flush(); // -> "deck d1 now has 2 card(s)"
effectService.disposeEffect(effect);
deckOne.unholdSlot();
OIMDB holds the clock, the default channel slot and the unused-slot collector slot that every
collection in the example shares. The optional strategies (entityWriter, slotReleasePolicy,
slotStamp, indexKeysService) are an OIMDefaults given to each factory as defaults. A service holds no
data: cardService is made once for the Card type, and cards is one store slot
of it, an instance carrying its own store. The collection service reads; its
slotContentService writes. A door that works on the store takes the
store slot first (writeSlotContentByKey(cards, …)); a door that works on a slot takes only
the slot. byDeck is a
manual bucket store slot: you write what a bucket holds, because no column
can express "the server did not return these". When membership follows from a
column, an index fills the buckets instead. Quick Start
builds that version, with a sorted view on top.
Every write is reported to the channel slot of the store slot it lands in.
createOIMSlotCollectionStoreAggregate(db, options) is the short form: it builds
createOIMSlotCollectionService(options), creates its store slot on db, and binds the two.
See Writing.
Packages
| Package | What it is |
|---|---|
@oimdb/core | The engine. |
@oimdb/react | React bindings: OIMDBProvider, useOIMDB, one read hook, useOIMSelector(db => …), which re-renders on what it read, and shorthands over it (useOIMEntityByKey, useOIMSingleEntity, …). |
@oimdb/persist | Storage-agnostic persistence, with five backends: persist-idb, persist-localstorage, persist-async-kv, persist-json, persist-memory. |
@oimdb/redux-adapter | Mirrors entity and bucket store slots into Redux. |
@oimdb/devtools | A debug registry: name store slots and indexes, inspect runtime state. |
@oimdb/cli | The command line: inspect a live page, a model module or Chrome over CDP, and run the DevTools UI. |
@oimdb/mcp | An MCP server that connects AI assistants without a shell to live browser state. |
See Packages for what each one imports from the core.