@oimdb/core 3.4.0 → 3.6.0

package/llms.txt

@@ -28,9 +28,13 @@ All reactive updates are batched. Mutations accumulate, then `queue.flush()` del
 import { OIMEventQueue, OIMEventQueueSchedulerImmediate } from '@oimdb/core';
 
 const queue = new OIMEventQueue({
-    scheduler: new OIMEventQueueSchedulerImmediate(), // flush on next microtask
+    scheduler: new OIMEventQueueSchedulerImmediate(), // macrotask: setImmediate (Node), fallback MessageChannel / setTimeout(0) (browser)
 });
-// or: OIMEventQueueSchedulerAnimationFrame, OIMEventQueueSchedulerTimeout, OIMEventQueueSchedulerMicrotask
+// or: OIMEventQueueSchedulerMicrotask (next microtask, before paint — lowest latency),
+//     OIMEventQueueSchedulerAnimationFrame, OIMEventQueueSchedulerTimeout
+// Async schedulers coalesce; call queue.flush() directly for sync delivery (e.g. tests).
+// OIMEventQueueSchedulerSync (createSync()) flushes synchronously per write, NO batching —
+//   debug/diagnostic only: swap in at the root to test if a bug is coalescing-related.
 ```
 
 ### Collections
@@ -84,6 +88,82 @@ Membership writes are incremental (touch only the changed pks):
 - `setPks` / `addPks` resolve each pk → slot (O(1) lookup); if you already hold slots (`collection.upsertMany` returns them) use `setSlots` / `appendSlots` to skip the lookup.
 - `getEntitiesByKey(key)` returns `(TEntity | undefined)[]` — positional holes for not-yet-loaded pks, aligned with `getPksByKey` (not dropped), so you can render a loading state.
 
+### Global (keyless / whole-collection) indexes
+
+When you need ONE index/ordered list over the **whole collection** ("all") there is no meaningful key. Use a **Global** index instead of inventing a phantom key like `'all'`. Same two shapes (array-based ordered / set-based unordered) and two modes (manual / derived), but keyless: `getPks()` / `getSlots()` / `getEntities()` take no key, and `subscribe(handler)` replaces `subscribeOnKey`. Internally a Global index holds ONE bucket with a single-carrier emitter (no key→carrier map / hashing), so it is strictly cheaper than a keyed index with one key.
+
+Classes mirror the keyed ones with `Global` inserted: `OIMGlobalIndexManual{Array,Set}Based` (raw slots), `OIMReactiveGlobalIndexManual{Array,Set}Based`, `OIMReactiveCollectionGlobalIndexManual{Array,Set}Based` (pk writes), `OIMDerivedCollectionGlobalIndex{Array,Set}Based`.
+
+```ts
+// Manual, collection-bound (pk writes) — e.g. a server-provided page order
+const list = indexFactory.arrayBasedGlobalIndex();
+list.setPks(['u2', 'u1']);          // also addPks / removePks (no key)
+list.getPks();                       // ['u2', 'u1']
+list.subscribe(() => { /* one bucket changed */ });
+queue.flush();
+
+// Derived — auto-tracks the whole collection, ordered
+const recent = indexFactory.derivedArrayGlobalIndex({ orderBy: (u) => u.createdAt });
+recent.getEntities();                // (User | undefined)[] in order, kept in sync
+
+// Derived set — whole-collection membership; `filter` narrows it
+const active = indexFactory.derivedSetGlobalIndex({ filter: (u) => !u.archived });
+```
+
+- Derived options: `orderBy` / `compareEntities` (array only) for order, `filter: (e) => boolean` to include a subset (default: entity exists), `buildInitial` (default true).
+- 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.
+
+### 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.
+
+```ts
+import { createOIMOrderedListMappedCommandStream } from '@oimdb/core';
+
+stream.push('main', 'u1');           // append by pk; also insertAt/setAt/removeAt/removeRange/moveRange/set
+stream.subscribeCommands('main', () => {
+    for (const cmd of stream.consumeCommands('main')) {
+        // { type:'insert', index, item } | { type:'remove', index, count? }
+        // | { type:'move', from, to, count? } | { type:'set', index, item }
+        // | { type:'reset', items }   — item is the entity slot; entity is item.item
+    }
+});
+stream.getEntitiesByKey('main'); // (TEntity | undefined)[] — holes preserved
+```
+
+`count` defaults to 1 (read `count ?? 1`). A whole-list change collapses to a single `reset`. Reads: `getPksByKey` / `getSlotsByKey` / `getEntitiesByKey`.
+
+**Mapping the list to your own elements** — `createOIMOrderedListMappedCommandStream(source, create)` projects element-wise: the same commands with `item` replaced by `create(slot)`'s result (a DOM node, view model, …). `create` is a plain function (no options object). Identity is positional — a `move` reuses the **same** mapped instance (never recreated); `create` runs on insert/set/reset/initial build. No teardown callback: the leaving element IS the `remove`/`set`/`reset` command the consumer applies against its own mirror, so cleanup belongs there. It needs no queue (rides the source's batching) and is itself an `IOIMOrderedListCommandSource`, so it consumes like the raw stream and chains via `.map(create)`. New exports: `IOIMOrderedListCommandSource`, `OIMOrderedListMappedCommandStream`, `createOIMOrderedListMappedCommandStream`.
+
+```ts
+const nodes = createOIMOrderedListMappedCommandStream(stream, (slot) => engine.makeNode(slot.item));
+nodes.subscribeCommands('main', () => {
+    for (const cmd of nodes.consumeCommands('main')) {
+        // cmd.item is your node; tear it down on remove/set/reset from your own mirror
+    }
+});
+nodes.getItemsByKey('main'); // current mapped elements — initial render
+```
+
+> Content updates (entity fields changed) are not list commands — they arrive via the collection's per-pk subscription. The stream carries structure only.
+
+**Deriving commands from an index** — the stream above is written imperatively. To instead get commands from an index whose order is maintained automatically (`derivedArrayIndex`, or any reactive array-based index replaced via `setPks`), use `createOIMOrderedListCommandStreamDiffDriven(queue, index, opts?)` / `OIMOrderedListCommandStreamDiffDriven`. On each per-key index change it diffs the previous order against the new one and emits the `insert`/`move`/`remove` that transforms it — identity by pk (a reorder is a `move` of the same slot, never a recreate), delivered on `AFTER_FLUSH`. An order-preserving change emits nothing. `opts.resetThreshold` (default `0` = always diff): below that fraction of shared pks it emits one `reset` instead of many edits. Output is an `IOIMOrderedListCommandSource`, so `createOIMOrderedListMappedCommandStream` composes on top to carry your own nodes. New exports: `OIMOrderedListCommandStreamDiffDriven`, `createOIMOrderedListCommandStreamDiffDriven`, `TOIMOrderedListDiffOptions`, `diffOrderedListByPk` (pure diff), `OIMOrderedListCommandBuffer` (shared abstract base of both streams).
+
+```ts
+const cardsByDeck = cards.indexFactory.derivedArrayIndex((c) => c.deckId, { orderBy: (c) => c.position });
+const stream = createOIMOrderedListCommandStreamDiffDriven(queue, cardsByDeck);
+stream.subscribeCommands('deck1', () => engine.apply(stream.consumeCommands('deck1'))); // insert/move/remove
+```
+
+**Mapping a plain index to stable objects** — for an ordinary set/array index (no commands), `createOIMIndexSlotMap(index, create)` / `OIMIndexSlotMap` memoizes `create(slot)` by slot identity (a `WeakMap`): the same slot returns the same object reference on every read, so `React.memo` / `Object.is` diffing works and view-models are reused. Same plain-function shape as the ordered mapper, no `destroy` (plain values, GC reclaims). `getByKey(key)` → mapped objects; `subscribeOnKey`/`subscribeOnKeys` passthrough to the index. New exports: `OIMIndexSlotMap`, `createOIMIndexSlotMap`, `IOIMIndexSlotSource`.
+
+```ts
+const usersByTeam = users.indexFactory.derivedSetIndex((u) => u.teamId);
+const rows = createOIMIndexSlotMap(usersByTeam, (slot) => makeRow(slot.item));
+rows.subscribeOnKey('team1', () => { for (const row of rows.getByKey('team1')) { /* stable per slot */ } });
+```
+
 ### DX Layer — Collection Model
 
 `createOIMCollectionKit` wires queue + collection + index factory + selectors together.

package/package.json

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