@oimdb/core 1.4.0 → 1.5.0

package/dist/index.d.ts

@@ -1,7 +1,17 @@
 type TOIMPk = string | number;
 
+type TOIMEntitySlot<TEntity extends object, TPk extends TOIMPk> = {
+    pk: TPk;
+    item: TEntity | undefined;
+};
+type TOIMAnyEntitySlot<TPk extends TOIMPk> = TOIMEntitySlot<object, TPk>;
+type TOIMEntitySlotResolver<TPk extends TOIMPk> = (pk: TPk) => TOIMAnyEntitySlot<TPk> | undefined;
+
 declare abstract class OIMCollectionStore<TEntity extends object, TPk extends TOIMPk> {
     abstract setOneByPk(pk: TPk, entity: TEntity): void;
+    abstract getSlotByPk(pk: TPk): TOIMEntitySlot<TEntity, TPk> | undefined;
+    abstract getSlotsByPks(pks: readonly TPk[]): TOIMEntitySlot<TEntity, TPk>[];
+    abstract getAllSlots(): TOIMEntitySlot<TEntity, TPk>[];
     abstract removeOneByPk(pk: TPk): void;
     abstract removeManyByPks(pks: readonly TPk[]): void;
     abstract getOneByPk(pk: TPk): TEntity | undefined;
@@ -14,25 +24,25 @@ declare abstract class OIMCollectionStore<TEntity extends object, TPk extends TO
 }
 
 declare abstract class OIMIndexStoreSetBased<TKey extends TOIMPk, TPk extends TOIMPk> {
-    abstract setOneByKey(key: TKey, pks: Set<TPk>): void;
+    abstract setOneByKey(key: TKey, slots: Set<TOIMAnyEntitySlot<TPk>>): void;
     abstract removeOneByKey(key: TKey): void;
     abstract removeManyByKeys(keys: readonly TKey[]): void;
-    abstract getOneByKey(key: TKey): Set<TPk> | undefined;
-    abstract getManyByKeys(keys: readonly TKey[]): Map<TKey, Set<TPk>>;
+    abstract getOneByKey(key: TKey): Set<TOIMAnyEntitySlot<TPk>> | undefined;
+    abstract getManyByKeys(keys: readonly TKey[]): Map<TKey, Set<TOIMAnyEntitySlot<TPk>>>;
     abstract getAllKeys(): TKey[];
-    abstract getAll(): Map<TKey, Set<TPk>>;
+    abstract getAll(): Map<TKey, Set<TOIMAnyEntitySlot<TPk>>>;
     abstract countAll(): number;
     abstract clear(): void;
 }
 
 declare abstract class OIMIndexStoreArrayBased<TKey extends TOIMPk, TPk extends TOIMPk> {
-    abstract setOneByKey(key: TKey, pks: TPk[]): void;
+    abstract setOneByKey(key: TKey, slots: TOIMAnyEntitySlot<TPk>[]): void;
     abstract removeOneByKey(key: TKey): void;
     abstract removeManyByKeys(keys: readonly TKey[]): void;
-    abstract getOneByKey(key: TKey): TPk[] | undefined;
-    abstract getManyByKeys(keys: readonly TKey[]): Map<TKey, TPk[]>;
+    abstract getOneByKey(key: TKey): TOIMAnyEntitySlot<TPk>[] | undefined;
+    abstract getManyByKeys(keys: readonly TKey[]): Map<TKey, TOIMAnyEntitySlot<TPk>[]>;
     abstract getAllKeys(): TKey[];
-    abstract getAll(): Map<TKey, TPk[]>;
+    abstract getAll(): Map<TKey, TOIMAnyEntitySlot<TPk>[]>;
     abstract countAll(): number;
     abstract clear(): void;
 }
@@ -41,6 +51,7 @@ type TOIMEventHandler<T> = (payload: T) => void;
 
 declare class OIMEventEmitter<T extends Record<string, unknown>> {
     private buckets;
+    hasHandlers<K extends keyof T>(event: K): boolean;
     private getOrCreateBucket;
     /**
      * Compacts the handlers array by removing null entries (tombstones) left by handler removal.
@@ -98,17 +109,21 @@ type TOIMIndexComparator<TPk extends TOIMPk> = (existingPks: readonly TPk[], new
 declare abstract class OIMIndexSetBased<TKey extends TOIMPk, TPk extends TOIMPk> {
     protected readonly comparePks?: TOIMIndexComparator<TPk>;
     protected readonly store: OIMIndexStoreSetBased<TKey, TPk>;
+    protected resolveSlot?: TOIMEntitySlotResolver<TPk>;
+    private readonly fallbackSlots;
     readonly emitter: OIMEventEmitter<{
         0: TOIMIndexUpdatePayload<TKey>;
     }>;
     constructor(options?: {
         comparePks?: TOIMIndexComparator<TPk>;
         store?: OIMIndexStoreSetBased<TKey, TPk>;
+        resolveSlot?: TOIMEntitySlotResolver<TPk>;
     });
     /**
      * Get primary keys for multiple index keys
      */
     getPksByKeys(keys: readonly TKey[]): Map<TKey, Set<TPk>>;
+    setSlotResolver(resolveSlot: TOIMEntitySlotResolver<TPk>): void;
     /**
      * @deprecated Use getPksByKey instead
      * Get primary keys for a specific index key
@@ -118,6 +133,8 @@ declare abstract class OIMIndexSetBased<TKey extends TOIMPk, TPk extends TOIMPk>
      * Get primary keys for a specific index key
      */
     getPksByKey(key: TKey): Set<TPk>;
+    getSlotsByKey(key: TKey): ReadonlySet<TOIMAnyEntitySlot<TPk>>;
+    getSlotsByKeys(keys: readonly TKey[]): Map<TKey, ReadonlySet<TOIMAnyEntitySlot<TPk>>>;
     /**
      * Check if an index key exists
      */
@@ -157,10 +174,18 @@ declare abstract class OIMIndexSetBased<TKey extends TOIMPk, TPk extends TOIMPk>
      * If comparator is provided and returns true (no changes), skip the update.
      */
     protected setPksWithComparison(key: TKey, newPks: Set<TPk>): boolean;
+    protected setSlotsWithComparison(key: TKey, newSlots: Set<TOIMAnyEntitySlot<TPk>>): boolean;
+    protected resolveSlots(pks: Iterable<TPk>): Set<TOIMAnyEntitySlot<TPk>>;
+    protected getOrCreateSlot(pk: TPk): TOIMAnyEntitySlot<TPk>;
+    protected slotsToPks(slots: Iterable<TOIMAnyEntitySlot<TPk>>): Set<TPk>;
     /**
      * Emit update event with changed keys
      */
     protected emitUpdate(keys: TKey[]): void;
+    /**
+     * Emit update event for a single key (fast-path override point).
+     */
+    protected emitUpdateOne(key: TKey): void;
 }
 
 /**
@@ -170,21 +195,27 @@ declare abstract class OIMIndexSetBased<TKey extends TOIMPk, TPk extends TOIMPk>
 declare abstract class OIMIndexArrayBased<TKey extends TOIMPk, TPk extends TOIMPk> {
     protected readonly comparePks?: TOIMIndexComparator<TPk>;
     protected readonly store: OIMIndexStoreArrayBased<TKey, TPk>;
+    protected resolveSlot?: TOIMEntitySlotResolver<TPk>;
+    private readonly fallbackSlots;
     readonly emitter: OIMEventEmitter<{
         0: TOIMIndexUpdatePayload<TKey>;
     }>;
     constructor(options?: {
         comparePks?: TOIMIndexComparator<TPk>;
         store?: OIMIndexStoreArrayBased<TKey, TPk>;
+        resolveSlot?: TOIMEntitySlotResolver<TPk>;
     });
     /**
      * Get primary keys for multiple index keys
      */
     getPksByKeys(keys: readonly TKey[]): Map<TKey, TPk[]>;
+    setSlotResolver(resolveSlot: TOIMEntitySlotResolver<TPk>): void;
     /**
      * Get primary keys for a specific index key
      */
     getPksByKey(key: TKey): TPk[];
+    getSlotsByKey(key: TKey): readonly TOIMAnyEntitySlot<TPk>[];
+    getSlotsByKeys(keys: readonly TKey[]): Map<TKey, readonly TOIMAnyEntitySlot<TPk>[]>;
     /**
      * Check if an index key exists
      */
@@ -224,87 +255,18 @@ declare abstract class OIMIndexArrayBased<TKey extends TOIMPk, TPk extends TOIMP
      * If comparator is provided and returns true (no changes), skip the update.
      */
     protected setPksWithComparison(key: TKey, newPks: TPk[]): boolean;
+    protected setSlotsWithComparison(key: TKey, newSlots: TOIMAnyEntitySlot<TPk>[]): boolean;
+    protected resolveSlots(pks: readonly TPk[]): TOIMAnyEntitySlot<TPk>[];
+    protected getOrCreateSlot(pk: TPk): TOIMAnyEntitySlot<TPk>;
+    protected slotsToPks(slots: readonly TOIMAnyEntitySlot<TPk>[]): TPk[];
     /**
      * Emit update event with changed keys
      */
     protected emitUpdate(keys: TKey[]): void;
-}
-
-/**
- * Manual Set-based index that allows direct manipulation of key-to-primary-keys mappings.
- * Extends the abstract OIMIndexSetBased with manual control methods and optional comparison.
- */
-declare class OIMIndexManualSetBased<TIndexKey extends TOIMPk, TPk extends TOIMPk> extends OIMIndexSetBased<TIndexKey, TPk> {
-    constructor(options?: {
-        comparePks?: TOIMIndexComparator<TPk>;
-        store?: OIMIndexStoreSetBased<TIndexKey, TPk>;
-    });
-    /**
-     * Set primary keys for a specific index key, replacing any existing values.
-     * Uses optional comparator to skip updates if PKs haven't actually changed.
-     */
-    setPks(key: TIndexKey, pks: TPk[]): void;
-    /**
-     * Add primary keys to a specific index key
-     */
-    addPks(key: TIndexKey, pks: readonly TPk[]): void;
     /**
-     * Remove primary keys from a specific index key
-     */
-    removePks(key: TIndexKey, pks: readonly TPk[]): void;
-    /**
-     * Clear all primary keys for a specific index key, or all keys if no key specified
+     * Emit update event for a single key (fast-path override point).
      */
-    clear(key?: TIndexKey): void;
-}
-
-/**
- * Static class containing OIMDB settings and constants.
- * Provides access to configuration values used throughout the library.
- */
-declare class OIMDBSettings {
-    /**
-     * Fixed key used in the manual index to store updated keys set in coalescers.
-     * This constant is exported so users can create their own indexes and pass them to coalescers.
-     */
-    static readonly UPDATED_KEYS_INDEX_KEY: "__updatedKeys__";
-    static readonly FLUSHING_KEYS_INDEX_KEY: "__flushingKeys__";
-}
-
-/**
- * Base abstract coalescer that groups updates by keys and emits consolidated events.
- * Designed to be extended for different entity types (collections, indexes, etc.).
- * Uses SetBased indexes for efficient key tracking.
- */
-declare abstract class OIMUpdateEventCoalescer<TKey extends TOIMPk> {
-    readonly emitter: OIMEventEmitter<{
-        0: void;
-        1: void;
-        2: void;
-    }>;
-    protected readonly updatedKeysIndex: OIMIndexManualSetBased<typeof OIMDBSettings.UPDATED_KEYS_INDEX_KEY, TKey>;
-    protected readonly flushingUpdatedKeysIndex: OIMIndexManualSetBased<typeof OIMDBSettings.FLUSHING_KEYS_INDEX_KEY, TKey>;
-    private hasEmittedChanges;
-    constructor(index?: OIMIndexManualSetBased<typeof OIMDBSettings.UPDATED_KEYS_INDEX_KEY, TKey>, flushingIndex?: OIMIndexManualSetBased<typeof OIMDBSettings.FLUSHING_KEYS_INDEX_KEY, TKey>);
-    /**
-     * Get the set of keys that have been updated since last clear
-     */
-    getUpdatedKeys(): Set<TKey>;
-    getFlushingUpdatedKeys(): Set<TKey>;
-    markUpdatedKeysAsFlushing(): void;
-    /**
-     * Clear all updated keys and reset the changed state
-     */
-    clearUpdatedKeys(): void;
-    clearFlushingUpdatedKeys(): void;
-    /**
-     * Add keys to the updated set and emit HAS_CHANGES event if needed
-     */
-    protected addUpdatedKeys(keys: readonly TKey[]): void;
-    /**
-     * Clean up event listeners when coalescer is no longer needed
-     */
-    abstract destroy(): void;
+    protected emitUpdateOne(key: TKey): void;
 }
 
 /**
@@ -329,20 +291,26 @@ declare enum EOIMEventQueueEventType {
  */
 declare class OIMEventQueue {
     readonly emitter: OIMEventEmitter<Record<EOIMEventQueueEventType, void>>;
-    protected queue: (() => void)[];
+    protected tasks: Set<() => void>;
     protected readonly scheduler?: OIMEventQueueScheduler;
     protected flushBound?: () => void;
     protected isFlushing: boolean;
-    protected pendingSchedule: boolean;
     constructor(options?: TOIMEventQueueOptions);
     /**
-     * Add a function to the queue. If scheduler is configured and autoSchedule is enabled,
-     * automatically schedules a flush operation.
+     * 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(fn: () => void): () => void;
+    get isInFlush(): boolean;
+    /**
+     * Dequeue (cancel) a previously enqueued task by its dequeue function.
      */
-    enqueue(fn: () => void): void;
+    dequeue(dequeueFn: () => void): void;
     /**
-     * Execute all queued functions and clear the queue.
-     * This method is safe to call multiple times and handles reentrancy.
+     * Execute all pending tasks.
+     *
+     * This flush drains until the queue is empty. If tasks enqueue more tasks, they will be
+     * executed within the same flush.
      */
     flush(): void;
     /**
@@ -357,41 +325,44 @@ declare class OIMEventQueue {
      * Clear the queue without executing functions and cancel any scheduled flush.
      */
     clear(): void;
+    protected ensureScheduled(): void;
     /**
      * Clean up scheduler subscription when queue is no longer needed.
      */
     destroy(): void;
 }
 
-/**
- * Options for creating an update event emitter */
-type TOIMUpdateEventEmitterOptions<TKey extends TOIMPk> = {
-    coalescer: OIMUpdateEventCoalescer<TKey>;
-    queue: OIMEventQueue;
-};
-
+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 keyHandlersBeforeFlush: Map<TKey, Set<TOIMEventHandler<void>>>;
     protected keyHandlers: Map<TKey, Set<TOIMEventHandler<void>>>;
-    protected coalescer: OIMUpdateEventCoalescer<TKey>;
     protected queue: OIMEventQueue;
-    private isDestroyed;
-    private isDispatching;
-    private isInPrePhase;
-    private hasPendingDuringPrePhase;
+    private readonly deliveryMode;
     private isFlushEnqueued;
-    constructor(opts: TOIMUpdateEventEmitterOptions<TKey>);
-    protected handleHasChanges: () => void;
+    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;
+    private readonly onAfterFlush;
     /**
-     * Helps to run computed values etc.
+     * Deliver updated keys and notify handlers once.
+     * Re-entrant updates during delivery are forbidden and will throw in markUpdatedKeys().
      */
-    protected runPrePhaseDrain(makeHandlerSnapshot: (handlers: Set<TOIMEventHandler<void>>) => TOIMEventHandler<void>[]): Set<TKey>;
-    protected runHandlersPhase(allKeysForNormalPhase: ReadonlySet<TKey>, makeHandlerSnapshot: (handlers: Set<TOIMEventHandler<void>>) => TOIMEventHandler<void>[]): void;
+    protected runSinglePass(makeHandlerSnapshot: (handlers: Set<TOIMEventHandler<void>>) => TOIMEventHandler<void>[]): void;
     destroy(): void;
     /**
      * Get performance metrics for monitoring and debugging
@@ -410,46 +381,25 @@ declare class OIMUpdateEventEmitter<TKey extends TOIMPk> {
      * Get the number of handlers for a specific key
      */
     getHandlerCount(key: TKey): number;
-    subscribeOnKeyBeforeFlush(key: TKey, handler: TOIMEventHandler<void>): () => void;
-    unsubscribeFromKeyBeforeFlush(key: TKey, handler: TOIMEventHandler<void>): void;
     subscribeOnKey(key: TKey, handler: TOIMEventHandler<void>): () => void;
     unsubscribeFromKey(key: TKey, handler: TOIMEventHandler<void>): void;
     subscribeOnKeys(keys: readonly TKey[], handler: TOIMEventHandler<void>): () => void;
-    subscribeOnKeysBeforeFlush(keys: readonly TKey[], handler: TOIMEventHandler<void>): () => void;
-    unsubscribeFromKeysBeforeFlush(keys: readonly TKey[], handler: TOIMEventHandler<void>): void;
     unsubscribeFromKeys(keys: readonly TKey[], handler: TOIMEventHandler<void>): void;
 }
 
-declare enum EOIMIndexEventType {
-    UPDATE = 0
-}
-
-/**
- * Index-specific coalescer that tracks index key updates and emits consolidated change events.
- * Takes an event emitter directly instead of the whole index to avoid circular dependencies.
- */
-declare class OIMUpdateEventCoalescerIndex<TIndexKey extends TOIMPk> extends OIMUpdateEventCoalescer<TIndexKey> {
-    private readonly indexEmitter;
-    constructor(indexEmitter: OIMEventEmitter<{
-        [EOIMIndexEventType.UPDATE]: TOIMIndexUpdatePayload<TIndexKey>;
-    }>);
-    destroy(): void;
-    /**
-     * When the index is updated, we keep track of the updated keys.
-     */
-    private handleUpdate;
+interface IOIMKeyedSubscription<TKey extends TOIMPk> {
+    subscribeOnKey(key: TKey, handler: TOIMEventHandler<void>): () => void;
+    subscribeOnKeys(keys: readonly TKey[], handler: TOIMEventHandler<void>): () => void;
 }
 
-declare abstract class OIMReactiveIndexSetBased<TKey extends TOIMPk, TPk extends TOIMPk, TIndex extends OIMIndexSetBased<TKey, TPk>> {
+declare abstract class OIMReactiveIndexSetBased<TKey extends TOIMPk, TPk extends TOIMPk, TIndex extends OIMIndexSetBased<TKey, TPk>> implements IOIMKeyedSubscription<TKey> {
     readonly index: TIndex;
-    readonly updateEventEmitter: OIMUpdateEventEmitter<TKey>;
-    readonly coalescer: OIMUpdateEventCoalescerIndex<TKey>;
-    constructor(queue: OIMEventQueue, opts?: {
-        index: TIndex;
-    });
-    protected abstract createDefaultIndex(): TIndex;
+    protected readonly updateEmitter: OIMUpdateEventEmitter<TKey>;
+    constructor(queue: OIMEventQueue, createIndex: (updateEmitter: OIMUpdateEventEmitter<TKey>) => TIndex);
     getPksByKey(key: TKey): Set<TPk>;
     getPksByKeys(keys: readonly TKey[]): Map<TKey, Set<TPk>>;
+    getSlotsByKey(key: TKey): ReadonlySet<TOIMAnyEntitySlot<TPk>>;
+    getSlotsByKeys(keys: readonly TKey[]): Map<TKey, ReadonlySet<TOIMAnyEntitySlot<TPk>>>;
     hasKey(key: TKey): boolean;
     getKeys(): readonly TKey[];
     getKeySize(key: TKey): number;
@@ -462,19 +412,29 @@ declare abstract class OIMReactiveIndexSetBased<TKey extends TOIMPk, TPk extends
         maxBucketSize: number;
         minBucketSize: number;
     };
+    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;
+    hasSubscriptions(): boolean;
+    getHandlerCount(key: TKey): number;
+    getSubscriptionMetrics(): {
+        totalKeys: number;
+        totalHandlers: number;
+        averageHandlersPerKey: number;
+        queueLength: number;
+    };
     destroy(): void;
 }
 
-declare abstract class OIMReactiveIndexArrayBased<TKey extends TOIMPk, TPk extends TOIMPk, TIndex extends OIMIndexArrayBased<TKey, TPk>> {
+declare abstract class OIMReactiveIndexArrayBased<TKey extends TOIMPk, TPk extends TOIMPk, TIndex extends OIMIndexArrayBased<TKey, TPk>> implements IOIMKeyedSubscription<TKey> {
     readonly index: TIndex;
-    readonly updateEventEmitter: OIMUpdateEventEmitter<TKey>;
-    readonly coalescer: OIMUpdateEventCoalescerIndex<TKey>;
-    constructor(queue: OIMEventQueue, opts?: {
-        index: TIndex;
-    });
-    protected abstract createDefaultIndex(): TIndex;
+    protected readonly updateEmitter: OIMUpdateEventEmitter<TKey>;
+    constructor(queue: OIMEventQueue, createIndex: (updateEmitter: OIMUpdateEventEmitter<TKey>) => TIndex);
     getPksByKey(key: TKey): TPk[];
     getPksByKeys(keys: readonly TKey[]): Map<TKey, TPk[]>;
+    getSlotsByKey(key: TKey): readonly TOIMAnyEntitySlot<TPk>[];
+    getSlotsByKeys(keys: readonly TKey[]): Map<TKey, readonly TOIMAnyEntitySlot<TPk>[]>;
     hasKey(key: TKey): boolean;
     getKeys(): readonly TKey[];
     getKeySize(key: TKey): number;
@@ -487,6 +447,18 @@ declare abstract class OIMReactiveIndexArrayBased<TKey extends TOIMPk, TPk exten
         maxBucketSize: number;
         minBucketSize: number;
     };
+    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;
+    hasSubscriptions(): boolean;
+    getHandlerCount(key: TKey): number;
+    getSubscriptionMetrics(): {
+        totalKeys: number;
+        totalHandlers: number;
+        averageHandlersPerKey: number;
+        queueLength: number;
+    };
     destroy(): void;
 }
 
@@ -523,12 +495,15 @@ declare class OIMCollection<TEntity extends object, TPk extends TOIMPk> {
     readonly emitter: OIMEventEmitter<{
         0: TOIMCollectionUpdatePayload<TPk>;
     }>;
-    protected readonly selectPk: TOIMPkSelector<TEntity, TPk>;
+    readonly selectPk: TOIMPkSelector<TEntity, TPk>;
     protected readonly store: OIMCollectionStore<TEntity, TPk>;
     protected readonly updateEntity: TOIMEntityUpdater<TEntity>;
     constructor(opts?: TOIMCollectionOptions<TEntity, TPk>);
     getOneByPk(pk: TPk): TEntity | undefined;
     getManyByPks(pks: readonly TPk[]): TEntity[];
+    getSlotByPk(pk: TPk): TOIMEntitySlot<TEntity, TPk> | undefined;
+    getSlotsByPks(pks: readonly TPk[]): TOIMEntitySlot<TEntity, TPk>[];
+    getAllSlots(): TOIMEntitySlot<TEntity, TPk>[];
     upsertOneByPk(pk: TPk, entity: Partial<TEntity>): void;
     upsertOne(entity: TEntity | Partial<TEntity>): void;
     upsertMany(entities: (TEntity | Partial<TEntity>)[]): void;
@@ -545,30 +520,42 @@ declare class OIMCollection<TEntity extends object, TPk extends TOIMPk> {
     destroy(): void;
 }
 
-declare enum EOIMCollectionEventType {
-    UPDATE = 0
-}
-
-/**
- * Collection-specific coalescer that tracks primary key updates and emits consolidated change events.
- * Takes an event emitter directly instead of the whole collection to avoid circular dependencies.
- */
-declare class OIMUpdateEventCoalescerCollection<TPk extends TOIMPk> extends OIMUpdateEventCoalescer<TPk> {
-    private readonly collectionEmitter;
-    constructor(collectionEmitter: OIMEventEmitter<{
-        [EOIMCollectionEventType.UPDATE]: TOIMCollectionUpdatePayload<TPk>;
-    }>);
-    destroy(): void;
-    /**
-     * When the collection is updated, we keep track of the updated pks.
-     */
-    private handleUpdate;
-}
-
-declare class OIMReactiveCollection<TEntity extends object, TPk extends TOIMPk> extends OIMCollection<TEntity, TPk> {
-    readonly updateEventEmitter: OIMUpdateEventEmitter<TPk>;
-    readonly coalescer: OIMUpdateEventCoalescerCollection<TPk>;
+declare class OIMReactiveCollection<TEntity extends object, TPk extends TOIMPk> extends OIMCollection<TEntity, TPk> implements IOIMKeyedSubscription<TPk> {
+    private readonly queue;
+    protected readonly updateEmitter: OIMUpdateEventEmitter<TPk>;
+    private readonly anyUpdateHandlers;
+    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;
+    unsubscribeFromKey(pk: TPk, handler: TOIMEventHandler<void>): void;
+    unsubscribeFromKeys(pks: readonly TPk[], handler: TOIMEventHandler<void>): void;
+    destroySubscriptions(): void;
+    hasSubscriptions(): boolean;
+    getHandlerCount(pk: TPk): number;
+    getMetrics(): {
+        totalKeys: number;
+        totalHandlers: number;
+        averageHandlersPerKey: number;
+        queueLength: number;
+    };
+    subscribeOnAnyUpdate(handler: (pks: readonly TPk[]) => void): () => void;
+    upsertOneByPk(pk: TPk, entity: Partial<TEntity>): void;
+    upsertOne(entity: TEntity | Partial<TEntity>): void;
+    upsertMany(entities: (TEntity | Partial<TEntity>)[]): void;
+    removeOne(entity: TEntity): void;
+    removeMany(entities: TEntity[]): void;
+    removeOneByPk(pk: TPk): void;
+    removeManyByPks(pks: readonly TPk[]): void;
+    clear(): void;
+    private trackAnyUpdatePk;
+    private trackAnyUpdatePks;
+    private trackAnyUpdateClear;
+    private ensureAnyUpdateEnqueued;
+    private readonly runAnyUpdate;
     destroy(): void;
 }
 
@@ -602,39 +589,64 @@ declare class OIMObject<TKey extends string, TValue> {
     destroy(): void;
 }
 
-declare enum EOIMObjectEventType {
-    UPDATE = 0
+declare class OIMReactiveObject<TKey extends string, TValue> extends OIMObject<TKey, TValue> implements IOIMKeyedSubscription<TKey> {
+    protected readonly updateEmitter: OIMUpdateEventEmitter<TKey>;
+    constructor(queue: OIMEventQueue, opts?: TOIMObjectOptions<TKey, TValue>);
+    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;
+    hasSubscriptions(): boolean;
+    getHandlerCount(key: TKey): number;
+    getMetrics(): {
+        totalKeys: number;
+        totalHandlers: number;
+        averageHandlersPerKey: number;
+        queueLength: number;
+    };
+    destroy(): void;
 }
 
 /**
- * Object-specific coalescer that tracks property key updates and emits consolidated change events.
- * Takes an event emitter directly instead of the whole object to avoid circular dependencies.
+ * Manual Set-based index that allows direct manipulation of key-to-primary-keys mappings.
+ * Extends the abstract OIMIndexSetBased with manual control methods and optional comparison.
  */
-declare class OIMUpdateEventCoalescerObject<TKey extends string> extends OIMUpdateEventCoalescer<TKey> {
-    private readonly objectEmitter;
-    constructor(objectEmitter: OIMEventEmitter<{
-        [EOIMObjectEventType.UPDATE]: TOIMUpdatePayload<TKey>;
-    }>);
-    destroy(): void;
+declare class OIMIndexManualSetBased<TIndexKey extends TOIMPk, TPk extends TOIMPk> extends OIMIndexSetBased<TIndexKey, TPk> {
+    constructor(options?: {
+        comparePks?: TOIMIndexComparator<TPk>;
+        store?: OIMIndexStoreSetBased<TIndexKey, TPk>;
+        resolveSlot?: TOIMEntitySlotResolver<TPk>;
+    });
     /**
-     * When the object is updated, we keep track of the updated keys.
+     * Set primary keys for a specific index key, replacing any existing values.
+     * Uses optional comparator to skip updates if PKs haven't actually changed.
      */
-    private handleUpdate;
-}
-
-declare class OIMReactiveObject<TKey extends string, TValue> extends OIMObject<TKey, TValue> {
-    readonly updateEventEmitter: OIMUpdateEventEmitter<TKey>;
-    readonly coalescer: OIMUpdateEventCoalescerObject<TKey>;
-    constructor(queue: OIMEventQueue, opts?: TOIMObjectOptions<TKey, TValue>);
-    destroy(): void;
+    setPks(key: TIndexKey, pks: TPk[]): void;
+    setSlots(key: TIndexKey, slots: Iterable<TOIMAnyEntitySlot<TPk>>): void;
+    /**
+     * Add primary keys to a specific index key
+     */
+    addPks(key: TIndexKey, pks: readonly TPk[]): void;
+    /**
+     * Remove primary keys from a specific index key
+     */
+    removePks(key: TIndexKey, pks: readonly TPk[]): void;
+    /**
+     * Clear all primary keys for a specific index key, or all keys if no key specified
+     */
+    clear(key?: TIndexKey): void;
 }
 
 declare class OIMReactiveIndexManualSetBased<TKey extends TOIMPk, TPk extends TOIMPk> extends OIMReactiveIndexSetBased<TKey, TPk, OIMIndexManualSetBased<TKey, TPk>> {
     constructor(queue: OIMEventQueue, opts?: {
-        index: OIMIndexManualSetBased<TKey, TPk>;
+        indexOptions?: {
+            comparePks?: TOIMIndexComparator<TPk>;
+            store?: OIMIndexStoreSetBased<TKey, TPk>;
+            resolveSlot?: TOIMEntitySlotResolver<TPk>;
+        };
     });
-    protected createDefaultIndex(): OIMIndexManualSetBased<TKey, TPk>;
     setPks(key: TKey, pks: TPk[]): void;
+    setSlots(key: TKey, slots: Iterable<TOIMAnyEntitySlot<TPk>>): void;
     addPks(key: TKey, pks: readonly TPk[]): void;
     removePks(key: TKey, pks: readonly TPk[]): void;
     clear(key?: TKey): void;
@@ -648,12 +660,14 @@ declare class OIMIndexManualArrayBased<TIndexKey extends TOIMPk, TPk extends TOI
     constructor(options?: {
         comparePks?: TOIMIndexComparator<TPk>;
         store?: OIMIndexStoreArrayBased<TIndexKey, TPk>;
+        resolveSlot?: TOIMEntitySlotResolver<TPk>;
     });
     /**
      * Set primary keys for a specific index key, replacing any existing values.
      * Uses optional comparator to skip updates if PKs haven't actually changed.
      */
     setPks(key: TIndexKey, pks: TPk[]): void;
+    setSlots(key: TIndexKey, slots: TOIMAnyEntitySlot<TPk>[]): void;
     /**
      * Add primary keys to a specific index key
      */
@@ -670,10 +684,14 @@ declare class OIMIndexManualArrayBased<TIndexKey extends TOIMPk, TPk extends TOI
 
 declare class OIMReactiveIndexManualArrayBased<TKey extends TOIMPk, TPk extends TOIMPk> extends OIMReactiveIndexArrayBased<TKey, TPk, OIMIndexManualArrayBased<TKey, TPk>> {
     constructor(queue: OIMEventQueue, opts?: {
-        index: OIMIndexManualArrayBased<TKey, TPk>;
+        indexOptions?: {
+            comparePks?: TOIMIndexComparator<TPk>;
+            store?: OIMIndexStoreArrayBased<TKey, TPk>;
+            resolveSlot?: TOIMEntitySlotResolver<TPk>;
+        };
     });
-    protected createDefaultIndex(): OIMIndexManualArrayBased<TKey, TPk>;
     setPks(key: TKey, pks: TPk[]): void;
+    setSlots(key: TKey, slots: TOIMAnyEntitySlot<TPk>[]): void;
     addPks(key: TKey, pks: readonly TPk[]): void;
     removePks(key: TKey, pks: readonly TPk[]): void;
     clear(key?: TKey): void;
@@ -689,9 +707,12 @@ declare class OIMRICollection<TEntity extends object, TPk extends TOIMPk, TIndex
 }
 
 declare class OIMCollectionStoreMapDriven<TEntity extends object, TPk extends TOIMPk> extends OIMCollectionStore<TEntity, TPk> {
-    protected readonly entities: Map<TPk, TEntity>;
+    protected readonly slots: Map<TPk, TOIMEntitySlot<TEntity, TPk>>;
     setOneByPk(pk: TPk, entity: TEntity): void;
     setManyByPks(pks: readonly TPk[], entities: TEntity[]): void;
+    getSlotByPk(pk: TPk): TOIMEntitySlot<TEntity, TPk> | undefined;
+    getSlotsByPks(pks: readonly TPk[]): TOIMEntitySlot<TEntity, TPk>[];
+    getAllSlots(): TOIMEntitySlot<TEntity, TPk>[];
     removeOneByPk(pk: TPk): void;
     removeManyByPks(pks: readonly TPk[]): void;
     getOneByPk(pk: TPk): TEntity | undefined;
@@ -741,27 +762,27 @@ declare class OIMObjectStoreRecordDriven<TKey extends string, TValue> extends OI
 }
 
 declare class OIMIndexStoreMapDrivenSetBased<TKey extends TOIMPk, TPk extends TOIMPk> extends OIMIndexStoreSetBased<TKey, TPk> {
-    protected readonly pks: Map<TKey, Set<TPk>>;
-    setOneByKey(key: TKey, pks: Set<TPk>): void;
+    protected readonly slots: Map<TKey, Set<TOIMAnyEntitySlot<TPk>>>;
+    setOneByKey(key: TKey, slots: Set<TOIMAnyEntitySlot<TPk>>): void;
     removeOneByKey(key: TKey): void;
     removeManyByKeys(keys: readonly TKey[]): void;
-    getOneByKey(key: TKey): Set<TPk> | undefined;
-    getManyByKeys(keys: readonly TKey[]): Map<TKey, Set<TPk>>;
+    getOneByKey(key: TKey): Set<TOIMAnyEntitySlot<TPk>> | undefined;
+    getManyByKeys(keys: readonly TKey[]): Map<TKey, Set<TOIMAnyEntitySlot<TPk>>>;
     getAllKeys(): TKey[];
-    getAll(): Map<TKey, Set<TPk>>;
+    getAll(): Map<TKey, Set<TOIMAnyEntitySlot<TPk>>>;
     countAll(): number;
     clear(): void;
 }
 
 declare class OIMIndexStoreMapDrivenArrayBased<TKey extends TOIMPk, TPk extends TOIMPk> extends OIMIndexStoreArrayBased<TKey, TPk> {
-    protected readonly pks: Map<TKey, TPk[]>;
-    setOneByKey(key: TKey, pks: TPk[]): void;
+    protected readonly slots: Map<TKey, TOIMAnyEntitySlot<TPk>[]>;
+    setOneByKey(key: TKey, slots: TOIMAnyEntitySlot<TPk>[]): void;
     removeOneByKey(key: TKey): void;
     removeManyByKeys(keys: readonly TKey[]): void;
-    getOneByKey(key: TKey): TPk[] | undefined;
-    getManyByKeys(keys: readonly TKey[]): Map<TKey, TPk[]>;
+    getOneByKey(key: TKey): TOIMAnyEntitySlot<TPk>[] | undefined;
+    getManyByKeys(keys: readonly TKey[]): Map<TKey, TOIMAnyEntitySlot<TPk>[]>;
     getAllKeys(): TKey[];
-    getAll(): Map<TKey, TPk[]>;
+    getAll(): Map<TKey, TOIMAnyEntitySlot<TPk>[]>;
     countAll(): number;
     clear(): void;
 }
@@ -820,29 +841,22 @@ declare class OIMPkSelectorFactory<TEntity extends object, TPk extends TOIMPk> {
     }, TPk>;
 }
 
-/**
- * Manual coalescer: you mark keys as updated explicitly.
- *
- * Useful for wrappers that maintain their own "derived" state (e.g. change-sets, command streams)
- * and want to reuse `OIMUpdateEventEmitter` batching/reentrancy semantics without piggybacking
- * on a collection/index/object emitter payload.
- */
-declare class OIMUpdateEventCoalescerManual<TKey extends TOIMPk> extends OIMUpdateEventCoalescer<TKey> {
-    markUpdatedKeys(keys: readonly TKey[]): void;
-    destroy(): void;
-}
-
 type TOIMFieldKey<TEntity extends object> = keyof TEntity & string;
 /**
- * Wrapper around `OIMReactiveCollection` that tracks "changed fields" per entity PK.
+ * Wrapper around `OIMCollection` that tracks "changed fields" per entity PK.
  *
  * Important: to get field-level info, you must perform writes through this wrapper.
- * If you mutate the underlying collection directly, this wrapper will not be able
- * to infer which fields changed (core update payloads carry only PKs).
+ *
+ * DX: if the underlying collection is mutated directly (bypassing this wrapper), we detect it
+ * via collection update events and infer changed fields by diffing the last observed entity snapshot.
  */
 declare class OIMCollectionChangedFieldsWrapper<TEntity extends object, TPk extends TOIMPk> {
-    readonly collection: OIMReactiveCollection<TEntity, TPk>;
+    readonly collection: OIMCollection<TEntity, TPk>;
     private readonly selectPk;
+    private readonly unsubscribeAfterFlush;
+    private readonly unsubscribeFromCollectionEmitter;
+    private isInWrite;
+    private readonly lastEntitySnapshotByPk;
     /**
      * Emits updates scoped by PK. Subscribe, then read state via `getChangedFieldsByPk(...)`
      * or drain via `consumeChangedFieldsByPk(...)`.
@@ -855,9 +869,7 @@ declare class OIMCollectionChangedFieldsWrapper<TEntity extends object, TPk exte
     readonly changedFieldsEventEmitter: OIMUpdateEventEmitter<TOIMFieldKey<TEntity>>;
     private readonly changedFieldsByPk;
     private readonly changedPksByField;
-    private readonly changedPksCoalescer;
-    private readonly changedFieldsCoalescer;
-    constructor(queue: OIMEventQueue, collection: OIMReactiveCollection<TEntity, TPk>, opts?: {
+    constructor(queue: OIMEventQueue, collection: OIMCollection<TEntity, TPk>, opts?: {
         /**
          * Optional PK selector for convenience APIs like `upsertOne(...)`.
          * If not provided, only `upsertOneByPk(...)` should be used.
@@ -873,6 +885,13 @@ declare class OIMCollectionChangedFieldsWrapper<TEntity extends object, TPk exte
     consumeChangedPksByField(field: TOIMFieldKey<TEntity>): Set<TPk>;
     clear(): void;
     destroy(): void;
+    private readonly onAfterFlush;
+    private readonly onCollectionUpdate;
+    private withWrite;
+    private trackExternalMutationByPk;
+    private diffChangedKeys;
+    private updateEntitySnapshot;
+    private trackChangedKeys;
     private trackPatch;
 }
 
@@ -910,7 +929,10 @@ type TOIMOrderedListCommand<TPk extends TOIMPk> = {
     fromIndex: number;
     toIndex: number;
 } | {
-    type: 'reset';
+    /**
+     * Replace the whole list for this key (preferred name).
+     */
+    type: 'set';
     keys: readonly TPk[];
 };
 
@@ -923,11 +945,13 @@ type TOIMOrderedListCommand<TPk extends TOIMPk> = {
  * Notes:
  * - Commands are buffered per key and delivered batched per queue flush.
  * - Order of commands is preserved.
- * - A future optimizer can collapse the command buffer into `reset(...)` if needed.
+ * - A future optimizer can collapse the command buffer into `set(...)` if needed.
  */
 declare class OIMOrderedListIndexCommandStreamWrapper<TKey extends TOIMPk, TItemKey extends TOIMPk> {
     readonly commandsEventEmitter: OIMUpdateEventEmitter<TKey>;
-    private readonly coalescer;
+    private readonly unsubscribeAfterFlush;
+    private readonly unsubscribeFromIndexEmitter;
+    private isInWrite;
     private readonly commandsByKey;
     /** Underlying ordered index (source of truth for the list). */
     readonly index: OIMIndexManualOrderedArrayBased<TKey, TItemKey>;
@@ -938,7 +962,7 @@ declare class OIMOrderedListIndexCommandStreamWrapper<TKey extends TOIMPk, TItem
     push(key: TKey, itemKey: TItemKey): void;
     removeAt(key: TKey, index: number): void;
     move(key: TKey, fromIndex: number, toIndex: number): void;
-    reset(key: TKey, keys: readonly TItemKey[]): void;
+    set(key: TKey, keys: readonly TItemKey[]): void;
     /**
      * Read-only peek at buffered commands without clearing them.
      */
@@ -950,6 +974,9 @@ declare class OIMOrderedListIndexCommandStreamWrapper<TKey extends TOIMPk, TItem
     consumeCommands(key: TKey): TOIMOrderedListCommand<TItemKey>[];
     clear(key?: TKey): void;
     destroy(): void;
+    private readonly onAfterFlush;
+    private readonly onIndexUpdate;
+    private withWrite;
     private appendCommand;
 }
 
@@ -1050,21 +1077,16 @@ declare class OIMEventQueueSchedulerFactory {
     static createImmediate(): OIMEventQueueSchedulerImmediate;
 }
 
-/**
- * Event types for update coalescers */
-declare enum EOIMUpdateEventCoalescerEventType {
-    /**
-     * @description Emitted when there are any first changes to the updated keys
-     */
-    HAS_CHANGES = 0,
-    /**
-     * @description Emitted before the flush of the updated keys
-     */
-    BEFORE_FLUSH = 1,
-    /**
-     * @description Emitted after the flush of the updated keys
-     */
-    AFTER_FLUSH = 2
+declare enum EOIMCollectionEventType {
+    UPDATE = 0
+}
+
+declare enum EOIMIndexEventType {
+    UPDATE = 0
+}
+
+declare enum EOIMObjectEventType {
+    UPDATE = 0
 }
 
 type TOIMIndexKey = string | number | bigint;
@@ -1074,12 +1096,14 @@ type TOIMIndexKey = string | number | bigint;
 type TOIMIndexOptionsSetBased<TIndexKey extends TOIMPk, TPk extends TOIMPk> = {
     comparePks?: TOIMIndexComparator<TPk>;
     store?: OIMIndexStoreSetBased<TIndexKey, TPk>;
+    resolveSlot?: TOIMEntitySlotResolver<TPk>;
 };
 /**
  * Configuration options for Array-based index instances */
 type TOIMIndexOptionsArrayBased<TIndexKey extends TOIMPk, TPk extends TOIMPk> = {
     comparePks?: TOIMIndexComparator<TPk>;
     store?: OIMIndexStoreArrayBased<TIndexKey, TPk>;
+    resolveSlot?: TOIMEntitySlotResolver<TPk>;
 };
 /**
  * @deprecated Use TOIMIndexOptionsSetBased or TOIMIndexOptionsArrayBased instead
@@ -1091,13 +1115,21 @@ type TOIMIndexPksUpdatePayload<TKey extends TOIMPk, TPk extends TOIMPk> = {
     pks: readonly TPk[];
 };
 
-declare enum EOIMEffectPhase {
-    PRE = "pre",
-    HANDLERS = "handlers"
+/**
+ * Static class containing OIMDB settings and constants.
+ * Provides access to configuration values used throughout the library.
+ */
+declare class OIMDBSettings {
+    /**
+     * Fixed key used in the manual index to store updated keys set in coalescers.
+     * This constant is exported so users can create their own indexes and pass them to coalescers.
+     */
+    static readonly UPDATED_KEYS_INDEX_KEY: "__updatedKeys__";
+    static readonly FLUSHING_KEYS_INDEX_KEY: "__flushingKeys__";
 }
 
 interface IOIMEffectDependency {
-    subscribe(phase: EOIMEffectPhase, onInvalidate: () => void): () => void;
+    subscribe(onUpdate: () => void): () => void;
 }
 
 type TOIMComputedOptions<TValue> = {
@@ -1110,17 +1142,30 @@ type TOIMComputedUpdatePayload<TKey extends TOIMPk> = {
     keys: readonly TKey[];
 };
 
-declare enum EOIMComputedEventType {
-    UPDATE = "update"
-}
-
-declare class OIMUpdateEventCoalescerComputed<TKey extends TOIMPk> extends OIMUpdateEventCoalescer<TKey> {
-    private readonly computedEmitter;
-    constructor(computedEmitter: OIMEventEmitter<{
-        [EOIMComputedEventType.UPDATE]: TOIMComputedUpdatePayload<TKey>;
-    }>);
-    destroy(): void;
-    private handleUpdate;
+/**
+ * Computative runtime that schedules derived computations by levels and runs them
+ * on `queue.flush()` boundary (AFTER_FLUSH).
+ */
+declare class OIMComputativeRuntime {
+    readonly queue: OIMEventQueue;
+    private isFlushScheduled;
+    private isFlushing;
+    private minLevel;
+    private maxLevel;
+    private readonly dirtyByLevel;
+    private readonly afterFlushTasks;
+    constructor(queue: OIMEventQueue);
+    /**
+     * Schedule a one-shot task to run on the next `queue.flush()` (AFTER_FLUSH),
+     * ordered by `level` ascending.
+     */
+    schedule(task: () => void, level?: number): () => void;
+    /**
+     * Run once at the start of the next runtime flush (i.e. after queue.flush()).
+     * Useful for resubscribing dependencies exactly once per source flush.
+     */
+    scheduleAfterFlush(task: () => void): () => void;
+    private flush;
 }
 
 type TOIMComputedKey$2 = 'value';
@@ -1128,27 +1173,26 @@ declare class OIMComputed<TValue> {
     readonly emitter: OIMEventEmitter<{
         update: TOIMComputedUpdatePayload<TOIMComputedKey$2>;
     }>;
-    readonly coalescer: OIMUpdateEventCoalescerComputed<TOIMComputedKey$2>;
     readonly updateEventEmitter: OIMUpdateEventEmitter<TOIMComputedKey$2>;
-    private readonly queue;
+    private readonly runtime;
     private readonly compute;
     private readonly compare;
     private readonly deps;
     private value;
     private hasValue;
     private isDirty;
-    private isInFlush;
-    private hasRecomputedInThisFlush;
     private readonly effect;
-    private readonly handleQueueBeforeFlush;
-    private readonly handleQueueAfterFlush;
-    constructor(queue: OIMEventQueue, opts: TOIMComputedOptions<TValue>);
+    constructor(runtime: OIMComputativeRuntime, opts: TOIMComputedOptions<TValue>);
     get(): TValue;
     getIfReady(): TValue | undefined;
     destroy(): void;
     private recomputeAndEmitIfChanged;
 }
 
+declare enum EOIMComputedEventType {
+    UPDATE = "update"
+}
+
 type TOIMComputedKey$1 = 'value';
 interface IOIMComputedEventSource {
     emitter: OIMEventEmitter<{
@@ -1158,62 +1202,64 @@ interface IOIMComputedEventSource {
 
 type TOIMEffectOptions = {
     deps?: readonly IOIMEffectDependency[];
-    phase: EOIMEffectPhase;
-    onInvalidate?: () => void;
+    onUpdate?: () => void;
     run: () => void;
 };
 
 declare class OIMEffect {
-    private readonly queue;
-    private readonly phase;
-    private readonly onInvalidate?;
+    private readonly runtime;
+    private readonly onUpdate?;
     private readonly run;
     private readonly deps;
-    private unsubscribers;
-    private isDestroyed;
-    private isInFlush;
-    private hasRunInThisFlush;
+    private readonly sourceDeps;
+    private readonly computedDeps;
+    private sourceUnsubscribers;
+    private computedUnsubscribers;
+    private dequeueResubscribe?;
+    private isResubscribeEnqueued;
+    private isTemporarilyUnsubscribedForFlush;
     private isScheduled;
-    private readonly handleQueueBeforeFlush;
-    private readonly handleQueueAfterFlush;
+    private dequeueScheduled?;
     private readonly runTask;
-    constructor(queue: OIMEventQueue, opts: TOIMEffectOptions);
+    constructor(runtime: OIMComputativeRuntime, opts: TOIMEffectOptions);
     destroy(): void;
-    private invalidate;
+    private onSourceInvalidate;
+    private onComputedInvalidate;
     private runOnce;
+    private subscribeToDeps;
+    private unsubscribeFromSourceDeps;
+    private unsubscribeFromAllDeps;
+    private ensureResubscribeAfterFlush;
+    private readonly onAfterFlush;
 }
 
 declare class OIMEffectDependencyKeyed<TKey extends TOIMPk> implements IOIMEffectDependency {
-    private readonly updateEventEmitter;
+    private readonly subscription;
     private readonly key;
     private readonly keys;
-    constructor(updateEventEmitter: OIMUpdateEventEmitter<TKey>, keyOrKeys: TKey | readonly TKey[]);
-    subscribe(phase: EOIMEffectPhase, onInvalidate: () => void): () => void;
+    constructor(subscription: IOIMKeyedSubscription<TKey>, keyOrKeys: TKey | readonly TKey[]);
+    subscribe(onUpdate: () => void): () => void;
 }
 
 declare class OIMEffectDependencyKeyedObject<TKey extends string, TValue> implements IOIMEffectDependency {
     private readonly dep;
     constructor(object: OIMReactiveObject<TKey, TValue>, key: TKey);
     constructor(object: OIMReactiveObject<TKey, TValue>, keys: readonly TKey[]);
-    subscribe(phase: EOIMEffectPhase, onInvalidate: () => void): () => void;
+    subscribe(onUpdate: () => void): () => void;
 }
 
 declare class OIMEffectDependencyKeyedCollection<TEntity extends object, TPk extends TOIMPk> implements IOIMEffectDependency {
     private readonly dep;
     constructor(collection: OIMReactiveCollection<TEntity, TPk>, pk: TPk);
     constructor(collection: OIMReactiveCollection<TEntity, TPk>, pks: readonly TPk[]);
-    subscribe(phase: EOIMEffectPhase, onInvalidate: () => void): () => void;
+    subscribe(onUpdate: () => void): () => void;
 }
 
 declare class OIMEffectDependencyKeyedIndex<TKey extends TOIMPk> implements IOIMEffectDependency {
     private readonly dep;
-    constructor(index: {
-        updateEventEmitter: OIMUpdateEventEmitter<TKey>;
-    }, key: TKey);
-    constructor(index: {
-        updateEventEmitter: OIMUpdateEventEmitter<TKey>;
-    }, keys: readonly TKey[]);
-    subscribe(phase: EOIMEffectPhase, onInvalidate: () => void): () => void;
+    constructor(index: IOIMKeyedSubscription<TKey>, key: TKey);
+    constructor(index: IOIMKeyedSubscription<TKey>, keys: readonly TKey[]);
+    subscribe(onUpdate: () => void): () => void;
 }
 
 type TOIMComputedKey = 'value';
@@ -1225,14 +1271,132 @@ type TOIMComputedLike = {
 };
 /**
  * Effect dependency on a computed.
- *
- * - PRE: subscribe directly to computed.emitter for immediate invalidation during pre-drain.
- * - HANDLERS: subscribe via computed.updateEventEmitter (normal handlers) which is delivered through queue.
  */
 declare class OIMEffectDependencyComputed implements IOIMEffectDependency {
     private readonly computed;
     constructor(computed: TOIMComputedLike);
-    subscribe(phase: EOIMEffectPhase, onInvalidate: () => void): () => void;
+    subscribe(onUpdate: () => void): () => void;
+}
+
+interface IOIMSelectorComputedDependency {
+    subscribe(onUpdate: () => void): () => void;
+}
+
+interface IOIMSelectorSourceDependency {
+    subscribe(onUpdate: () => void): () => void;
+}
+
+declare abstract class OIMSelector<TValue> {
+    protected readonly runtime: OIMComputativeRuntime;
+    protected readonly sourceDeps: readonly IOIMSelectorSourceDependency[];
+    protected readonly computedDeps: readonly IOIMSelectorComputedDependency[];
+    private readonly listeners;
+    private sourceUnsubscribers;
+    private computedUnsubscribers;
+    private dequeueResubscribe?;
+    private isResubscribeEnqueued;
+    private isTemporarilyUnsubscribedForFlush;
+    private isDeliveryEnqueued;
+    private dequeueDelivery?;
+    private hasLastValue;
+    private lastValue;
+    protected get queue(): OIMEventQueue;
+    protected constructor(runtime: OIMComputativeRuntime, sourceDeps: readonly IOIMSelectorSourceDependency[], computedDeps?: readonly IOIMSelectorComputedDependency[]);
+    abstract getValue(): TValue;
+    /**
+     * Start watching this selector. The callback is called immediately with the current value,
+     * then coalesced and delivered on `queue.flush()` when the selector invalidates.
+     */
+    watch(onValue: (value: TValue) => void): () => void;
+    protected areEqual(prev: TValue, next: TValue): boolean;
+    private readonly onSourceInvalidate;
+    private readonly onComputedInvalidate;
+    private readonly deliver;
+    private setLastValue;
+    private subscribeToDeps;
+    private unsubscribeFromSourceDeps;
+    private unsubscribeFromAllDeps;
+    private ensureResubscribeAfterFlush;
+    private readonly onAfterFlush;
+}
+
+declare class OIMCollectionByPkSelector<TEntity extends object, TPk extends TOIMPk> extends OIMSelector<TEntity | undefined> {
+    private readonly collection;
+    private readonly pk;
+    constructor(runtime: OIMComputativeRuntime, collection: OIMReactiveCollection<TEntity, TPk>, pk: TPk);
+    getValue(): TEntity | undefined;
+}
+
+declare class OIMCollectionByPksSelector<TEntity extends object, TPk extends TOIMPk> extends OIMSelector<readonly (TEntity | undefined)[]> {
+    private readonly collection;
+    private readonly pks;
+    constructor(runtime: OIMComputativeRuntime, collection: OIMReactiveCollection<TEntity, TPk>, pks: readonly TPk[]);
+    getValue(): readonly (TEntity | undefined)[];
+    protected areEqual(prev: readonly (TEntity | undefined)[], next: readonly (TEntity | undefined)[]): boolean;
+}
+
+declare class OIMObjectValueByKeySelector<TKey extends string, TValue> extends OIMSelector<TValue | undefined> {
+    private readonly obj;
+    private readonly key;
+    constructor(runtime: OIMComputativeRuntime, obj: OIMReactiveObject<TKey, TValue>, key: TKey);
+    getValue(): TValue | undefined;
+}
+
+declare class OIMObjectValuesByKeysSelector<TKey extends string, TValue> extends OIMSelector<readonly (TValue | undefined)[]> {
+    private readonly obj;
+    private readonly keys;
+    constructor(runtime: OIMComputativeRuntime, obj: OIMReactiveObject<TKey, TValue>, keys: readonly TKey[]);
+    getValue(): readonly (TValue | undefined)[];
+    protected areEqual(prev: readonly (TValue | undefined)[], next: readonly (TValue | undefined)[]): boolean;
+}
+
+declare class OIMIndexPksByKeySetBasedSelector<TKey extends TOIMPk, TPk extends TOIMPk, TIndex extends OIMIndexSetBased<TKey, TPk>> extends OIMSelector<Set<TPk>> {
+    private readonly reactiveIndex;
+    private readonly key;
+    constructor(runtime: OIMComputativeRuntime, reactiveIndex: OIMReactiveIndexSetBased<TKey, TPk, TIndex>, key: TKey);
+    getValue(): Set<TPk>;
+}
+
+declare class OIMIndexPksByKeyArrayBasedSelector<TKey extends TOIMPk, TPk extends TOIMPk, TIndex extends OIMIndexArrayBased<TKey, TPk>> extends OIMSelector<readonly TPk[]> {
+    private readonly reactiveIndex;
+    private readonly key;
+    constructor(runtime: OIMComputativeRuntime, reactiveIndex: OIMReactiveIndexArrayBased<TKey, TPk, TIndex>, key: TKey);
+    getValue(): readonly TPk[];
+    protected areEqual(prev: readonly TPk[], next: readonly TPk[]): boolean;
+}
+
+declare class OIMIndexPksByKeysSetBasedSelector<TKey extends TOIMPk, TPk extends TOIMPk, TIndex extends OIMIndexSetBased<TKey, TPk>> extends OIMSelector<readonly TPk[]> {
+    private readonly reactiveIndex;
+    private readonly keys;
+    constructor(runtime: OIMComputativeRuntime, reactiveIndex: OIMReactiveIndexSetBased<TKey, TPk, TIndex>, keys: readonly TKey[]);
+    getValue(): readonly TPk[];
+    protected areEqual(prev: readonly TPk[], next: readonly TPk[]): boolean;
+}
+
+declare class OIMIndexPksByKeysArrayBasedSelector<TKey extends TOIMPk, TPk extends TOIMPk, TIndex extends OIMIndexArrayBased<TKey, TPk>> extends OIMSelector<readonly TPk[]> {
+    private readonly reactiveIndex;
+    private readonly keys;
+    constructor(runtime: OIMComputativeRuntime, reactiveIndex: OIMReactiveIndexArrayBased<TKey, TPk, TIndex>, keys: readonly TKey[]);
+    getValue(): readonly TPk[];
+    protected areEqual(prev: readonly TPk[], next: readonly TPk[]): boolean;
+}
+
+declare class OIMEntitiesByIndexKeySetBasedSelector<TEntity extends object, TPk extends TOIMPk, TKey extends TOIMPk, TIndex extends OIMIndexSetBased<TKey, TPk>> extends OIMSelector<readonly (TEntity | undefined)[]> {
+    private readonly collection;
+    private readonly reactiveIndex;
+    private readonly key;
+    constructor(runtime: OIMComputativeRuntime, collection: OIMReactiveCollection<TEntity, TPk>, reactiveIndex: OIMReactiveIndexSetBased<TKey, TPk, TIndex>, key: TKey);
+    getValue(): readonly (TEntity | undefined)[];
+    protected areEqual(prev: readonly (TEntity | undefined)[], next: readonly (TEntity | undefined)[]): boolean;
+}
+
+declare class OIMEntitiesByIndexKeyArrayBasedSelector<TEntity extends object, TPk extends TOIMPk, TKey extends TOIMPk, TIndex extends OIMIndexArrayBased<TKey, TPk>> extends OIMSelector<readonly (TEntity | undefined)[]> {
+    private readonly collection;
+    private readonly reactiveIndex;
+    private readonly key;
+    constructor(runtime: OIMComputativeRuntime, collection: OIMReactiveCollection<TEntity, TPk>, reactiveIndex: OIMReactiveIndexArrayBased<TKey, TPk, TIndex>, key: TKey);
+    getValue(): readonly (TEntity | undefined)[];
+    protected areEqual(prev: readonly (TEntity | undefined)[], next: readonly (TEntity | undefined)[]): boolean;
 }
 
-export { EOIMCollectionEventType, EOIMComputedEventType, EOIMEffectPhase, EOIMEventQueueEventType, EOIMEventQueueSchedulerEventType, EOIMIndexEventType, EOIMObjectEventType, EOIMUpdateEventCoalescerEventType, type IOIMComputedEventSource, type IOIMEffectDependency, type IOIMEventQueueSchedulerEvents, OIMCollection, OIMCollectionChangedFieldsWrapper, OIMCollectionStore, OIMCollectionStoreMapDriven, OIMComparatorFactory, OIMComputed, OIMDBSettings, OIMEffect, OIMEffectDependencyComputed, OIMEffectDependencyKeyed, OIMEffectDependencyKeyedCollection, OIMEffectDependencyKeyedIndex, OIMEffectDependencyKeyedObject, OIMEntityUpdaterFactory, OIMEventEmitter, OIMEventQueue, OIMEventQueueScheduler, OIMEventQueueSchedulerAnimationFrame, OIMEventQueueSchedulerFactory, OIMEventQueueSchedulerImmediate, OIMEventQueueSchedulerMicrotask, OIMEventQueueSchedulerTimeout, OIMIndexArrayBased, OIMIndexComparatorFactory, OIMIndexManualArrayBased, OIMIndexManualOrderedArrayBased, OIMIndexManualSetBased, OIMIndexSetBased, OIMIndexStoreArrayBased, OIMIndexStoreMapDrivenArrayBased, OIMIndexStoreMapDrivenSetBased, OIMIndexStoreSetBased, OIMMap2Keys, OIMObject, OIMObjectStore, OIMObjectStoreMapDriven, OIMObjectStoreRecordDriven, OIMOrderedListIndexCommandStreamWrapper, OIMPkSelectorFactory, OIMRICollection, OIMReactiveCollection, OIMReactiveIndexArrayBased, OIMReactiveIndexManualArrayBased, OIMReactiveIndexManualSetBased, OIMReactiveIndexSetBased, OIMReactiveObject, OIMUpdateEventCoalescer, OIMUpdateEventCoalescerCollection, OIMUpdateEventCoalescerComputed, OIMUpdateEventCoalescerIndex, OIMUpdateEventCoalescerManual, OIMUpdateEventCoalescerObject, OIMUpdateEventEmitter, type TOIMCollectionOptions, type TOIMCollectionUpdatePayload, type TOIMComparator, type TOIMComputedOptions, type TOIMComputedUpdatePayload, type TOIMEffectOptions, type TOIMEntityUpdater, type TOIMEventHandler, type TOIMEventQueueOptions, type TOIMIndexComparator, type TOIMIndexKey, type TOIMIndexOptions, type TOIMIndexOptionsArrayBased, type TOIMIndexOptionsSetBased, type TOIMIndexPksUpdatePayload, type TOIMIndexUpdatePayload, type TOIMObjectOptions, type TOIMOrderedListCommand, type TOIMPk, type TOIMPkSelector, type TOIMSchedulerOptions, type TOIMSchedulerType, type TOIMUpdateEventEmitterOptions, type TOIMUpdatePayload };
+export { EOIMCollectionEventType, EOIMComputedEventType, EOIMEventQueueEventType, EOIMEventQueueSchedulerEventType, EOIMIndexEventType, EOIMObjectEventType, type IOIMComputedEventSource, type IOIMEffectDependency, type IOIMEventQueueSchedulerEvents, OIMCollection, OIMCollectionByPkSelector, OIMCollectionByPksSelector, OIMCollectionChangedFieldsWrapper, OIMCollectionStore, OIMCollectionStoreMapDriven, OIMComparatorFactory, OIMComputativeRuntime, OIMComputed, OIMDBSettings, OIMEffect, OIMEffectDependencyComputed, OIMEffectDependencyKeyed, OIMEffectDependencyKeyedCollection, OIMEffectDependencyKeyedIndex, OIMEffectDependencyKeyedObject, OIMEntitiesByIndexKeyArrayBasedSelector, OIMEntitiesByIndexKeySetBasedSelector, OIMEntityUpdaterFactory, OIMEventEmitter, OIMEventQueue, OIMEventQueueScheduler, OIMEventQueueSchedulerAnimationFrame, OIMEventQueueSchedulerFactory, OIMEventQueueSchedulerImmediate, OIMEventQueueSchedulerMicrotask, OIMEventQueueSchedulerTimeout, OIMIndexArrayBased, OIMIndexComparatorFactory, OIMIndexManualArrayBased, OIMIndexManualOrderedArrayBased, OIMIndexManualSetBased, OIMIndexPksByKeyArrayBasedSelector, OIMIndexPksByKeySetBasedSelector, OIMIndexPksByKeysArrayBasedSelector, OIMIndexPksByKeysSetBasedSelector, OIMIndexSetBased, OIMIndexStoreArrayBased, OIMIndexStoreMapDrivenArrayBased, OIMIndexStoreMapDrivenSetBased, OIMIndexStoreSetBased, OIMMap2Keys, OIMObject, OIMObjectStore, OIMObjectStoreMapDriven, OIMObjectStoreRecordDriven, OIMObjectValueByKeySelector, OIMObjectValuesByKeysSelector, OIMOrderedListIndexCommandStreamWrapper, OIMPkSelectorFactory, OIMRICollection, OIMReactiveCollection, OIMReactiveIndexArrayBased, OIMReactiveIndexManualArrayBased, OIMReactiveIndexManualSetBased, OIMReactiveIndexSetBased, OIMReactiveObject, OIMSelector, type TOIMAnyEntitySlot, type TOIMCollectionOptions, type TOIMCollectionUpdatePayload, type TOIMComparator, type TOIMComputedOptions, type TOIMComputedUpdatePayload, type TOIMEffectOptions, type TOIMEntitySlot, type TOIMEntitySlotResolver, type TOIMEntityUpdater, type TOIMEventHandler, type TOIMEventQueueOptions, type TOIMIndexComparator, type TOIMIndexKey, type TOIMIndexOptions, type TOIMIndexOptionsArrayBased, type TOIMIndexOptionsSetBased, type TOIMIndexPksUpdatePayload, type TOIMIndexUpdatePayload, type TOIMObjectOptions, type TOIMOrderedListCommand, type TOIMPk, type TOIMPkSelector, type TOIMSchedulerOptions, type TOIMSchedulerType, type TOIMUpdatePayload };