@oimdb/core 3.4.0 → 3.5.0

package/dist/index.cjs

@@ -83,6 +83,7 @@ __export(index_exports, {
   OIMObjectValueByKeySelector: () => OIMObjectValueByKeySelector,
   OIMObjectValuesByKeysSelector: () => OIMObjectValuesByKeysSelector,
   OIMOrderedListCommandStream: () => OIMOrderedListCommandStream,
+  OIMOrderedListMappedCommandStream: () => OIMOrderedListMappedCommandStream,
   OIMPkSelectorFactory: () => OIMPkSelectorFactory,
   OIMReactiveCollection: () => OIMReactiveCollection,
   OIMReactiveCollectionIndexManualArrayBased: () => OIMReactiveCollectionIndexManualArrayBased,
@@ -97,7 +98,8 @@ __export(index_exports, {
   createInPlaceEntityUpdater: () => createInPlaceEntityUpdater,
   createMergeEntityUpdater: () => createMergeEntityUpdater,
   createOIMCollectionIndexFactory: () => createOIMCollectionIndexFactory,
-  createOIMCollectionKit: () => createOIMCollectionKit
+  createOIMCollectionKit: () => createOIMCollectionKit,
+  createOIMOrderedListMappedCommandStream: () => createOIMOrderedListMappedCommandStream
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -1704,6 +1706,14 @@ var OIMOrderedListCommandStream = class {
       key
     );
   }
+  /** {@link IOIMOrderedListCommandSource} — alias of {@link getSlotsByKey}. */
+  getItemsByKey(key) {
+    return this.getSlotsByKey(key);
+  }
+  /** {@link IOIMOrderedListCommandSource} — per-key command subscription. */
+  subscribeCommands(key, handler) {
+    return this.commandsEventEmitter.subscribeOnKey(key, handler);
+  }
   getEntitiesByKey(key) {
     return this.index.getEntitiesByKey(key);
   }
@@ -3650,6 +3660,162 @@ var OIMCollectionChangedFields = class {
   }
 };
 
+// src/modules/wrapper/index/OIMOrderedListMappedCommandStream.ts
+var OIMOrderedListMappedCommandStream = class _OIMOrderedListMappedCommandStream {
+  constructor(source, opts) {
+    /** Per-key positional mirror of the mapped elements. */
+    this.mirror = /* @__PURE__ */ new Map();
+    /** Mapped commands produced for the current delivery, per key. */
+    this.buffer = /* @__PURE__ */ new Map();
+    this.subscribers = /* @__PURE__ */ new Map();
+    this.sourceUnsubscribers = /* @__PURE__ */ new Map();
+    this.source = source;
+    this.create = opts.create;
+    this.destroyItem = opts.destroy;
+  }
+  subscribeCommands(key, handler) {
+    this.ensureWired(key);
+    let subs = this.subscribers.get(key);
+    if (!subs) {
+      subs = /* @__PURE__ */ new Set();
+      this.subscribers.set(key, subs);
+    }
+    subs.add(handler);
+    return () => {
+      const current = this.subscribers.get(key);
+      if (!current) return;
+      current.delete(handler);
+      if (current.size === 0) this.subscribers.delete(key);
+    };
+  }
+  consumeCommands(key) {
+    const cmds = this.buffer.get(key);
+    if (!cmds || cmds.length === 0) return [];
+    return cmds.slice();
+  }
+  getItemsByKey(key) {
+    this.ensureWired(key);
+    return this.mirror.get(key) ?? [];
+  }
+  /** Map this source again, chaining the projection. */
+  map(opts) {
+    return new _OIMOrderedListMappedCommandStream(
+      this,
+      opts
+    );
+  }
+  destroy() {
+    this.sourceUnsubscribers.forEach((unsubscribe) => unsubscribe());
+    this.sourceUnsubscribers.clear();
+    if (this.destroyItem) {
+      this.mirror.forEach(
+        (items) => items.forEach((item) => this.destroyItem(item))
+      );
+    }
+    this.mirror.clear();
+    this.buffer.clear();
+    this.subscribers.clear();
+  }
+  /** Build the initial mirror and subscribe to the source once per key. */
+  ensureWired(key) {
+    if (this.mirror.has(key)) return;
+    const items = this.source.getItemsByKey(key);
+    this.mirror.set(key, items.map((item) => this.create(item)));
+    const unsubscribe = this.source.subscribeCommands(
+      key,
+      () => this.onSourceCommands(key)
+    );
+    this.sourceUnsubscribers.set(key, unsubscribe);
+  }
+  onSourceCommands(key) {
+    const cmds = this.source.consumeCommands(key);
+    if (cmds.length === 0) return;
+    let mirror = this.mirror.get(key);
+    if (!mirror) {
+      mirror = [];
+      this.mirror.set(key, mirror);
+    }
+    const out = [];
+    for (let i = 0; i < cmds.length; i++) {
+      const cmd = cmds[i];
+      switch (cmd.type) {
+        case "insert": {
+          const mapped = this.create(cmd.item);
+          mirror.splice(cmd.index, 0, mapped);
+          out.push({
+            type: "insert",
+            index: cmd.index,
+            item: mapped
+          });
+          break;
+        }
+        case "remove": {
+          const count = cmd.count ?? 1;
+          const removed = mirror.splice(cmd.index, count);
+          if (this.destroyItem) {
+            for (let r = 0; r < removed.length; r++) {
+              this.destroyItem(removed[r]);
+            }
+          }
+          out.push({ type: "remove", index: cmd.index, count });
+          break;
+        }
+        case "move": {
+          const count = cmd.count ?? 1;
+          const segment = mirror.splice(cmd.from, count);
+          mirror.splice(cmd.to, 0, ...segment);
+          out.push({
+            type: "move",
+            from: cmd.from,
+            to: cmd.to,
+            count
+          });
+          break;
+        }
+        case "set": {
+          const mapped = this.create(cmd.item);
+          const replaced = mirror.splice(cmd.index, 1, mapped);
+          if (this.destroyItem && replaced.length > 0) {
+            this.destroyItem(replaced[0]);
+          }
+          out.push({ type: "set", index: cmd.index, item: mapped });
+          break;
+        }
+        case "reset": {
+          if (this.destroyItem) {
+            for (let r = 0; r < mirror.length; r++) {
+              this.destroyItem(mirror[r]);
+            }
+          }
+          const mapped = cmd.items.map((item) => this.create(item));
+          mirror = mapped;
+          this.mirror.set(key, mapped);
+          out.push({ type: "reset", items: mapped });
+          break;
+        }
+      }
+    }
+    this.buffer.set(key, out);
+    try {
+      const subs = this.subscribers.get(key);
+      if (subs && subs.size > 0) {
+        const snapshot = Array.from(subs);
+        for (let s = 0; s < snapshot.length; s++) {
+          const handler = snapshot[s];
+          if (subs.has(handler)) handler();
+        }
+      }
+    } finally {
+      this.buffer.delete(key);
+    }
+  }
+};
+
+// src/modules/wrapper/index/createOIMOrderedListMappedCommandStream.ts
+function createOIMOrderedListMappedCommandStream(source, opts) {
+  return new OIMOrderedListMappedCommandStream(source, opts);
+}
+
 // src/core/event-queue-scheduler/OIMEventQueueSchedulerAnimationFrame.ts
 var OIMEventQueueSchedulerAnimationFrame = class extends OIMEventQueueScheduler {
   constructor() {
@@ -4283,6 +4449,7 @@ var OIMIndexPksByKeysArrayBasedSelector = class extends OIMSelector {
   OIMObjectValueByKeySelector,
   OIMObjectValuesByKeysSelector,
   OIMOrderedListCommandStream,
+  OIMOrderedListMappedCommandStream,
   OIMPkSelectorFactory,
   OIMReactiveCollection,
   OIMReactiveCollectionIndexManualArrayBased,
@@ -4297,5 +4464,6 @@ var OIMIndexPksByKeysArrayBasedSelector = class extends OIMSelector {
   createInPlaceEntityUpdater,
   createMergeEntityUpdater,
   createOIMCollectionIndexFactory,
-  createOIMCollectionKit
+  createOIMCollectionKit,
+  createOIMOrderedListMappedCommandStream
 });

package/dist/index.d.cts

@@ -759,6 +759,32 @@ type TOIMOrderedListCommand<TItem> = {
     items: readonly TItem[];
 };
 
+/**
+ * Read/consume side of an ordered-list command stream, generic over the element
+ * type it carries.
+ *
+ * The concrete stream stores entity slots (`TItem = TOIMEntitySlot<...>`); a
+ * mapped source ({@link OIMOrderedListMappedCommandStream}) carries whatever the
+ * mapping produces. A consumer that depends on this interface works unchanged
+ * against either — raw or mapped.
+ *
+ * Consumption is pull-based and synchronous: the notification carries no
+ * payload, so `consumeCommands(key)` must be called inside the `handler`, before
+ * the buffer for that key is cleared.
+ */
+interface IOIMOrderedListCommandSource<TKey extends TOIMPk, TItem> {
+    /**
+     * Subscribe to per-key command notifications. The handler receives no
+     * payload — pull the commands with {@link consumeCommands} synchronously.
+     * Returns an unsubscribe function.
+     */
+    subscribeCommands(key: TKey, handler: () => void): () => void;
+    /** Drain the commands buffered for `key` this delivery (a copy). */
+    consumeCommands(key: TKey): TOIMOrderedListCommand<TItem>[];
+    /** Current ordered items for `key` — the initial state before any command. */
+    getItemsByKey(key: TKey): readonly TItem[];
+}
+
 /**
  * Slot-first ordered-list command stream.
  *
@@ -766,8 +792,12 @@ type TOIMOrderedListCommand<TItem> = {
  * entity slot. Use this when you already have slots and want incremental
  * commands for an imperative renderer. For PK writes bound to a collection, use
  * `OIMCollectionOrderedListCommandStream`.
+ *
+ * Implements {@link IOIMOrderedListCommandSource} (with the slot as the element)
+ * so it can be projected element-wise via
+ * `createOIMOrderedListMappedCommandStream`.
  */
-declare class OIMOrderedListCommandStream<TKey extends TOIMPk, TPk extends TOIMPk, TEntity extends object = object> {
+declare class OIMOrderedListCommandStream<TKey extends TOIMPk, TPk extends TOIMPk, TEntity extends object = object> implements IOIMOrderedListCommandSource<TKey, TOIMEntitySlot<TEntity, TPk>> {
     readonly commandsEventEmitter: OIMUpdateEventEmitter<TKey>;
     private readonly unsubscribeAfterFlush;
     private readonly unsubscribeFromIndexEmitter;
@@ -778,6 +808,10 @@ declare class OIMOrderedListCommandStream<TKey extends TOIMPk, TPk extends TOIMP
     constructor(queue: OIMEventQueue, index?: OIMIndexManualOrderedArrayBased<TKey, TPk>);
     getPksByKey(key: TKey): readonly TPk[];
     getSlotsByKey(key: TKey): readonly TOIMEntitySlot<TEntity, TPk>[];
+    /** {@link IOIMOrderedListCommandSource} — alias of {@link getSlotsByKey}. */
+    getItemsByKey(key: TKey): readonly TOIMEntitySlot<TEntity, TPk>[];
+    /** {@link IOIMOrderedListCommandSource} — per-key command subscription. */
+    subscribeCommands(key: TKey, handler: () => void): () => void;
     getEntitiesByKey(key: TKey): (TEntity | undefined)[];
     hasKey(key: TKey): boolean;
     getKeys(): readonly TKey[];
@@ -1398,6 +1432,80 @@ declare class OIMCollectionChangedFields<TEntity extends object, TPk extends TOI
     private trackPatch;
 }
 
+/**
+ * Options for {@link OIMOrderedListMappedCommandStream} — how a source element
+ * (`TIn`) is projected to a downstream element (`TOut`) and torn down.
+ *
+ * `create` runs once per element when it enters the list (an `insert`, a `set`
+ * replacement, or list build / `reset`). `destroy` runs when it leaves (a
+ * `remove`, the replaced half of a `set`, every element on `reset`, and on
+ * stream `destroy()`). A `move` reuses the same `TOut` — it is never recreated.
+ */
+type TOIMOrderedListMapOptions<TIn, TOut> = {
+    create: (item: TIn) => TOut;
+    destroy?: (mapped: TOut) => void;
+};
+
+/**
+ * Projects an ordered-list command source element-wise, re-emitting the same
+ * position-addressed commands with `item` replaced by the mapped value.
+ *
+ * It rides the source's batching: there is no queue and no independent
+ * scheduling. On each source notification it pulls the source commands,
+ * translates them (running `create` / `destroy` and updating a positional
+ * mirror of the mapped elements), and notifies its own subscribers
+ * synchronously — so the source's `after_flush` semantics carry through.
+ *
+ * Identity is positional: a `move` reorders the *same* mapped references in the
+ * mirror, so the mapped element is preserved across moves and never recreated.
+ * `create` runs on `insert` / `set` / `reset` / initial build; `destroy` on
+ * `remove` / the replaced half of `set` / every element on `reset` / `destroy()`.
+ *
+ * Wiring to the source for a key is lazy (on first `subscribeCommands` or
+ * `getItemsByKey`) and lives until `destroy()`; subscriber churn does not
+ * create or tear down mapped elements.
+ *
+ * The output is itself an {@link IOIMOrderedListCommandSource}, so maps chain:
+ * `source.map(...)` → `.map(...)`.
+ */
+declare class OIMOrderedListMappedCommandStream<TKey extends TOIMPk, TOut, TIn> implements IOIMOrderedListCommandSource<TKey, TOut> {
+    private readonly source;
+    private readonly create;
+    private readonly destroyItem?;
+    /** Per-key positional mirror of the mapped elements. */
+    private readonly mirror;
+    /** Mapped commands produced for the current delivery, per key. */
+    private readonly buffer;
+    private readonly subscribers;
+    private readonly sourceUnsubscribers;
+    constructor(source: IOIMOrderedListCommandSource<TKey, TIn>, opts: TOIMOrderedListMapOptions<TIn, TOut>);
+    subscribeCommands(key: TKey, handler: () => void): () => void;
+    consumeCommands(key: TKey): TOIMOrderedListCommand<TOut>[];
+    getItemsByKey(key: TKey): readonly TOut[];
+    /** Map this source again, chaining the projection. */
+    map<TNext>(opts: TOIMOrderedListMapOptions<TOut, TNext>): OIMOrderedListMappedCommandStream<TKey, TNext, TOut>;
+    destroy(): void;
+    /** Build the initial mirror and subscribe to the source once per key. */
+    private ensureWired;
+    private onSourceCommands;
+}
+
+/**
+ * Map an ordered-list command source element-wise. The result is itself a
+ * source, so it can be mapped again (or via its `.map()` method).
+ *
+ * ```ts
+ * const nodes = createOIMOrderedListMappedCommandStream(stream, {
+ *     create: (slot) => engine.makeNode(slot.item),
+ *     destroy: (node) => engine.dropNode(node),
+ * });
+ * nodes.subscribeCommands(key, () =>
+ *     engine.apply(nodes.consumeCommands(key))
+ * );
+ * ```
+ */
+declare function createOIMOrderedListMappedCommandStream<TKey extends TOIMPk, TIn, TOut>(source: IOIMOrderedListCommandSource<TKey, TIn>, opts: TOIMOrderedListMapOptions<TIn, TOut>): OIMOrderedListMappedCommandStream<TKey, TOut, TIn>;
+
 /**
  * Animation frame-based scheduler that executes flushes synchronized with the browser's repaint cycle.
  * Ideal for UI-related updates that need to be synchronized with rendering.
@@ -1750,4 +1858,4 @@ declare class OIMEntitiesByIndexKeyArrayBasedSelector<TEntity extends object, TP
     protected areEqual(prev: readonly (TEntity | undefined)[], next: readonly (TEntity | undefined)[]): boolean;
 }
 
-export { EOIMCollectionEventType, EOIMComputedEventType, EOIMEventQueueEventType, EOIMEventQueueSchedulerEventType, EOIMIndexEventType, EOIMObjectEventType, type IOIMCarrierResolver, type IOIMComputedEventSource, type IOIMEffectDependency, type IOIMEventQueueSchedulerEvents, type IOIMIndexStore, type IOIMKeyedUpdateEmitter, type IOIMSubscribable, OIMCarrierKeyedEmitter, OIMCollection, OIMCollectionByPkSelector, OIMCollectionByPksSelector, OIMCollectionChangedFields, OIMCollectionIndexFactory, OIMCollectionIndexManualOrderedArrayBased, OIMCollectionOrderedListCommandStream, OIMCollectionSelectors, OIMCollectionStore, OIMCollectionStoreMapDriven, OIMComparatorFactory, OIMComputeRuntime, OIMComputed, OIMDBSettings, OIMDerivedCollectionIndexArrayBased, OIMDerivedCollectionIndexSetBased, OIMEffect, OIMEffectDependencyComputed, OIMEffectDependencyKeyed, OIMEffectDependencyKeyedCollection, OIMEffectDependencyKeyedIndex, OIMEffectDependencyKeyedObject, OIMEntitiesByIndexKeyArrayBasedSelector, OIMEntitiesByIndexKeySetBasedSelector, OIMEntityUpdaterFactory, OIMEventEmitter, OIMEventQueue, OIMEventQueueScheduler, OIMEventQueueSchedulerAnimationFrame, OIMEventQueueSchedulerFactory, OIMEventQueueSchedulerImmediate, OIMEventQueueSchedulerMicrotask, OIMEventQueueSchedulerTimeout, OIMIndex, OIMIndexArrayBased, OIMIndexComparatorFactory, OIMIndexManualArrayBased, OIMIndexManualOrderedArrayBased, OIMIndexManualSetBased, OIMIndexPksByKeyArrayBasedSelector, OIMIndexPksByKeySetBasedSelector, OIMIndexPksByKeysArrayBasedSelector, OIMIndexPksByKeysSetBasedSelector, OIMIndexSetBased, OIMIndexStoreArrayBased, OIMIndexStoreMapDrivenArrayBased, OIMIndexStoreMapDrivenSetBased, OIMIndexStoreSetBased, OIMMap2Keys, OIMObject, OIMObjectStore, OIMObjectStoreMapDriven, OIMObjectStoreRecordDriven, OIMObjectValueByKeySelector, OIMObjectValuesByKeysSelector, OIMOrderedListCommandStream, OIMPkSelectorFactory, OIMReactiveCollection, OIMReactiveCollectionIndexManualArrayBased, OIMReactiveCollectionIndexManualSetBased, OIMReactiveIndex, OIMReactiveIndexArrayBased, OIMReactiveIndexManualArrayBased, OIMReactiveIndexManualSetBased, OIMReactiveIndexSetBased, OIMReactiveObject, OIMSelector, type TOIMAnyEntitySlot, type TOIMCollectionEntitiesSelector, type TOIMCollectionEntitySelector, type TOIMCollectionIndexArrayBasedOptions, type TOIMCollectionIndexSetBasedOptions, type TOIMCollectionKit, type TOIMCollectionOptions, type TOIMCollectionOrderedIndexOptions, type TOIMCollectionOrderedListCommandStreamOptions, type TOIMCollectionUpdatePayload, type TOIMComparator, type TOIMComputedOptions, type TOIMComputedUpdatePayload, type TOIMDerivedCollectionIndexArrayBasedOptions, type TOIMDerivedCollectionIndexSetBasedOptions, type TOIMDerivedEntityComparator, type TOIMDerivedEntityOrderSelector, type TOIMDerivedEntityOrderValue, type TOIMDerivedIndexKeySelector, type TOIMEffectOptions, type TOIMEntitySlot, type TOIMEntitySlotResolver, type TOIMEntityUpdater, type TOIMEventHandler, type TOIMEventQueueOptions, type TOIMIndexComparator, type TOIMIndexKey, type TOIMIndexOptionsArrayBased, type TOIMIndexOptionsSetBased, type TOIMIndexPksUpdatePayload, type TOIMIndexUpdatePayload, type TOIMObjectOptions, type TOIMOrderedListCommand, type TOIMPk, type TOIMPkSelector, type TOIMReactiveCollectionFactoryOptions, type TOIMRelationsArrayIndexOptions, type TOIMRelationsDerivedArrayIndexOptions, type TOIMRelationsDerivedSetIndexOptions, type TOIMRelationsOrderedListOptions, type TOIMRelationsSetIndexOptions, type TOIMSchedulerOptions, type TOIMSchedulerType, type TOIMUpdatePayload, createInPlaceEntityUpdater, createMergeEntityUpdater, createOIMCollectionIndexFactory, createOIMCollectionKit };
+export { EOIMCollectionEventType, EOIMComputedEventType, EOIMEventQueueEventType, EOIMEventQueueSchedulerEventType, EOIMIndexEventType, EOIMObjectEventType, type IOIMCarrierResolver, type IOIMComputedEventSource, type IOIMEffectDependency, type IOIMEventQueueSchedulerEvents, type IOIMIndexStore, type IOIMKeyedUpdateEmitter, type IOIMOrderedListCommandSource, type IOIMSubscribable, OIMCarrierKeyedEmitter, OIMCollection, OIMCollectionByPkSelector, OIMCollectionByPksSelector, OIMCollectionChangedFields, OIMCollectionIndexFactory, OIMCollectionIndexManualOrderedArrayBased, OIMCollectionOrderedListCommandStream, OIMCollectionSelectors, OIMCollectionStore, OIMCollectionStoreMapDriven, OIMComparatorFactory, OIMComputeRuntime, OIMComputed, OIMDBSettings, OIMDerivedCollectionIndexArrayBased, OIMDerivedCollectionIndexSetBased, OIMEffect, OIMEffectDependencyComputed, OIMEffectDependencyKeyed, OIMEffectDependencyKeyedCollection, OIMEffectDependencyKeyedIndex, OIMEffectDependencyKeyedObject, OIMEntitiesByIndexKeyArrayBasedSelector, OIMEntitiesByIndexKeySetBasedSelector, OIMEntityUpdaterFactory, OIMEventEmitter, OIMEventQueue, OIMEventQueueScheduler, OIMEventQueueSchedulerAnimationFrame, OIMEventQueueSchedulerFactory, OIMEventQueueSchedulerImmediate, OIMEventQueueSchedulerMicrotask, OIMEventQueueSchedulerTimeout, OIMIndex, OIMIndexArrayBased, OIMIndexComparatorFactory, OIMIndexManualArrayBased, OIMIndexManualOrderedArrayBased, OIMIndexManualSetBased, OIMIndexPksByKeyArrayBasedSelector, OIMIndexPksByKeySetBasedSelector, OIMIndexPksByKeysArrayBasedSelector, OIMIndexPksByKeysSetBasedSelector, OIMIndexSetBased, OIMIndexStoreArrayBased, OIMIndexStoreMapDrivenArrayBased, OIMIndexStoreMapDrivenSetBased, OIMIndexStoreSetBased, OIMMap2Keys, OIMObject, OIMObjectStore, OIMObjectStoreMapDriven, OIMObjectStoreRecordDriven, OIMObjectValueByKeySelector, OIMObjectValuesByKeysSelector, OIMOrderedListCommandStream, OIMOrderedListMappedCommandStream, OIMPkSelectorFactory, OIMReactiveCollection, OIMReactiveCollectionIndexManualArrayBased, OIMReactiveCollectionIndexManualSetBased, OIMReactiveIndex, OIMReactiveIndexArrayBased, OIMReactiveIndexManualArrayBased, OIMReactiveIndexManualSetBased, OIMReactiveIndexSetBased, OIMReactiveObject, OIMSelector, type TOIMAnyEntitySlot, type TOIMCollectionEntitiesSelector, type TOIMCollectionEntitySelector, type TOIMCollectionIndexArrayBasedOptions, type TOIMCollectionIndexSetBasedOptions, type TOIMCollectionKit, type TOIMCollectionOptions, type TOIMCollectionOrderedIndexOptions, type TOIMCollectionOrderedListCommandStreamOptions, type TOIMCollectionUpdatePayload, type TOIMComparator, type TOIMComputedOptions, type TOIMComputedUpdatePayload, type TOIMDerivedCollectionIndexArrayBasedOptions, type TOIMDerivedCollectionIndexSetBasedOptions, type TOIMDerivedEntityComparator, type TOIMDerivedEntityOrderSelector, type TOIMDerivedEntityOrderValue, type TOIMDerivedIndexKeySelector, type TOIMEffectOptions, type TOIMEntitySlot, type TOIMEntitySlotResolver, type TOIMEntityUpdater, type TOIMEventHandler, type TOIMEventQueueOptions, type TOIMIndexComparator, type TOIMIndexKey, type TOIMIndexOptionsArrayBased, type TOIMIndexOptionsSetBased, type TOIMIndexPksUpdatePayload, type TOIMIndexUpdatePayload, type TOIMObjectOptions, type TOIMOrderedListCommand, type TOIMOrderedListMapOptions, type TOIMPk, type TOIMPkSelector, type TOIMReactiveCollectionFactoryOptions, type TOIMRelationsArrayIndexOptions, type TOIMRelationsDerivedArrayIndexOptions, type TOIMRelationsDerivedSetIndexOptions, type TOIMRelationsOrderedListOptions, type TOIMRelationsSetIndexOptions, type TOIMSchedulerOptions, type TOIMSchedulerType, type TOIMUpdatePayload, createInPlaceEntityUpdater, createMergeEntityUpdater, createOIMCollectionIndexFactory, createOIMCollectionKit, createOIMOrderedListMappedCommandStream };

package/dist/index.d.ts

@@ -759,6 +759,32 @@ type TOIMOrderedListCommand<TItem> = {
     items: readonly TItem[];
 };
 
+/**
+ * Read/consume side of an ordered-list command stream, generic over the element
+ * type it carries.
+ *
+ * The concrete stream stores entity slots (`TItem = TOIMEntitySlot<...>`); a
+ * mapped source ({@link OIMOrderedListMappedCommandStream}) carries whatever the
+ * mapping produces. A consumer that depends on this interface works unchanged
+ * against either — raw or mapped.
+ *
+ * Consumption is pull-based and synchronous: the notification carries no
+ * payload, so `consumeCommands(key)` must be called inside the `handler`, before
+ * the buffer for that key is cleared.
+ */
+interface IOIMOrderedListCommandSource<TKey extends TOIMPk, TItem> {
+    /**
+     * Subscribe to per-key command notifications. The handler receives no
+     * payload — pull the commands with {@link consumeCommands} synchronously.
+     * Returns an unsubscribe function.
+     */
+    subscribeCommands(key: TKey, handler: () => void): () => void;
+    /** Drain the commands buffered for `key` this delivery (a copy). */
+    consumeCommands(key: TKey): TOIMOrderedListCommand<TItem>[];
+    /** Current ordered items for `key` — the initial state before any command. */
+    getItemsByKey(key: TKey): readonly TItem[];
+}
+
 /**
  * Slot-first ordered-list command stream.
  *
@@ -766,8 +792,12 @@ type TOIMOrderedListCommand<TItem> = {
  * entity slot. Use this when you already have slots and want incremental
  * commands for an imperative renderer. For PK writes bound to a collection, use
  * `OIMCollectionOrderedListCommandStream`.
+ *
+ * Implements {@link IOIMOrderedListCommandSource} (with the slot as the element)
+ * so it can be projected element-wise via
+ * `createOIMOrderedListMappedCommandStream`.
  */
-declare class OIMOrderedListCommandStream<TKey extends TOIMPk, TPk extends TOIMPk, TEntity extends object = object> {
+declare class OIMOrderedListCommandStream<TKey extends TOIMPk, TPk extends TOIMPk, TEntity extends object = object> implements IOIMOrderedListCommandSource<TKey, TOIMEntitySlot<TEntity, TPk>> {
     readonly commandsEventEmitter: OIMUpdateEventEmitter<TKey>;
     private readonly unsubscribeAfterFlush;
     private readonly unsubscribeFromIndexEmitter;
@@ -778,6 +808,10 @@ declare class OIMOrderedListCommandStream<TKey extends TOIMPk, TPk extends TOIMP
     constructor(queue: OIMEventQueue, index?: OIMIndexManualOrderedArrayBased<TKey, TPk>);
     getPksByKey(key: TKey): readonly TPk[];
     getSlotsByKey(key: TKey): readonly TOIMEntitySlot<TEntity, TPk>[];
+    /** {@link IOIMOrderedListCommandSource} — alias of {@link getSlotsByKey}. */
+    getItemsByKey(key: TKey): readonly TOIMEntitySlot<TEntity, TPk>[];
+    /** {@link IOIMOrderedListCommandSource} — per-key command subscription. */
+    subscribeCommands(key: TKey, handler: () => void): () => void;
     getEntitiesByKey(key: TKey): (TEntity | undefined)[];
     hasKey(key: TKey): boolean;
     getKeys(): readonly TKey[];
@@ -1398,6 +1432,80 @@ declare class OIMCollectionChangedFields<TEntity extends object, TPk extends TOI
     private trackPatch;
 }
 
+/**
+ * Options for {@link OIMOrderedListMappedCommandStream} — how a source element
+ * (`TIn`) is projected to a downstream element (`TOut`) and torn down.
+ *
+ * `create` runs once per element when it enters the list (an `insert`, a `set`
+ * replacement, or list build / `reset`). `destroy` runs when it leaves (a
+ * `remove`, the replaced half of a `set`, every element on `reset`, and on
+ * stream `destroy()`). A `move` reuses the same `TOut` — it is never recreated.
+ */
+type TOIMOrderedListMapOptions<TIn, TOut> = {
+    create: (item: TIn) => TOut;
+    destroy?: (mapped: TOut) => void;
+};
+
+/**
+ * Projects an ordered-list command source element-wise, re-emitting the same
+ * position-addressed commands with `item` replaced by the mapped value.
+ *
+ * It rides the source's batching: there is no queue and no independent
+ * scheduling. On each source notification it pulls the source commands,
+ * translates them (running `create` / `destroy` and updating a positional
+ * mirror of the mapped elements), and notifies its own subscribers
+ * synchronously — so the source's `after_flush` semantics carry through.
+ *
+ * Identity is positional: a `move` reorders the *same* mapped references in the
+ * mirror, so the mapped element is preserved across moves and never recreated.
+ * `create` runs on `insert` / `set` / `reset` / initial build; `destroy` on
+ * `remove` / the replaced half of `set` / every element on `reset` / `destroy()`.
+ *
+ * Wiring to the source for a key is lazy (on first `subscribeCommands` or
+ * `getItemsByKey`) and lives until `destroy()`; subscriber churn does not
+ * create or tear down mapped elements.
+ *
+ * The output is itself an {@link IOIMOrderedListCommandSource}, so maps chain:
+ * `source.map(...)` → `.map(...)`.
+ */
+declare class OIMOrderedListMappedCommandStream<TKey extends TOIMPk, TOut, TIn> implements IOIMOrderedListCommandSource<TKey, TOut> {
+    private readonly source;
+    private readonly create;
+    private readonly destroyItem?;
+    /** Per-key positional mirror of the mapped elements. */
+    private readonly mirror;
+    /** Mapped commands produced for the current delivery, per key. */
+    private readonly buffer;
+    private readonly subscribers;
+    private readonly sourceUnsubscribers;
+    constructor(source: IOIMOrderedListCommandSource<TKey, TIn>, opts: TOIMOrderedListMapOptions<TIn, TOut>);
+    subscribeCommands(key: TKey, handler: () => void): () => void;
+    consumeCommands(key: TKey): TOIMOrderedListCommand<TOut>[];
+    getItemsByKey(key: TKey): readonly TOut[];
+    /** Map this source again, chaining the projection. */
+    map<TNext>(opts: TOIMOrderedListMapOptions<TOut, TNext>): OIMOrderedListMappedCommandStream<TKey, TNext, TOut>;
+    destroy(): void;
+    /** Build the initial mirror and subscribe to the source once per key. */
+    private ensureWired;
+    private onSourceCommands;
+}
+
+/**
+ * Map an ordered-list command source element-wise. The result is itself a
+ * source, so it can be mapped again (or via its `.map()` method).
+ *
+ * ```ts
+ * const nodes = createOIMOrderedListMappedCommandStream(stream, {
+ *     create: (slot) => engine.makeNode(slot.item),
+ *     destroy: (node) => engine.dropNode(node),
+ * });
+ * nodes.subscribeCommands(key, () =>
+ *     engine.apply(nodes.consumeCommands(key))
+ * );
+ * ```
+ */
+declare function createOIMOrderedListMappedCommandStream<TKey extends TOIMPk, TIn, TOut>(source: IOIMOrderedListCommandSource<TKey, TIn>, opts: TOIMOrderedListMapOptions<TIn, TOut>): OIMOrderedListMappedCommandStream<TKey, TOut, TIn>;
+
 /**
  * Animation frame-based scheduler that executes flushes synchronized with the browser's repaint cycle.
  * Ideal for UI-related updates that need to be synchronized with rendering.
@@ -1750,4 +1858,4 @@ declare class OIMEntitiesByIndexKeyArrayBasedSelector<TEntity extends object, TP
     protected areEqual(prev: readonly (TEntity | undefined)[], next: readonly (TEntity | undefined)[]): boolean;
 }
 
-export { EOIMCollectionEventType, EOIMComputedEventType, EOIMEventQueueEventType, EOIMEventQueueSchedulerEventType, EOIMIndexEventType, EOIMObjectEventType, type IOIMCarrierResolver, type IOIMComputedEventSource, type IOIMEffectDependency, type IOIMEventQueueSchedulerEvents, type IOIMIndexStore, type IOIMKeyedUpdateEmitter, type IOIMSubscribable, OIMCarrierKeyedEmitter, OIMCollection, OIMCollectionByPkSelector, OIMCollectionByPksSelector, OIMCollectionChangedFields, OIMCollectionIndexFactory, OIMCollectionIndexManualOrderedArrayBased, OIMCollectionOrderedListCommandStream, OIMCollectionSelectors, OIMCollectionStore, OIMCollectionStoreMapDriven, OIMComparatorFactory, OIMComputeRuntime, OIMComputed, OIMDBSettings, OIMDerivedCollectionIndexArrayBased, OIMDerivedCollectionIndexSetBased, OIMEffect, OIMEffectDependencyComputed, OIMEffectDependencyKeyed, OIMEffectDependencyKeyedCollection, OIMEffectDependencyKeyedIndex, OIMEffectDependencyKeyedObject, OIMEntitiesByIndexKeyArrayBasedSelector, OIMEntitiesByIndexKeySetBasedSelector, OIMEntityUpdaterFactory, OIMEventEmitter, OIMEventQueue, OIMEventQueueScheduler, OIMEventQueueSchedulerAnimationFrame, OIMEventQueueSchedulerFactory, OIMEventQueueSchedulerImmediate, OIMEventQueueSchedulerMicrotask, OIMEventQueueSchedulerTimeout, OIMIndex, OIMIndexArrayBased, OIMIndexComparatorFactory, OIMIndexManualArrayBased, OIMIndexManualOrderedArrayBased, OIMIndexManualSetBased, OIMIndexPksByKeyArrayBasedSelector, OIMIndexPksByKeySetBasedSelector, OIMIndexPksByKeysArrayBasedSelector, OIMIndexPksByKeysSetBasedSelector, OIMIndexSetBased, OIMIndexStoreArrayBased, OIMIndexStoreMapDrivenArrayBased, OIMIndexStoreMapDrivenSetBased, OIMIndexStoreSetBased, OIMMap2Keys, OIMObject, OIMObjectStore, OIMObjectStoreMapDriven, OIMObjectStoreRecordDriven, OIMObjectValueByKeySelector, OIMObjectValuesByKeysSelector, OIMOrderedListCommandStream, OIMPkSelectorFactory, OIMReactiveCollection, OIMReactiveCollectionIndexManualArrayBased, OIMReactiveCollectionIndexManualSetBased, OIMReactiveIndex, OIMReactiveIndexArrayBased, OIMReactiveIndexManualArrayBased, OIMReactiveIndexManualSetBased, OIMReactiveIndexSetBased, OIMReactiveObject, OIMSelector, type TOIMAnyEntitySlot, type TOIMCollectionEntitiesSelector, type TOIMCollectionEntitySelector, type TOIMCollectionIndexArrayBasedOptions, type TOIMCollectionIndexSetBasedOptions, type TOIMCollectionKit, type TOIMCollectionOptions, type TOIMCollectionOrderedIndexOptions, type TOIMCollectionOrderedListCommandStreamOptions, type TOIMCollectionUpdatePayload, type TOIMComparator, type TOIMComputedOptions, type TOIMComputedUpdatePayload, type TOIMDerivedCollectionIndexArrayBasedOptions, type TOIMDerivedCollectionIndexSetBasedOptions, type TOIMDerivedEntityComparator, type TOIMDerivedEntityOrderSelector, type TOIMDerivedEntityOrderValue, type TOIMDerivedIndexKeySelector, type TOIMEffectOptions, type TOIMEntitySlot, type TOIMEntitySlotResolver, type TOIMEntityUpdater, type TOIMEventHandler, type TOIMEventQueueOptions, type TOIMIndexComparator, type TOIMIndexKey, type TOIMIndexOptionsArrayBased, type TOIMIndexOptionsSetBased, type TOIMIndexPksUpdatePayload, type TOIMIndexUpdatePayload, type TOIMObjectOptions, type TOIMOrderedListCommand, type TOIMPk, type TOIMPkSelector, type TOIMReactiveCollectionFactoryOptions, type TOIMRelationsArrayIndexOptions, type TOIMRelationsDerivedArrayIndexOptions, type TOIMRelationsDerivedSetIndexOptions, type TOIMRelationsOrderedListOptions, type TOIMRelationsSetIndexOptions, type TOIMSchedulerOptions, type TOIMSchedulerType, type TOIMUpdatePayload, createInPlaceEntityUpdater, createMergeEntityUpdater, createOIMCollectionIndexFactory, createOIMCollectionKit };
+export { EOIMCollectionEventType, EOIMComputedEventType, EOIMEventQueueEventType, EOIMEventQueueSchedulerEventType, EOIMIndexEventType, EOIMObjectEventType, type IOIMCarrierResolver, type IOIMComputedEventSource, type IOIMEffectDependency, type IOIMEventQueueSchedulerEvents, type IOIMIndexStore, type IOIMKeyedUpdateEmitter, type IOIMOrderedListCommandSource, type IOIMSubscribable, OIMCarrierKeyedEmitter, OIMCollection, OIMCollectionByPkSelector, OIMCollectionByPksSelector, OIMCollectionChangedFields, OIMCollectionIndexFactory, OIMCollectionIndexManualOrderedArrayBased, OIMCollectionOrderedListCommandStream, OIMCollectionSelectors, OIMCollectionStore, OIMCollectionStoreMapDriven, OIMComparatorFactory, OIMComputeRuntime, OIMComputed, OIMDBSettings, OIMDerivedCollectionIndexArrayBased, OIMDerivedCollectionIndexSetBased, OIMEffect, OIMEffectDependencyComputed, OIMEffectDependencyKeyed, OIMEffectDependencyKeyedCollection, OIMEffectDependencyKeyedIndex, OIMEffectDependencyKeyedObject, OIMEntitiesByIndexKeyArrayBasedSelector, OIMEntitiesByIndexKeySetBasedSelector, OIMEntityUpdaterFactory, OIMEventEmitter, OIMEventQueue, OIMEventQueueScheduler, OIMEventQueueSchedulerAnimationFrame, OIMEventQueueSchedulerFactory, OIMEventQueueSchedulerImmediate, OIMEventQueueSchedulerMicrotask, OIMEventQueueSchedulerTimeout, OIMIndex, OIMIndexArrayBased, OIMIndexComparatorFactory, OIMIndexManualArrayBased, OIMIndexManualOrderedArrayBased, OIMIndexManualSetBased, OIMIndexPksByKeyArrayBasedSelector, OIMIndexPksByKeySetBasedSelector, OIMIndexPksByKeysArrayBasedSelector, OIMIndexPksByKeysSetBasedSelector, OIMIndexSetBased, OIMIndexStoreArrayBased, OIMIndexStoreMapDrivenArrayBased, OIMIndexStoreMapDrivenSetBased, OIMIndexStoreSetBased, OIMMap2Keys, OIMObject, OIMObjectStore, OIMObjectStoreMapDriven, OIMObjectStoreRecordDriven, OIMObjectValueByKeySelector, OIMObjectValuesByKeysSelector, OIMOrderedListCommandStream, OIMOrderedListMappedCommandStream, OIMPkSelectorFactory, OIMReactiveCollection, OIMReactiveCollectionIndexManualArrayBased, OIMReactiveCollectionIndexManualSetBased, OIMReactiveIndex, OIMReactiveIndexArrayBased, OIMReactiveIndexManualArrayBased, OIMReactiveIndexManualSetBased, OIMReactiveIndexSetBased, OIMReactiveObject, OIMSelector, type TOIMAnyEntitySlot, type TOIMCollectionEntitiesSelector, type TOIMCollectionEntitySelector, type TOIMCollectionIndexArrayBasedOptions, type TOIMCollectionIndexSetBasedOptions, type TOIMCollectionKit, type TOIMCollectionOptions, type TOIMCollectionOrderedIndexOptions, type TOIMCollectionOrderedListCommandStreamOptions, type TOIMCollectionUpdatePayload, type TOIMComparator, type TOIMComputedOptions, type TOIMComputedUpdatePayload, type TOIMDerivedCollectionIndexArrayBasedOptions, type TOIMDerivedCollectionIndexSetBasedOptions, type TOIMDerivedEntityComparator, type TOIMDerivedEntityOrderSelector, type TOIMDerivedEntityOrderValue, type TOIMDerivedIndexKeySelector, type TOIMEffectOptions, type TOIMEntitySlot, type TOIMEntitySlotResolver, type TOIMEntityUpdater, type TOIMEventHandler, type TOIMEventQueueOptions, type TOIMIndexComparator, type TOIMIndexKey, type TOIMIndexOptionsArrayBased, type TOIMIndexOptionsSetBased, type TOIMIndexPksUpdatePayload, type TOIMIndexUpdatePayload, type TOIMObjectOptions, type TOIMOrderedListCommand, type TOIMOrderedListMapOptions, type TOIMPk, type TOIMPkSelector, type TOIMReactiveCollectionFactoryOptions, type TOIMRelationsArrayIndexOptions, type TOIMRelationsDerivedArrayIndexOptions, type TOIMRelationsDerivedSetIndexOptions, type TOIMRelationsOrderedListOptions, type TOIMRelationsSetIndexOptions, type TOIMSchedulerOptions, type TOIMSchedulerType, type TOIMUpdatePayload, createInPlaceEntityUpdater, createMergeEntityUpdater, createOIMCollectionIndexFactory, createOIMCollectionKit, createOIMOrderedListMappedCommandStream };

package/dist/index.js

@@ -1601,6 +1601,14 @@ var OIMOrderedListCommandStream = class {
       key
     );
   }
+  /** {@link IOIMOrderedListCommandSource} — alias of {@link getSlotsByKey}. */
+  getItemsByKey(key) {
+    return this.getSlotsByKey(key);
+  }
+  /** {@link IOIMOrderedListCommandSource} — per-key command subscription. */
+  subscribeCommands(key, handler) {
+    return this.commandsEventEmitter.subscribeOnKey(key, handler);
+  }
   getEntitiesByKey(key) {
     return this.index.getEntitiesByKey(key);
   }
@@ -3547,6 +3555,162 @@ var OIMCollectionChangedFields = class {
   }
 };
 
+// src/modules/wrapper/index/OIMOrderedListMappedCommandStream.ts
+var OIMOrderedListMappedCommandStream = class _OIMOrderedListMappedCommandStream {
+  constructor(source, opts) {
+    /** Per-key positional mirror of the mapped elements. */
+    this.mirror = /* @__PURE__ */ new Map();
+    /** Mapped commands produced for the current delivery, per key. */
+    this.buffer = /* @__PURE__ */ new Map();
+    this.subscribers = /* @__PURE__ */ new Map();
+    this.sourceUnsubscribers = /* @__PURE__ */ new Map();
+    this.source = source;
+    this.create = opts.create;
+    this.destroyItem = opts.destroy;
+  }
+  subscribeCommands(key, handler) {
+    this.ensureWired(key);
+    let subs = this.subscribers.get(key);
+    if (!subs) {
+      subs = /* @__PURE__ */ new Set();
+      this.subscribers.set(key, subs);
+    }
+    subs.add(handler);
+    return () => {
+      const current = this.subscribers.get(key);
+      if (!current) return;
+      current.delete(handler);
+      if (current.size === 0) this.subscribers.delete(key);
+    };
+  }
+  consumeCommands(key) {
+    const cmds = this.buffer.get(key);
+    if (!cmds || cmds.length === 0) return [];
+    return cmds.slice();
+  }
+  getItemsByKey(key) {
+    this.ensureWired(key);
+    return this.mirror.get(key) ?? [];
+  }
+  /** Map this source again, chaining the projection. */
+  map(opts) {
+    return new _OIMOrderedListMappedCommandStream(
+      this,
+      opts
+    );
+  }
+  destroy() {
+    this.sourceUnsubscribers.forEach((unsubscribe) => unsubscribe());
+    this.sourceUnsubscribers.clear();
+    if (this.destroyItem) {
+      this.mirror.forEach(
+        (items) => items.forEach((item) => this.destroyItem(item))
+      );
+    }
+    this.mirror.clear();
+    this.buffer.clear();
+    this.subscribers.clear();
+  }
+  /** Build the initial mirror and subscribe to the source once per key. */
+  ensureWired(key) {
+    if (this.mirror.has(key)) return;
+    const items = this.source.getItemsByKey(key);
+    this.mirror.set(key, items.map((item) => this.create(item)));
+    const unsubscribe = this.source.subscribeCommands(
+      key,
+      () => this.onSourceCommands(key)
+    );
+    this.sourceUnsubscribers.set(key, unsubscribe);
+  }
+  onSourceCommands(key) {
+    const cmds = this.source.consumeCommands(key);
+    if (cmds.length === 0) return;
+    let mirror = this.mirror.get(key);
+    if (!mirror) {
+      mirror = [];
+      this.mirror.set(key, mirror);
+    }
+    const out = [];
+    for (let i = 0; i < cmds.length; i++) {
+      const cmd = cmds[i];
+      switch (cmd.type) {
+        case "insert": {
+          const mapped = this.create(cmd.item);
+          mirror.splice(cmd.index, 0, mapped);
+          out.push({
+            type: "insert",
+            index: cmd.index,
+            item: mapped
+          });
+          break;
+        }
+        case "remove": {
+          const count = cmd.count ?? 1;
+          const removed = mirror.splice(cmd.index, count);
+          if (this.destroyItem) {
+            for (let r = 0; r < removed.length; r++) {
+              this.destroyItem(removed[r]);
+            }
+          }
+          out.push({ type: "remove", index: cmd.index, count });
+          break;
+        }
+        case "move": {
+          const count = cmd.count ?? 1;
+          const segment = mirror.splice(cmd.from, count);
+          mirror.splice(cmd.to, 0, ...segment);
+          out.push({
+            type: "move",
+            from: cmd.from,
+            to: cmd.to,
+            count
+          });
+          break;
+        }
+        case "set": {
+          const mapped = this.create(cmd.item);
+          const replaced = mirror.splice(cmd.index, 1, mapped);
+          if (this.destroyItem && replaced.length > 0) {
+            this.destroyItem(replaced[0]);
+          }
+          out.push({ type: "set", index: cmd.index, item: mapped });
+          break;
+        }
+        case "reset": {
+          if (this.destroyItem) {
+            for (let r = 0; r < mirror.length; r++) {
+              this.destroyItem(mirror[r]);
+            }
+          }
+          const mapped = cmd.items.map((item) => this.create(item));
+          mirror = mapped;
+          this.mirror.set(key, mapped);
+          out.push({ type: "reset", items: mapped });
+          break;
+        }
+      }
+    }
+    this.buffer.set(key, out);
+    try {
+      const subs = this.subscribers.get(key);
+      if (subs && subs.size > 0) {
+        const snapshot = Array.from(subs);
+        for (let s = 0; s < snapshot.length; s++) {
+          const handler = snapshot[s];
+          if (subs.has(handler)) handler();
+        }
+      }
+    } finally {
+      this.buffer.delete(key);
+    }
+  }
+};
+
+// src/modules/wrapper/index/createOIMOrderedListMappedCommandStream.ts
+function createOIMOrderedListMappedCommandStream(source, opts) {
+  return new OIMOrderedListMappedCommandStream(source, opts);
+}
+
 // src/core/event-queue-scheduler/OIMEventQueueSchedulerAnimationFrame.ts
 var OIMEventQueueSchedulerAnimationFrame = class extends OIMEventQueueScheduler {
   constructor() {
@@ -4179,6 +4343,7 @@ export {
   OIMObjectValueByKeySelector,
   OIMObjectValuesByKeysSelector,
   OIMOrderedListCommandStream,
+  OIMOrderedListMappedCommandStream,
   OIMPkSelectorFactory,
   OIMReactiveCollection,
   OIMReactiveCollectionIndexManualArrayBased,
@@ -4193,5 +4358,6 @@ export {
   createInPlaceEntityUpdater,
   createMergeEntityUpdater,
   createOIMCollectionIndexFactory,
-  createOIMCollectionKit
+  createOIMCollectionKit,
+  createOIMOrderedListMappedCommandStream
 };

package/llms.txt

@@ -84,6 +84,39 @@ 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.
 
+### 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, destroy? })` projects element-wise: the same commands with `item` replaced by `create(slot)`'s result (a DOM node, view model, …). Identity is positional — a `move` reuses the **same** mapped instance (never recreated); `create` runs on insert/set/reset/initial build, `destroy` on remove / replaced-set / reset / `destroy()`. 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(...)`. New exports: `IOIMOrderedListCommandSource`, `TOIMOrderedListMapOptions`, `OIMOrderedListMappedCommandStream`, `createOIMOrderedListMappedCommandStream`.
+
+```ts
+const nodes = createOIMOrderedListMappedCommandStream(stream, {
+    create:  (slot) => engine.makeNode(slot.item),
+    destroy: (node) => engine.dropNode(node),
+});
+nodes.subscribeCommands('main', () => engine.apply(nodes.consumeCommands('main'))); // cmd.item is your node
+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.
+
 ### 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.5.0",
   "description": "Core in-memory data library with type-safe indices, reactive subscriptions, and event processing",
   "type": "module",
   "main": "./dist/index.cjs",