@oimdb/core 3.2.0 → 3.4.0

package/dist/index.d.cts

@@ -254,25 +254,15 @@ declare class OIMEventQueue {
     protected isFlushing: boolean;
     constructor(options?: TOIMEventQueueOptions);
     /**
-     * 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: () => void): () => void;
-    /**
-     * 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: () => void): void;
-    /** Cancel a task scheduled via {@link enqueueTask}; safe to call mid-flush. */
-    cancelTask(fn: () => void): void;
+    enqueue(fn: () => void): void;
+    /** Cancel a previously enqueued task by its reference; safe to call mid-flush. */
+    cancel(fn: () => void): void;
     get isInFlush(): boolean;
-    /**
-     * Dequeue (cancel) a previously enqueued task by its dequeue function.
-     */
-    dequeue(dequeueFn: () => void): void;
     /**
      * Execute all pending tasks.
      *
@@ -637,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;
 }
@@ -722,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> {
@@ -770,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>>;
 }
 
 /**
@@ -795,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)[];
@@ -1159,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.
@@ -1307,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(...)`.
@@ -1328,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>;
@@ -1700,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

@@ -254,25 +254,15 @@ declare class OIMEventQueue {
     protected isFlushing: boolean;
     constructor(options?: TOIMEventQueueOptions);
     /**
-     * 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: () => void): () => void;
-    /**
-     * 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: () => void): void;
-    /** Cancel a task scheduled via {@link enqueueTask}; safe to call mid-flush. */
-    cancelTask(fn: () => void): void;
+    enqueue(fn: () => void): void;
+    /** Cancel a previously enqueued task by its reference; safe to call mid-flush. */
+    cancel(fn: () => void): void;
     get isInFlush(): boolean;
-    /**
-     * Dequeue (cancel) a previously enqueued task by its dequeue function.
-     */
-    dequeue(dequeueFn: () => void): void;
     /**
      * Execute all pending tasks.
      *
@@ -637,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;
 }
@@ -722,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> {
@@ -770,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>>;
 }
 
 /**
@@ -795,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)[];
@@ -1159,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.
@@ -1307,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(...)`.
@@ -1328,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>;
@@ -1700,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 };