@oimdb/core 3.0.1 → 3.2.0

package/dist/index.js

@@ -422,265 +422,197 @@ var OIMIndexArrayBased = class extends OIMIndex {
   }
 };
 
-// src/enums/EOIMEventQueueEventType.ts
-var EOIMEventQueueEventType = /* @__PURE__ */ ((EOIMEventQueueEventType2) => {
-  EOIMEventQueueEventType2[EOIMEventQueueEventType2["AFTER_FLUSH"] = 0] = "AFTER_FLUSH";
-  EOIMEventQueueEventType2[EOIMEventQueueEventType2["BEFORE_FLUSH"] = 1] = "BEFORE_FLUSH";
-  return EOIMEventQueueEventType2;
-})(EOIMEventQueueEventType || {});
-
-// src/core/OIMUpdateEventEmitter.ts
-var OIMUpdateEventEmitter = class {
-  constructor(queue, deliveryMode = "queue") {
-    this.keyHandlers = /* @__PURE__ */ new Map();
+// src/core/OIMCarrierKeyedEmitter.ts
+var OIMCarrierKeyedEmitter = class {
+  constructor(queue, resolver) {
+    // Carriers with at least one subscriber — for markAllUpdated / metrics.
+    this.subscribedCarriers = /* @__PURE__ */ new Set();
+    // Pending flush batch. A plain array + a `carrier.dirty` flag for dedup —
+    // marking is the hottest write-path op, and pushing to an array with a
+    // boolean check is ~4x cheaper than a `Set` identity-hash add. The flag
+    // doubles as membership: a carrier is in this array iff `carrier.dirty`.
+    this.dirtyCarriers = [];
     this.isFlushEnqueued = false;
-    this.updatedKeys = /* @__PURE__ */ new Set();
-    this.isAfterFlushDeliveryScheduled = false;
-    // 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;
+      if (this.dirtyCarriers.length === 0) return;
+      const flushing = this.dirtyCarriers;
+      this.dirtyCarriers = [];
+      let i = 0;
+      try {
+        for (; i < flushing.length; i++) {
+          flushing[i].dirty = false;
+          this.notify(flushing[i]);
+        }
+      } finally {
+        for (; i < flushing.length; i++) flushing[i].dirty = false;
       }
-      this.runSinglePass();
-    };
-    this.onAfterFlush = () => {
-      if (!this.isAfterFlushDeliveryScheduled) return;
-      this.isAfterFlushDeliveryScheduled = false;
-      this.deliverImmediate();
     };
     this.queue = queue;
-    this.deliveryMode = deliveryMode;
-    if (this.deliveryMode === "after_flush") {
-      this.unsubscribeAfterFlushDelivery = this.queue.emitter.on(
-        0 /* AFTER_FLUSH */,
-        this.onAfterFlush
-      );
-    }
+    this.resolver = resolver;
   }
-  /**
-   * Mark keys as updated and schedule delivery.
-   *
-   * If there are no subscriptions, this is a no-op and does not allocate or retain keys.
-   */
-  markUpdatedKeys(keys) {
-    if (keys.length === 0) return;
-    if (this.deliveryMode === "queue" && this.queue.isInFlush) {
-      throw new Error(
-        "OIMUpdateEventEmitter: updates during queue.flush() are not allowed. Finish all writes before calling queue.flush()."
-      );
+  subscribeOnKey(key, handler) {
+    const carrier = this.resolver.getOrReserveCarrier(key);
+    this.addHandler(carrier, handler);
+    return () => this.removeHandler(carrier, handler);
+  }
+  subscribeOnKeys(keys, handler) {
+    const carriers = [];
+    for (let i = 0; i < keys.length; i++) {
+      const carrier = this.resolver.getOrReserveCarrier(keys[i]);
+      this.addHandler(carrier, handler);
+      carriers.push(carrier);
     }
-    if (this.keyHandlers.size === 0) return;
-    let didAddAny = false;
+    return () => {
+      for (let i = 0; i < carriers.length; i++) {
+        this.removeHandler(carriers[i], handler);
+      }
+    };
+  }
+  unsubscribeFromKey(key, handler) {
+    const carrier = this.resolver.findCarrier(key);
+    if (carrier) this.removeHandler(carrier, handler);
+  }
+  unsubscribeFromKeys(keys, handler) {
     for (let i = 0; i < keys.length; i++) {
-      const key = keys[i];
-      const handlers = this.keyHandlers.get(key);
-      if (!handlers || handlers.size === 0) continue;
-      this.updatedKeys.add(key);
-      didAddAny = true;
+      this.unsubscribeFromKey(keys[i], handler);
     }
-    if (!didAddAny) return;
-    if (this.deliveryMode === "immediate") {
-      this.deliverImmediate();
-      return;
+  }
+  addHandler(carrier, handler) {
+    let subscribers = carrier.subscribers;
+    if (!subscribers) {
+      subscribers = /* @__PURE__ */ new Set();
+      carrier.subscribers = subscribers;
     }
-    if (this.deliveryMode === "after_flush") {
-      this.isAfterFlushDeliveryScheduled = true;
-      return;
+    subscribers.add(handler);
+    this.subscribedCarriers.add(carrier);
+  }
+  removeHandler(carrier, handler) {
+    const subscribers = carrier.subscribers;
+    if (!subscribers) return;
+    subscribers.delete(handler);
+    if (subscribers.size === 0) {
+      this.subscribedCarriers.delete(carrier);
+      this.resolver.onCarrierEmptied?.(carrier);
     }
-    if (this.isFlushEnqueued) return;
-    this.isFlushEnqueued = true;
-    this.dequeueFlush = this.queue.enqueue(this.onFlush);
+  }
+  /** Fast path: the writer already holds the carrier. */
+  markUpdatedCarrier(carrier) {
+    this.assertNotInFlush();
+    const subscribers = carrier.subscribers;
+    if (!subscribers || subscribers.size === 0) return;
+    if (carrier.dirty) return;
+    carrier.dirty = true;
+    this.dirtyCarriers.push(carrier);
+    this.scheduleFlush();
   }
   markUpdatedKey(key) {
-    if (this.deliveryMode === "queue" && this.queue.isInFlush) {
-      throw new Error(
-        "OIMUpdateEventEmitter: updates during queue.flush() are not allowed. Finish all writes before calling queue.flush()."
-      );
-    }
-    if (this.keyHandlers.size === 0) return;
-    const handlers = this.keyHandlers.get(key);
-    if (!handlers || handlers.size === 0) return;
-    this.updatedKeys.add(key);
-    if (this.deliveryMode === "immediate") {
-      this.deliverImmediate();
-      return;
-    }
-    if (this.deliveryMode === "after_flush") {
-      this.isAfterFlushDeliveryScheduled = true;
-      return;
-    }
-    if (this.isFlushEnqueued) return;
-    this.isFlushEnqueued = true;
-    this.dequeueFlush = this.queue.enqueue(this.onFlush);
+    const carrier = this.resolver.findCarrier(key);
+    if (carrier) this.markUpdatedCarrier(carrier);
+    else this.assertNotInFlush();
+  }
+  markUpdatedKeys(keys) {
+    for (let i = 0; i < keys.length; i++) this.markUpdatedKey(keys[i]);
   }
   markAllUpdated() {
-    if (this.deliveryMode === "queue" && this.queue.isInFlush) {
-      throw new Error(
-        "OIMUpdateEventEmitter: updates during queue.flush() are not allowed. Finish all writes before calling queue.flush()."
-      );
-    }
-    if (this.keyHandlers.size === 0) return;
-    this.keyHandlers.forEach((_handlers, key) => {
-      this.updatedKeys.add(key);
+    this.assertNotInFlush();
+    if (this.subscribedCarriers.size === 0) return;
+    this.subscribedCarriers.forEach((carrier) => {
+      if (carrier.dirty) return;
+      carrier.dirty = true;
+      this.dirtyCarriers.push(carrier);
     });
-    if (this.deliveryMode === "immediate") {
-      this.deliverImmediate();
-      return;
-    }
-    if (this.deliveryMode === "after_flush") {
-      this.isAfterFlushDeliveryScheduled = true;
-      return;
-    }
-    if (this.isFlushEnqueued) return;
-    this.isFlushEnqueued = true;
-    this.dequeueFlush = this.queue.enqueue(this.onFlush);
-  }
-  deliverImmediate() {
-    this.runSinglePass();
-  }
-  /**
-   * Notifies all handlers for a key. The overwhelmingly common case is a
-   * single subscriber per key (one component per pk), handled without any
-   * allocation. For multiple subscribers a snapshot is taken so a handler may
-   * (un)subscribe during iteration without corrupting the walk.
-   */
-  notifyHandlers(handlers) {
-    if (handlers.size === 1) {
-      const only = handlers.values().next().value;
-      if (only) only();
-      return;
-    }
-    const snapshot = [];
-    handlers.forEach((h) => snapshot.push(h));
-    for (let i = 0; i < snapshot.length; i++) {
-      const handler = snapshot[i];
-      if (handlers.has(handler)) handler();
-    }
+    this.scheduleFlush();
   }
-  /**
-   * Deliver updated keys and notify handlers once.
-   * Re-entrant updates during delivery are forbidden and will throw in markUpdatedKeys().
-   */
-  runSinglePass() {
-    if (this.updatedKeys.size === 0) return;
-    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 (!handlers || handlers.size === 0) return;
-        this.notifyHandlers(handlers);
-      });
-    } else {
-      this.keyHandlers.forEach((handlers, key) => {
-        if (!flushingKeys.has(key)) return;
-        if (!handlers || handlers.size === 0) return;
-        this.notifyHandlers(handlers);
-      });
-    }
+  hasSubscriptions() {
+    return this.subscribedCarriers.size > 0;
   }
-  destroy() {
-    if (this.dequeueFlush) {
-      this.dequeueFlush();
-      this.dequeueFlush = void 0;
-    }
-    if (this.unsubscribeAfterFlushDelivery) {
-      this.unsubscribeAfterFlushDelivery();
-      this.unsubscribeAfterFlushDelivery = void 0;
-    }
-    this.keyHandlers.forEach((handlers) => handlers.clear());
-    this.keyHandlers.clear();
-    this.updatedKeys.clear();
+  getHandlerCount(key) {
+    return this.resolver.findCarrier(key)?.subscribers?.size ?? 0;
   }
-  /**
-   * Get performance metrics for monitoring and debugging
-   */
   getMetrics() {
     let totalHandlers = 0;
-    this.keyHandlers.forEach((handlers) => {
-      totalHandlers += handlers.size;
+    this.subscribedCarriers.forEach((carrier) => {
+      totalHandlers += carrier.subscribers?.size ?? 0;
     });
+    const totalKeys = this.subscribedCarriers.size;
     return {
-      totalKeys: this.keyHandlers.size,
+      totalKeys,
       totalHandlers,
-      averageHandlersPerKey: this.keyHandlers.size > 0 ? totalHandlers / this.keyHandlers.size : 0,
-      queueLength: this.queue.length
+      averageHandlersPerKey: totalKeys > 0 ? totalHandlers / totalKeys : 0,
+      queueLength: this.dirtyCarriers.length
     };
   }
-  /**
-   * Check if there are any active subscriptions
-   */
-  hasSubscriptions() {
-    return this.keyHandlers.size > 0;
-  }
-  /**
-   * Get the number of handlers for a specific key
-   */
-  getHandlerCount(key) {
-    return this.keyHandlers.get(key)?.size ?? 0;
+  destroy() {
+    if (this.isFlushEnqueued) {
+      this.queue.cancelTask(this.onFlush);
+      this.isFlushEnqueued = false;
+    }
+    this.subscribedCarriers.forEach((carrier) => {
+      carrier.subscribers?.clear();
+      carrier.subscribers = void 0;
+    });
+    this.subscribedCarriers.clear();
+    for (let i = 0; i < this.dirtyCarriers.length; i++) {
+      this.dirtyCarriers[i].dirty = false;
+    }
+    this.dirtyCarriers = [];
+    this.isFlushEnqueued = false;
   }
-  subscribeOnKey(key, handler) {
-    let handlers = this.keyHandlers.get(key);
-    if (!handlers) {
-      handlers = /* @__PURE__ */ new Set();
-      this.keyHandlers.set(key, handlers);
+  assertNotInFlush() {
+    if (this.queue.isInFlush) {
+      throw new Error(
+        "OIMCarrierKeyedEmitter: updates during queue.flush() are not allowed. Finish all writes before calling queue.flush()."
+      );
     }
-    handlers.add(handler);
-    return () => {
-      this.unsubscribeFromKey(key, handler);
-    };
   }
-  unsubscribeFromKey(key, handler) {
-    const handlers = this.keyHandlers.get(key);
-    if (!handlers) return;
-    handlers.delete(handler);
-    if (handlers.size === 0) {
-      this.keyHandlers.delete(key);
-      this.updatedKeys.delete(key);
+  scheduleFlush() {
+    if (this.isFlushEnqueued) return;
+    this.isFlushEnqueued = true;
+    this.queue.enqueueTask(this.onFlush);
+  }
+  notify(carrier) {
+    const subscribers = carrier.subscribers;
+    if (!subscribers || subscribers.size === 0) return;
+    if (subscribers.size === 1) {
+      const only = subscribers.values().next().value;
+      if (only) only();
+      return;
     }
-    if (this.keyHandlers.size === 0) {
-      this.updatedKeys.clear();
-      if (this.dequeueFlush) {
-        this.dequeueFlush();
-        this.dequeueFlush = void 0;
-      }
-      this.isFlushEnqueued = false;
+    const snapshot = [];
+    subscribers.forEach((h) => snapshot.push(h));
+    for (let i = 0; i < snapshot.length; i++) {
+      const handler = snapshot[i];
+      if (subscribers.has(handler)) handler();
     }
   }
-  subscribeOnKeys(keys, handler) {
-    const subscribedKeys = [];
-    for (const key of keys) {
-      let handlers = this.keyHandlers.get(key);
-      if (!handlers) {
-        handlers = /* @__PURE__ */ new Set();
-        this.keyHandlers.set(key, handlers);
-      }
-      if (!handlers.has(handler)) {
-        handlers.add(handler);
-        subscribedKeys.push(key);
-      }
-    }
-    return () => {
-      for (const key of subscribedKeys) {
-        this.unsubscribeFromKey(key, handler);
-      }
-    };
+};
+
+// src/core/OIMKeyedCarrierResolver.ts
+var OIMKeyedCarrierResolver = class {
+  constructor() {
+    this.carriers = /* @__PURE__ */ new Map();
   }
-  unsubscribeFromKeys(keys, handler) {
-    for (const key of keys) {
-      this.unsubscribeFromKey(key, handler);
+  getOrReserveCarrier(key) {
+    let carrier = this.carriers.get(key);
+    if (!carrier) {
+      carrier = { key };
+      this.carriers.set(key, carrier);
     }
+    return carrier;
+  }
+  findCarrier(key) {
+    return this.carriers.get(key);
+  }
+  onCarrierEmptied(carrier) {
+    this.carriers.delete(carrier.key);
   }
 };
 
 // src/abstract/OIMReactiveIndex.ts
 var OIMReactiveIndex = class {
   constructor(queue, createIndex) {
-    this.updateEmitter = new OIMUpdateEventEmitter(queue);
+    this.updateEmitter = new OIMCarrierKeyedEmitter(queue, new OIMKeyedCarrierResolver());
     this.index = createIndex(this.updateEmitter);
   }
   getEntitiesByKey(key) {
@@ -1011,192 +943,45 @@ var OIMCollection = class {
   removeManyByPks(pks) {
     if (pks.length === 0) return;
     this.store.removeManyByPks(pks);
-    this.emitter.emit(0 /* UPDATE */, { pks });
-  }
-  clear() {
-    this.store.clear();
-    this.emitter.emit(0 /* UPDATE */, { pks: [] });
-  }
-  countAll() {
-    return this.store.countAll();
-  }
-  getAll() {
-    return this.store.getAll();
-  }
-  getAllPks() {
-    return this.store.getAllPks();
-  }
-  upsertOneWithoutNotifications(entity) {
-    const pk = this.selectPk(entity);
-    return this.upsertOneWithoutNotificationsByPk(pk, entity);
-  }
-  upsertOneWithoutNotificationsByPk(pk, entity) {
-    if (!pk) {
-      throw new Error(
-        `[OIMCollection]: PK is required to upsert an entity ${JSON.stringify(entity)}`
-      );
-    }
-    const existingEntity = this.store.getOneByPk(pk);
-    if (existingEntity) {
-      return this.store.setOneByPk(
-        pk,
-        this.updateEntity(entity, existingEntity)
-      );
-    } else {
-      return this.store.setOneByPk(pk, entity);
-    }
-  }
-  destroy() {
-    this.store.destroy();
-    this.emitter.offAll();
-  }
-};
-
-// src/core/OIMCarrierKeyedEmitter.ts
-var OIMCarrierKeyedEmitter = class {
-  constructor(queue, resolver) {
-    // Carriers with at least one subscriber — for markAllUpdated / metrics.
-    this.subscribedCarriers = /* @__PURE__ */ new Set();
-    this.dirtyCarriers = /* @__PURE__ */ new Set();
-    this.isFlushEnqueued = false;
-    this.onFlush = () => {
-      this.isFlushEnqueued = false;
-      this.dequeueFlush = void 0;
-      if (this.dirtyCarriers.size === 0) return;
-      const flushing = this.dirtyCarriers;
-      this.dirtyCarriers = /* @__PURE__ */ new Set();
-      flushing.forEach((carrier) => this.notify(carrier));
-    };
-    this.queue = queue;
-    this.resolver = resolver;
-  }
-  subscribeOnKey(key, handler) {
-    const carrier = this.resolver.getOrReserveCarrier(key);
-    this.addHandler(carrier, handler);
-    return () => this.removeHandler(carrier, handler);
-  }
-  subscribeOnKeys(keys, handler) {
-    const carriers = [];
-    for (let i = 0; i < keys.length; i++) {
-      const carrier = this.resolver.getOrReserveCarrier(keys[i]);
-      this.addHandler(carrier, handler);
-      carriers.push(carrier);
-    }
-    return () => {
-      for (let i = 0; i < carriers.length; i++) {
-        this.removeHandler(carriers[i], handler);
-      }
-    };
-  }
-  unsubscribeFromKey(key, handler) {
-    const carrier = this.resolver.findCarrier(key);
-    if (carrier) this.removeHandler(carrier, handler);
-  }
-  unsubscribeFromKeys(keys, handler) {
-    for (let i = 0; i < keys.length; i++) {
-      this.unsubscribeFromKey(keys[i], handler);
-    }
-  }
-  addHandler(carrier, handler) {
-    let subscribers = carrier.subscribers;
-    if (!subscribers) {
-      subscribers = /* @__PURE__ */ new Set();
-      carrier.subscribers = subscribers;
-    }
-    subscribers.add(handler);
-    this.subscribedCarriers.add(carrier);
-  }
-  removeHandler(carrier, handler) {
-    const subscribers = carrier.subscribers;
-    if (!subscribers) return;
-    subscribers.delete(handler);
-    if (subscribers.size === 0) {
-      this.subscribedCarriers.delete(carrier);
-    }
-  }
-  /** Fast path: the writer already holds the carrier. */
-  markUpdatedCarrier(carrier) {
-    this.assertNotInFlush();
-    const subscribers = carrier.subscribers;
-    if (!subscribers || subscribers.size === 0) return;
-    this.dirtyCarriers.add(carrier);
-    this.scheduleFlush();
-  }
-  markUpdatedKey(key) {
-    const carrier = this.resolver.findCarrier(key);
-    if (carrier) this.markUpdatedCarrier(carrier);
-    else this.assertNotInFlush();
-  }
-  markUpdatedKeys(keys) {
-    for (let i = 0; i < keys.length; i++) this.markUpdatedKey(keys[i]);
-  }
-  markAllUpdated() {
-    this.assertNotInFlush();
-    if (this.subscribedCarriers.size === 0) return;
-    this.subscribedCarriers.forEach(
-      (carrier) => this.dirtyCarriers.add(carrier)
-    );
-    this.scheduleFlush();
+    this.emitter.emit(0 /* UPDATE */, { pks });
   }
-  hasSubscriptions() {
-    return this.subscribedCarriers.size > 0;
+  clear() {
+    this.store.clear();
+    this.emitter.emit(0 /* UPDATE */, { pks: [] });
   }
-  getHandlerCount(key) {
-    return this.resolver.findCarrier(key)?.subscribers?.size ?? 0;
+  countAll() {
+    return this.store.countAll();
   }
-  getMetrics() {
-    let totalHandlers = 0;
-    this.subscribedCarriers.forEach((carrier) => {
-      totalHandlers += carrier.subscribers?.size ?? 0;
-    });
-    const totalKeys = this.subscribedCarriers.size;
-    return {
-      totalKeys,
-      totalHandlers,
-      averageHandlersPerKey: totalKeys > 0 ? totalHandlers / totalKeys : 0,
-      queueLength: this.dirtyCarriers.size
-    };
+  getAll() {
+    return this.store.getAll();
   }
-  destroy() {
-    if (this.dequeueFlush) {
-      this.dequeueFlush();
-      this.dequeueFlush = void 0;
-    }
-    this.subscribedCarriers.forEach((carrier) => {
-      carrier.subscribers?.clear();
-      carrier.subscribers = void 0;
-    });
-    this.subscribedCarriers.clear();
-    this.dirtyCarriers.clear();
-    this.isFlushEnqueued = false;
+  getAllPks() {
+    return this.store.getAllPks();
   }
-  assertNotInFlush() {
-    if (this.queue.isInFlush) {
+  upsertOneWithoutNotifications(entity) {
+    const pk = this.selectPk(entity);
+    return this.upsertOneWithoutNotificationsByPk(pk, entity);
+  }
+  upsertOneWithoutNotificationsByPk(pk, entity) {
+    if (!pk) {
       throw new Error(
-        "OIMCarrierKeyedEmitter: updates during queue.flush() are not allowed. Finish all writes before calling queue.flush()."
+        `[OIMCollection]: PK is required to upsert an entity ${JSON.stringify(entity)}`
       );
     }
-  }
-  scheduleFlush() {
-    if (this.isFlushEnqueued) return;
-    this.isFlushEnqueued = true;
-    this.dequeueFlush = this.queue.enqueue(this.onFlush);
-  }
-  notify(carrier) {
-    const subscribers = carrier.subscribers;
-    if (!subscribers || subscribers.size === 0) return;
-    if (subscribers.size === 1) {
-      const only = subscribers.values().next().value;
-      if (only) only();
-      return;
-    }
-    const snapshot = [];
-    subscribers.forEach((h) => snapshot.push(h));
-    for (let i = 0; i < snapshot.length; i++) {
-      const handler = snapshot[i];
-      if (subscribers.has(handler)) handler();
+    const existingEntity = this.store.getOneByPk(pk);
+    if (existingEntity) {
+      return this.store.setOneByPk(
+        pk,
+        this.updateEntity(entity, existingEntity)
+      );
+    } else {
+      return this.store.setOneByPk(pk, entity);
     }
   }
+  destroy() {
+    this.store.destroy();
+    this.emitter.offAll();
+  }
 };
 
 // src/core/OIMReactiveCollection.ts
@@ -1210,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;
@@ -1350,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.enqueueTask(this.runAnyUpdate);
   }
   destroy() {
     this.updateEmitter.destroy();
-    if (this.dequeueAnyUpdate) {
-      this.dequeueAnyUpdate();
-      this.dequeueAnyUpdate = void 0;
+    if (this.isAnyUpdateScheduled) {
+      this.queue.cancelTask(this.runAnyUpdate);
+      this.isAnyUpdateScheduled = false;
     }
     this.anyUpdateHandlers.clear();
     this.pendingAnyUpdatePks.clear();
@@ -1375,109 +1159,362 @@ var OIMIndexManualOrderedArrayBased = class extends OIMIndexArrayBased {
       }
       return;
     }
-    if (this.store.getOneByKey(key) !== void 0) {
-      this.store.removeOneByKey(key);
-      this.emitUpdate([key]);
+    if (this.store.getOneByKey(key) !== void 0) {
+      this.store.removeOneByKey(key);
+      this.emitUpdate([key]);
+    }
+  }
+  pushSlot(key, slot) {
+    const list = this.getOrCreateList(key);
+    const index = list.length;
+    list.push(slot);
+    this.emitUpdate([key]);
+    return index;
+  }
+  insertSlotAt(key, index, slot) {
+    const list = this.getOrCreateList(key);
+    const safeIndex = Math.max(0, Math.min(index, list.length));
+    list.splice(safeIndex, 0, slot);
+    this.emitUpdate([key]);
+    return safeIndex;
+  }
+  removeAt(key, index) {
+    const list = this.store.getOneByKey(key);
+    if (!list) return void 0;
+    if (index < 0 || index >= list.length) return void 0;
+    const [removed] = list.splice(index, 1);
+    if (list.length === 0) {
+      this.store.removeOneByKey(key);
+    }
+    this.emitUpdate([key]);
+    return removed;
+  }
+  move(key, fromIndex, toIndex) {
+    const list = this.store.getOneByKey(key);
+    if (!list) return void 0;
+    if (fromIndex < 0 || fromIndex >= list.length) return void 0;
+    if (toIndex < 0 || toIndex >= list.length) return void 0;
+    if (fromIndex === toIndex) return list[fromIndex];
+    const [slot] = list.splice(fromIndex, 1);
+    if (slot === void 0) return void 0;
+    list.splice(toIndex, 0, slot);
+    this.emitUpdate([key]);
+    return slot;
+  }
+  resetSlots(key, slots) {
+    if (slots.length === 0) {
+      if (this.store.getOneByKey(key) !== void 0) {
+        this.store.removeOneByKey(key);
+        this.emitUpdate([key]);
+      }
+      return;
+    }
+    this.store.setOneByKey(key, slots.slice());
+    this.emitUpdate([key]);
+  }
+  getOrCreateList(key) {
+    let list = this.store.getOneByKey(key);
+    if (!list) {
+      list = [];
+      this.store.setOneByKey(key, list);
+    }
+    return list;
+  }
+};
+
+// src/modules/wrapper/index/OIMCollectionIndexManualOrderedArrayBased.ts
+var OIMCollectionIndexManualOrderedArrayBased = class extends OIMIndexManualOrderedArrayBased {
+  constructor(opts) {
+    super();
+    this.resolveSlot = opts.collection !== void 0 ? (pk) => opts.collection.getSlotByPk(pk) : opts.resolveSlot;
+  }
+  push(key, pk) {
+    return this.pushSlot(key, this.resolveRequiredSlot(pk));
+  }
+  insertAt(key, index, pk) {
+    return this.insertSlotAt(key, index, this.resolveRequiredSlot(pk));
+  }
+  reset(key, pks) {
+    this.resetSlots(key, this.resolveSlots(pks));
+  }
+  getEntitiesByKey(key) {
+    return super.getEntitiesByKey(key);
+  }
+  getEntitiesByKeys(keys) {
+    return super.getEntitiesByKeys(keys);
+  }
+  resolvePk(pk) {
+    return this.resolveRequiredSlot(pk);
+  }
+  resolveSlots(pks) {
+    const slots = [];
+    slots.length = pks.length;
+    for (let i = 0; i < pks.length; i++) {
+      slots[i] = this.resolveRequiredSlot(pks[i]);
+    }
+    return slots;
+  }
+  resolveRequiredSlot(pk) {
+    const slot = this.resolveSlot(pk);
+    if (!slot) {
+      throw new Error(
+        `[OIMCollectionIndexManualOrderedArrayBased]: Unable to resolve slot for PK "${String(pk)}".`
+      );
+    }
+    return slot;
+  }
+};
+
+// src/enums/EOIMEventQueueEventType.ts
+var EOIMEventQueueEventType = /* @__PURE__ */ ((EOIMEventQueueEventType2) => {
+  EOIMEventQueueEventType2[EOIMEventQueueEventType2["AFTER_FLUSH"] = 0] = "AFTER_FLUSH";
+  EOIMEventQueueEventType2[EOIMEventQueueEventType2["BEFORE_FLUSH"] = 1] = "BEFORE_FLUSH";
+  return EOIMEventQueueEventType2;
+})(EOIMEventQueueEventType || {});
+
+// src/core/OIMUpdateEventEmitter.ts
+var OIMUpdateEventEmitter = class {
+  constructor(queue, deliveryMode = "queue") {
+    this.keyHandlers = /* @__PURE__ */ new Map();
+    this.isFlushEnqueued = false;
+    this.updatedKeys = /* @__PURE__ */ new Set();
+    this.isAfterFlushDeliveryScheduled = false;
+    // Stable handler reference to avoid allocating a new closure on every HAS_CHANGES.
+    this.onFlush = () => {
+      this.isFlushEnqueued = false;
+      if (this.keyHandlers.size === 0) {
+        this.updatedKeys.clear();
+        return;
+      }
+      this.runSinglePass();
+    };
+    this.onAfterFlush = () => {
+      if (!this.isAfterFlushDeliveryScheduled) return;
+      this.isAfterFlushDeliveryScheduled = false;
+      this.deliverImmediate();
+    };
+    this.queue = queue;
+    this.deliveryMode = deliveryMode;
+    if (this.deliveryMode === "after_flush") {
+      this.unsubscribeAfterFlushDelivery = this.queue.emitter.on(
+        0 /* AFTER_FLUSH */,
+        this.onAfterFlush
+      );
+    }
+  }
+  /**
+   * Mark keys as updated and schedule delivery.
+   *
+   * If there are no subscriptions, this is a no-op and does not allocate or retain keys.
+   */
+  markUpdatedKeys(keys) {
+    if (keys.length === 0) return;
+    if (this.deliveryMode === "queue" && this.queue.isInFlush) {
+      throw new Error(
+        "OIMUpdateEventEmitter: updates during queue.flush() are not allowed. Finish all writes before calling queue.flush()."
+      );
+    }
+    if (this.keyHandlers.size === 0) return;
+    let didAddAny = false;
+    for (let i = 0; i < keys.length; i++) {
+      const key = keys[i];
+      const handlers = this.keyHandlers.get(key);
+      if (!handlers || handlers.size === 0) continue;
+      this.updatedKeys.add(key);
+      didAddAny = true;
+    }
+    if (!didAddAny) return;
+    if (this.deliveryMode === "immediate") {
+      this.deliverImmediate();
+      return;
+    }
+    if (this.deliveryMode === "after_flush") {
+      this.isAfterFlushDeliveryScheduled = true;
+      return;
+    }
+    if (this.isFlushEnqueued) return;
+    this.isFlushEnqueued = true;
+    this.queue.enqueueTask(this.onFlush);
+  }
+  markUpdatedKey(key) {
+    if (this.deliveryMode === "queue" && this.queue.isInFlush) {
+      throw new Error(
+        "OIMUpdateEventEmitter: updates during queue.flush() are not allowed. Finish all writes before calling queue.flush()."
+      );
+    }
+    if (this.keyHandlers.size === 0) return;
+    const handlers = this.keyHandlers.get(key);
+    if (!handlers || handlers.size === 0) return;
+    this.updatedKeys.add(key);
+    if (this.deliveryMode === "immediate") {
+      this.deliverImmediate();
+      return;
+    }
+    if (this.deliveryMode === "after_flush") {
+      this.isAfterFlushDeliveryScheduled = true;
+      return;
     }
+    if (this.isFlushEnqueued) return;
+    this.isFlushEnqueued = true;
+    this.queue.enqueueTask(this.onFlush);
   }
-  pushSlot(key, slot) {
-    const list = this.getOrCreateList(key);
-    const index = list.length;
-    list.push(slot);
-    this.emitUpdate([key]);
-    return index;
-  }
-  insertSlotAt(key, index, slot) {
-    const list = this.getOrCreateList(key);
-    const safeIndex = Math.max(0, Math.min(index, list.length));
-    list.splice(safeIndex, 0, slot);
-    this.emitUpdate([key]);
-    return safeIndex;
-  }
-  removeAt(key, index) {
-    const list = this.store.getOneByKey(key);
-    if (!list) return void 0;
-    if (index < 0 || index >= list.length) return void 0;
-    const [removed] = list.splice(index, 1);
-    if (list.length === 0) {
-      this.store.removeOneByKey(key);
+  markAllUpdated() {
+    if (this.deliveryMode === "queue" && this.queue.isInFlush) {
+      throw new Error(
+        "OIMUpdateEventEmitter: updates during queue.flush() are not allowed. Finish all writes before calling queue.flush()."
+      );
     }
-    this.emitUpdate([key]);
-    return removed;
+    if (this.keyHandlers.size === 0) return;
+    this.keyHandlers.forEach((_handlers, key) => {
+      this.updatedKeys.add(key);
+    });
+    if (this.deliveryMode === "immediate") {
+      this.deliverImmediate();
+      return;
+    }
+    if (this.deliveryMode === "after_flush") {
+      this.isAfterFlushDeliveryScheduled = true;
+      return;
+    }
+    if (this.isFlushEnqueued) return;
+    this.isFlushEnqueued = true;
+    this.queue.enqueueTask(this.onFlush);
   }
-  move(key, fromIndex, toIndex) {
-    const list = this.store.getOneByKey(key);
-    if (!list) return void 0;
-    if (fromIndex < 0 || fromIndex >= list.length) return void 0;
-    if (toIndex < 0 || toIndex >= list.length) return void 0;
-    if (fromIndex === toIndex) return list[fromIndex];
-    const [slot] = list.splice(fromIndex, 1);
-    if (slot === void 0) return void 0;
-    list.splice(toIndex, 0, slot);
-    this.emitUpdate([key]);
-    return slot;
+  deliverImmediate() {
+    this.runSinglePass();
   }
-  resetSlots(key, slots) {
-    if (slots.length === 0) {
-      if (this.store.getOneByKey(key) !== void 0) {
-        this.store.removeOneByKey(key);
-        this.emitUpdate([key]);
-      }
+  /**
+   * Notifies all handlers for a key. The overwhelmingly common case is a
+   * single subscriber per key (one component per pk), handled without any
+   * allocation. For multiple subscribers a snapshot is taken so a handler may
+   * (un)subscribe during iteration without corrupting the walk.
+   */
+  notifyHandlers(handlers) {
+    if (handlers.size === 1) {
+      const only = handlers.values().next().value;
+      if (only) only();
       return;
     }
-    this.store.setOneByKey(key, slots.slice());
-    this.emitUpdate([key]);
-  }
-  getOrCreateList(key) {
-    let list = this.store.getOneByKey(key);
-    if (!list) {
-      list = [];
-      this.store.setOneByKey(key, list);
+    const snapshot = [];
+    handlers.forEach((h) => snapshot.push(h));
+    for (let i = 0; i < snapshot.length; i++) {
+      const handler = snapshot[i];
+      if (handlers.has(handler)) handler();
     }
-    return list;
   }
-};
-
-// src/modules/wrapper/index/OIMCollectionIndexManualOrderedArrayBased.ts
-var OIMCollectionIndexManualOrderedArrayBased = class extends OIMIndexManualOrderedArrayBased {
-  constructor(opts) {
-    super();
-    this.resolveSlot = opts.collection !== void 0 ? (pk) => opts.collection.getSlotByPk(pk) : opts.resolveSlot;
+  /**
+   * Deliver updated keys and notify handlers once.
+   * Re-entrant updates during delivery are forbidden and will throw in markUpdatedKeys().
+   */
+  runSinglePass() {
+    if (this.updatedKeys.size === 0) return;
+    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 (!handlers || handlers.size === 0) return;
+        this.notifyHandlers(handlers);
+      });
+    } else {
+      this.keyHandlers.forEach((handlers, key) => {
+        if (!flushingKeys.has(key)) return;
+        if (!handlers || handlers.size === 0) return;
+        this.notifyHandlers(handlers);
+      });
+    }
   }
-  push(key, pk) {
-    return this.pushSlot(key, this.resolveRequiredSlot(pk));
+  destroy() {
+    if (this.isFlushEnqueued) {
+      this.queue.cancelTask(this.onFlush);
+      this.isFlushEnqueued = false;
+    }
+    if (this.unsubscribeAfterFlushDelivery) {
+      this.unsubscribeAfterFlushDelivery();
+      this.unsubscribeAfterFlushDelivery = void 0;
+    }
+    this.keyHandlers.forEach((handlers) => handlers.clear());
+    this.keyHandlers.clear();
+    this.updatedKeys.clear();
   }
-  insertAt(key, index, pk) {
-    return this.insertSlotAt(key, index, this.resolveRequiredSlot(pk));
+  /**
+   * Get performance metrics for monitoring and debugging
+   */
+  getMetrics() {
+    let totalHandlers = 0;
+    this.keyHandlers.forEach((handlers) => {
+      totalHandlers += handlers.size;
+    });
+    return {
+      totalKeys: this.keyHandlers.size,
+      totalHandlers,
+      averageHandlersPerKey: this.keyHandlers.size > 0 ? totalHandlers / this.keyHandlers.size : 0,
+      queueLength: this.queue.length
+    };
   }
-  reset(key, pks) {
-    this.resetSlots(key, this.resolveSlots(pks));
+  /**
+   * Check if there are any active subscriptions
+   */
+  hasSubscriptions() {
+    return this.keyHandlers.size > 0;
   }
-  getEntitiesByKey(key) {
-    return super.getEntitiesByKey(key);
+  /**
+   * Get the number of handlers for a specific key
+   */
+  getHandlerCount(key) {
+    return this.keyHandlers.get(key)?.size ?? 0;
   }
-  getEntitiesByKeys(keys) {
-    return super.getEntitiesByKeys(keys);
+  subscribeOnKey(key, handler) {
+    let handlers = this.keyHandlers.get(key);
+    if (!handlers) {
+      handlers = /* @__PURE__ */ new Set();
+      this.keyHandlers.set(key, handlers);
+    }
+    handlers.add(handler);
+    return () => {
+      this.unsubscribeFromKey(key, handler);
+    };
   }
-  resolvePk(pk) {
-    return this.resolveRequiredSlot(pk);
+  unsubscribeFromKey(key, handler) {
+    const handlers = this.keyHandlers.get(key);
+    if (!handlers) return;
+    handlers.delete(handler);
+    if (handlers.size === 0) {
+      this.keyHandlers.delete(key);
+      this.updatedKeys.delete(key);
+    }
+    if (this.keyHandlers.size === 0) {
+      this.updatedKeys.clear();
+      if (this.isFlushEnqueued) {
+        this.queue.cancelTask(this.onFlush);
+      }
+      this.isFlushEnqueued = false;
+    }
   }
-  resolveSlots(pks) {
-    const slots = [];
-    slots.length = pks.length;
-    for (let i = 0; i < pks.length; i++) {
-      slots[i] = this.resolveRequiredSlot(pks[i]);
+  subscribeOnKeys(keys, handler) {
+    const subscribedKeys = [];
+    for (const key of keys) {
+      let handlers = this.keyHandlers.get(key);
+      if (!handlers) {
+        handlers = /* @__PURE__ */ new Set();
+        this.keyHandlers.set(key, handlers);
+      }
+      if (!handlers.has(handler)) {
+        handlers.add(handler);
+        subscribedKeys.push(key);
+      }
     }
-    return slots;
+    return () => {
+      for (const key of subscribedKeys) {
+        this.unsubscribeFromKey(key, handler);
+      }
+    };
   }
-  resolveRequiredSlot(pk) {
-    const slot = this.resolveSlot(pk);
-    if (!slot) {
-      throw new Error(
-        `[OIMCollectionIndexManualOrderedArrayBased]: Unable to resolve slot for PK "${String(pk)}".`
-      );
+  unsubscribeFromKeys(keys, handler) {
+    for (const key of keys) {
+      this.unsubscribeFromKey(key, handler);
     }
-    return slot;
   }
 };
 
@@ -2408,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);
@@ -2428,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();
@@ -2452,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);
@@ -2559,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) {
@@ -2587,6 +2652,22 @@ var OIMEventQueue = class {
       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) {
+    this.tasks.delete(fn);
+    this.flushing?.delete(fn);
+  }
   get isInFlush() {
     return this.isFlushing;
   }
@@ -2606,11 +2687,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);
   }