Skip to main content

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.

entity collection
entity slot 'c1'content: slot.entity
column slottitle
column slotrank
→
bucket collection or index
bucket 'spades'content: the entity slots filed under that key
→
computed collection
computed 'spades'its value is derived from its source slots, refreshed by the read that asks for it
→
effectfiled on the slots it reads; a frame runs it when one of them moved
Every box is a slot except the effect. Each slot has an owner, the collection that files it, and a count of what holds it.

Three sentences carry the rest:

  1. Four doors mint an identity: writing a value, subscribing, taking a hold, and getSlotByKey, whose mint the unused-slot collector holds for the turn. peekSlotByKey and hasSlotContentByKey read without minting.
  2. A slot goes when nothing refers to it, and whatever took a reference gives it back.
  3. 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​

PackageWhat it is
@oimdb/coreThe engine.
@oimdb/reactReact bindings: OIMDBProvider, useOIMDB, one read hook, useOIMSelector(db => …), which re-renders on what it read, and shorthands over it (useOIMEntityByKey, useOIMSingleEntity, …).
@oimdb/persistStorage-agnostic persistence, with five backends: persist-idb, persist-localstorage, persist-async-kv, persist-json, persist-memory.
@oimdb/redux-adapterMirrors entity and bucket store slots into Redux.
@oimdb/devtoolsA debug registry: name store slots and indexes, inspect runtime state.
@oimdb/cliThe command line: inspect a live page, a model module or Chrome over CDP, and run the DevTools UI.
@oimdb/mcpAn MCP server that connects AI assistants without a shell to live browser state.

See Packages for what each one imports from the core.

Where to go for your task​

Start​

Store and change data​

Derive and deliver​

Apps and operations​

Under the hood​