@oimdb/core 3.7.0 → 3.9.0

package/llms.txt

@@ -13,6 +13,7 @@ OIMDB is a TypeScript in-memory reactive database. It stores entities in typed c
 | `@oimdb/core` | Collections, indexes, event queue, reactive primitives |
 | `@oimdb/persist` | Storage-agnostic persist/hydrate engine (source adapters, resources, versioned codec). Backends ship separately: `@oimdb/persist-memory`, `-localstorage`, `-idb`, `-async-kv`, `-json` |
 | `@oimdb/react` | React hooks for collections and selectors |
+| `@oimdb/exodra` | [Exodra](https://exodra.org) adapter: OIMDB selectors/computeds → read-only `TExoBindable` (no React) |
 | `@oimdb/async` | Async-aware reactive collection and index variants |
 | `@oimdb/devtools` | Debug registry: name collections/indexes/computeds, inspect runtime state |
 | `@oimdb/snapshot-manager` | Snapshot/restore collection state |
@@ -114,6 +115,35 @@ const active = indexFactory.derivedSetGlobalIndex({ filter: (u) => !u.archived }
 - Selectors: `select.entitiesByArrayGlobalIndex(list)` / `select.entitiesBySetGlobalIndex(set)` → `(TEntity | undefined)[]` (no key).
 - React: `useSelectEntitiesByGlobalIndex{Array,Set}Based(collection, index)`, `useSelectPksByGlobalIndex{Array,Set}Based(index)`, plus `…Signal` variants — all drop the `key` argument.
 
+### Composite (key-path) indexes
+
+When the key is a **combination of values** (e.g. `[userId, projectId, role]`) rather than one primitive, use a **composite** set-based index instead of concatenating a string key. Create it with `indexFactory.compositeSetIndex()`. The key is a `TOIMKeyPath` — an ordered, **arbitrary-length** tuple of primitive segments (`readonly (string | number)[]`). Every method that takes a `key` takes a path array instead; everything else (pk writes, slot resolution, reactivity, `getEntitiesByKey` holes) is identical to `setBasedIndex`.
+
+```ts
+const membersByScope = indexFactory.compositeSetIndex();
+membersByScope.setPks(['u1', 'p1', 'admin'], ['m1', 'm2']); // also addPks / removePks
+membersByScope.getPksByKey(['u1', 'p1', 'admin']);          // Set { 'm1', 'm2' }
+membersByScope.getEntitiesByKey(['u1', 'p1', 'admin']);     // (Member | undefined)[]
+membersByScope.subscribeOnKey(['u1', 'p1', 'admin'], () => {/* … */});
+queue.flush();
+```
+
+- **Matched by content, not reference / string.** A freshly built `['u1','p1','admin']` resolves to the same bucket as the one written earlier — no need to reuse the array instance. Segments keep their own type (`1` ≠ `'1'`) and no separator can collide (`['a|b','c']` ≠ `['a','b|c']`), unlike a `"a|b|c"` string key.
+- **Full path is the lookup unit.** O(arity) — effectively O(1) for a fixed arity — a lookup walks one native-`Map` level per segment. No partial/prefix queries (subscribe/lookup are by the whole path). Paths of different lengths coexist (`['a','b']` and `['a','b','c']` never collide).
+- **No perf cost to primitive indexes.** It is a distinct opt-in index: `setBasedIndex` and all others keep their native-`Map` fast path untouched. The trie cost is paid only where you use a composite index.
+- **Ordered variant:** `indexFactory.compositeArrayIndex()` — same key path, but buckets are ordered slot arrays (`getPksByKey` returns an array in write order). Use it when order matters per composite key (e.g. `[channelId, threadId]` messages).
+- **Selectors:** `select.entitiesByCompositeSetIndexKey(index, path)` / `select.entitiesByCompositeArrayIndexKey(index, path)` → `(TEntity | undefined)[]`, tracking both index and entity changes.
+- **React:** `useSelectEntitiesByCompositeIndexKey{Set,Array}Based(collection, index, path)` and `useSelectPksByCompositeIndexKey{Set,Array}Based(index, path)`. Unlike the primitive hooks (which stabilize the key by `===`), these stabilize the path **by content**, so a freshly built `['p1','admin']` on every render does not re-subscribe.
+- New exports: `OIMReactiveCollectionIndexCompositeTrie{Set,Array}Based`, `OIMIndexStoreTrieDriven{Set,Array}Based` (inject via `indexOptions.store` for a custom key path store), `OIMKeyPathCarrierProvider`, `OIMTrieMap` (the generic N-level trie util), types `TOIMKeyPath` / `TOIMKey`. The keyed-emitter / index generics accept `TKey extends TOIMKey` (= `TOIMPk | TOIMKeyPath`) — a pure widening; primitive keys are unaffected.
+
+### Composite PRIMARY key (collection keyed by a tuple)
+
+Beyond composite index *keys*, a **collection's PK itself** can be a composite path. Pass a trie store: `new OIMReactiveCollection(queue, { selectPk: e => [e.userId, e.projectId], store: new OIMCollectionStoreTrieDriven() })`. Then `getOneByPk([1,10])`, `subscribeOnKey([1,10])`, `removeOneByPk([1,10])` all match by content; the store interns each logical PK to one canonical `slot.pk` reference so downstream native `Set<pk>` stays correct. Primitive-PK collections keep `OIMCollectionStoreMapDriven` (native `Map`) untouched — no regression.
+
+- **Indexes work over a composite-PK collection.** `indexFactory.setBasedIndex()` (or `compositeSetIndex`) on such a collection indexes composite PKs: `byRole.setPks('admin', [[1,10],[2,10]])`, `getPksByKey`, `addPks`, `removePks([[2,10]])` all match PKs by content (the per-bucket pk→slot membership uses the collection's trie key domain).
+- **Serialization boundaries.** `@oimdb/persist` (stores entities as an array, re-derives the PK via `selectPk` on hydrate) and `@oimdb/snapshot-manager` (stores the PK as a value) round-trip a composite PK with **no codec** — just pass the composite-PK collection. **`@oimdb/redux-adapter`** keys Redux state by string (`Record<pk, entity>`), so a composite PK needs an `IOIMPkCodec`: pass it to `createCollectionReducer(collection, child?, mapper?, pkCodec)` — one codec drives both the default mapper (encode: `entities` keyed by JSON-encoded PK, `ids` keep the raw tuple) AND child write-back / linked-index sync (decode: Redux string key → raw PK). `OIMPkCodecKeyPath` is the ready codec. (Or pass `mapper: createDefaultCollectionMapper(codec)` directly for a read-only projection.)
+- New exports: `OIMCollectionStoreTrieDriven`, `OIMKeyDomainTrie` / `OIMKeyDomainNative` (`IOIMKeyDomain`), `OIMTrieSet`, `IOIMPkCodec` / `OIMPkCodecKeyPath`. The collection/index PK generics accept `TPk extends TOIMKey`.
+
 ### Ordered list command stream
 
 For an ordered per-key list that emits **position-addressed commands** (insert / remove / move / set / reset) instead of a new array to diff — for imperative renderers that apply edits in place. `OIMCollectionOrderedListCommandStream` (pk writes, via `indexFactory.orderedList()`) or `OIMOrderedListCommandStream` (slot writes). Commands are not in the event payload — subscribe, then pull synchronously.
@@ -227,6 +257,8 @@ const logEffect = new OIMEffect(runtime, {
 - `OIMEffectDependencyKeyedIndex(index, key)` — watch a key in an index
 - `OIMEffectDependencyComputed(computed)` — depend on another computed
 
+Each keyed dependency watches exactly **one** key — the key argument is the whole key, so a composite key/PK path `[a, b]` is one key (never split into `a`, `b`). For a composite-PK collection or composite index, pass the tuple: `new OIMEffectDependencyKeyedCollection(reqs, ['t1', 'open'])`. To depend on several keys, add several dependencies to the effect's `deps` array.
+
 ### Objects
 
 Key-value stores for singleton data (settings, flags, etc.).
@@ -317,6 +349,42 @@ Signal hooks: `useSelectEntityByPkSignal(collection, pk)`, `useSelectPksByIndexK
 
 Trade-offs (use only when every reader is subscription-driven): NOT Concurrent-safe; the entity reference is stable across changes, so `React.memo` on entities, prev/next diffing, time-travel, and the default uSES hooks on the same collection won't see updates. Default to the standard immutable hooks; reach for this only when a profile shows the data layer is the bottleneck.
 
+## Exodra (`@oimdb/exodra`)
+
+```bash
+npm install @oimdb/exodra @exodra/reactivity @oimdb/core
+```
+
+The [Exodra](https://exodra.org) counterpart of `@oimdb/react`: instead of a hook + re-render, every OIMDB source becomes a read-only Exodra bindable (`TExoBindable<T> = { getValue(): T; subscribe(update): () => void }`). No React. Built on `@oimdb/core`'s `OIMSelector` (`{ getValue, watch }`) — the fine-grained subscription already lives there, so this is a thin adapter. Bindables are read-only, lazy (subscribe upstream only while they have a downstream subscriber → cost O(visible)) and SSR-safe (`getValue()` reads fresh, valid without an active subscription).
+
+```ts
+import { fromSelector, bindSelectors, fromComputed, combine, entityRows } from '@oimdb/exodra';
+import { bindable, derive } from '@exodra/reactivity';
+
+// wrap any OIMSelector
+const alice = fromSelector(kit.select.byPk('u1')); // TExoBindable<User | undefined>
+
+// mirror OIMCollectionSelectors → bindables; keys accept a bindable (reactive key re-points the sub)
+const bound = bindSelectors(kit.select);
+const selectedTeam = bindable('team-1');
+const members = bound.entitiesBySetIndexKey(usersByTeam, selectedTeam);
+// <ul bindable={{ children: entityRows(memberPks, pk => bound.byPk(pk), (u, pk) => renderRow(u)) }} />
+```
+
+| Export | Purpose |
+|---|---|
+| `fromSelector(selector, opts?)` | primary adapter: `OIMSelector<T>` → `TExoBindable<T>` |
+| `fromOimdb(read, subscribe, opts?)` | escape hatch for a raw read/subscribe pair |
+| `fromSelectorFactory(key, makeSelector, opts?)` | reactive key (`TKey \| bindable`) → rebuilds the selector on change |
+| `fromComputed(computed, opts?)` | `OIMComputed<T>` → `TExoBindable<T>` |
+| `combine(sources, fn)` | multi-source derive (Exodra's own `derive` is single-source) |
+| `bindSelectors(selectors, defaults?)` | mirror of `OIMCollectionSelectors`, each method returning a bindable |
+| `keyedChildren(source, { key, render })` / `entityRows(order, bindEntity, render)` | identity-stable list children (field edit = reconcile no-op, focus-safe) |
+| `listFromCommandStream(stream, key, render)` | O(delta) path: OIMDB ordered command stream → Exodra `bindableList` (commands map 1:1 to `TExoListOp`) |
+| `read*/subscribe*` (6 fns) | low-level pairs mirroring an inline app bridge 1:1 (find-replace migration) |
+
+Options `{ equals?, alwaysNotify? }`: `equals` defaults to `Object.is`; `alwaysNotify: true` for in-place entity updaters (stable ref, where `Object.is` would swallow the update). `bindSelectors` takes `kit.select` (not a bare collection) because the collection's queue is private and the selectors own a queue-bound compute runtime. Exodra bucket bindings subscribe at *build* (not `onExoMount`); the low-level `subscribe*` fns cover `onExoMount`-scoped needs. Write-side is intentionally omitted (apps write via orchestration, e.g. cnstra, not from views).
+
 ## Persist (`@oimdb/persist`)
 
 ```ts
@@ -462,6 +530,8 @@ unsubscribe();
 
 ### Destroy lifecycle (always call destroy in reverse order)
 
+Teardown is LIFO: dispose dependents before what they depend on — indexes / streams / selectors before the collection, the collection before the queue. By hand:
+
 ```ts
 logEffect.destroy();
 openCount.destroy();
@@ -470,6 +540,18 @@ tasks.destroy();
 queue.destroy();
 ```
 
+**`OIMDisposeScope`** does this for you — register as you build, tear everything down in one LIFO call. It accepts both `{ destroy(): void }` objects AND bare `() => void` unsubscribe functions (selectors' `watch`, per-key `subscribeOnKey`, `emitter.on`, scheduler tasks expose only the function form). `add(x)` returns `x` for inline capture; idempotent; every item is disposed even if one throws (first error rethrown after); `child()` nests a sub-scope. `createOIMDisposeScope()` factory. New exports: `OIMDisposeScope`, `createOIMDisposeScope`, `IOIMDisposable` (`{ destroy(): void }`), `TOIMDisposable` (`IOIMDisposable | (() => void)`).
+
+```ts
+const scope = new OIMDisposeScope();
+const queue = scope.add(new OIMEventQueue());
+const tasks = scope.add(new OIMReactiveCollection(queue, { selectPk: t => t.id }));
+const byStatus = scope.add(tasks.indexFactory.setBasedIndex());
+scope.add(select.entitiesBySetIndexKey(byStatus, 'open').watch(render));
+// …later — one call, correct LIFO order, no manual bookkeeping:
+scope.destroy();
+```
+
 ## DevTools UI (`@oimdb/mcp devtools`)
 
 For human developers — runs a local web UI at `http://localhost:7433`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oimdb/core",
-  "version": "3.7.0",
+  "version": "3.9.0",
   "description": "Core in-memory data library with type-safe indices, reactive subscriptions, and event processing",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -29,6 +29,7 @@
     "build": "tsup src/index.ts --dts --format esm,cjs",
     "test": "jest",
     "type-check": "tsc --noEmit",
+    "bench": "tsx scripts/run-bench.ts",
     "clean": "rimraf dist",
     "prepack": "node -e \"require('fs').copyFileSync('../../llms.txt', 'llms.txt')\"",
     "prepublishOnly": "npm run type-check && npm test && npm run build"