@oimdb/core 3.2.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;
         }
     }
@@ -546,6 +550,31 @@ users.upsertOne({ id: 'user1', name: 'John' });
 users.upsertOne({ id: 'user1', email: 'john@example.com' }); // Merges with existing
 ```
 
+#### Built-in updaters
+
+Two updater strategies ship as factories — pass the result as `updateEntity`:
+
+```typescript
+import { createMergeEntityUpdater, createInPlaceEntityUpdater } from '@oimdb/core';
+
+// Default: immutable shallow merge — `{ ...prev, ...draft }`. Each update produces
+// a NEW entity object (required for React's Object.is / useSyncExternalStore).
+const a = new OIMReactiveCollection<User, string>(queue, {
+    selectPk: (u) => u.id,
+    updateEntity: createMergeEntityUpdater(),
+});
+
+// In-place: `Object.assign(prev, draft)` — mutates the existing object, no
+// per-update allocation. The entity reference is STABLE across changes, so it
+// only works with subscription-driven readers (e.g. the `*Signal` hooks in
+// @oimdb/react), not with Object.is/React.memo diffing. Fastest on the data
+// layer for update-heavy workloads.
+const b = new OIMReactiveCollection<User, string>(queue, {
+    selectPk: (u) => u.id,
+    updateEntity: createInPlaceEntityUpdater(),
+});
+```
+
 ### Event Coalescing and Update Subscriptions
 
 ```typescript
@@ -1509,7 +1538,7 @@ new OIMIndexManualOrderedArrayBased<TKey, TPk>()
 **Query:**
 - `getPksByKey(key: TKey): TPk[]` - Returns the ordered primary-key array
 - `getSlotsByKey(key: TKey): readonly TOIMAnyEntitySlot<TPk>[]` - Returns the stored ordered slots
-- `getEntitiesByKey<TEntity>(key: TKey): TEntity[]` - Returns existing entities from stored slots
+- `getEntitiesByKey<TEntity>(key: TKey): (TEntity | undefined)[]` - Returns entities from stored slots, aligned 1:1 with the pks (holes are `undefined`)
 
 #### `OIMCollectionIndexManualOrderedArrayBased<TKey, TPk, TEntity>`
 Collection-bound ordered Array-based index. Use this when ordered PK writes should resolve to canonical slots from a collection.
@@ -1518,10 +1547,19 @@ Collection-bound ordered Array-based index. Use this when ordered PK writes shou
 - `push(key: TKey, pk: TPk): number` - Append a PK as its canonical slot
 - `insertAt(key: TKey, index: number, pk: TPk): number` - Insert a PK as its canonical slot
 - `reset(key: TKey, pks: readonly TPk[]): void` - Replace the whole ordered list from PKs
-- `getEntitiesByKey(key: TKey): TEntity[]` - Returns entities from canonical slots
+- `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
@@ -1535,25 +1573,29 @@ 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[]` - Read current ordered entities
+- `getEntitiesByKey(key: TKey): (TEntity | undefined)[]` - Read current ordered entities (holes are `undefined`)
 - `clear(key?: TKey): void` - Clear all keys or a specific key
 - `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
 });
@@ -647,7 +648,7 @@ var OIMCarrierKeyedEmitter = class {
   }
   destroy() {
     if (this.isFlushEnqueued) {
-      this.queue.cancelTask(this.onFlush);
+      this.queue.cancel(this.onFlush);
       this.isFlushEnqueued = false;
     }
     this.subscribedCarriers.forEach((carrier) => {
@@ -671,7 +672,7 @@ var OIMCarrierKeyedEmitter = class {
   scheduleFlush() {
     if (this.isFlushEnqueued) return;
     this.isFlushEnqueued = true;
-    this.queue.enqueueTask(this.onFlush);
+    this.queue.enqueue(this.onFlush);
   }
   notify(carrier) {
     const subscribers = carrier.subscribers;
@@ -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();
   }
 };
 
@@ -1236,12 +1240,12 @@ var OIMReactiveCollection = class extends OIMCollection {
   ensureAnyUpdateEnqueued() {
     if (this.isAnyUpdateScheduled) return;
     this.isAnyUpdateScheduled = true;
-    this.queue.enqueueTask(this.runAnyUpdate);
+    this.queue.enqueue(this.runAnyUpdate);
   }
   destroy() {
     this.updateEmitter.destroy();
     if (this.isAnyUpdateScheduled) {
-      this.queue.cancelTask(this.runAnyUpdate);
+      this.queue.cancel(this.runAnyUpdate);
       this.isAnyUpdateScheduled = false;
     }
     this.anyUpdateHandlers.clear();
@@ -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) {
@@ -1436,7 +1482,7 @@ var OIMUpdateEventEmitter = class {
     }
     if (this.isFlushEnqueued) return;
     this.isFlushEnqueued = true;
-    this.queue.enqueueTask(this.onFlush);
+    this.queue.enqueue(this.onFlush);
   }
   markUpdatedKey(key) {
     if (this.deliveryMode === "queue" && this.queue.isInFlush) {
@@ -1458,7 +1504,7 @@ var OIMUpdateEventEmitter = class {
     }
     if (this.isFlushEnqueued) return;
     this.isFlushEnqueued = true;
-    this.queue.enqueueTask(this.onFlush);
+    this.queue.enqueue(this.onFlush);
   }
   markAllUpdated() {
     if (this.deliveryMode === "queue" && this.queue.isInFlush) {
@@ -1480,7 +1526,7 @@ var OIMUpdateEventEmitter = class {
     }
     if (this.isFlushEnqueued) return;
     this.isFlushEnqueued = true;
-    this.queue.enqueueTask(this.onFlush);
+    this.queue.enqueue(this.onFlush);
   }
   deliverImmediate() {
     this.runSinglePass();
@@ -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);
       });
@@ -1529,7 +1575,7 @@ var OIMUpdateEventEmitter = class {
   }
   destroy() {
     if (this.isFlushEnqueued) {
-      this.queue.cancelTask(this.onFlush);
+      this.queue.cancel(this.onFlush);
       this.isFlushEnqueued = false;
     }
     if (this.unsubscribeAfterFlushDelivery) {
@@ -1589,7 +1635,7 @@ var OIMUpdateEventEmitter = class {
     if (this.keyHandlers.size === 0) {
       this.updatedKeys.clear();
       if (this.isFlushEnqueued) {
-        this.queue.cancelTask(this.onFlush);
+        this.queue.cancel(this.onFlush);
       }
       this.isFlushEnqueued = false;
     }
@@ -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) {
@@ -2737,48 +2803,23 @@ var OIMEventQueue = class {
     }
   }
   /**
-   * Enqueue a one-shot task to be executed on the next flush.
-   * Returns a dequeue function that can be called to cancel the task before it runs.
+   * Enqueue a one-shot task to run on the next flush. The function is stored
+   * directly (no wrapper, no returned closure) and cancelled via {@link cancel}
+   * by passing the same reference. Enqueuing the same reference twice is
+   * idempotent — it is Set-deduped and runs once per flush.
    */
   enqueue(fn) {
-    let isActive = true;
-    const task = () => {
-      if (!isActive) return;
-      fn();
-    };
-    this.tasks.add(task);
-    this.ensureScheduled();
-    return () => {
-      if (!isActive) return;
-      isActive = false;
-      this.tasks.delete(task);
-    };
-  }
-  /**
-   * Allocation-free enqueue for a **stable** function reference (e.g. a bound
-   * `onFlush` method). The function is stored directly — no wrapper, no
-   * returned closure — and cancelled via {@link cancelTask}. Enqueuing the
-   * same reference twice is idempotent (Set-deduped); callers that may run a
-   * task more than once per flush should use {@link enqueue} instead.
-   */
-  enqueueTask(fn) {
     this.tasks.add(fn);
     this.ensureScheduled();
   }
-  /** Cancel a task scheduled via {@link enqueueTask}; safe to call mid-flush. */
-  cancelTask(fn) {
+  /** Cancel a previously enqueued task by its reference; safe to call mid-flush. */
+  cancel(fn) {
     this.tasks.delete(fn);
     this.flushing?.delete(fn);
   }
   get isInFlush() {
     return this.isFlushing;
   }
-  /**
-   * Dequeue (cancel) a previously enqueued task by its dequeue function.
-   */
-  dequeue(dequeueFn) {
-    dequeueFn();
-  }
   /**
    * Execute all pending tasks.
    *
@@ -3425,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.`
@@ -3453,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(() => {
@@ -3517,7 +3567,7 @@ var OIMCollectionChangedFields = class {
     this.changedPksEventEmitter.destroy();
     this.changedFieldsEventEmitter.destroy();
     this.unsubscribeAfterFlush();
-    this.unsubscribeFromCollectionEmitter();
+    this.unsubscribeFromCollectionEmitter?.();
     this.clear();
   }
   withWrite(fn) {
@@ -3559,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);
@@ -4243,6 +4295,7 @@ var OIMIndexPksByKeysArrayBasedSelector = class extends OIMSelector {
   OIMReactiveObject,
   OIMSelector,
   createInPlaceEntityUpdater,
+  createMergeEntityUpdater,
   createOIMCollectionIndexFactory,
   createOIMCollectionKit
 });