@oimdb/core 3.9.0 → 3.11.0

package/llms.txt

@@ -30,6 +30,7 @@ import { OIMEventQueue, OIMEventQueueSchedulerImmediate } from '@oimdb/core';
 
 const queue = new OIMEventQueue({
     scheduler: new OIMEventQueueSchedulerImmediate(), // macrotask: setImmediate (Node), fallback MessageChannel / setTimeout(0) (browser)
+    onError: (e) => reportToSentry(e),                // optional; see below
 });
 // or: OIMEventQueueSchedulerMicrotask (next microtask, before paint — lowest latency),
 //     OIMEventQueueSchedulerAnimationFrame, OIMEventQueueSchedulerTimeout
@@ -38,6 +39,8 @@ const queue = new OIMEventQueue({
 //   debug/diagnostic only: swap in at the root to test if a bug is coalescing-related.
 ```
 
+**Errors during flush.** If a task (subscriber / effect / computed) throws while the queue is flushing, the other tasks in that flush still run (each is isolated) and the queue's internal state is always restored — one bad task never wedges the queue. By default the error is then **raised, not swallowed**: it propagates out of `flush()` (thrown to the caller of a manual flush, or uncaught in async/scheduled mode). Pass `onError` to handle it instead (then it is NOT re-raised). Regardless of `onError`, a `EOIMEventQueueEventType.FLUSH_ERROR` event (payload `TOIMFlushError = { error }`) is emitted per failing task — the channel `@oimdb/devtools` `trackFlushErrors` / MCP use to surface failed flushes.
+
 ### Collections
 
 `OIMCollection` — base CRUD store. `OIMReactiveCollection` — same + emits events on flush.
@@ -83,6 +86,8 @@ byRole.subscribeOnKey('admin', () => {
 queue.flush(); // delivers subscription
 ```
 
+**`subscribeOnKeys(keys, handler)` delivery is coalesced per flush:** the handler fires at most ONCE per flush no matter how many of the subscribed keys changed in it (the callback gets no key, so per-key fan-out would be pure waste). This holds across all reactive primitives — sync (collection / index / object, via `OIMCarrierKeyedEmitter`) and the `@oimdb/async` nodes (via `OIMUpdateEventEmitterAsync`) alike. `subscribeOnKey` (single key) is unchanged. Handler identity is preserved, so `unsubscribeFromKeys(keys, handler)` still removes a `subscribeOnKeys` subscription.
+
 Membership writes are incremental (touch only the changed pks):
 - `addPks(key, pks)` / `removePks(key, pks)` — **set-based**: O(1) per pk for both. **array-based**: `addPks` O(1), `removePks` O(bucket) (ordered, must scan).
 - For frequently changing membership (e.g. a **virtual/windowed list** indexing the on-screen rows, adding/removing on scroll) prefer **set-based**.
@@ -194,6 +199,20 @@ const rows = createOIMIndexSlotMap(usersByTeam, (slot) => makeRow(slot.item));
 rows.subscribeOnKey('team1', () => { for (const row of rows.getByKey('team1')) { /* stable per slot */ } });
 ```
 
+### Derived collections
+
+`OIMDerivedCollection(queue, source, derive, opts?)` is a reactive collection whose entities are derived **one-to-one** from a source collection — `derived[pk] = derive(source[pk], pk)`, keyed by the SOURCE pk — kept in sync (add / update / remove) automatically. It is itself a first-class `OIMReactiveCollection`, so it can be indexed, selected, and derived-from again (join → join); maintenance runs on the source's **synchronous** update channel, so a chain of derivations stays consistent within a flush (delivery to keyed subscribers is batched on flush as usual). It parallels `OIMDerivedCollectionIndex*` and needs no compute runtime.
+
+```ts
+const nameView = new OIMDerivedCollection(queue, users,
+    (u) => ({ id: u.id, full: `${u.first} ${u.last}` }));
+nameView.getOneByPk('u1'); // { id, full } — stays in sync with `users`
+```
+
+- `opts.compare` (default `Object.is`) — skip a downstream update when a source change leaves the re-derived entity equal (pass a field/shallow compare to memoize finer; the default recomputes a fresh object each time, so it propagates every source change).
+- `opts.store` — pass a trie-driven store when the source PK is composite (`TOIMKeyPath`).
+- `opts.buildInitial` (default true).
+
 ### DX Layer — Collection Model
 
 `createOIMCollectionKit` wires queue + collection + index factory + selectors together.
@@ -216,6 +235,31 @@ const u1 = select.byPk('u1');
 u1.getValue(); // → User | undefined
 ```
 
+The kit also fronts the compute system, so you don't hand-write dependency wrappers or manage a runtime. `on.*` builds dependencies; `kit.computed` / `kit.effect` create nodes on the queue's **shared** runtime (all computeds/effects/selectors on one queue form ONE dependency graph — so a computed can depend on selectors and on other collections) and register them in `kit.scope` for teardown:
+
+```ts
+const { collection, computed, effect, on } =
+    createOIMCollectionKit<User, string>(queue, { selectPk: (u) => u.id });
+
+const isAdmin = computed(
+    [on.collection(collection, 'u1'), on.index(byRole, 'admin'), on.computed(orderCount)],
+    () => collection.getOneByPk('u1')?.role === 'admin',
+);
+effect([on.computed(isAdmin)], () => console.log(isAdmin.get()));
+```
+
+`on` builders: `on.collection(collection, pk)`, `on.index(index, key)`, `on.object(object, key)`, `on.computed(computed)`. Need the runtime directly (e.g. outside a kit)? `getOIMComputeRuntime(queue)` returns the one shared runtime for a queue. The low-level primitives below are what these wrap.
+
+**Runtime registry.** Every computed / effect / selector on a queue MUST share one runtime — they form one dependency graph, and topological levels only mean anything within a single runtime. Three functions manage that, all keyed by queue (there is no global instance; two queues get two runtimes, so tests need no reset):
+
+| Function | Use |
+|---|---|
+| `getOIMComputeRuntime(queue)` | The runtime for a queue, created on first use. A destroyed one is replaced, never handed back. |
+| `peekOIMComputeRuntime(queue)` | The runtime **if one exists**, else `undefined` — never creates. For devtools/teardown/assertions that must not change what they observe. A destroyed runtime reads as `undefined`. |
+| `setOIMComputeRuntime(queue, runtime)` | Install your own (instrumented subclass, test double). Throws if `runtime.queue !== queue`. Call BEFORE anything builds the graph — nodes capture their runtime at construction, so a late swap splits the graph in two. Does not destroy the previous runtime. |
+
+`runtime.destroy()` detaches it from the queue's `AFTER_FLUSH` and drops everything pending; `runtime.isDestroyed` reports it. Destroy the nodes first, then the runtime — destroying the runtime does not destroy the computeds/effects scheduled on it. Idempotent. Without it the subscription lives as long as the queue, which is harmless (the handler early-returns) but cannot be unwound.
+
 ### Computed Values
 
 Derived values that recompute lazily when dependencies change. Recomputation is scheduled on `queue.flush()`.
@@ -352,10 +396,10 @@ Trade-offs (use only when every reader is subscription-driven): NOT Concurrent-s
 ## Exodra (`@oimdb/exodra`)
 
 ```bash
-npm install @oimdb/exodra @exodra/reactivity @oimdb/core
+npm install @oimdb/exodra @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).
+Depends only on the type-only `@exodra/reactivity-types` (never the reactivity runtime); peer dep `@oimdb/core`. Your Exodra app already provides `@exodra/reactivity` for the runtime (`bindable`, `derive`, `h`). 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';
@@ -407,6 +451,42 @@ await persistor.hydrate(); // load from storage into collections
 persistor.start();          // autosave on every queue.flush()
 ```
 
+### Delta writes (persist only changed keys)
+
+Default: any change writes the WHOLE snapshot (`takeSnapshot()` reads the whole
+collection; `strategy.write` rewrites all of it) — `O(N)` per flush. A strategy can
+opt into key-granular writes by implementing the optional
+`writeDelta(persistor, delta)`. When it does AND the source is key-aware (an
+`OIMReactiveCollection`, whose `subscribeOnAnyUpdate` reports changed PKs), the
+engine sends only what changed in the flush instead of the full snapshot:
+
+```ts
+import { TOIMPersistDelta } from '@oimdb/persist';
+// delta: { upserts: Array<{ key, value }>; deletedKeys: key[] }
+async writeDelta(p, delta: TOIMPersistDelta<string, User>) {
+    for (const { key, value } of delta.upserts) p.storage.put(key, value);
+    for (const key of delta.deletedKeys) p.storage.delete(key);
+}
+```
+
+- Opt-in and optional. A whole-blob backend (one localStorage key, one KV entry) OMITS
+  `writeDelta` → engine always full-rewrites (a single-key change still rewrites the
+  whole collection — by design / unavoidable there).
+- A `writeDelta` strategy owns its per-key storage format; the resource-level
+  whole-snapshot `codec` is NOT applied on the delta path.
+- Manual `persist()` always writes full snapshots; deltas apply to the autosave path
+  (`start()` + change + `flush`), where the changed keys are known.
+- `collection.clear()` enumerates every removed key in its UPDATE / `subscribeOnAnyUpdate`
+  payload — it is NOT an empty-`pks` "reset" signal. So the delta path deletes the cleared
+  rows (they arrive as `deletedKeys`), snapshot-manager records them as deletions, and
+  keyed subscribers on any cleared key are notified. Clearing an empty collection emits
+  nothing. Same for `OIMObject.clear()` (enumerates removed keys).
+- Built-in: the `records` strategies of `-memory` and `-idb` implement `writeDelta`
+  (IndexedDB batches changed rows into the shared tx instead of clearing+rewriting the
+  table). `entry`/`path` (localStorage, async-kv) do not.
+- Exported types: `TOIMPersistDelta`, `TOIMPersistKeyedCapability` (source side),
+  `TOIMPersistBatchItem` (for backends overriding `batchPersist`).
+
 ### Error handling
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oimdb/core",
-  "version": "3.9.0",
+  "version": "3.11.0",
   "description": "Core in-memory data library with type-safe indices, reactive subscriptions, and event processing",
   "type": "module",
   "main": "./dist/index.cjs",