@oimdb/core 3.11.0 → 3.11.1

package/dist/index.cjs

@@ -728,19 +728,13 @@ var OIMCarrierKeyedEmitter = class {
     // doubles as membership: a carrier is in this array iff `carrier.dirty`.
     this.dirtyCarriers = [];
     this.isFlushEnqueued = false;
-    // Number of live subscriptions whose single handler spans 2+ distinct
-    // carriers (a `subscribeOnKeys` over distinct keys). While this is > 0 a
-    // flush coalesces delivery so such a handler fires at most ONCE per flush,
-    // not once per changed carrier — the callback carries no key, so extra
-    // fires are pure waste. At 0 the hot single-subscriber path pays nothing:
-    // no per-flush Set, no membership checks.
-    this.multiCarrierSubscriptions = 0;
     this.onFlush = () => {
       this.isFlushEnqueued = false;
       if (this.dirtyCarriers.length === 0) return;
       const flushing = this.dirtyCarriers;
       this.dirtyCarriers = [];
-      const delivered = this.multiCarrierSubscriptions > 0 ? this.deliveredPool ?? (this.deliveredPool = /* @__PURE__ */ new Set()) : void 0;
+      const multiCarrierHandlers = this.multiCarrierHandlers;
+      const delivered = multiCarrierHandlers !== void 0 && multiCarrierHandlers.size > 0 ? this.deliveredPool ?? (this.deliveredPool = /* @__PURE__ */ new Set()) : void 0;
       let i = 0;
       try {
         for (; i < flushing.length; i++) {
@@ -768,12 +762,14 @@ var OIMCarrierKeyedEmitter = class {
       carriers.push(carrier);
     }
     const spansMultipleCarriers = carriers.length > 1;
-    if (spansMultipleCarriers) this.multiCarrierSubscriptions++;
+    if (spansMultipleCarriers) this.retainMultiCarrierHandler(handler);
     let unsubscribed = false;
     return () => {
       if (unsubscribed) return;
       unsubscribed = true;
-      if (spansMultipleCarriers) this.multiCarrierSubscriptions--;
+      if (spansMultipleCarriers) {
+        this.releaseMultiCarrierHandler(handler);
+      }
       for (let i = 0; i < carriers.length; i++) {
         this.removeHandler(carriers[i], handler);
       }
@@ -784,10 +780,25 @@ var OIMCarrierKeyedEmitter = class {
     if (carrier) this.removeHandler(carrier, handler);
   }
   unsubscribeFromKeys(keys, handler) {
+    if (keys.length > 1) this.releaseMultiCarrierHandler(handler);
     for (let i = 0; i < keys.length; i++) {
       this.unsubscribeFromKey(keys[i], handler);
     }
   }
+  /** Take a reference for a handler whose subscription spans several carriers. */
+  retainMultiCarrierHandler(handler) {
+    const handlers = this.multiCarrierHandlers ?? (this.multiCarrierHandlers = /* @__PURE__ */ new Map());
+    handlers.set(handler, (handlers.get(handler) ?? 0) + 1);
+  }
+  /** Drop one reference; the handler leaves the set when none are left. */
+  releaseMultiCarrierHandler(handler) {
+    const handlers = this.multiCarrierHandlers;
+    if (handlers === void 0) return;
+    const count = handlers.get(handler);
+    if (count === void 0) return;
+    if (count > 1) handlers.set(handler, count - 1);
+    else handlers.delete(handler);
+  }
   addHandler(carrier, handler) {
     let subscribers = carrier.subscribers;
     if (!subscribers) {
@@ -876,6 +887,8 @@ var OIMCarrierKeyedEmitter = class {
     }
     this.dirtyCarriers = [];
     this.isFlushEnqueued = false;
+    this.multiCarrierHandlers?.clear();
+    this.deliveredPool?.clear();
   }
   assertNotInFlush() {
     if (this.queue.isInFlush) {
@@ -892,13 +905,12 @@ var OIMCarrierKeyedEmitter = class {
   notify(carrier, delivered) {
     const subscribers = carrier.subscribers;
     if (!subscribers || subscribers.size === 0) return;
+    const multiCarrierHandlers = delivered ? this.multiCarrierHandlers : void 0;
     if (subscribers.size === 1) {
       const only = subscribers.values().next().value;
       if (!only) return;
-      if (delivered) {
-        const size = delivered.size;
-        delivered.add(only);
-        if (delivered.size === size) return;
+      if (this.isAlreadyDelivered(only, delivered, multiCarrierHandlers)) {
+        return;
       }
       only();
       return;
@@ -908,14 +920,25 @@ var OIMCarrierKeyedEmitter = class {
     for (let i = 0; i < snapshot.length; i++) {
       const handler = snapshot[i];
       if (!subscribers.has(handler)) continue;
-      if (delivered) {
-        const size = delivered.size;
-        delivered.add(handler);
-        if (delivered.size === size) continue;
+      if (this.isAlreadyDelivered(handler, delivered, multiCarrierHandlers)) {
+        continue;
       }
       handler();
     }
   }
+  /**
+   * Whether this handler already fired in the current flush and must be
+   * skipped. Only multi-carrier handlers are tracked; everything else always
+   * delivers. Membership is recorded via the size delta of a single `add` —
+   * one hash probe instead of `has` + `add`.
+   */
+  isAlreadyDelivered(handler, delivered, multiCarrierHandlers) {
+    if (delivered === void 0) return false;
+    if (multiCarrierHandlers?.has(handler) !== true) return false;
+    const size = delivered.size;
+    delivered.add(handler);
+    return delivered.size === size;
+  }
 };
 
 // src/core/OIMKeyedCarrierProvider.ts

package/dist/index.d.cts

@@ -509,13 +509,17 @@ declare class OIMCarrierKeyedEmitter<TKey extends TOIMKey, TCarrier extends IOIM
     private readonly subscribedCarriers;
     private dirtyCarriers;
     private isFlushEnqueued;
-    private multiCarrierSubscriptions;
+    private multiCarrierHandlers?;
     private deliveredPool?;
     constructor(queue: OIMEventQueue, carrierProvider: IOIMCarrierProvider<TKey, TCarrier>);
     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;
+    /** Take a reference for a handler whose subscription spans several carriers. */
+    private retainMultiCarrierHandler;
+    /** Drop one reference; the handler leaves the set when none are left. */
+    private releaseMultiCarrierHandler;
     private addHandler;
     private removeHandler;
     /** Fast path: the writer already holds the carrier. */
@@ -536,6 +540,13 @@ declare class OIMCarrierKeyedEmitter<TKey extends TOIMKey, TCarrier extends IOIM
     private scheduleFlush;
     private readonly onFlush;
     private notify;
+    /**
+     * Whether this handler already fired in the current flush and must be
+     * skipped. Only multi-carrier handlers are tracked; everything else always
+     * delivers. Membership is recorded via the size delta of a single `add` —
+     * one hash probe instead of `has` + `add`.
+     */
+    private isAlreadyDelivered;
 }
 
 /**

package/dist/index.d.ts

@@ -509,13 +509,17 @@ declare class OIMCarrierKeyedEmitter<TKey extends TOIMKey, TCarrier extends IOIM
     private readonly subscribedCarriers;
     private dirtyCarriers;
     private isFlushEnqueued;
-    private multiCarrierSubscriptions;
+    private multiCarrierHandlers?;
     private deliveredPool?;
     constructor(queue: OIMEventQueue, carrierProvider: IOIMCarrierProvider<TKey, TCarrier>);
     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;
+    /** Take a reference for a handler whose subscription spans several carriers. */
+    private retainMultiCarrierHandler;
+    /** Drop one reference; the handler leaves the set when none are left. */
+    private releaseMultiCarrierHandler;
     private addHandler;
     private removeHandler;
     /** Fast path: the writer already holds the carrier. */
@@ -536,6 +540,13 @@ declare class OIMCarrierKeyedEmitter<TKey extends TOIMKey, TCarrier extends IOIM
     private scheduleFlush;
     private readonly onFlush;
     private notify;
+    /**
+     * Whether this handler already fired in the current flush and must be
+     * skipped. Only multi-carrier handlers are tracked; everything else always
+     * delivers. Membership is recorded via the size delta of a single `add` —
+     * one hash probe instead of `has` + `add`.
+     */
+    private isAlreadyDelivered;
 }
 
 /**

package/dist/index.js

@@ -578,19 +578,13 @@ var OIMCarrierKeyedEmitter = class {
     // doubles as membership: a carrier is in this array iff `carrier.dirty`.
     this.dirtyCarriers = [];
     this.isFlushEnqueued = false;
-    // Number of live subscriptions whose single handler spans 2+ distinct
-    // carriers (a `subscribeOnKeys` over distinct keys). While this is > 0 a
-    // flush coalesces delivery so such a handler fires at most ONCE per flush,
-    // not once per changed carrier — the callback carries no key, so extra
-    // fires are pure waste. At 0 the hot single-subscriber path pays nothing:
-    // no per-flush Set, no membership checks.
-    this.multiCarrierSubscriptions = 0;
     this.onFlush = () => {
       this.isFlushEnqueued = false;
       if (this.dirtyCarriers.length === 0) return;
       const flushing = this.dirtyCarriers;
       this.dirtyCarriers = [];
-      const delivered = this.multiCarrierSubscriptions > 0 ? this.deliveredPool ?? (this.deliveredPool = /* @__PURE__ */ new Set()) : void 0;
+      const multiCarrierHandlers = this.multiCarrierHandlers;
+      const delivered = multiCarrierHandlers !== void 0 && multiCarrierHandlers.size > 0 ? this.deliveredPool ?? (this.deliveredPool = /* @__PURE__ */ new Set()) : void 0;
       let i = 0;
       try {
         for (; i < flushing.length; i++) {
@@ -618,12 +612,14 @@ var OIMCarrierKeyedEmitter = class {
       carriers.push(carrier);
     }
     const spansMultipleCarriers = carriers.length > 1;
-    if (spansMultipleCarriers) this.multiCarrierSubscriptions++;
+    if (spansMultipleCarriers) this.retainMultiCarrierHandler(handler);
     let unsubscribed = false;
     return () => {
       if (unsubscribed) return;
       unsubscribed = true;
-      if (spansMultipleCarriers) this.multiCarrierSubscriptions--;
+      if (spansMultipleCarriers) {
+        this.releaseMultiCarrierHandler(handler);
+      }
       for (let i = 0; i < carriers.length; i++) {
         this.removeHandler(carriers[i], handler);
       }
@@ -634,10 +630,25 @@ var OIMCarrierKeyedEmitter = class {
     if (carrier) this.removeHandler(carrier, handler);
   }
   unsubscribeFromKeys(keys, handler) {
+    if (keys.length > 1) this.releaseMultiCarrierHandler(handler);
     for (let i = 0; i < keys.length; i++) {
       this.unsubscribeFromKey(keys[i], handler);
     }
   }
+  /** Take a reference for a handler whose subscription spans several carriers. */
+  retainMultiCarrierHandler(handler) {
+    const handlers = this.multiCarrierHandlers ?? (this.multiCarrierHandlers = /* @__PURE__ */ new Map());
+    handlers.set(handler, (handlers.get(handler) ?? 0) + 1);
+  }
+  /** Drop one reference; the handler leaves the set when none are left. */
+  releaseMultiCarrierHandler(handler) {
+    const handlers = this.multiCarrierHandlers;
+    if (handlers === void 0) return;
+    const count = handlers.get(handler);
+    if (count === void 0) return;
+    if (count > 1) handlers.set(handler, count - 1);
+    else handlers.delete(handler);
+  }
   addHandler(carrier, handler) {
     let subscribers = carrier.subscribers;
     if (!subscribers) {
@@ -726,6 +737,8 @@ var OIMCarrierKeyedEmitter = class {
     }
     this.dirtyCarriers = [];
     this.isFlushEnqueued = false;
+    this.multiCarrierHandlers?.clear();
+    this.deliveredPool?.clear();
   }
   assertNotInFlush() {
     if (this.queue.isInFlush) {
@@ -742,13 +755,12 @@ var OIMCarrierKeyedEmitter = class {
   notify(carrier, delivered) {
     const subscribers = carrier.subscribers;
     if (!subscribers || subscribers.size === 0) return;
+    const multiCarrierHandlers = delivered ? this.multiCarrierHandlers : void 0;
     if (subscribers.size === 1) {
       const only = subscribers.values().next().value;
       if (!only) return;
-      if (delivered) {
-        const size = delivered.size;
-        delivered.add(only);
-        if (delivered.size === size) return;
+      if (this.isAlreadyDelivered(only, delivered, multiCarrierHandlers)) {
+        return;
       }
       only();
       return;
@@ -758,14 +770,25 @@ var OIMCarrierKeyedEmitter = class {
     for (let i = 0; i < snapshot.length; i++) {
       const handler = snapshot[i];
       if (!subscribers.has(handler)) continue;
-      if (delivered) {
-        const size = delivered.size;
-        delivered.add(handler);
-        if (delivered.size === size) continue;
+      if (this.isAlreadyDelivered(handler, delivered, multiCarrierHandlers)) {
+        continue;
       }
       handler();
     }
   }
+  /**
+   * Whether this handler already fired in the current flush and must be
+   * skipped. Only multi-carrier handlers are tracked; everything else always
+   * delivers. Membership is recorded via the size delta of a single `add` —
+   * one hash probe instead of `has` + `add`.
+   */
+  isAlreadyDelivered(handler, delivered, multiCarrierHandlers) {
+    if (delivered === void 0) return false;
+    if (multiCarrierHandlers?.has(handler) !== true) return false;
+    const size = delivered.size;
+    delivered.add(handler);
+    return delivered.size === size;
+  }
 };
 
 // src/core/OIMKeyedCarrierProvider.ts

package/llms.txt

@@ -86,7 +86,9 @@ byRole.subscribeOnKey('admin', () => {
 queue.flush(); // delivers subscription
 ```
 
-**`subscribeOnKeys(keys, handler)` delivery is coalesced per flush:** the handler fires at most ONCE per flush no matter how many of the subscribed keys changed in it (the callback gets no key, so per-key fan-out would be pure waste). This holds across all reactive primitives — sync (collection / index / object, via `OIMCarrierKeyedEmitter`) and the `@oimdb/async` nodes (via `OIMUpdateEventEmitterAsync`) alike. `subscribeOnKey` (single key) is unchanged. Handler identity is preserved, so `unsubscribeFromKeys(keys, handler)` still removes a `subscribeOnKeys` subscription.
+**`subscribeOnKeys(keys, handler)` delivery is coalesced per flush:** the handler fires at most ONCE per flush no matter how many of the subscribed keys changed in it (the callback gets no key, so per-key fan-out would be pure waste). This holds across all reactive primitives — sync (collection / index / object, via `OIMCarrierKeyedEmitter`) and the `@oimdb/async` nodes (via `OIMUpdateEventEmitterAsync`) alike. `subscribeOnKey` (single key) is unchanged. Handler identity is preserved, so `unsubscribeFromKeys(keys, handler)` still removes a `subscribeOnKeys` subscription — and releases the coalescing exactly like the returned unsubscribe closure does.
+
+**Coalescing is scoped to the subscription, not to the handler.** It applies only to handlers registered through a multi-key `subscribeOnKeys`. If the same function holds several *independent* `subscribeOnKey` subscriptions, it still gets one delivery per changed key — an unrelated multi-key subscription elsewhere on the same collection/index never changes that.
 
 Membership writes are incremental (touch only the changed pks):
 - `addPks(key, pks)` / `removePks(key, pks)` — **set-based**: O(1) per pk for both. **array-based**: `addPks` O(1), `removePks` O(bucket) (ordered, must scan).

package/package.json

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