@oimdb/core 2.1.0 → 3.0.0

package/dist/index.cjs

@@ -26,6 +26,7 @@ __export(index_exports, {
   EOIMEventQueueSchedulerEventType: () => EOIMEventQueueSchedulerEventType,
   EOIMIndexEventType: () => EOIMIndexEventType,
   EOIMObjectEventType: () => EOIMObjectEventType,
+  OIMCarrierKeyedEmitter: () => OIMCarrierKeyedEmitter,
   OIMCollection: () => OIMCollection,
   OIMCollectionByPkSelector: () => OIMCollectionByPkSelector,
   OIMCollectionByPksSelector: () => OIMCollectionByPksSelector,
@@ -93,6 +94,7 @@ __export(index_exports, {
   OIMReactiveIndexSetBased: () => OIMReactiveIndexSetBased,
   OIMReactiveObject: () => OIMReactiveObject,
   OIMSelector: () => OIMSelector,
+  createInPlaceEntityUpdater: () => createInPlaceEntityUpdater,
   createOIMCollectionIndexFactory: () => createOIMCollectionIndexFactory,
   createOIMCollectionKit: () => createOIMCollectionKit
 });
@@ -277,10 +279,18 @@ var OIMIndex = class {
   emitUpdateOne(key) {
     this.emitUpdate([key]);
   }
+  /**
+   * Maps a bucket's slots to entities, preserving positional holes: a slot
+   * whose entity is not present yet (reserved by an index ahead of its data)
+   * or was removed yields `undefined` at its position rather than being
+   * dropped. This keeps the result aligned with `getPksByKey`, so callers can
+   * render a per-item loading/placeholder state instead of a silently shorter
+   * list.
+   */
   slotsToEntities(slots) {
     const entities = [];
     for (const slot of slots) {
-      if (slot.item !== void 0) entities.push(slot.item);
+      entities.push(slot.item);
     }
     return entities;
   }
@@ -536,12 +546,7 @@ var OIMUpdateEventEmitter = class {
         this.updatedKeys.clear();
         return;
       }
-      const makeHandlerSnapshot = (handlers) => {
-        const snapshot = [];
-        handlers.forEach((h) => snapshot.push(h));
-        return snapshot;
-      };
-      this.runSinglePass(makeHandlerSnapshot);
+      this.runSinglePass();
     };
     this.onAfterFlush = () => {
       if (!this.isAfterFlushDeliveryScheduled) return;
@@ -636,18 +641,32 @@ var OIMUpdateEventEmitter = class {
     this.dequeueFlush = this.queue.enqueue(this.onFlush);
   }
   deliverImmediate() {
-    const makeHandlerSnapshot = (handlers) => {
-      const snapshot = [];
-      handlers.forEach((h) => snapshot.push(h));
-      return snapshot;
-    };
-    this.runSinglePass(makeHandlerSnapshot);
+    this.runSinglePass();
+  }
+  /**
+   * Notifies all handlers for a key. The overwhelmingly common case is a
+   * single subscriber per key (one component per pk), handled without any
+   * allocation. For multiple subscribers a snapshot is taken so a handler may
+   * (un)subscribe during iteration without corrupting the walk.
+   */
+  notifyHandlers(handlers) {
+    if (handlers.size === 1) {
+      const only = handlers.values().next().value;
+      if (only) only();
+      return;
+    }
+    const snapshot = [];
+    handlers.forEach((h) => snapshot.push(h));
+    for (let i = 0; i < snapshot.length; i++) {
+      const handler = snapshot[i];
+      if (handlers.has(handler)) handler();
+    }
   }
   /**
    * Deliver updated keys and notify handlers once.
    * Re-entrant updates during delivery are forbidden and will throw in markUpdatedKeys().
    */
-  runSinglePass(makeHandlerSnapshot) {
+  runSinglePass() {
     if (this.updatedKeys.size === 0) return;
     const flushingKeys = this.updatedKeys;
     this.updatedKeys = /* @__PURE__ */ new Set();
@@ -656,21 +675,13 @@ var OIMUpdateEventEmitter = class {
       flushingKeys.forEach((key) => {
         const handlers = this.keyHandlers.get(key);
         if (!handlers || handlers.size === 0) return;
-        const handlerSnapshot = makeHandlerSnapshot(handlers);
-        for (let i = 0; i < handlerSnapshot.length; i++) {
-          const handler = handlerSnapshot[i];
-          if (handlers.has(handler)) handler();
-        }
+        this.notifyHandlers(handlers);
       });
     } else {
       this.keyHandlers.forEach((handlers, key) => {
         if (!flushingKeys.has(key)) return;
         if (!handlers || handlers.size === 0) return;
-        const handlerSnapshot = makeHandlerSnapshot(handlers);
-        for (let i = 0; i < handlerSnapshot.length; i++) {
-          const handler = handlerSnapshot[i];
-          if (handlers.has(handler)) handler();
-        }
+        this.notifyHandlers(handlers);
       });
     }
   }
@@ -879,17 +890,39 @@ var OIMCollectionStoreMapDriven = class extends OIMCollectionStore {
   constructor() {
     super(...arguments);
     this.slots = /* @__PURE__ */ new Map();
+    // Slots reserved by indexes for PKs whose entity has not arrived yet.
+    // They carry `item: undefined` and live apart from `slots` so they do not
+    // leak into entity enumeration (getAll/getAllPks/countAll). When the entity
+    // is finally written, the reserved slot is promoted into `slots` — keeping
+    // the reference that indexes already hold, so it fills in live.
+    this.reservedSlots = /* @__PURE__ */ new Map();
   }
   setOneByPk(pk, entity) {
     const slot = this.slots.get(pk);
     if (slot) {
       slot.item = entity;
       return slot;
-    } else {
-      const nextSlot = { pk, item: entity };
-      this.slots.set(pk, nextSlot);
-      return nextSlot;
     }
+    const reserved = this.reservedSlots.get(pk);
+    if (reserved) {
+      reserved.item = entity;
+      this.reservedSlots.delete(pk);
+      this.slots.set(pk, reserved);
+      return reserved;
+    }
+    const nextSlot = { pk, item: entity };
+    this.slots.set(pk, nextSlot);
+    return nextSlot;
+  }
+  getOrReserveSlotByPk(pk) {
+    const slot = this.slots.get(pk);
+    if (slot) return slot;
+    let reserved = this.reservedSlots.get(pk);
+    if (!reserved) {
+      reserved = { pk, item: void 0 };
+      this.reservedSlots.set(pk, reserved);
+    }
+    return reserved;
   }
   setManyByPks(pks, entities) {
     const slots = [];
@@ -902,6 +935,12 @@ var OIMCollectionStoreMapDriven = class extends OIMCollectionStore {
   getSlotByPk(pk) {
     return this.slots.get(pk);
   }
+  findSlotByPk(pk) {
+    return this.slots.get(pk) ?? this.reservedSlots.get(pk);
+  }
+  hasSubscribers(slot) {
+    return slot.subscribers !== void 0 && slot.subscribers.size > 0;
+  }
   getSlotsByPks(pks) {
     const result = [];
     result.length = pks.length;
@@ -920,8 +959,21 @@ var OIMCollectionStoreMapDriven = class extends OIMCollectionStore {
   }
   removeOneByPk(pk) {
     const slot = this.slots.get(pk);
-    if (slot) slot.item = void 0;
-    this.slots.delete(pk);
+    if (slot) {
+      slot.item = void 0;
+      this.slots.delete(pk);
+      if (this.hasSubscribers(slot)) {
+        this.reservedSlots.set(pk, slot);
+      }
+      return;
+    }
+    const reserved = this.reservedSlots.get(pk);
+    if (reserved) {
+      reserved.item = void 0;
+      if (!this.hasSubscribers(reserved)) {
+        this.reservedSlots.delete(pk);
+      }
+    }
   }
   removeManyByPks(pks) {
     for (const pk of pks) {
@@ -955,16 +1007,31 @@ var OIMCollectionStoreMapDriven = class extends OIMCollectionStore {
     return this.slots.size;
   }
   clear() {
+    const retained = [];
     for (const slot of this.slots.values()) {
       slot.item = void 0;
+      if (this.hasSubscribers(slot)) retained.push(slot);
     }
     this.slots.clear();
+    for (const slot of this.reservedSlots.values()) {
+      slot.item = void 0;
+      if (this.hasSubscribers(slot)) retained.push(slot);
+    }
+    this.reservedSlots.clear();
+    for (const slot of retained) {
+      this.reservedSlots.set(slot.pk, slot);
+    }
   }
   getAllPks() {
     return Array.from(this.slots.keys());
   }
   destroy() {
     this.clear();
+    for (const slot of this.reservedSlots.values()) {
+      slot.subscribers?.clear();
+      slot.subscribers = void 0;
+    }
+    this.reservedSlots.clear();
   }
 };
 
@@ -1000,6 +1067,9 @@ var OIMCollection = class {
   getSlotByPk(pk) {
     return this.store.getSlotByPk(pk);
   }
+  getOrReserveSlotByPk(pk) {
+    return this.store.getOrReserveSlotByPk(pk);
+  }
   getSlotsByPks(pks) {
     return this.store.getSlotsByPks(pks);
   }
@@ -1084,6 +1154,153 @@ var OIMCollection = class {
   }
 };
 
+// src/core/OIMCarrierKeyedEmitter.ts
+var OIMCarrierKeyedEmitter = class {
+  constructor(queue, resolver) {
+    // Carriers with at least one subscriber — for markAllUpdated / metrics.
+    this.subscribedCarriers = /* @__PURE__ */ new Set();
+    this.dirtyCarriers = /* @__PURE__ */ new Set();
+    this.isFlushEnqueued = false;
+    this.onFlush = () => {
+      this.isFlushEnqueued = false;
+      this.dequeueFlush = void 0;
+      if (this.dirtyCarriers.size === 0) return;
+      const flushing = this.dirtyCarriers;
+      this.dirtyCarriers = /* @__PURE__ */ new Set();
+      flushing.forEach((carrier) => this.notify(carrier));
+    };
+    this.queue = queue;
+    this.resolver = resolver;
+  }
+  subscribeOnKey(key, handler) {
+    const carrier = this.resolver.getOrReserveCarrier(key);
+    this.addHandler(carrier, handler);
+    return () => this.removeHandler(carrier, handler);
+  }
+  subscribeOnKeys(keys, handler) {
+    const carriers = [];
+    for (let i = 0; i < keys.length; i++) {
+      const carrier = this.resolver.getOrReserveCarrier(keys[i]);
+      this.addHandler(carrier, handler);
+      carriers.push(carrier);
+    }
+    return () => {
+      for (let i = 0; i < carriers.length; i++) {
+        this.removeHandler(carriers[i], handler);
+      }
+    };
+  }
+  unsubscribeFromKey(key, handler) {
+    const carrier = this.resolver.findCarrier(key);
+    if (carrier) this.removeHandler(carrier, handler);
+  }
+  unsubscribeFromKeys(keys, handler) {
+    for (let i = 0; i < keys.length; i++) {
+      this.unsubscribeFromKey(keys[i], handler);
+    }
+  }
+  addHandler(carrier, handler) {
+    let subscribers = carrier.subscribers;
+    if (!subscribers) {
+      subscribers = /* @__PURE__ */ new Set();
+      carrier.subscribers = subscribers;
+    }
+    subscribers.add(handler);
+    this.subscribedCarriers.add(carrier);
+  }
+  removeHandler(carrier, handler) {
+    const subscribers = carrier.subscribers;
+    if (!subscribers) return;
+    subscribers.delete(handler);
+    if (subscribers.size === 0) {
+      this.subscribedCarriers.delete(carrier);
+    }
+  }
+  /** Fast path: the writer already holds the carrier. */
+  markUpdatedCarrier(carrier) {
+    this.assertNotInFlush();
+    const subscribers = carrier.subscribers;
+    if (!subscribers || subscribers.size === 0) return;
+    this.dirtyCarriers.add(carrier);
+    this.scheduleFlush();
+  }
+  markUpdatedKey(key) {
+    const carrier = this.resolver.findCarrier(key);
+    if (carrier) this.markUpdatedCarrier(carrier);
+    else this.assertNotInFlush();
+  }
+  markUpdatedKeys(keys) {
+    for (let i = 0; i < keys.length; i++) this.markUpdatedKey(keys[i]);
+  }
+  markAllUpdated() {
+    this.assertNotInFlush();
+    if (this.subscribedCarriers.size === 0) return;
+    this.subscribedCarriers.forEach(
+      (carrier) => this.dirtyCarriers.add(carrier)
+    );
+    this.scheduleFlush();
+  }
+  hasSubscriptions() {
+    return this.subscribedCarriers.size > 0;
+  }
+  getHandlerCount(key) {
+    return this.resolver.findCarrier(key)?.subscribers?.size ?? 0;
+  }
+  getMetrics() {
+    let totalHandlers = 0;
+    this.subscribedCarriers.forEach((carrier) => {
+      totalHandlers += carrier.subscribers?.size ?? 0;
+    });
+    const totalKeys = this.subscribedCarriers.size;
+    return {
+      totalKeys,
+      totalHandlers,
+      averageHandlersPerKey: totalKeys > 0 ? totalHandlers / totalKeys : 0,
+      queueLength: this.dirtyCarriers.size
+    };
+  }
+  destroy() {
+    if (this.dequeueFlush) {
+      this.dequeueFlush();
+      this.dequeueFlush = void 0;
+    }
+    this.subscribedCarriers.forEach((carrier) => {
+      carrier.subscribers?.clear();
+      carrier.subscribers = void 0;
+    });
+    this.subscribedCarriers.clear();
+    this.dirtyCarriers.clear();
+    this.isFlushEnqueued = false;
+  }
+  assertNotInFlush() {
+    if (this.queue.isInFlush) {
+      throw new Error(
+        "OIMCarrierKeyedEmitter: updates during queue.flush() are not allowed. Finish all writes before calling queue.flush()."
+      );
+    }
+  }
+  scheduleFlush() {
+    if (this.isFlushEnqueued) return;
+    this.isFlushEnqueued = true;
+    this.dequeueFlush = this.queue.enqueue(this.onFlush);
+  }
+  notify(carrier) {
+    const subscribers = carrier.subscribers;
+    if (!subscribers || subscribers.size === 0) return;
+    if (subscribers.size === 1) {
+      const only = subscribers.values().next().value;
+      if (only) only();
+      return;
+    }
+    const snapshot = [];
+    subscribers.forEach((h) => snapshot.push(h));
+    for (let i = 0; i < snapshot.length; i++) {
+      const handler = snapshot[i];
+      if (subscribers.has(handler)) handler();
+    }
+  }
+};
+
 // src/core/OIMReactiveCollection.ts
 var OIMReactiveCollection = class extends OIMCollection {
   constructor(queue, opts) {
@@ -1103,7 +1320,10 @@ var OIMReactiveCollection = class extends OIMCollection {
       for (let i = 0; i < snapshot.length; i++) snapshot[i](pks);
     };
     this.queue = queue;
-    this.updateEmitter = new OIMUpdateEventEmitter(queue, "queue");
+    this.updateEmitter = new OIMCarrierKeyedEmitter(queue, {
+      getOrReserveCarrier: (pk) => this.store.getOrReserveSlotByPk(pk),
+      findCarrier: (pk) => this.store.findSlotByPk(pk)
+    });
   }
   subscribeOnKey(pk, handler) {
     return this.updateEmitter.subscribeOnKey(pk, handler);
@@ -1135,17 +1355,31 @@ var OIMReactiveCollection = class extends OIMCollection {
       this.anyUpdateHandlers.delete(handler);
     };
   }
+  // The legacy `emitter` (EOIMCollectionEventType.UPDATE) coexists with the
+  // keyed `updateEmitter`. Build its payload only when something is actually
+  // subscribed — otherwise every upsert/remove allocates a throwaway
+  // `{ pks }` object (and array) that nobody reads.
+  notifyLegacy(pk) {
+    if (this.emitter.hasHandlers(0 /* UPDATE */)) {
+      this.emitter.emit(0 /* UPDATE */, { pks: [pk] });
+    }
+  }
+  notifyLegacyMany(pks) {
+    if (this.emitter.hasHandlers(0 /* UPDATE */)) {
+      this.emitter.emit(0 /* UPDATE */, { pks });
+    }
+  }
   upsertOneByPk(pk, entity) {
     const slot = this.upsertOneWithoutNotificationsByPk(pk, entity);
-    this.emitter.emit(0 /* UPDATE */, { pks: [pk] });
-    this.updateEmitter.markUpdatedKey(pk);
+    this.notifyLegacy(pk);
+    this.updateEmitter.markUpdatedCarrier(slot);
     this.trackAnyUpdatePk(pk);
     return slot;
   }
   upsertOne(entity) {
     const slot = this.upsertOneWithoutNotifications(entity);
-    this.emitter.emit(0 /* UPDATE */, { pks: [slot.pk] });
-    this.updateEmitter.markUpdatedKey(slot.pk);
+    this.notifyLegacy(slot.pk);
+    this.updateEmitter.markUpdatedCarrier(slot);
     this.trackAnyUpdatePk(slot.pk);
     return slot;
   }
@@ -1155,15 +1389,17 @@ var OIMReactiveCollection = class extends OIMCollection {
       (entity) => this.upsertOneWithoutNotifications(entity)
     );
     const pks = slots.map((slot) => slot.pk);
-    this.emitter.emit(0 /* UPDATE */, { pks });
-    this.updateEmitter.markUpdatedKeys(pks);
+    this.notifyLegacyMany(pks);
+    for (let i = 0; i < slots.length; i++) {
+      this.updateEmitter.markUpdatedCarrier(slots[i]);
+    }
     this.trackAnyUpdatePks(pks);
     return slots;
   }
   removeOne(entity) {
     const pk = this.selectPk(entity);
     this.store.removeOneByPk(pk);
-    this.emitter.emit(0 /* UPDATE */, { pks: [pk] });
+    this.notifyLegacy(pk);
     this.updateEmitter.markUpdatedKey(pk);
     this.trackAnyUpdatePk(pk);
   }
@@ -1171,26 +1407,28 @@ var OIMReactiveCollection = class extends OIMCollection {
     if (entities.length === 0) return;
     const pks = entities.map(this.selectPk);
     this.store.removeManyByPks(pks);
-    this.emitter.emit(0 /* UPDATE */, { pks });
+    this.notifyLegacyMany(pks);
     this.updateEmitter.markUpdatedKeys(pks);
     this.trackAnyUpdatePks(pks);
   }
   removeOneByPk(pk) {
     this.store.removeOneByPk(pk);
-    this.emitter.emit(0 /* UPDATE */, { pks: [pk] });
+    this.notifyLegacy(pk);
     this.updateEmitter.markUpdatedKey(pk);
     this.trackAnyUpdatePk(pk);
   }
   removeManyByPks(pks) {
     if (pks.length === 0) return;
     this.store.removeManyByPks(pks);
-    this.emitter.emit(0 /* UPDATE */, { pks });
+    this.notifyLegacyMany(pks);
     this.updateEmitter.markUpdatedKeys(pks);
     this.trackAnyUpdatePks(pks);
   }
   clear() {
     this.store.clear();
-    this.emitter.emit(0 /* UPDATE */, { pks: [] });
+    if (this.emitter.hasHandlers(0 /* UPDATE */)) {
+      this.emitter.emit(0 /* UPDATE */, { pks: [] });
+    }
     this.updateEmitter.markAllUpdated();
     this.trackAnyUpdateClear();
   }
@@ -1573,6 +1811,21 @@ var OIMIndexManualArrayBased = class extends OIMIndexArrayBased {
       this.emitUpdateOne(key);
     }
   }
+  /**
+   * Appends pre-deduplicated slots to a key's bucket IN PLACE (no copy of the
+   * existing bucket) and emits once. Callers own dedup (so this stays O(added),
+   * not O(bucket)); used by collection-bound indexes for fast `addPks`.
+   */
+  appendSlots(key, slots) {
+    if (slots.length === 0) return;
+    let bucket = this.store.getOneByKey(key);
+    if (!bucket) {
+      bucket = [];
+      this.store.setOneByKey(key, bucket);
+    }
+    for (let i = 0; i < slots.length; i++) bucket.push(slots[i]);
+    this.emitUpdateOne(key);
+  }
   /**
    * Clear all primary keys for a specific index key, or all keys if no key specified
    */
@@ -1617,6 +1870,9 @@ var OIMReactiveIndexManualArrayBased = class extends OIMReactiveIndexArrayBased
   setSlots(key, slots) {
     this.index.setSlots(key, slots);
   }
+  appendSlots(key, slots) {
+    this.index.appendSlots(key, slots);
+  }
   clear(key) {
     this.index.clear(key);
   }
@@ -1625,28 +1881,31 @@ var OIMReactiveIndexManualArrayBased = class extends OIMReactiveIndexArrayBased
 // src/core/OIMReactiveCollectionIndexManualArrayBased.ts
 var OIMReactiveCollectionIndexManualArrayBased = class extends OIMReactiveIndexManualArrayBased {
   constructor(queue, opts) {
-    const resolveSlot = opts.collection !== void 0 ? (pk) => opts.collection.getSlotByPk(pk) : opts.resolveSlot;
+    const resolveSlot = opts.collection !== void 0 ? (pk) => opts.collection.getOrReserveSlotByPk(pk) : opts.resolveSlot;
     super(queue, {
       indexOptions: opts.indexOptions
     });
+    // Persistent per-key pk membership for O(1) `addPks` dedup (avoids rebuilding
+    // a Set from the whole bucket on every call). Kept in sync by setSlots/clear.
+    this.pksByKey = /* @__PURE__ */ new Map();
     this.resolveSlot = resolveSlot;
   }
   setPks(key, pks) {
-    this.setSlots(key, this.resolveSlots(pks));
+    const pkSet = /* @__PURE__ */ new Set();
+    for (let i = 0; i < pks.length; i++) pkSet.add(pks[i]);
+    this.pksByKey.set(key, pkSet);
+    super.setSlots(key, this.resolveSlots(pks));
   }
   addPks(key, pks) {
     if (pks.length === 0) return;
-    const existingSlots = this.index.getSlotsByKey(key);
-    const existingPks = new Set(existingSlots.map((slot) => slot.pk));
-    const nextSlots = existingSlots.slice();
-    let hasChanges = false;
+    const pkSet = this.membershipOf(key);
+    const newSlots = [];
     for (const pk of pks) {
-      if (existingPks.has(pk)) continue;
-      nextSlots.push(this.resolveRequiredSlot(pk));
-      existingPks.add(pk);
-      hasChanges = true;
+      if (pkSet.has(pk)) continue;
+      pkSet.add(pk);
+      newSlots.push(this.resolveRequiredSlot(pk));
     }
-    if (hasChanges) this.setSlots(key, nextSlots);
+    if (newSlots.length > 0) this.appendSlots(key, newSlots);
   }
   removePks(key, pks) {
     if (pks.length === 0) return;
@@ -1656,8 +1915,33 @@ var OIMReactiveCollectionIndexManualArrayBased = class extends OIMReactiveIndexM
       (slot) => !pksToRemove.has(slot.pk)
     );
     if (nextSlots.length === existingSlots.length) return;
+    const pkSet = this.pksByKey.get(key);
+    if (pkSet) {
+      for (let i = 0; i < pks.length; i++) pkSet.delete(pks[i]);
+    }
     if (nextSlots.length === 0) this.clear(key);
-    else this.setSlots(key, nextSlots);
+    else super.setSlots(key, nextSlots);
+  }
+  clear(key) {
+    if (key === void 0) this.pksByKey.clear();
+    else this.pksByKey.delete(key);
+    super.clear(key);
+  }
+  /**
+   * The membership set for a key, lazily seeded from the current bucket so it
+   * stays correct even if slots were set through a lower-level path.
+   */
+  membershipOf(key) {
+    let pkSet = this.pksByKey.get(key);
+    if (!pkSet) {
+      pkSet = /* @__PURE__ */ new Set();
+      const existing = this.index.getSlotsByKey(key);
+      for (let i = 0; i < existing.length; i++) {
+        pkSet.add(existing[i].pk);
+      }
+      this.pksByKey.set(key, pkSet);
+    }
+    return pkSet;
   }
   getEntitiesByKey(key) {
     return super.getEntitiesByKey(key);
@@ -1675,11 +1959,7 @@ var OIMReactiveCollectionIndexManualArrayBased = class extends OIMReactiveIndexM
   }
   resolveRequiredSlot(pk) {
     const slot = this.resolveSlot(pk);
-    if (!slot) {
-      throw new Error(
-        `[OIMReactiveCollectionIndexManualArrayBased]: Unable to resolve slot for PK "${String(pk)}".`
-      );
-    }
+    if (!slot) return { pk, item: void 0 };
     return slot;
   }
 };
@@ -1695,6 +1975,41 @@ var OIMIndexManualSetBased = class extends OIMIndexSetBased {
       this.emitUpdateOne(key);
     }
   }
+  /**
+   * Adds slots to a key's bucket IN PLACE (no copy of the existing Set) and
+   * emits once. O(added). Used by collection-bound indexes for fast `addPks`.
+   */
+  addSlots(key, slots) {
+    if (slots.length === 0) return;
+    let bucket = this.store.getOneByKey(key);
+    if (!bucket) {
+      bucket = /* @__PURE__ */ new Set();
+      this.store.setOneByKey(key, bucket);
+    }
+    let changed = false;
+    for (let i = 0; i < slots.length; i++) {
+      if (!bucket.has(slots[i])) {
+        bucket.add(slots[i]);
+        changed = true;
+      }
+    }
+    if (changed) this.emitUpdateOne(key);
+  }
+  /**
+   * Removes slots from a key's bucket IN PLACE (O(removed)) and emits once.
+   */
+  removeSlots(key, slots) {
+    if (slots.length === 0) return;
+    const bucket = this.store.getOneByKey(key);
+    if (!bucket) return;
+    let changed = false;
+    for (let i = 0; i < slots.length; i++) {
+      if (bucket.delete(slots[i])) changed = true;
+    }
+    if (!changed) return;
+    if (bucket.size === 0) this.store.removeOneByKey(key);
+    this.emitUpdateOne(key);
+  }
   /**
    * Clear all primary keys for a specific index key, or all keys if no key specified
    */
@@ -1739,6 +2054,12 @@ var OIMReactiveIndexManualSetBased = class extends OIMReactiveIndexSetBased {
   setSlots(key, slots) {
     this.index.setSlots(key, slots);
   }
+  addSlots(key, slots) {
+    this.index.addSlots(key, slots);
+  }
+  removeSlots(key, slots) {
+    this.index.removeSlots(key, slots);
+  }
   clear(key) {
     this.index.clear(key);
   }
@@ -1747,46 +2068,73 @@ var OIMReactiveIndexManualSetBased = class extends OIMReactiveIndexSetBased {
 // src/core/OIMReactiveCollectionIndexManualSetBased.ts
 var OIMReactiveCollectionIndexManualSetBased = class extends OIMReactiveIndexManualSetBased {
   constructor(queue, opts) {
-    const resolveSlot = opts.collection !== void 0 ? (pk) => opts.collection.getSlotByPk(pk) : opts.resolveSlot;
+    const resolveSlot = opts.collection !== void 0 ? (pk) => opts.collection.getOrReserveSlotByPk(pk) : opts.resolveSlot;
     super(queue, {
       indexOptions: opts.indexOptions
     });
+    // Persistent per-key pk → slot map for O(1) add (dedup) and O(1) remove
+    // (slot lookup by pk). Kept in sync by setPks/addPks/removePks/clear.
+    this.slotByPk = /* @__PURE__ */ new Map();
     this.resolveSlot = resolveSlot;
   }
   setPks(key, pks) {
-    this.setSlots(key, this.resolveSlots(pks));
+    const map = /* @__PURE__ */ new Map();
+    const slots = [];
+    for (let i = 0; i < pks.length; i++) {
+      const pk = pks[i];
+      const slot = this.resolveRequiredSlot(pk);
+      if (!map.has(pk)) map.set(pk, slot);
+      slots.push(slot);
+    }
+    this.slotByPk.set(key, map);
+    super.setSlots(key, slots);
   }
   addPks(key, pks) {
     if (pks.length === 0) return;
-    const existingSlots = this.index.getSlotsByKey(key);
-    const existingPks = this.index.getPksByKey(key);
-    const nextSlots = new Set(existingSlots);
-    let hasChanges = false;
+    const map = this.membershipOf(key);
+    const newSlots = [];
     for (const pk of pks) {
-      if (existingPks.has(pk)) continue;
+      if (map.has(pk)) continue;
       const slot = this.resolveRequiredSlot(pk);
-      nextSlots.add(slot);
-      existingPks.add(pk);
-      hasChanges = true;
+      map.set(pk, slot);
+      newSlots.push(slot);
     }
-    if (hasChanges) this.setSlots(key, nextSlots);
+    if (newSlots.length > 0) this.addSlots(key, newSlots);
   }
   removePks(key, pks) {
     if (pks.length === 0) return;
-    const pksToRemove = new Set(pks);
-    const existingSlots = this.index.getSlotsByKey(key);
-    const nextSlots = /* @__PURE__ */ new Set();
-    let hasChanges = false;
-    for (const slot of existingSlots) {
-      if (pksToRemove.has(slot.pk)) {
-        hasChanges = true;
-      } else {
-        nextSlots.add(slot);
+    const map = this.membershipOf(key);
+    if (map.size === 0) return;
+    const removed = [];
+    for (const pk of pks) {
+      const slot = map.get(pk);
+      if (slot) {
+        map.delete(pk);
+        removed.push(slot);
       }
     }
-    if (!hasChanges) return;
-    if (nextSlots.size === 0) this.clear(key);
-    else this.setSlots(key, nextSlots);
+    if (removed.length === 0) return;
+    if (map.size === 0) this.slotByPk.delete(key);
+    this.removeSlots(key, removed);
+  }
+  clear(key) {
+    if (key === void 0) this.slotByPk.clear();
+    else this.slotByPk.delete(key);
+    super.clear(key);
+  }
+  /**
+   * The pk→slot map for a key, lazily seeded from the current bucket so it
+   * stays correct even if slots were set through a lower-level path.
+   */
+  membershipOf(key) {
+    let map = this.slotByPk.get(key);
+    if (!map) {
+      map = /* @__PURE__ */ new Map();
+      const existing = this.index.getSlotsByKey(key);
+      for (const slot of existing) map.set(slot.pk, slot);
+      this.slotByPk.set(key, map);
+    }
+    return map;
   }
   getEntitiesByKey(key) {
     return super.getEntitiesByKey(key);
@@ -1794,18 +2142,9 @@ var OIMReactiveCollectionIndexManualSetBased = class extends OIMReactiveIndexMan
   getEntitiesByKeys(keys) {
     return super.getEntitiesByKeys(keys);
   }
-  resolveSlots(pks) {
-    const slots = /* @__PURE__ */ new Set();
-    for (const pk of pks) slots.add(this.resolveRequiredSlot(pk));
-    return slots;
-  }
   resolveRequiredSlot(pk) {
     const slot = this.resolveSlot(pk);
-    if (!slot) {
-      throw new Error(
-        `[OIMReactiveCollectionIndexManualSetBased]: Unable to resolve slot for PK "${String(pk)}".`
-      );
-    }
+    if (!slot) return { pk, item: void 0 };
     return slot;
   }
 };
@@ -1920,17 +2259,56 @@ var OIMDerivedCollectionIndexArrayBased = class extends OIMReactiveCollectionInd
       indexOptions: opts.indexOptions
     });
     this.keysByPk = /* @__PURE__ */ new Map();
+    // Last known sort value per pk (only when `orderBy` is used), so an update
+    // touching an unrelated field can skip re-sorting when the value is unchanged.
+    this.orderValueByPk = /* @__PURE__ */ new Map();
     this.onCollectionUpdate = (pks) => {
       if (pks.length === 0) {
         this.rebuildFromCollection();
         return;
       }
-      const affectedKeys = /* @__PURE__ */ new Set();
+      const ordered = !!(this.compareEntities || this.orderBy);
+      const keysToSort = ordered ? /* @__PURE__ */ new Set() : null;
       for (const pk of pks) {
-        this.trackPkKeys(pk, affectedKeys);
+        const prevKeys = this.keysByPk.get(pk) ?? /* @__PURE__ */ new Set();
+        const slot = this.collection.getSlotByPk(pk);
+        const entity = slot?.item;
+        const nextKeys = entity === void 0 ? /* @__PURE__ */ new Set() : new Set(this.normalizeKeys(this.selectIndexKeys(entity)));
+        let orderChanged = false;
+        if (this.orderBy) {
+          if (entity === void 0 || nextKeys.size === 0) {
+            this.orderValueByPk.delete(pk);
+          } else {
+            const value = this.orderBy(entity);
+            orderChanged = !this.orderValueByPk.has(pk) || this.orderValueByPk.get(pk) !== value;
+            this.orderValueByPk.set(pk, value);
+          }
+        } else if (this.compareEntities && entity !== void 0) {
+          orderChanged = true;
+        }
+        for (const key of prevKeys) {
+          if (!nextKeys.has(key)) this.removePks(key, [pk]);
+        }
+        if (entity !== void 0) {
+          for (const key of nextKeys) {
+            if (!prevKeys.has(key)) {
+              this.addPks(key, [pk]);
+              keysToSort?.add(key);
+            } else if (orderChanged) {
+              keysToSort?.add(key);
+            }
+          }
+        }
+        if (nextKeys.size === 0) this.keysByPk.delete(pk);
+        else this.keysByPk.set(pk, nextKeys);
       }
-      for (const key of affectedKeys) {
-        this.rebuildKey(key);
+      if (keysToSort) {
+        for (const key of keysToSort) {
+          this.setSlots(
+            key,
+            this.sortSlots(this.index.getSlotsByKey(key))
+          );
+        }
       }
     };
     this.collection = collection;
@@ -1947,6 +2325,7 @@ var OIMDerivedCollectionIndexArrayBased = class extends OIMReactiveCollectionInd
   }
   rebuildFromCollection() {
     this.keysByPk.clear();
+    this.orderValueByPk.clear();
     super.clear();
     const slotsByKey = /* @__PURE__ */ new Map();
     const slots = this.collection.getAllSlots();
@@ -1955,6 +2334,9 @@ var OIMDerivedCollectionIndexArrayBased = class extends OIMReactiveCollectionInd
       const keys = this.normalizeKeys(this.selectIndexKeys(slot.item));
       if (keys.length === 0) continue;
       this.keysByPk.set(slot.pk, new Set(keys));
+      if (this.orderBy) {
+        this.orderValueByPk.set(slot.pk, this.orderBy(slot.item));
+      }
       for (const key of keys) {
         let slotsForKey = slotsByKey.get(key);
         if (!slotsForKey) {
@@ -1971,6 +2353,7 @@ var OIMDerivedCollectionIndexArrayBased = class extends OIMReactiveCollectionInd
   clear(key) {
     if (key === void 0) {
       this.keysByPk.clear();
+      this.orderValueByPk.clear();
     } else {
       for (const keys of this.keysByPk.values()) {
         keys.delete(key);
@@ -1981,37 +2364,11 @@ var OIMDerivedCollectionIndexArrayBased = class extends OIMReactiveCollectionInd
   destroy() {
     this.unsubscribeFromCollection();
     this.keysByPk.clear();
+    this.orderValueByPk.clear();
     super.destroy();
   }
-  trackPkKeys(pk, affectedKeys) {
-    const prevKeys = this.keysByPk.get(pk) ?? /* @__PURE__ */ new Set();
-    for (const key of prevKeys) affectedKeys.add(key);
-    const slot = this.collection.getSlotByPk(pk);
-    const entity = slot?.item;
-    const nextKeys = entity === void 0 ? /* @__PURE__ */ new Set() : new Set(this.normalizeKeys(this.selectIndexKeys(entity)));
-    for (const key of nextKeys) affectedKeys.add(key);
-    if (nextKeys.size === 0) {
-      this.keysByPk.delete(pk);
-    } else {
-      this.keysByPk.set(pk, nextKeys);
-    }
-  }
-  rebuildKey(key) {
-    const keySlots = [];
-    const slots = this.collection.getAllSlots();
-    for (const slot of slots) {
-      if (slot.item === void 0) continue;
-      const keys = this.keysByPk.get(slot.pk);
-      if (keys?.has(key)) keySlots.push(slot);
-    }
-    if (keySlots.length === 0) {
-      super.clear(key);
-    } else {
-      this.setSlots(key, this.sortSlots(keySlots));
-    }
-  }
   sortSlots(slots) {
-    if (!this.compareEntities && !this.orderBy) return slots;
+    if (!this.compareEntities && !this.orderBy) return slots.slice();
     return slots.slice().sort((a, b) => {
       const aItem = a.item;
       const bItem = b.item;
@@ -2294,6 +2651,11 @@ var OIMComparatorFactory = class {
   }
 };
 
+// src/core/createInPlaceEntityUpdater.ts
+function createInPlaceEntityUpdater() {
+  return (draft, prev) => Object.assign(prev, draft);
+}
+
 // src/core/OIMEventQueue.ts
 var OIMEventQueue = class {
   constructor(options = {}) {
@@ -3729,6 +4091,7 @@ var OIMIndexPksByKeysArrayBasedSelector = class extends OIMSelector {
   EOIMEventQueueSchedulerEventType,
   EOIMIndexEventType,
   EOIMObjectEventType,
+  OIMCarrierKeyedEmitter,
   OIMCollection,
   OIMCollectionByPkSelector,
   OIMCollectionByPksSelector,
@@ -3796,6 +4159,7 @@ var OIMIndexPksByKeysArrayBasedSelector = class extends OIMSelector {
   OIMReactiveIndexSetBased,
   OIMReactiveObject,
   OIMSelector,
+  createInPlaceEntityUpdater,
   createOIMCollectionIndexFactory,
   createOIMCollectionKit
 });