@oimdb/core 3.0.1 → 3.1.0

package/dist/index.d.cts

@@ -197,6 +197,33 @@ declare abstract class OIMIndexArrayBased<TKey extends TOIMPk, TPk extends TOIMP
     protected setSlotsWithComparison(key: TKey, newSlots: TOIMAnyEntitySlot<TPk>[]): boolean;
 }
 
+/**
+ * The keyed pub/sub surface a reactive node needs from its update emitter:
+ * per-key subscribe/unsubscribe plus batched "mark updated" delivery.
+ *
+ * Both keyed emitters implement it — `OIMUpdateEventEmitter` (Map of handlers)
+ * and `OIMCarrierKeyedEmitter` (handlers on a per-key carrier). Typing the node
+ * against this interface lets either back the node without leaking the carrier
+ * generic into the node's signatures.
+ */
+interface IOIMKeyedUpdateEmitter<TKey extends TOIMPk> {
+    subscribeOnKey(key: TKey, handler: TOIMEventHandler<void>): () => void;
+    subscribeOnKeys(keys: readonly TKey[], handler: TOIMEventHandler<void>): () => void;
+    unsubscribeFromKey(key: TKey, handler: TOIMEventHandler<void>): void;
+    unsubscribeFromKeys(keys: readonly TKey[], handler: TOIMEventHandler<void>): void;
+    markUpdatedKey(key: TKey): void;
+    markUpdatedKeys(keys: readonly TKey[]): void;
+    hasSubscriptions(): boolean;
+    getHandlerCount(key: TKey): number;
+    getMetrics(): {
+        totalKeys: number;
+        totalHandlers: number;
+        averageHandlersPerKey: number;
+        queueLength: number;
+    };
+    destroy(): void;
+}
+
 /**
  * Configuration options for event queue initialization.
  */
@@ -260,68 +287,6 @@ declare class OIMEventQueue {
     destroy(): void;
 }
 
-type TOIMUpdateEventEmitterDeliveryMode = 'queue' | 'after_flush' | 'immediate';
-/**
- * Universal event emitter that handles subscriptions and notifications for any key type.
- * Optimized for performance with adaptive algorithms and memory management.
- */
-declare class OIMUpdateEventEmitter<TKey extends TOIMPk> {
-    protected keyHandlers: Map<TKey, Set<TOIMEventHandler<void>>>;
-    protected queue: OIMEventQueue;
-    private readonly deliveryMode;
-    private isFlushEnqueued;
-    private dequeueFlush?;
-    private updatedKeys;
-    private isAfterFlushDeliveryScheduled;
-    private unsubscribeAfterFlushDelivery?;
-    constructor(queue: OIMEventQueue, deliveryMode?: TOIMUpdateEventEmitterDeliveryMode);
-    /**
-     * 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: readonly TKey[]): void;
-    markUpdatedKey(key: TKey): void;
-    markAllUpdated(): void;
-    protected readonly onFlush: () => void;
-    private deliverImmediate;
-    /**
-     * 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.
-     */
-    private notifyHandlers;
-    private readonly onAfterFlush;
-    /**
-     * Deliver updated keys and notify handlers once.
-     * Re-entrant updates during delivery are forbidden and will throw in markUpdatedKeys().
-     */
-    protected runSinglePass(): void;
-    destroy(): void;
-    /**
-     * Get performance metrics for monitoring and debugging
-     */
-    getMetrics(): {
-        totalKeys: number;
-        totalHandlers: number;
-        averageHandlersPerKey: number;
-        queueLength: number;
-    };
-    /**
-     * Check if there are any active subscriptions
-     */
-    hasSubscriptions(): boolean;
-    /**
-     * Get the number of handlers for a specific key
-     */
-    getHandlerCount(key: TKey): number;
-    subscribeOnKey(key: TKey, handler: TOIMEventHandler<void>): () => void;
-    unsubscribeFromKey(key: TKey, handler: TOIMEventHandler<void>): void;
-    subscribeOnKeys(keys: readonly TKey[], handler: TOIMEventHandler<void>): () => void;
-    unsubscribeFromKeys(keys: readonly TKey[], handler: TOIMEventHandler<void>): void;
-}
-
 interface IOIMKeyedSubscription<TKey extends TOIMPk> {
     subscribeOnKey(key: TKey, handler: TOIMEventHandler<void>): () => void;
     subscribeOnKeys(keys: readonly TKey[], handler: TOIMEventHandler<void>): () => void;
@@ -329,8 +294,8 @@ interface IOIMKeyedSubscription<TKey extends TOIMPk> {
 
 declare abstract class OIMReactiveIndex<TKey extends TOIMPk, TPk extends TOIMPk, TIndex extends OIMIndex<TKey, TPk, Iterable<TOIMAnyEntitySlot<TPk>>>> implements IOIMKeyedSubscription<TKey> {
     readonly index: TIndex;
-    protected readonly updateEmitter: OIMUpdateEventEmitter<TKey>;
-    constructor(queue: OIMEventQueue, createIndex: (updateEmitter: OIMUpdateEventEmitter<TKey>) => TIndex);
+    protected readonly updateEmitter: IOIMKeyedUpdateEmitter<TKey>;
+    constructor(queue: OIMEventQueue, createIndex: (updateEmitter: IOIMKeyedUpdateEmitter<TKey>) => TIndex);
     getEntitiesByKey<TEntity extends object = object>(key: TKey): (TEntity | undefined)[];
     getEntitiesByKeys<TEntity extends object = object>(keys: readonly TKey[]): Map<TKey, (TEntity | undefined)[]>;
     hasKey(key: TKey): boolean;
@@ -361,7 +326,7 @@ declare abstract class OIMReactiveIndex<TKey extends TOIMPk, TPk extends TOIMPk,
 }
 
 declare abstract class OIMReactiveIndexSetBased<TKey extends TOIMPk, TPk extends TOIMPk, TIndex extends OIMIndexSetBased<TKey, TPk>> extends OIMReactiveIndex<TKey, TPk, TIndex> {
-    constructor(queue: OIMEventQueue, createIndex: (updateEmitter: OIMUpdateEventEmitter<TKey>) => TIndex);
+    constructor(queue: OIMEventQueue, createIndex: (updateEmitter: IOIMKeyedUpdateEmitter<TKey>) => TIndex);
     getPksByKey(key: TKey): Set<TPk>;
     getPksByKeys(keys: readonly TKey[]): Map<TKey, Set<TPk>>;
     getSlotsByKey(key: TKey): ReadonlySet<TOIMAnyEntitySlot<TPk>>;
@@ -369,7 +334,7 @@ declare abstract class OIMReactiveIndexSetBased<TKey extends TOIMPk, TPk extends
 }
 
 declare abstract class OIMReactiveIndexArrayBased<TKey extends TOIMPk, TPk extends TOIMPk, TIndex extends OIMIndexArrayBased<TKey, TPk>> extends OIMReactiveIndex<TKey, TPk, TIndex> {
-    constructor(queue: OIMEventQueue, createIndex: (updateEmitter: OIMUpdateEventEmitter<TKey>) => TIndex);
+    constructor(queue: OIMEventQueue, createIndex: (updateEmitter: IOIMKeyedUpdateEmitter<TKey>) => TIndex);
     getPksByKey(key: TKey): TPk[];
     getPksByKeys(keys: readonly TKey[]): Map<TKey, TPk[]>;
     getSlotsByKey(key: TKey): readonly TOIMAnyEntitySlot<TPk>[];
@@ -442,6 +407,14 @@ declare class OIMCollection<TEntity extends object, TPk extends TOIMPk> {
  */
 interface IOIMSubscribable {
     subscribers?: Set<() => void>;
+    /**
+     * Dirty-batch membership flag, owned by the keyed emitter. `true` while the
+     * carrier sits in the pending flush batch — lets the emitter dedup marks with
+     * an O(1) boolean check instead of a `Set` identity-hash lookup. Reset to
+     * `false` as the carrier is delivered (or on flush teardown). Do not read or
+     * write outside the emitter.
+     */
+    dirty?: boolean;
 }
 
 /**
@@ -456,6 +429,13 @@ interface IOIMSubscribable {
 interface IOIMCarrierResolver<TKey extends TOIMPk, TCarrier> {
     getOrReserveCarrier(key: TKey): TCarrier;
     findCarrier(key: TKey): TCarrier | undefined;
+    /**
+     * Optional: called when a carrier loses its last subscriber, so a resolver
+     * that owns standalone carriers (e.g. the index's key→carrier map) can prune
+     * it and not leak the key space. Resolvers whose carriers are owned
+     * elsewhere (e.g. the collection's slots) leave this unset.
+     */
+    onCarrierEmptied?(carrier: TCarrier): void;
 }
 /**
  * Keyed (per-key) pub/sub that stores handlers ON the carrier object
@@ -468,7 +448,7 @@ interface IOIMCarrierResolver<TKey extends TOIMPk, TCarrier> {
  * index's keyed emitter. Reused with carrier = slot (collection) or carrier =
  * bucket (index).
  */
-declare class OIMCarrierKeyedEmitter<TKey extends TOIMPk, TCarrier extends IOIMSubscribable> {
+declare class OIMCarrierKeyedEmitter<TKey extends TOIMPk, TCarrier extends IOIMSubscribable> implements IOIMKeyedUpdateEmitter<TKey> {
     private readonly queue;
     private readonly resolver;
     private readonly subscribedCarriers;
@@ -671,6 +651,68 @@ declare class OIMCollectionIndexManualOrderedArrayBased<TKey extends TOIMPk, TPk
     private resolveRequiredSlot;
 }
 
+type TOIMUpdateEventEmitterDeliveryMode = 'queue' | 'after_flush' | 'immediate';
+/**
+ * Universal event emitter that handles subscriptions and notifications for any key type.
+ * Optimized for performance with adaptive algorithms and memory management.
+ */
+declare class OIMUpdateEventEmitter<TKey extends TOIMPk> {
+    protected keyHandlers: Map<TKey, Set<TOIMEventHandler<void>>>;
+    protected queue: OIMEventQueue;
+    private readonly deliveryMode;
+    private isFlushEnqueued;
+    private dequeueFlush?;
+    private updatedKeys;
+    private isAfterFlushDeliveryScheduled;
+    private unsubscribeAfterFlushDelivery?;
+    constructor(queue: OIMEventQueue, deliveryMode?: TOIMUpdateEventEmitterDeliveryMode);
+    /**
+     * 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: readonly TKey[]): void;
+    markUpdatedKey(key: TKey): void;
+    markAllUpdated(): void;
+    protected readonly onFlush: () => void;
+    private deliverImmediate;
+    /**
+     * 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.
+     */
+    private notifyHandlers;
+    private readonly onAfterFlush;
+    /**
+     * Deliver updated keys and notify handlers once.
+     * Re-entrant updates during delivery are forbidden and will throw in markUpdatedKeys().
+     */
+    protected runSinglePass(): void;
+    destroy(): void;
+    /**
+     * Get performance metrics for monitoring and debugging
+     */
+    getMetrics(): {
+        totalKeys: number;
+        totalHandlers: number;
+        averageHandlersPerKey: number;
+        queueLength: number;
+    };
+    /**
+     * Check if there are any active subscriptions
+     */
+    hasSubscriptions(): boolean;
+    /**
+     * Get the number of handlers for a specific key
+     */
+    getHandlerCount(key: TKey): number;
+    subscribeOnKey(key: TKey, handler: TOIMEventHandler<void>): () => void;
+    unsubscribeFromKey(key: TKey, handler: TOIMEventHandler<void>): void;
+    subscribeOnKeys(keys: readonly TKey[], handler: TOIMEventHandler<void>): () => void;
+    unsubscribeFromKeys(keys: readonly TKey[], handler: TOIMEventHandler<void>): void;
+}
+
 type TOIMOrderedListCommand<TPk extends TOIMPk, TEntity extends object = object> = {
     type: 'insert';
     pk: TPk;
@@ -1633,4 +1675,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 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, createOIMCollectionIndexFactory, createOIMCollectionKit };

package/dist/index.d.ts

@@ -197,6 +197,33 @@ declare abstract class OIMIndexArrayBased<TKey extends TOIMPk, TPk extends TOIMP
     protected setSlotsWithComparison(key: TKey, newSlots: TOIMAnyEntitySlot<TPk>[]): boolean;
 }
 
+/**
+ * The keyed pub/sub surface a reactive node needs from its update emitter:
+ * per-key subscribe/unsubscribe plus batched "mark updated" delivery.
+ *
+ * Both keyed emitters implement it — `OIMUpdateEventEmitter` (Map of handlers)
+ * and `OIMCarrierKeyedEmitter` (handlers on a per-key carrier). Typing the node
+ * against this interface lets either back the node without leaking the carrier
+ * generic into the node's signatures.
+ */
+interface IOIMKeyedUpdateEmitter<TKey extends TOIMPk> {
+    subscribeOnKey(key: TKey, handler: TOIMEventHandler<void>): () => void;
+    subscribeOnKeys(keys: readonly TKey[], handler: TOIMEventHandler<void>): () => void;
+    unsubscribeFromKey(key: TKey, handler: TOIMEventHandler<void>): void;
+    unsubscribeFromKeys(keys: readonly TKey[], handler: TOIMEventHandler<void>): void;
+    markUpdatedKey(key: TKey): void;
+    markUpdatedKeys(keys: readonly TKey[]): void;
+    hasSubscriptions(): boolean;
+    getHandlerCount(key: TKey): number;
+    getMetrics(): {
+        totalKeys: number;
+        totalHandlers: number;
+        averageHandlersPerKey: number;
+        queueLength: number;
+    };
+    destroy(): void;
+}
+
 /**
  * Configuration options for event queue initialization.
  */
@@ -260,68 +287,6 @@ declare class OIMEventQueue {
     destroy(): void;
 }
 
-type TOIMUpdateEventEmitterDeliveryMode = 'queue' | 'after_flush' | 'immediate';
-/**
- * Universal event emitter that handles subscriptions and notifications for any key type.
- * Optimized for performance with adaptive algorithms and memory management.
- */
-declare class OIMUpdateEventEmitter<TKey extends TOIMPk> {
-    protected keyHandlers: Map<TKey, Set<TOIMEventHandler<void>>>;
-    protected queue: OIMEventQueue;
-    private readonly deliveryMode;
-    private isFlushEnqueued;
-    private dequeueFlush?;
-    private updatedKeys;
-    private isAfterFlushDeliveryScheduled;
-    private unsubscribeAfterFlushDelivery?;
-    constructor(queue: OIMEventQueue, deliveryMode?: TOIMUpdateEventEmitterDeliveryMode);
-    /**
-     * 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: readonly TKey[]): void;
-    markUpdatedKey(key: TKey): void;
-    markAllUpdated(): void;
-    protected readonly onFlush: () => void;
-    private deliverImmediate;
-    /**
-     * 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.
-     */
-    private notifyHandlers;
-    private readonly onAfterFlush;
-    /**
-     * Deliver updated keys and notify handlers once.
-     * Re-entrant updates during delivery are forbidden and will throw in markUpdatedKeys().
-     */
-    protected runSinglePass(): void;
-    destroy(): void;
-    /**
-     * Get performance metrics for monitoring and debugging
-     */
-    getMetrics(): {
-        totalKeys: number;
-        totalHandlers: number;
-        averageHandlersPerKey: number;
-        queueLength: number;
-    };
-    /**
-     * Check if there are any active subscriptions
-     */
-    hasSubscriptions(): boolean;
-    /**
-     * Get the number of handlers for a specific key
-     */
-    getHandlerCount(key: TKey): number;
-    subscribeOnKey(key: TKey, handler: TOIMEventHandler<void>): () => void;
-    unsubscribeFromKey(key: TKey, handler: TOIMEventHandler<void>): void;
-    subscribeOnKeys(keys: readonly TKey[], handler: TOIMEventHandler<void>): () => void;
-    unsubscribeFromKeys(keys: readonly TKey[], handler: TOIMEventHandler<void>): void;
-}
-
 interface IOIMKeyedSubscription<TKey extends TOIMPk> {
     subscribeOnKey(key: TKey, handler: TOIMEventHandler<void>): () => void;
     subscribeOnKeys(keys: readonly TKey[], handler: TOIMEventHandler<void>): () => void;
@@ -329,8 +294,8 @@ interface IOIMKeyedSubscription<TKey extends TOIMPk> {
 
 declare abstract class OIMReactiveIndex<TKey extends TOIMPk, TPk extends TOIMPk, TIndex extends OIMIndex<TKey, TPk, Iterable<TOIMAnyEntitySlot<TPk>>>> implements IOIMKeyedSubscription<TKey> {
     readonly index: TIndex;
-    protected readonly updateEmitter: OIMUpdateEventEmitter<TKey>;
-    constructor(queue: OIMEventQueue, createIndex: (updateEmitter: OIMUpdateEventEmitter<TKey>) => TIndex);
+    protected readonly updateEmitter: IOIMKeyedUpdateEmitter<TKey>;
+    constructor(queue: OIMEventQueue, createIndex: (updateEmitter: IOIMKeyedUpdateEmitter<TKey>) => TIndex);
     getEntitiesByKey<TEntity extends object = object>(key: TKey): (TEntity | undefined)[];
     getEntitiesByKeys<TEntity extends object = object>(keys: readonly TKey[]): Map<TKey, (TEntity | undefined)[]>;
     hasKey(key: TKey): boolean;
@@ -361,7 +326,7 @@ declare abstract class OIMReactiveIndex<TKey extends TOIMPk, TPk extends TOIMPk,
 }
 
 declare abstract class OIMReactiveIndexSetBased<TKey extends TOIMPk, TPk extends TOIMPk, TIndex extends OIMIndexSetBased<TKey, TPk>> extends OIMReactiveIndex<TKey, TPk, TIndex> {
-    constructor(queue: OIMEventQueue, createIndex: (updateEmitter: OIMUpdateEventEmitter<TKey>) => TIndex);
+    constructor(queue: OIMEventQueue, createIndex: (updateEmitter: IOIMKeyedUpdateEmitter<TKey>) => TIndex);
     getPksByKey(key: TKey): Set<TPk>;
     getPksByKeys(keys: readonly TKey[]): Map<TKey, Set<TPk>>;
     getSlotsByKey(key: TKey): ReadonlySet<TOIMAnyEntitySlot<TPk>>;
@@ -369,7 +334,7 @@ declare abstract class OIMReactiveIndexSetBased<TKey extends TOIMPk, TPk extends
 }
 
 declare abstract class OIMReactiveIndexArrayBased<TKey extends TOIMPk, TPk extends TOIMPk, TIndex extends OIMIndexArrayBased<TKey, TPk>> extends OIMReactiveIndex<TKey, TPk, TIndex> {
-    constructor(queue: OIMEventQueue, createIndex: (updateEmitter: OIMUpdateEventEmitter<TKey>) => TIndex);
+    constructor(queue: OIMEventQueue, createIndex: (updateEmitter: IOIMKeyedUpdateEmitter<TKey>) => TIndex);
     getPksByKey(key: TKey): TPk[];
     getPksByKeys(keys: readonly TKey[]): Map<TKey, TPk[]>;
     getSlotsByKey(key: TKey): readonly TOIMAnyEntitySlot<TPk>[];
@@ -442,6 +407,14 @@ declare class OIMCollection<TEntity extends object, TPk extends TOIMPk> {
  */
 interface IOIMSubscribable {
     subscribers?: Set<() => void>;
+    /**
+     * Dirty-batch membership flag, owned by the keyed emitter. `true` while the
+     * carrier sits in the pending flush batch — lets the emitter dedup marks with
+     * an O(1) boolean check instead of a `Set` identity-hash lookup. Reset to
+     * `false` as the carrier is delivered (or on flush teardown). Do not read or
+     * write outside the emitter.
+     */
+    dirty?: boolean;
 }
 
 /**
@@ -456,6 +429,13 @@ interface IOIMSubscribable {
 interface IOIMCarrierResolver<TKey extends TOIMPk, TCarrier> {
     getOrReserveCarrier(key: TKey): TCarrier;
     findCarrier(key: TKey): TCarrier | undefined;
+    /**
+     * Optional: called when a carrier loses its last subscriber, so a resolver
+     * that owns standalone carriers (e.g. the index's key→carrier map) can prune
+     * it and not leak the key space. Resolvers whose carriers are owned
+     * elsewhere (e.g. the collection's slots) leave this unset.
+     */
+    onCarrierEmptied?(carrier: TCarrier): void;
 }
 /**
  * Keyed (per-key) pub/sub that stores handlers ON the carrier object
@@ -468,7 +448,7 @@ interface IOIMCarrierResolver<TKey extends TOIMPk, TCarrier> {
  * index's keyed emitter. Reused with carrier = slot (collection) or carrier =
  * bucket (index).
  */
-declare class OIMCarrierKeyedEmitter<TKey extends TOIMPk, TCarrier extends IOIMSubscribable> {
+declare class OIMCarrierKeyedEmitter<TKey extends TOIMPk, TCarrier extends IOIMSubscribable> implements IOIMKeyedUpdateEmitter<TKey> {
     private readonly queue;
     private readonly resolver;
     private readonly subscribedCarriers;
@@ -671,6 +651,68 @@ declare class OIMCollectionIndexManualOrderedArrayBased<TKey extends TOIMPk, TPk
     private resolveRequiredSlot;
 }
 
+type TOIMUpdateEventEmitterDeliveryMode = 'queue' | 'after_flush' | 'immediate';
+/**
+ * Universal event emitter that handles subscriptions and notifications for any key type.
+ * Optimized for performance with adaptive algorithms and memory management.
+ */
+declare class OIMUpdateEventEmitter<TKey extends TOIMPk> {
+    protected keyHandlers: Map<TKey, Set<TOIMEventHandler<void>>>;
+    protected queue: OIMEventQueue;
+    private readonly deliveryMode;
+    private isFlushEnqueued;
+    private dequeueFlush?;
+    private updatedKeys;
+    private isAfterFlushDeliveryScheduled;
+    private unsubscribeAfterFlushDelivery?;
+    constructor(queue: OIMEventQueue, deliveryMode?: TOIMUpdateEventEmitterDeliveryMode);
+    /**
+     * 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: readonly TKey[]): void;
+    markUpdatedKey(key: TKey): void;
+    markAllUpdated(): void;
+    protected readonly onFlush: () => void;
+    private deliverImmediate;
+    /**
+     * 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.
+     */
+    private notifyHandlers;
+    private readonly onAfterFlush;
+    /**
+     * Deliver updated keys and notify handlers once.
+     * Re-entrant updates during delivery are forbidden and will throw in markUpdatedKeys().
+     */
+    protected runSinglePass(): void;
+    destroy(): void;
+    /**
+     * Get performance metrics for monitoring and debugging
+     */
+    getMetrics(): {
+        totalKeys: number;
+        totalHandlers: number;
+        averageHandlersPerKey: number;
+        queueLength: number;
+    };
+    /**
+     * Check if there are any active subscriptions
+     */
+    hasSubscriptions(): boolean;
+    /**
+     * Get the number of handlers for a specific key
+     */
+    getHandlerCount(key: TKey): number;
+    subscribeOnKey(key: TKey, handler: TOIMEventHandler<void>): () => void;
+    unsubscribeFromKey(key: TKey, handler: TOIMEventHandler<void>): void;
+    subscribeOnKeys(keys: readonly TKey[], handler: TOIMEventHandler<void>): () => void;
+    unsubscribeFromKeys(keys: readonly TKey[], handler: TOIMEventHandler<void>): void;
+}
+
 type TOIMOrderedListCommand<TPk extends TOIMPk, TEntity extends object = object> = {
     type: 'insert';
     pk: TPk;
@@ -1633,4 +1675,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 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, createOIMCollectionIndexFactory, createOIMCollectionKit };