@oimdb/core 3.3.0 → 3.5.0

package/dist/index.js

@@ -865,12 +865,15 @@ var OIMCollectionStoreMapDriven = class extends OIMCollectionStore {
   }
 };
 
+// src/core/createMergeEntityUpdater.ts
+function createMergeEntityUpdater() {
+  return (draft, prev) => ({ ...prev, ...draft });
+}
+
 // src/core/OIMEntityUpdaterFactory.ts
 var OIMEntityUpdaterFactory = class {
   createMergeEntityUpdater() {
-    return (draft, prev) => {
-      return { ...prev, ...draft };
-    };
+    return createMergeEntityUpdater();
   }
 };
 
@@ -1189,6 +1192,22 @@ var OIMIndexManualOrderedArrayBased = class extends OIMIndexArrayBased {
     this.emitUpdate([key]);
     return removed;
   }
+  /**
+   * Remove up to `count` consecutive slots starting at `index`.
+   * Returns the number actually removed (clamped to bounds; 0 if nothing).
+   */
+  removeRange(key, index, count) {
+    const list = this.store.getOneByKey(key);
+    if (!list) return 0;
+    if (index < 0 || index >= list.length || count <= 0) return 0;
+    const actual = Math.min(count, list.length - index);
+    list.splice(index, actual);
+    if (list.length === 0) {
+      this.store.removeOneByKey(key);
+    }
+    this.emitUpdate([key]);
+    return actual;
+  }
   move(key, fromIndex, toIndex) {
     const list = this.store.getOneByKey(key);
     if (!list) return void 0;
@@ -1201,6 +1220,32 @@ var OIMIndexManualOrderedArrayBased = class extends OIMIndexArrayBased {
     this.emitUpdate([key]);
     return slot;
   }
+  /** Replace the slot at `index` in place. Returns the safe index, or -1. */
+  setSlotAt(key, index, slot) {
+    const list = this.store.getOneByKey(key);
+    if (!list) return -1;
+    if (index < 0 || index >= list.length) return -1;
+    list[index] = slot;
+    this.emitUpdate([key]);
+    return index;
+  }
+  /**
+   * Move up to `count` consecutive slots from `from` to `to`. `to` is in the
+   * coordinate space *after* the block is extracted (same as single `move`).
+   * Returns the number actually moved (0 if a no-op / out of bounds).
+   */
+  moveRange(key, from, to, count) {
+    const list = this.store.getOneByKey(key);
+    if (!list) return 0;
+    if (from < 0 || from >= list.length || count <= 0) return 0;
+    const actual = Math.min(count, list.length - from);
+    const insertAt = Math.max(0, Math.min(to, list.length - actual));
+    if (insertAt === from) return 0;
+    const block = list.splice(from, actual);
+    list.splice(insertAt, 0, ...block);
+    this.emitUpdate([key]);
+    return actual;
+  }
   resetSlots(key, slots) {
     if (slots.length === 0) {
       if (this.store.getOneByKey(key) !== void 0) {
@@ -1411,15 +1456,15 @@ var OIMUpdateEventEmitter = class {
     const flushingKeys = this.updatedKeys;
     this.updatedKeys = /* @__PURE__ */ new Set();
     if (this.keyHandlers.size === 0 || flushingKeys.size === 0) return;
-    if (flushingKeys.size * 2 < this.keyHandlers.size) {
-      flushingKeys.forEach((key) => {
-        const handlers = this.keyHandlers.get(key);
+    if (flushingKeys.size === this.keyHandlers.size) {
+      this.keyHandlers.forEach((handlers, key) => {
+        if (!flushingKeys.has(key)) return;
         if (!handlers || handlers.size === 0) return;
         this.notifyHandlers(handlers);
       });
     } else {
-      this.keyHandlers.forEach((handlers, key) => {
-        if (!flushingKeys.has(key)) return;
+      flushingKeys.forEach((key) => {
+        const handlers = this.keyHandlers.get(key);
         if (!handlers || handlers.size === 0) return;
         this.notifyHandlers(handlers);
       });
@@ -1531,7 +1576,7 @@ var OIMOrderedListCommandStream = class {
       if (payload.keys.length === 0) return;
       for (let i = 0; i < payload.keys.length; i++) {
         const key = payload.keys[i];
-        this.appendSetCommand(key, this.getSlotsByKey(key));
+        this.appendResetCommand(key, this.getSlotsByKey(key));
       }
     };
     this.commandsEventEmitter = new OIMUpdateEventEmitter(
@@ -1556,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);
   }
@@ -1568,12 +1621,7 @@ var OIMOrderedListCommandStream = class {
   pushSlot(key, slot) {
     this.withWrite(() => {
       const index = this.index.pushSlot(key, slot);
-      this.appendCommand(key, {
-        type: "insert",
-        pk: slot.pk,
-        slot,
-        index
-      });
+      this.appendCommand(key, { type: "insert", index, item: slot });
     });
   }
   insertSlotAt(key, index, slot) {
@@ -1581,9 +1629,20 @@ var OIMOrderedListCommandStream = class {
       const safeIndex = this.index.insertSlotAt(key, index, slot);
       this.appendCommand(key, {
         type: "insert",
-        pk: slot.pk,
-        slot,
-        index: safeIndex
+        index: safeIndex,
+        item: slot
+      });
+    });
+  }
+  /** Replace the slot at `index` in place. */
+  setSlotAt(key, index, slot) {
+    this.withWrite(() => {
+      const safeIndex = this.index.setSlotAt(key, index, slot);
+      if (safeIndex < 0) return;
+      this.appendCommand(key, {
+        type: "set",
+        index: safeIndex,
+        item: slot
       });
     });
   }
@@ -1591,12 +1650,15 @@ var OIMOrderedListCommandStream = class {
     this.withWrite(() => {
       const slot = this.index.removeAt(key, index);
       if (slot === void 0) return;
-      this.appendCommand(key, {
-        type: "remove",
-        pk: slot.pk,
-        slot,
-        index
-      });
+      this.appendCommand(key, { type: "remove", index });
+    });
+  }
+  /** Remove `count` consecutive elements from `index`; emits `remove` with `count`. */
+  removeRange(key, index, count) {
+    this.withWrite(() => {
+      const removed = this.index.removeRange(key, index, count);
+      if (removed <= 0) return;
+      this.appendCommand(key, { type: "remove", index, count: removed });
     });
   }
   move(key, fromIndex, toIndex) {
@@ -1605,17 +1667,26 @@ var OIMOrderedListCommandStream = class {
       if (slot === void 0) return;
       this.appendCommand(key, {
         type: "move",
-        pk: slot.pk,
-        slot,
-        fromIndex,
-        toIndex
+        from: fromIndex,
+        to: toIndex
       });
     });
   }
+  /**
+   * Move `count` consecutive elements from `from` to `to`; emits `move` with
+   * `count`. `to` is in the post-extraction coordinate space (as single `move`).
+   */
+  moveRange(key, from, to, count) {
+    this.withWrite(() => {
+      const moved = this.index.moveRange(key, from, to, count);
+      if (moved <= 0) return;
+      this.appendCommand(key, { type: "move", from, to, count: moved });
+    });
+  }
   setSlots(key, slots) {
     this.withWrite(() => {
       this.index.resetSlots(key, slots);
-      this.appendSetCommand(key, slots);
+      this.appendResetCommand(key, slots);
     });
   }
   getBufferedCommands(key) {
@@ -1659,26 +1730,21 @@ var OIMOrderedListCommandStream = class {
       cmds = [];
       this.commandsByKey.set(key, cmds);
     }
-    if (cmd.type === "set") {
+    if (cmd.type === "reset") {
       cmds.length = 0;
       cmds.push(cmd);
-    } else if (cmds.length > 0 && cmds[0].type === "set") {
-      const slots = this.getSlotsByKey(key);
-      cmds[0] = this.createSetCommand(slots);
+    } else if (cmds.length > 0 && cmds[0].type === "reset") {
+      cmds[0] = this.createResetCommand(this.getSlotsByKey(key));
     } else {
       cmds.push(cmd);
     }
     this.commandsEventEmitter.markUpdatedKeys([key]);
   }
-  appendSetCommand(key, slots) {
-    this.appendCommand(key, this.createSetCommand(slots));
+  appendResetCommand(key, slots) {
+    this.appendCommand(key, this.createResetCommand(slots));
   }
-  createSetCommand(slots) {
-    return {
-      type: "set",
-      pks: slots.map((slot) => slot.pk),
-      slots
-    };
+  createResetCommand(slots) {
+    return { type: "reset", items: slots };
   }
 };
 
@@ -1695,12 +1761,7 @@ var OIMCollectionOrderedListCommandStream = class extends OIMOrderedListCommandS
     this.withWrite(() => {
       const slot = this.resolvePk(pk);
       const index = this.index.pushSlot(key, slot);
-      this.appendCommand(key, {
-        type: "insert",
-        pk,
-        slot,
-        index
-      });
+      this.appendCommand(key, { type: "insert", index, item: slot });
     });
   }
   insertAt(key, index, pk) {
@@ -1709,9 +1770,21 @@ var OIMCollectionOrderedListCommandStream = class extends OIMOrderedListCommandS
       const safeIndex = this.index.insertSlotAt(key, index, slot);
       this.appendCommand(key, {
         type: "insert",
-        pk,
-        slot,
-        index: safeIndex
+        index: safeIndex,
+        item: slot
+      });
+    });
+  }
+  /** Replace the element at `index` with the slot for `pk`, in place. */
+  setAt(key, index, pk) {
+    this.withWrite(() => {
+      const slot = this.resolvePk(pk);
+      const safeIndex = this.index.setSlotAt(key, index, slot);
+      if (safeIndex < 0) return;
+      this.appendCommand(key, {
+        type: "set",
+        index: safeIndex,
+        item: slot
       });
     });
   }
@@ -1719,7 +1792,7 @@ var OIMCollectionOrderedListCommandStream = class extends OIMOrderedListCommandS
     this.withWrite(() => {
       const slots = pks.map((pk) => this.resolvePk(pk));
       this.index.resetSlots(key, slots);
-      this.appendSetCommand(key, slots);
+      this.appendResetCommand(key, slots);
     });
   }
   getSlotsByKey(key) {
@@ -3298,20 +3371,27 @@ var OIMCollectionChangedFields = class {
   constructor(queue, collection, opts) {
     this.isInWrite = false;
     this.lastEntitySnapshotByPk = /* @__PURE__ */ new Map();
+    // PKs written through this wrapper during the current flush. Their fields are
+    // already tracked accurately via trackPatch, so the flush-time external-write
+    // handler skips them — no redundant diff + snapshot re-clone. Cleared per flush.
+    this.writtenThroughThisFlush = /* @__PURE__ */ new Set();
     this.changedFieldsByPk = /* @__PURE__ */ new Map();
     this.changedPksByField = /* @__PURE__ */ new Map();
     this.onAfterFlush = () => {
       this.clear();
+      this.writtenThroughThisFlush.clear();
     };
     this.onCollectionUpdate = (payload) => {
       if (this.isInWrite) return;
       if (payload.pks.length === 0) return;
       for (let i = 0; i < payload.pks.length; i++) {
         const pk = payload.pks[i];
+        if (this.writtenThroughThisFlush.has(pk)) continue;
         this.trackExternalMutationByPk(pk);
       }
     };
     this.collection = collection;
+    this.detectExternalMutations = opts?.detectExternalMutations !== false;
     this.selectPk = opts?.selectPk ?? (() => {
       throw new Error(
         `[OIMCollectionChangedFields]: selectPk was not provided. Use upsertOneByPk(...) or pass opts.selectPk.`
@@ -3326,15 +3406,17 @@ var OIMCollectionChangedFields = class {
       0 /* AFTER_FLUSH */,
       this.onAfterFlush
     );
-    const maybeReactive = collection;
-    this.unsubscribeFromCollectionEmitter = maybeReactive.subscribeOnAnyUpdate ? maybeReactive.subscribeOnAnyUpdate((pks) => {
-      this.onCollectionUpdate({
-        pks
-      });
-    }) : collection.emitter.on(
-      0 /* UPDATE */,
-      this.onCollectionUpdate
-    );
+    if (this.detectExternalMutations) {
+      const maybeReactive = collection;
+      this.unsubscribeFromCollectionEmitter = maybeReactive.subscribeOnAnyUpdate ? maybeReactive.subscribeOnAnyUpdate((pks) => {
+        this.onCollectionUpdate({
+          pks
+        });
+      }) : collection.emitter.on(
+        0 /* UPDATE */,
+        this.onCollectionUpdate
+      );
+    }
   }
   upsertOneByPk(pk, patch) {
     const slot = this.withWrite(() => {
@@ -3390,7 +3472,7 @@ var OIMCollectionChangedFields = class {
     this.changedPksEventEmitter.destroy();
     this.changedFieldsEventEmitter.destroy();
     this.unsubscribeAfterFlush();
-    this.unsubscribeFromCollectionEmitter();
+    this.unsubscribeFromCollectionEmitter?.();
     this.clear();
   }
   withWrite(fn) {
@@ -3432,6 +3514,8 @@ var OIMCollectionChangedFields = class {
     return changed;
   }
   updateEntitySnapshot(pk) {
+    if (!this.detectExternalMutations) return;
+    this.writtenThroughThisFlush.add(pk);
     const entity = this.collection.getOneByPk(pk);
     if (!entity) {
       this.lastEntitySnapshotByPk.delete(pk);
@@ -3471,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() {
@@ -4103,6 +4343,7 @@ export {
   OIMObjectValueByKeySelector,
   OIMObjectValuesByKeysSelector,
   OIMOrderedListCommandStream,
+  OIMOrderedListMappedCommandStream,
   OIMPkSelectorFactory,
   OIMReactiveCollection,
   OIMReactiveCollectionIndexManualArrayBased,
@@ -4115,6 +4356,8 @@ export {
   OIMReactiveObject,
   OIMSelector,
   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.3.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",