@oimdb/core 3.1.0 → 3.3.0

package/README.md

@@ -546,6 +546,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 +1534,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,7 +1543,7 @@ 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`.
@@ -1545,7 +1570,7 @@ new OIMOrderedListCommandStream(
 - `getBufferedCommands(key: TKey): readonly TOIMOrderedListCommand<TPk, TEntity>[]` - 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
 

package/dist/index.cjs

@@ -537,7 +537,6 @@ var OIMCarrierKeyedEmitter = class {
     this.isFlushEnqueued = false;
     this.onFlush = () => {
       this.isFlushEnqueued = false;
-      this.dequeueFlush = void 0;
       if (this.dirtyCarriers.length === 0) return;
       const flushing = this.dirtyCarriers;
       this.dirtyCarriers = [];
@@ -647,9 +646,9 @@ var OIMCarrierKeyedEmitter = class {
     };
   }
   destroy() {
-    if (this.dequeueFlush) {
-      this.dequeueFlush();
-      this.dequeueFlush = void 0;
+    if (this.isFlushEnqueued) {
+      this.queue.cancel(this.onFlush);
+      this.isFlushEnqueued = false;
     }
     this.subscribedCarriers.forEach((carrier) => {
       carrier.subscribers?.clear();
@@ -672,7 +671,7 @@ var OIMCarrierKeyedEmitter = class {
   scheduleFlush() {
     if (this.isFlushEnqueued) return;
     this.isFlushEnqueued = true;
-    this.dequeueFlush = this.queue.enqueue(this.onFlush);
+    this.queue.enqueue(this.onFlush);
   }
   notify(carrier) {
     const subscribers = carrier.subscribers;
@@ -1098,7 +1097,6 @@ var OIMReactiveCollection = class extends OIMCollection {
     this.runAnyUpdate = () => {
       if (!this.isAnyUpdateScheduled) return;
       this.isAnyUpdateScheduled = false;
-      this.dequeueAnyUpdate = void 0;
       const pks = this.isAnyUpdateClearPending ? [] : Array.from(this.pendingAnyUpdatePks);
       this.pendingAnyUpdatePks.clear();
       this.isAnyUpdateClearPending = false;
@@ -1238,13 +1236,13 @@ var OIMReactiveCollection = class extends OIMCollection {
   ensureAnyUpdateEnqueued() {
     if (this.isAnyUpdateScheduled) return;
     this.isAnyUpdateScheduled = true;
-    this.dequeueAnyUpdate = this.queue.enqueue(this.runAnyUpdate);
+    this.queue.enqueue(this.runAnyUpdate);
   }
   destroy() {
     this.updateEmitter.destroy();
-    if (this.dequeueAnyUpdate) {
-      this.dequeueAnyUpdate();
-      this.dequeueAnyUpdate = void 0;
+    if (this.isAnyUpdateScheduled) {
+      this.queue.cancel(this.runAnyUpdate);
+      this.isAnyUpdateScheduled = false;
     }
     this.anyUpdateHandlers.clear();
     this.pendingAnyUpdatePks.clear();
@@ -1386,7 +1384,6 @@ var OIMUpdateEventEmitter = class {
     // Stable handler reference to avoid allocating a new closure on every HAS_CHANGES.
     this.onFlush = () => {
       this.isFlushEnqueued = false;
-      this.dequeueFlush = void 0;
       if (this.keyHandlers.size === 0) {
         this.updatedKeys.clear();
         return;
@@ -1439,7 +1436,7 @@ var OIMUpdateEventEmitter = class {
     }
     if (this.isFlushEnqueued) return;
     this.isFlushEnqueued = true;
-    this.dequeueFlush = this.queue.enqueue(this.onFlush);
+    this.queue.enqueue(this.onFlush);
   }
   markUpdatedKey(key) {
     if (this.deliveryMode === "queue" && this.queue.isInFlush) {
@@ -1461,7 +1458,7 @@ var OIMUpdateEventEmitter = class {
     }
     if (this.isFlushEnqueued) return;
     this.isFlushEnqueued = true;
-    this.dequeueFlush = this.queue.enqueue(this.onFlush);
+    this.queue.enqueue(this.onFlush);
   }
   markAllUpdated() {
     if (this.deliveryMode === "queue" && this.queue.isInFlush) {
@@ -1483,7 +1480,7 @@ var OIMUpdateEventEmitter = class {
     }
     if (this.isFlushEnqueued) return;
     this.isFlushEnqueued = true;
-    this.dequeueFlush = this.queue.enqueue(this.onFlush);
+    this.queue.enqueue(this.onFlush);
   }
   deliverImmediate() {
     this.runSinglePass();
@@ -1531,9 +1528,9 @@ var OIMUpdateEventEmitter = class {
     }
   }
   destroy() {
-    if (this.dequeueFlush) {
-      this.dequeueFlush();
-      this.dequeueFlush = void 0;
+    if (this.isFlushEnqueued) {
+      this.queue.cancel(this.onFlush);
+      this.isFlushEnqueued = false;
     }
     if (this.unsubscribeAfterFlushDelivery) {
       this.unsubscribeAfterFlushDelivery();
@@ -1591,9 +1588,8 @@ var OIMUpdateEventEmitter = class {
     }
     if (this.keyHandlers.size === 0) {
       this.updatedKeys.clear();
-      if (this.dequeueFlush) {
-        this.dequeueFlush();
-        this.dequeueFlush = void 0;
+      if (this.isFlushEnqueued) {
+        this.queue.cancel(this.onFlush);
       }
       this.isFlushEnqueued = false;
     }
@@ -2551,17 +2547,15 @@ var OIMObject = class {
   }
   setProperty(key, value) {
     this.store.setProperty(key, value);
-    this.emitter.emit(0 /* UPDATE */, { keys: [key] });
+    this.onUpdatedKey(key);
   }
   merge(draft) {
     this.store.merge(draft);
-    this.emitter.emit(0 /* UPDATE */, {
-      keys: Object.keys(draft)
-    });
+    this.onUpdatedKeys(Object.keys(draft));
   }
   delete(key) {
     this.store.delete(key);
-    this.emitter.emit(0 /* UPDATE */, { keys: [key] });
+    this.onUpdatedKey(key);
   }
   get(key) {
     return this.store.get(key);
@@ -2571,7 +2565,24 @@ var OIMObject = class {
   }
   clear() {
     this.store.clear();
-    this.emitter.emit(0 /* UPDATE */, { keys: [] });
+    this.onUpdatedKeys([]);
+  }
+  /**
+   * Write fan-out hooks. Split single-key vs multi-key so a reactive subclass
+   * can mark its keyed emitter on the hot single-property path without
+   * allocating a `{ keys: [key] }` payload. The base only fires the general
+   * UPDATE event, and only when something is actually subscribed to it — so an
+   * unobserved write skips the payload allocation entirely.
+   */
+  onUpdatedKey(key) {
+    if (this.emitter.hasHandlers(0 /* UPDATE */)) {
+      this.emitter.emit(0 /* UPDATE */, { keys: [key] });
+    }
+  }
+  onUpdatedKeys(keys) {
+    if (this.emitter.hasHandlers(0 /* UPDATE */)) {
+      this.emitter.emit(0 /* UPDATE */, { keys });
+    }
   }
   count() {
     return this.store.count();
@@ -2595,10 +2606,20 @@ var OIMObject = class {
 var OIMReactiveObject = class extends OIMObject {
   constructor(queue, opts) {
     super(opts);
-    this.updateEmitter = new OIMUpdateEventEmitter(queue, "queue");
-    this.emitter.on(0 /* UPDATE */, (payload) => {
-      this.updateEmitter.markUpdatedKeys(payload.keys);
-    });
+    this.updateEmitter = new OIMCarrierKeyedEmitter(queue, new OIMKeyedCarrierResolver());
+  }
+  /**
+   * Mark the written key(s) on the keyed emitter directly — no general-event
+   * bridge, no `{ keys }` payload on the single-key path. `super` still fires
+   * the general UPDATE event for any low-level `emitter` subscribers.
+   */
+  onUpdatedKey(key) {
+    this.updateEmitter.markUpdatedKey(key);
+    super.onUpdatedKey(key);
+  }
+  onUpdatedKeys(keys) {
+    this.updateEmitter.markUpdatedKeys(keys);
+    super.onUpdatedKeys(keys);
   }
   subscribeOnKey(key, handler) {
     return this.updateEmitter.subscribeOnKey(key, handler);
@@ -2702,6 +2723,9 @@ var OIMEventQueue = class {
   constructor(options = {}) {
     this.emitter = new OIMEventEmitter();
     this.tasks = /* @__PURE__ */ new Set();
+    // Reused buffer swapped in during flush so the pending set is never copied
+    // (no per-flush array snapshot) and new enqueues land in a fresh set.
+    this.tasksSpare = /* @__PURE__ */ new Set();
     this.isFlushing = false;
     this.scheduler = options.scheduler;
     if (this.scheduler) {
@@ -2713,32 +2737,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.tasks.add(fn);
     this.ensureScheduled();
-    return () => {
-      if (!isActive) return;
-      isActive = false;
-      this.tasks.delete(task);
-    };
+  }
+  /** 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.
    *
@@ -2749,11 +2764,13 @@ var OIMEventQueue = class {
     this.scheduler?.cancel();
     this.isFlushing = true;
     this.emitter.emit(1 /* BEFORE_FLUSH */, void 0);
-    const snapshot = Array.from(this.tasks);
-    this.tasks.clear();
-    for (let i = 0; i < snapshot.length; i++) {
-      snapshot[i]();
-    }
+    const flushing = this.tasks;
+    this.tasks = this.tasksSpare;
+    this.flushing = flushing;
+    for (const task of flushing) task();
+    flushing.clear();
+    this.tasksSpare = flushing;
+    this.flushing = void 0;
     this.isFlushing = false;
     this.emitter.emit(0 /* AFTER_FLUSH */, void 0);
   }

package/dist/index.d.cts

@@ -247,20 +247,22 @@ declare enum EOIMEventQueueEventType {
 declare class OIMEventQueue {
     readonly emitter: OIMEventEmitter<Record<EOIMEventQueueEventType, void>>;
     protected tasks: Set<() => void>;
+    protected tasksSpare: Set<() => void>;
+    protected flushing?: Set<() => void>;
     protected readonly scheduler?: OIMEventQueueScheduler;
     protected flushBound?: () => void;
     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;
+    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.
      *
@@ -454,7 +456,6 @@ declare class OIMCarrierKeyedEmitter<TKey extends TOIMPk, TCarrier extends IOIMS
     private readonly subscribedCarriers;
     private dirtyCarriers;
     private isFlushEnqueued;
-    private dequeueFlush?;
     constructor(queue: OIMEventQueue, resolver: IOIMCarrierResolver<TKey, TCarrier>);
     subscribeOnKey(key: TKey, handler: TOIMEventHandler<void>): () => void;
     subscribeOnKeys(keys: readonly TKey[], handler: TOIMEventHandler<void>): () => void;
@@ -489,7 +490,6 @@ declare class OIMReactiveCollection<TEntity extends object, TPk extends TOIMPk>
     private pendingAnyUpdatePks;
     private isAnyUpdateClearPending;
     private isAnyUpdateScheduled;
-    private dequeueAnyUpdate?;
     constructor(queue: OIMEventQueue, opts?: TOIMCollectionOptions<TEntity, TPk>);
     subscribeOnKey(pk: TPk, handler: TOIMEventHandler<void>): () => void;
     subscribeOnKeys(pks: readonly TPk[], handler: TOIMEventHandler<void>): () => void;
@@ -661,7 +661,6 @@ declare class OIMUpdateEventEmitter<TKey extends TOIMPk> {
     protected queue: OIMEventQueue;
     private readonly deliveryMode;
     private isFlushEnqueued;
-    private dequeueFlush?;
     private updatedKeys;
     private isAfterFlushDeliveryScheduled;
     private unsubscribeAfterFlushDelivery?;
@@ -999,6 +998,15 @@ declare class OIMObject<TKey extends string, TValue> {
     get(key: TKey): TValue | undefined;
     getAll(): Record<TKey, TValue>;
     clear(): void;
+    /**
+     * Write fan-out hooks. Split single-key vs multi-key so a reactive subclass
+     * can mark its keyed emitter on the hot single-property path without
+     * allocating a `{ keys: [key] }` payload. The base only fires the general
+     * UPDATE event, and only when something is actually subscribed to it — so an
+     * unobserved write skips the payload allocation entirely.
+     */
+    protected onUpdatedKey(key: TKey): void;
+    protected onUpdatedKeys(keys: TKey[]): void;
     count(): number;
     keys(): TKey[];
     values(): TValue[];
@@ -1007,8 +1015,15 @@ declare class OIMObject<TKey extends string, TValue> {
 }
 
 declare class OIMReactiveObject<TKey extends string, TValue> extends OIMObject<TKey, TValue> implements IOIMKeyedSubscription<TKey> {
-    protected readonly updateEmitter: OIMUpdateEventEmitter<TKey>;
+    protected readonly updateEmitter: IOIMKeyedUpdateEmitter<TKey>;
     constructor(queue: OIMEventQueue, opts?: TOIMObjectOptions<TKey, TValue>);
+    /**
+     * Mark the written key(s) on the keyed emitter directly — no general-event
+     * bridge, no `{ keys }` payload on the single-key path. `super` still fires
+     * the general UPDATE event for any low-level `emitter` subscribers.
+     */
+    protected onUpdatedKey(key: TKey): void;
+    protected onUpdatedKeys(keys: TKey[]): void;
     subscribeOnKey(key: TKey, handler: TOIMEventHandler<void>): () => void;
     subscribeOnKeys(keys: readonly TKey[], handler: TOIMEventHandler<void>): () => void;
     unsubscribeFromKey(key: TKey, handler: TOIMEventHandler<void>): void;

package/dist/index.d.ts

@@ -247,20 +247,22 @@ declare enum EOIMEventQueueEventType {
 declare class OIMEventQueue {
     readonly emitter: OIMEventEmitter<Record<EOIMEventQueueEventType, void>>;
     protected tasks: Set<() => void>;
+    protected tasksSpare: Set<() => void>;
+    protected flushing?: Set<() => void>;
     protected readonly scheduler?: OIMEventQueueScheduler;
     protected flushBound?: () => void;
     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;
+    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.
      *
@@ -454,7 +456,6 @@ declare class OIMCarrierKeyedEmitter<TKey extends TOIMPk, TCarrier extends IOIMS
     private readonly subscribedCarriers;
     private dirtyCarriers;
     private isFlushEnqueued;
-    private dequeueFlush?;
     constructor(queue: OIMEventQueue, resolver: IOIMCarrierResolver<TKey, TCarrier>);
     subscribeOnKey(key: TKey, handler: TOIMEventHandler<void>): () => void;
     subscribeOnKeys(keys: readonly TKey[], handler: TOIMEventHandler<void>): () => void;
@@ -489,7 +490,6 @@ declare class OIMReactiveCollection<TEntity extends object, TPk extends TOIMPk>
     private pendingAnyUpdatePks;
     private isAnyUpdateClearPending;
     private isAnyUpdateScheduled;
-    private dequeueAnyUpdate?;
     constructor(queue: OIMEventQueue, opts?: TOIMCollectionOptions<TEntity, TPk>);
     subscribeOnKey(pk: TPk, handler: TOIMEventHandler<void>): () => void;
     subscribeOnKeys(pks: readonly TPk[], handler: TOIMEventHandler<void>): () => void;
@@ -661,7 +661,6 @@ declare class OIMUpdateEventEmitter<TKey extends TOIMPk> {
     protected queue: OIMEventQueue;
     private readonly deliveryMode;
     private isFlushEnqueued;
-    private dequeueFlush?;
     private updatedKeys;
     private isAfterFlushDeliveryScheduled;
     private unsubscribeAfterFlushDelivery?;
@@ -999,6 +998,15 @@ declare class OIMObject<TKey extends string, TValue> {
     get(key: TKey): TValue | undefined;
     getAll(): Record<TKey, TValue>;
     clear(): void;
+    /**
+     * Write fan-out hooks. Split single-key vs multi-key so a reactive subclass
+     * can mark its keyed emitter on the hot single-property path without
+     * allocating a `{ keys: [key] }` payload. The base only fires the general
+     * UPDATE event, and only when something is actually subscribed to it — so an
+     * unobserved write skips the payload allocation entirely.
+     */
+    protected onUpdatedKey(key: TKey): void;
+    protected onUpdatedKeys(keys: TKey[]): void;
     count(): number;
     keys(): TKey[];
     values(): TValue[];
@@ -1007,8 +1015,15 @@ declare class OIMObject<TKey extends string, TValue> {
 }
 
 declare class OIMReactiveObject<TKey extends string, TValue> extends OIMObject<TKey, TValue> implements IOIMKeyedSubscription<TKey> {
-    protected readonly updateEmitter: OIMUpdateEventEmitter<TKey>;
+    protected readonly updateEmitter: IOIMKeyedUpdateEmitter<TKey>;
     constructor(queue: OIMEventQueue, opts?: TOIMObjectOptions<TKey, TValue>);
+    /**
+     * Mark the written key(s) on the keyed emitter directly — no general-event
+     * bridge, no `{ keys }` payload on the single-key path. `super` still fires
+     * the general UPDATE event for any low-level `emitter` subscribers.
+     */
+    protected onUpdatedKey(key: TKey): void;
+    protected onUpdatedKeys(keys: TKey[]): void;
     subscribeOnKey(key: TKey, handler: TOIMEventHandler<void>): () => void;
     subscribeOnKeys(keys: readonly TKey[], handler: TOIMEventHandler<void>): () => void;
     unsubscribeFromKey(key: TKey, handler: TOIMEventHandler<void>): void;

package/dist/index.js

@@ -435,7 +435,6 @@ var OIMCarrierKeyedEmitter = class {
     this.isFlushEnqueued = false;
     this.onFlush = () => {
       this.isFlushEnqueued = false;
-      this.dequeueFlush = void 0;
       if (this.dirtyCarriers.length === 0) return;
       const flushing = this.dirtyCarriers;
       this.dirtyCarriers = [];
@@ -545,9 +544,9 @@ var OIMCarrierKeyedEmitter = class {
     };
   }
   destroy() {
-    if (this.dequeueFlush) {
-      this.dequeueFlush();
-      this.dequeueFlush = void 0;
+    if (this.isFlushEnqueued) {
+      this.queue.cancel(this.onFlush);
+      this.isFlushEnqueued = false;
     }
     this.subscribedCarriers.forEach((carrier) => {
       carrier.subscribers?.clear();
@@ -570,7 +569,7 @@ var OIMCarrierKeyedEmitter = class {
   scheduleFlush() {
     if (this.isFlushEnqueued) return;
     this.isFlushEnqueued = true;
-    this.dequeueFlush = this.queue.enqueue(this.onFlush);
+    this.queue.enqueue(this.onFlush);
   }
   notify(carrier) {
     const subscribers = carrier.subscribers;
@@ -996,7 +995,6 @@ var OIMReactiveCollection = class extends OIMCollection {
     this.runAnyUpdate = () => {
       if (!this.isAnyUpdateScheduled) return;
       this.isAnyUpdateScheduled = false;
-      this.dequeueAnyUpdate = void 0;
       const pks = this.isAnyUpdateClearPending ? [] : Array.from(this.pendingAnyUpdatePks);
       this.pendingAnyUpdatePks.clear();
       this.isAnyUpdateClearPending = false;
@@ -1136,13 +1134,13 @@ var OIMReactiveCollection = class extends OIMCollection {
   ensureAnyUpdateEnqueued() {
     if (this.isAnyUpdateScheduled) return;
     this.isAnyUpdateScheduled = true;
-    this.dequeueAnyUpdate = this.queue.enqueue(this.runAnyUpdate);
+    this.queue.enqueue(this.runAnyUpdate);
   }
   destroy() {
     this.updateEmitter.destroy();
-    if (this.dequeueAnyUpdate) {
-      this.dequeueAnyUpdate();
-      this.dequeueAnyUpdate = void 0;
+    if (this.isAnyUpdateScheduled) {
+      this.queue.cancel(this.runAnyUpdate);
+      this.isAnyUpdateScheduled = false;
     }
     this.anyUpdateHandlers.clear();
     this.pendingAnyUpdatePks.clear();
@@ -1284,7 +1282,6 @@ var OIMUpdateEventEmitter = class {
     // Stable handler reference to avoid allocating a new closure on every HAS_CHANGES.
     this.onFlush = () => {
       this.isFlushEnqueued = false;
-      this.dequeueFlush = void 0;
       if (this.keyHandlers.size === 0) {
         this.updatedKeys.clear();
         return;
@@ -1337,7 +1334,7 @@ var OIMUpdateEventEmitter = class {
     }
     if (this.isFlushEnqueued) return;
     this.isFlushEnqueued = true;
-    this.dequeueFlush = this.queue.enqueue(this.onFlush);
+    this.queue.enqueue(this.onFlush);
   }
   markUpdatedKey(key) {
     if (this.deliveryMode === "queue" && this.queue.isInFlush) {
@@ -1359,7 +1356,7 @@ var OIMUpdateEventEmitter = class {
     }
     if (this.isFlushEnqueued) return;
     this.isFlushEnqueued = true;
-    this.dequeueFlush = this.queue.enqueue(this.onFlush);
+    this.queue.enqueue(this.onFlush);
   }
   markAllUpdated() {
     if (this.deliveryMode === "queue" && this.queue.isInFlush) {
@@ -1381,7 +1378,7 @@ var OIMUpdateEventEmitter = class {
     }
     if (this.isFlushEnqueued) return;
     this.isFlushEnqueued = true;
-    this.dequeueFlush = this.queue.enqueue(this.onFlush);
+    this.queue.enqueue(this.onFlush);
   }
   deliverImmediate() {
     this.runSinglePass();
@@ -1429,9 +1426,9 @@ var OIMUpdateEventEmitter = class {
     }
   }
   destroy() {
-    if (this.dequeueFlush) {
-      this.dequeueFlush();
-      this.dequeueFlush = void 0;
+    if (this.isFlushEnqueued) {
+      this.queue.cancel(this.onFlush);
+      this.isFlushEnqueued = false;
     }
     if (this.unsubscribeAfterFlushDelivery) {
       this.unsubscribeAfterFlushDelivery();
@@ -1489,9 +1486,8 @@ var OIMUpdateEventEmitter = class {
     }
     if (this.keyHandlers.size === 0) {
       this.updatedKeys.clear();
-      if (this.dequeueFlush) {
-        this.dequeueFlush();
-        this.dequeueFlush = void 0;
+      if (this.isFlushEnqueued) {
+        this.queue.cancel(this.onFlush);
       }
       this.isFlushEnqueued = false;
     }
@@ -2449,17 +2445,15 @@ var OIMObject = class {
   }
   setProperty(key, value) {
     this.store.setProperty(key, value);
-    this.emitter.emit(0 /* UPDATE */, { keys: [key] });
+    this.onUpdatedKey(key);
   }
   merge(draft) {
     this.store.merge(draft);
-    this.emitter.emit(0 /* UPDATE */, {
-      keys: Object.keys(draft)
-    });
+    this.onUpdatedKeys(Object.keys(draft));
   }
   delete(key) {
     this.store.delete(key);
-    this.emitter.emit(0 /* UPDATE */, { keys: [key] });
+    this.onUpdatedKey(key);
   }
   get(key) {
     return this.store.get(key);
@@ -2469,7 +2463,24 @@ var OIMObject = class {
   }
   clear() {
     this.store.clear();
-    this.emitter.emit(0 /* UPDATE */, { keys: [] });
+    this.onUpdatedKeys([]);
+  }
+  /**
+   * Write fan-out hooks. Split single-key vs multi-key so a reactive subclass
+   * can mark its keyed emitter on the hot single-property path without
+   * allocating a `{ keys: [key] }` payload. The base only fires the general
+   * UPDATE event, and only when something is actually subscribed to it — so an
+   * unobserved write skips the payload allocation entirely.
+   */
+  onUpdatedKey(key) {
+    if (this.emitter.hasHandlers(0 /* UPDATE */)) {
+      this.emitter.emit(0 /* UPDATE */, { keys: [key] });
+    }
+  }
+  onUpdatedKeys(keys) {
+    if (this.emitter.hasHandlers(0 /* UPDATE */)) {
+      this.emitter.emit(0 /* UPDATE */, { keys });
+    }
   }
   count() {
     return this.store.count();
@@ -2493,10 +2504,20 @@ var OIMObject = class {
 var OIMReactiveObject = class extends OIMObject {
   constructor(queue, opts) {
     super(opts);
-    this.updateEmitter = new OIMUpdateEventEmitter(queue, "queue");
-    this.emitter.on(0 /* UPDATE */, (payload) => {
-      this.updateEmitter.markUpdatedKeys(payload.keys);
-    });
+    this.updateEmitter = new OIMCarrierKeyedEmitter(queue, new OIMKeyedCarrierResolver());
+  }
+  /**
+   * Mark the written key(s) on the keyed emitter directly — no general-event
+   * bridge, no `{ keys }` payload on the single-key path. `super` still fires
+   * the general UPDATE event for any low-level `emitter` subscribers.
+   */
+  onUpdatedKey(key) {
+    this.updateEmitter.markUpdatedKey(key);
+    super.onUpdatedKey(key);
+  }
+  onUpdatedKeys(keys) {
+    this.updateEmitter.markUpdatedKeys(keys);
+    super.onUpdatedKeys(keys);
   }
   subscribeOnKey(key, handler) {
     return this.updateEmitter.subscribeOnKey(key, handler);
@@ -2600,6 +2621,9 @@ var OIMEventQueue = class {
   constructor(options = {}) {
     this.emitter = new OIMEventEmitter();
     this.tasks = /* @__PURE__ */ new Set();
+    // Reused buffer swapped in during flush so the pending set is never copied
+    // (no per-flush array snapshot) and new enqueues land in a fresh set.
+    this.tasksSpare = /* @__PURE__ */ new Set();
     this.isFlushing = false;
     this.scheduler = options.scheduler;
     if (this.scheduler) {
@@ -2611,32 +2635,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.tasks.add(fn);
     this.ensureScheduled();
-    return () => {
-      if (!isActive) return;
-      isActive = false;
-      this.tasks.delete(task);
-    };
+  }
+  /** 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.
    *
@@ -2647,11 +2662,13 @@ var OIMEventQueue = class {
     this.scheduler?.cancel();
     this.isFlushing = true;
     this.emitter.emit(1 /* BEFORE_FLUSH */, void 0);
-    const snapshot = Array.from(this.tasks);
-    this.tasks.clear();
-    for (let i = 0; i < snapshot.length; i++) {
-      snapshot[i]();
-    }
+    const flushing = this.tasks;
+    this.tasks = this.tasksSpare;
+    this.flushing = flushing;
+    for (const task of flushing) task();
+    flushing.clear();
+    this.tasksSpare = flushing;
+    this.flushing = void 0;
     this.isFlushing = false;
     this.emitter.emit(0 /* AFTER_FLUSH */, void 0);
   }

package/package.json

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