@oimdb/core 3.3.0 → 3.4.0

package/README.md

@@ -318,16 +318,20 @@ cardsByDeck.commandsEventEmitter.subscribeOnKey('deck1', () => {
     for (const command of commands) {
         switch (command.type) {
             case 'insert':
-                // Insert command.pk / command.slot.item at command.index
+                // Insert command.item (the slot; entity is command.item.item)
+                // at command.index
                 break;
             case 'remove':
-                // Remove command.pk from command.index
+                // Remove command.count ?? 1 elements starting at command.index
                 break;
             case 'move':
-                // Move command.pk from command.fromIndex to command.toIndex
+                // Move command.count ?? 1 elements from command.from to command.to
                 break;
             case 'set':
-                // Replace the whole list with command.pks or command.slots
+                // Replace the single element at command.index with command.item
+                break;
+            case 'reset':
+                // Replace the whole list with command.items (slots)
                 break;
         }
     }
@@ -1546,7 +1550,16 @@ Collection-bound ordered Array-based index. Use this when ordered PK writes shou
 - `getEntitiesByKey(key: TKey): (TEntity | undefined)[]` - Returns entities from canonical slots (holes are `undefined`)
 
 #### `OIMOrderedListCommandStream<TKey, TPk, TEntity>`
-Slot-first ordered per-key list with a command stream for imperative consumers. It stores data in an `OIMIndexManualOrderedArrayBased` and emits `TOIMOrderedListCommand` batches through `commandsEventEmitter`.
+Slot-first ordered per-key list with a command stream for imperative consumers. It stores data in an `OIMIndexManualOrderedArrayBased` and emits position-addressed `TOIMOrderedListCommand<Slot>` batches through `commandsEventEmitter`. Each command's `item` is the entity slot (read the entity via `item.item`):
+
+```typescript
+type TOIMOrderedListCommand<TItem> =
+    | { type: 'insert'; index: number; item: TItem }
+    | { type: 'remove'; index: number; count?: number }   // count may be > 1
+    | { type: 'move'; from: number; to: number; count?: number }
+    | { type: 'set'; index: number; item: TItem }          // replace one element
+    | { type: 'reset'; items: readonly TItem[] };          // replace whole list
+```
 
 **Constructor:**
 ```typescript
@@ -1560,14 +1573,17 @@ new OIMOrderedListCommandStream(
 - `index: OIMIndexManualOrderedArrayBased<TKey, TPk>` - Underlying ordered index and source of truth
 - `commandsEventEmitter: OIMUpdateEventEmitter<TKey>` - Key-specific command notifications delivered after queue flush
 
-**Methods:**
-- `setSlots(key: TKey, slots: readonly TOIMEntitySlot<TEntity, TPk>[]): void` - Replace the whole ordered list and emit a `set` command
-- `pushSlot(key: TKey, slot: TOIMEntitySlot<TEntity, TPk>): void` - Append a slot and emit an `insert` command
-- `insertSlotAt(key: TKey, index: number, slot: TOIMEntitySlot<TEntity, TPk>): void` - Insert a slot and emit an `insert` command
+**Methods:** (`Slot` = `TOIMEntitySlot<TEntity, TPk>`)
+- `setSlots(key: TKey, slots: readonly Slot[]): void` - Replace the whole ordered list and emit a `reset` command
+- `pushSlot(key: TKey, slot: Slot): void` - Append a slot and emit an `insert` command
+- `insertSlotAt(key: TKey, index: number, slot: Slot): void` - Insert a slot and emit an `insert` command
+- `setSlotAt(key: TKey, index: number, slot: Slot): void` - Replace the slot at `index` in place and emit a `set` command
 - `removeAt(key: TKey, index: number): void` - Remove by index and emit a `remove` command
+- `removeRange(key: TKey, index: number, count: number): void` - Remove `count` consecutive elements from `index` and emit a `remove` command with `count`
 - `move(key: TKey, fromIndex: number, toIndex: number): void` - Move within the list and emit a `move` command
-- `consumeCommands(key: TKey): TOIMOrderedListCommand<TPk, TEntity>[]` - Read buffered commands for a key inside the notification handler
-- `getBufferedCommands(key: TKey): readonly TOIMOrderedListCommand<TPk, TEntity>[]` - Peek at buffered commands without clearing them
+- `moveRange(key: TKey, from: number, to: number, count: number): void` - Move `count` consecutive elements and emit a `move` command with `count` (`to` is post-extraction space)
+- `consumeCommands(key: TKey): TOIMOrderedListCommand<Slot>[]` - Read buffered commands for a key inside the notification handler
+- `getBufferedCommands(key: TKey): readonly TOIMOrderedListCommand<Slot>[]` - Peek at buffered commands without clearing them
 - `getPksByKey(key: TKey): readonly TPk[]` - Read the current ordered list
 - `getSlotsByKey(key: TKey): readonly TOIMEntitySlot<TEntity, TPk>[]` - Read current ordered slots
 - `getEntitiesByKey(key: TKey): (TEntity | undefined)[]` - Read current ordered entities (holes are `undefined`)
@@ -1575,10 +1591,11 @@ new OIMOrderedListCommandStream(
 - `destroy(): void` - Dispose subscriptions and clear state
 
 #### `OIMCollectionOrderedListCommandStream<TKey, TPk, TEntity>`
-Collection-bound ordered-list command stream. Public writes use PKs, commands include both `pk`/`pks` and canonical `slot`/`slots`.
+Collection-bound ordered-list command stream. Public writes use PKs that resolve to canonical collection slots; emitted commands carry the slot as `item` (entity via `item.item`).
 
 **Methods:**
-- `set(key: TKey, pks: readonly TPk[]): void` - Replace the whole ordered list from PKs
+- `set(key: TKey, pks: readonly TPk[]): void` - Replace the whole ordered list from PKs (emits `reset`)
+- `setAt(key: TKey, index: number, pk: TPk): void` - Replace the element at `index` with the slot for `pk` (emits `set`)
 - `push(key: TKey, pk: TPk): void` - Append a PK
 - `insertAt(key: TKey, index: number, pk: TPk): void` - Insert a PK
 - all read/command methods from `OIMOrderedListCommandStream`

package/dist/index.cjs

@@ -95,6 +95,7 @@ __export(index_exports, {
   OIMReactiveObject: () => OIMReactiveObject,
   OIMSelector: () => OIMSelector,
   createInPlaceEntityUpdater: () => createInPlaceEntityUpdater,
+  createMergeEntityUpdater: () => createMergeEntityUpdater,
   createOIMCollectionIndexFactory: () => createOIMCollectionIndexFactory,
   createOIMCollectionKit: () => createOIMCollectionKit
 });
@@ -967,12 +968,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();
   }
 };
 
@@ -1291,6 +1295,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;
@@ -1303,6 +1323,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) {
@@ -1513,15 +1559,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);
       });
@@ -1633,7 +1679,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(
@@ -1670,12 +1716,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) {
@@ -1683,9 +1724,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
       });
     });
   }
@@ -1693,12 +1745,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) {
@@ -1707,17 +1762,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) {
@@ -1761,26 +1825,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 };
   }
 };
 
@@ -1797,12 +1856,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) {
@@ -1811,9 +1865,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
       });
     });
   }
@@ -1821,7 +1887,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) {
@@ -3400,20 +3466,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.`
@@ -3428,15 +3501,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(() => {
@@ -3492,7 +3567,7 @@ var OIMCollectionChangedFields = class {
     this.changedPksEventEmitter.destroy();
     this.changedFieldsEventEmitter.destroy();
     this.unsubscribeAfterFlush();
-    this.unsubscribeFromCollectionEmitter();
+    this.unsubscribeFromCollectionEmitter?.();
     this.clear();
   }
   withWrite(fn) {
@@ -3534,6 +3609,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);
@@ -4218,6 +4295,7 @@ var OIMIndexPksByKeysArrayBasedSelector = class extends OIMSelector {
   OIMReactiveObject,
   OIMSelector,
   createInPlaceEntityUpdater,
+  createMergeEntityUpdater,
   createOIMCollectionIndexFactory,
   createOIMCollectionKit
 });

package/dist/index.d.cts

@@ -627,7 +627,20 @@ declare class OIMIndexManualOrderedArrayBased<TKey extends TOIMPk, TItemKey exte
     pushSlot(key: TKey, slot: TOIMAnyEntitySlot<TItemKey>): number;
     insertSlotAt(key: TKey, index: number, slot: TOIMAnyEntitySlot<TItemKey>): number;
     removeAt(key: TKey, index: number): TOIMAnyEntitySlot<TItemKey> | undefined;
+    /**
+     * Remove up to `count` consecutive slots starting at `index`.
+     * Returns the number actually removed (clamped to bounds; 0 if nothing).
+     */
+    removeRange(key: TKey, index: number, count: number): number;
     move(key: TKey, fromIndex: number, toIndex: number): TOIMAnyEntitySlot<TItemKey> | undefined;
+    /** Replace the slot at `index` in place. Returns the safe index, or -1. */
+    setSlotAt(key: TKey, index: number, slot: TOIMAnyEntitySlot<TItemKey>): number;
+    /**
+     * 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: TKey, from: number, to: number, count: number): number;
     resetSlots(key: TKey, slots: readonly TOIMAnyEntitySlot<TItemKey>[]): void;
     private getOrCreateList;
 }
@@ -712,36 +725,46 @@ declare class OIMUpdateEventEmitter<TKey extends TOIMPk> {
     unsubscribeFromKeys(keys: readonly TKey[], handler: TOIMEventHandler<void>): void;
 }
 
-type TOIMOrderedListCommand<TPk extends TOIMPk, TEntity extends object = object> = {
+/**
+ * Incremental command for an ordered per-key list, addressed by position.
+ *
+ * `item` is whatever the stream stores per element — the command stream uses the
+ * entity slot (`TOIMEntitySlot`), so a consumer reads `item.item` for the entity.
+ *
+ * - `insert` — a single element appears at `index`.
+ * - `remove` — `count` elements (default 1, may be > 1) disappear from `index`.
+ * - `move`   — `count` elements (default 1) move from `from` to `to`.
+ * - `set`    — the element at `index` is replaced in place.
+ * - `reset`  — the whole list for the key is replaced by `items`.
+ */
+type TOIMOrderedListCommand<TItem> = {
     type: 'insert';
-    pk: TPk;
-    slot: TOIMEntitySlot<TEntity, TPk>;
     index: number;
+    item: TItem;
 } | {
     type: 'remove';
-    pk: TPk;
-    slot: TOIMEntitySlot<TEntity, TPk>;
     index: number;
+    count?: number;
 } | {
     type: 'move';
-    pk: TPk;
-    slot: TOIMEntitySlot<TEntity, TPk>;
-    fromIndex: number;
-    toIndex: number;
+    from: number;
+    to: number;
+    count?: number;
 } | {
-    /**
-     * Replace the whole list for this key (preferred name).
-     */
     type: 'set';
-    pks: readonly TPk[];
-    slots: readonly TOIMEntitySlot<TEntity, TPk>[];
+    index: number;
+    item: TItem;
+} | {
+    type: 'reset';
+    items: readonly TItem[];
 };
 
 /**
  * Slot-first ordered-list command stream.
  *
- * Use this when you already have slots and want incremental commands for an
- * imperative renderer. For PK writes bound to a collection, use
+ * Emits position-addressed {@link TOIMOrderedListCommand}s whose `item` is the
+ * 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`.
  */
 declare class OIMOrderedListCommandStream<TKey extends TOIMPk, TPk extends TOIMPk, TEntity extends object = object> {
@@ -760,19 +783,28 @@ declare class OIMOrderedListCommandStream<TKey extends TOIMPk, TPk extends TOIMP
     getKeys(): readonly TKey[];
     pushSlot(key: TKey, slot: TOIMEntitySlot<TEntity, TPk>): void;
     insertSlotAt(key: TKey, index: number, slot: TOIMEntitySlot<TEntity, TPk>): void;
+    /** Replace the slot at `index` in place. */
+    setSlotAt(key: TKey, index: number, slot: TOIMEntitySlot<TEntity, TPk>): void;
     removeAt(key: TKey, index: number): void;
+    /** Remove `count` consecutive elements from `index`; emits `remove` with `count`. */
+    removeRange(key: TKey, index: number, count: number): void;
     move(key: TKey, fromIndex: number, toIndex: number): void;
+    /**
+     * 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: TKey, from: number, to: number, count: number): void;
     setSlots(key: TKey, slots: readonly TOIMEntitySlot<TEntity, TPk>[]): void;
-    getBufferedCommands(key: TKey): readonly TOIMOrderedListCommand<TPk, TEntity>[];
-    consumeCommands(key: TKey): TOIMOrderedListCommand<TPk, TEntity>[];
+    getBufferedCommands(key: TKey): readonly TOIMOrderedListCommand<TOIMEntitySlot<TEntity, TPk>>[];
+    consumeCommands(key: TKey): TOIMOrderedListCommand<TOIMEntitySlot<TEntity, TPk>>[];
     clear(key?: TKey): void;
     destroy(): void;
     private readonly onAfterFlush;
     private readonly onIndexUpdate;
     protected withWrite(fn: () => void): void;
-    protected appendCommand(key: TKey, cmd: TOIMOrderedListCommand<TPk, TEntity>): void;
-    protected appendSetCommand(key: TKey, slots: readonly TOIMEntitySlot<TEntity, TPk>[]): void;
-    protected createSetCommand(slots: readonly TOIMEntitySlot<TEntity, TPk>[]): TOIMOrderedListCommand<TPk, TEntity>;
+    protected appendCommand(key: TKey, cmd: TOIMOrderedListCommand<TOIMEntitySlot<TEntity, TPk>>): void;
+    protected appendResetCommand(key: TKey, slots: readonly TOIMEntitySlot<TEntity, TPk>[]): void;
+    protected createResetCommand(slots: readonly TOIMEntitySlot<TEntity, TPk>[]): TOIMOrderedListCommand<TOIMEntitySlot<TEntity, TPk>>;
 }
 
 /**
@@ -785,6 +817,8 @@ declare class OIMCollectionOrderedListCommandStream<TKey extends TOIMPk, TPk ext
     constructor(queue: OIMEventQueue, opts: TOIMCollectionOrderedListCommandStreamOptions<TKey, TPk, TEntity>);
     push(key: TKey, pk: TPk): void;
     insertAt(key: TKey, index: number, pk: TPk): void;
+    /** Replace the element at `index` with the slot for `pk`, in place. */
+    setAt(key: TKey, index: number, pk: TPk): void;
     set(key: TKey, pks: readonly TPk[]): void;
     getSlotsByKey(key: TKey): readonly TOIMEntitySlot<TEntity, TPk>[];
     getEntitiesByKey(key: TKey): (TEntity | undefined)[];
@@ -1149,6 +1183,18 @@ declare class OIMEntityUpdaterFactory<TEntity extends object> {
  */
 declare function createInPlaceEntityUpdater<TEntity extends object>(): TOIMEntityUpdater<TEntity>;
 
+/**
+ * Default entity updater: shallow-merges the patch into a NEW object
+ * (`{ ...prev, ...draft }`). Each update produces a fresh entity reference, which
+ * reference-comparison bindings (React's `Object.is` / `useSyncExternalStore`,
+ * `React.memo`, prev/next diffing, time-travel) need to detect a change.
+ *
+ * The new-object allocation is the biggest per-update data-layer cost; for
+ * update-heavy, subscription-driven readers use {@link createInPlaceEntityUpdater}
+ * instead.
+ */
+declare function createMergeEntityUpdater<TEntity extends object>(): TOIMEntityUpdater<TEntity>;
+
 /**
  * Factory for creating index comparators.
  * Provides common comparison strategies for primary key arrays.
@@ -1297,9 +1343,11 @@ declare class OIMCollectionChangedFields<TEntity extends object, TPk extends TOI
     readonly collection: OIMCollection<TEntity, TPk>;
     private readonly selectPk;
     private readonly unsubscribeAfterFlush;
-    private readonly unsubscribeFromCollectionEmitter;
+    private readonly unsubscribeFromCollectionEmitter?;
+    private readonly detectExternalMutations;
     private isInWrite;
     private readonly lastEntitySnapshotByPk;
+    private readonly writtenThroughThisFlush;
     /**
      * Emits updates scoped by PK. Subscribe, then read state via `getChangedFieldsByPk(...)`
      * or drain via `consumeChangedFieldsByPk(...)`.
@@ -1318,6 +1366,18 @@ declare class OIMCollectionChangedFields<TEntity extends object, TPk extends TOI
          * If not provided, only `upsertOneByPk(...)` should be used.
          */
         selectPk?: (entity: TEntity | Partial<TEntity>) => TPk;
+        /**
+         * Detect writes that bypass this wrapper (direct collection
+         * mutations) by diffing entity snapshots. Default `true`.
+         *
+         * Set to `false` when you always write through this wrapper: it
+         * drops the per-write snapshot clone and the per-PK snapshot map
+         * (~2x entity memory), since those exist only to power external
+         * detection. The shallow diff also can't see deep in-place
+         * mutations anyway — so if that's your model, opting out costs you
+         * nothing it could have caught.
+         */
+        detectExternalMutations?: boolean;
     });
     upsertOneByPk(pk: TPk, patch: Partial<TEntity>): TOIMEntitySlot<TEntity, TPk>;
     upsertOne(entity: TEntity | Partial<TEntity>): TOIMEntitySlot<TEntity, TPk>;
@@ -1690,4 +1750,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, createOIMCollectionIndexFactory, createOIMCollectionKit };
+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 };

package/dist/index.d.ts

@@ -627,7 +627,20 @@ declare class OIMIndexManualOrderedArrayBased<TKey extends TOIMPk, TItemKey exte
     pushSlot(key: TKey, slot: TOIMAnyEntitySlot<TItemKey>): number;
     insertSlotAt(key: TKey, index: number, slot: TOIMAnyEntitySlot<TItemKey>): number;
     removeAt(key: TKey, index: number): TOIMAnyEntitySlot<TItemKey> | undefined;
+    /**
+     * Remove up to `count` consecutive slots starting at `index`.
+     * Returns the number actually removed (clamped to bounds; 0 if nothing).
+     */
+    removeRange(key: TKey, index: number, count: number): number;
     move(key: TKey, fromIndex: number, toIndex: number): TOIMAnyEntitySlot<TItemKey> | undefined;
+    /** Replace the slot at `index` in place. Returns the safe index, or -1. */
+    setSlotAt(key: TKey, index: number, slot: TOIMAnyEntitySlot<TItemKey>): number;
+    /**
+     * 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: TKey, from: number, to: number, count: number): number;
     resetSlots(key: TKey, slots: readonly TOIMAnyEntitySlot<TItemKey>[]): void;
     private getOrCreateList;
 }
@@ -712,36 +725,46 @@ declare class OIMUpdateEventEmitter<TKey extends TOIMPk> {
     unsubscribeFromKeys(keys: readonly TKey[], handler: TOIMEventHandler<void>): void;
 }
 
-type TOIMOrderedListCommand<TPk extends TOIMPk, TEntity extends object = object> = {
+/**
+ * Incremental command for an ordered per-key list, addressed by position.
+ *
+ * `item` is whatever the stream stores per element — the command stream uses the
+ * entity slot (`TOIMEntitySlot`), so a consumer reads `item.item` for the entity.
+ *
+ * - `insert` — a single element appears at `index`.
+ * - `remove` — `count` elements (default 1, may be > 1) disappear from `index`.
+ * - `move`   — `count` elements (default 1) move from `from` to `to`.
+ * - `set`    — the element at `index` is replaced in place.
+ * - `reset`  — the whole list for the key is replaced by `items`.
+ */
+type TOIMOrderedListCommand<TItem> = {
     type: 'insert';
-    pk: TPk;
-    slot: TOIMEntitySlot<TEntity, TPk>;
     index: number;
+    item: TItem;
 } | {
     type: 'remove';
-    pk: TPk;
-    slot: TOIMEntitySlot<TEntity, TPk>;
     index: number;
+    count?: number;
 } | {
     type: 'move';
-    pk: TPk;
-    slot: TOIMEntitySlot<TEntity, TPk>;
-    fromIndex: number;
-    toIndex: number;
+    from: number;
+    to: number;
+    count?: number;
 } | {
-    /**
-     * Replace the whole list for this key (preferred name).
-     */
     type: 'set';
-    pks: readonly TPk[];
-    slots: readonly TOIMEntitySlot<TEntity, TPk>[];
+    index: number;
+    item: TItem;
+} | {
+    type: 'reset';
+    items: readonly TItem[];
 };
 
 /**
  * Slot-first ordered-list command stream.
  *
- * Use this when you already have slots and want incremental commands for an
- * imperative renderer. For PK writes bound to a collection, use
+ * Emits position-addressed {@link TOIMOrderedListCommand}s whose `item` is the
+ * 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`.
  */
 declare class OIMOrderedListCommandStream<TKey extends TOIMPk, TPk extends TOIMPk, TEntity extends object = object> {
@@ -760,19 +783,28 @@ declare class OIMOrderedListCommandStream<TKey extends TOIMPk, TPk extends TOIMP
     getKeys(): readonly TKey[];
     pushSlot(key: TKey, slot: TOIMEntitySlot<TEntity, TPk>): void;
     insertSlotAt(key: TKey, index: number, slot: TOIMEntitySlot<TEntity, TPk>): void;
+    /** Replace the slot at `index` in place. */
+    setSlotAt(key: TKey, index: number, slot: TOIMEntitySlot<TEntity, TPk>): void;
     removeAt(key: TKey, index: number): void;
+    /** Remove `count` consecutive elements from `index`; emits `remove` with `count`. */
+    removeRange(key: TKey, index: number, count: number): void;
     move(key: TKey, fromIndex: number, toIndex: number): void;
+    /**
+     * 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: TKey, from: number, to: number, count: number): void;
     setSlots(key: TKey, slots: readonly TOIMEntitySlot<TEntity, TPk>[]): void;
-    getBufferedCommands(key: TKey): readonly TOIMOrderedListCommand<TPk, TEntity>[];
-    consumeCommands(key: TKey): TOIMOrderedListCommand<TPk, TEntity>[];
+    getBufferedCommands(key: TKey): readonly TOIMOrderedListCommand<TOIMEntitySlot<TEntity, TPk>>[];
+    consumeCommands(key: TKey): TOIMOrderedListCommand<TOIMEntitySlot<TEntity, TPk>>[];
     clear(key?: TKey): void;
     destroy(): void;
     private readonly onAfterFlush;
     private readonly onIndexUpdate;
     protected withWrite(fn: () => void): void;
-    protected appendCommand(key: TKey, cmd: TOIMOrderedListCommand<TPk, TEntity>): void;
-    protected appendSetCommand(key: TKey, slots: readonly TOIMEntitySlot<TEntity, TPk>[]): void;
-    protected createSetCommand(slots: readonly TOIMEntitySlot<TEntity, TPk>[]): TOIMOrderedListCommand<TPk, TEntity>;
+    protected appendCommand(key: TKey, cmd: TOIMOrderedListCommand<TOIMEntitySlot<TEntity, TPk>>): void;
+    protected appendResetCommand(key: TKey, slots: readonly TOIMEntitySlot<TEntity, TPk>[]): void;
+    protected createResetCommand(slots: readonly TOIMEntitySlot<TEntity, TPk>[]): TOIMOrderedListCommand<TOIMEntitySlot<TEntity, TPk>>;
 }
 
 /**
@@ -785,6 +817,8 @@ declare class OIMCollectionOrderedListCommandStream<TKey extends TOIMPk, TPk ext
     constructor(queue: OIMEventQueue, opts: TOIMCollectionOrderedListCommandStreamOptions<TKey, TPk, TEntity>);
     push(key: TKey, pk: TPk): void;
     insertAt(key: TKey, index: number, pk: TPk): void;
+    /** Replace the element at `index` with the slot for `pk`, in place. */
+    setAt(key: TKey, index: number, pk: TPk): void;
     set(key: TKey, pks: readonly TPk[]): void;
     getSlotsByKey(key: TKey): readonly TOIMEntitySlot<TEntity, TPk>[];
     getEntitiesByKey(key: TKey): (TEntity | undefined)[];
@@ -1149,6 +1183,18 @@ declare class OIMEntityUpdaterFactory<TEntity extends object> {
  */
 declare function createInPlaceEntityUpdater<TEntity extends object>(): TOIMEntityUpdater<TEntity>;
 
+/**
+ * Default entity updater: shallow-merges the patch into a NEW object
+ * (`{ ...prev, ...draft }`). Each update produces a fresh entity reference, which
+ * reference-comparison bindings (React's `Object.is` / `useSyncExternalStore`,
+ * `React.memo`, prev/next diffing, time-travel) need to detect a change.
+ *
+ * The new-object allocation is the biggest per-update data-layer cost; for
+ * update-heavy, subscription-driven readers use {@link createInPlaceEntityUpdater}
+ * instead.
+ */
+declare function createMergeEntityUpdater<TEntity extends object>(): TOIMEntityUpdater<TEntity>;
+
 /**
  * Factory for creating index comparators.
  * Provides common comparison strategies for primary key arrays.
@@ -1297,9 +1343,11 @@ declare class OIMCollectionChangedFields<TEntity extends object, TPk extends TOI
     readonly collection: OIMCollection<TEntity, TPk>;
     private readonly selectPk;
     private readonly unsubscribeAfterFlush;
-    private readonly unsubscribeFromCollectionEmitter;
+    private readonly unsubscribeFromCollectionEmitter?;
+    private readonly detectExternalMutations;
     private isInWrite;
     private readonly lastEntitySnapshotByPk;
+    private readonly writtenThroughThisFlush;
     /**
      * Emits updates scoped by PK. Subscribe, then read state via `getChangedFieldsByPk(...)`
      * or drain via `consumeChangedFieldsByPk(...)`.
@@ -1318,6 +1366,18 @@ declare class OIMCollectionChangedFields<TEntity extends object, TPk extends TOI
          * If not provided, only `upsertOneByPk(...)` should be used.
          */
         selectPk?: (entity: TEntity | Partial<TEntity>) => TPk;
+        /**
+         * Detect writes that bypass this wrapper (direct collection
+         * mutations) by diffing entity snapshots. Default `true`.
+         *
+         * Set to `false` when you always write through this wrapper: it
+         * drops the per-write snapshot clone and the per-PK snapshot map
+         * (~2x entity memory), since those exist only to power external
+         * detection. The shallow diff also can't see deep in-place
+         * mutations anyway — so if that's your model, opting out costs you
+         * nothing it could have caught.
+         */
+        detectExternalMutations?: boolean;
     });
     upsertOneByPk(pk: TPk, patch: Partial<TEntity>): TOIMEntitySlot<TEntity, TPk>;
     upsertOne(entity: TEntity | Partial<TEntity>): TOIMEntitySlot<TEntity, TPk>;
@@ -1690,4 +1750,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, createOIMCollectionIndexFactory, createOIMCollectionKit };
+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 };

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(
@@ -1568,12 +1613,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 +1621,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 +1642,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 +1659,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 +1722,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 +1753,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 +1762,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 +1784,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 +3363,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 +3398,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 +3464,7 @@ var OIMCollectionChangedFields = class {
     this.changedPksEventEmitter.destroy();
     this.changedFieldsEventEmitter.destroy();
     this.unsubscribeAfterFlush();
-    this.unsubscribeFromCollectionEmitter();
+    this.unsubscribeFromCollectionEmitter?.();
     this.clear();
   }
   withWrite(fn) {
@@ -3432,6 +3506,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);
@@ -4115,6 +4191,7 @@ export {
   OIMReactiveObject,
   OIMSelector,
   createInPlaceEntityUpdater,
+  createMergeEntityUpdater,
   createOIMCollectionIndexFactory,
   createOIMCollectionKit
 };

package/package.json

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