@oimdb/core 2.0.1 → 2.2.0

package/README.md

@@ -94,7 +94,7 @@ Use the `dx` factories when you want a concise entrypoint without changing the u
 
 ```typescript
 import {
-    createOIMCollectionContext,
+    createOIMCollectionKit,
     OIMEventQueue,
     OIMEventQueueSchedulerFactory
 } from '@oimdb/core';
@@ -108,7 +108,7 @@ type User = {
 const queue = new OIMEventQueue({
     scheduler: OIMEventQueueSchedulerFactory.createMicrotask()
 });
-const users = createOIMCollectionContext<User, string>(queue, {
+const users = createOIMCollectionKit<User, string>(queue, {
     selectPk: user => user.id,
 });
 
@@ -191,7 +191,7 @@ OIMDB provides two types of indexes optimized for different use cases:
 
 Indexes are slot-backed internally and expose PK projections through `getPksByKey` (`Set<TPk>` for SetBased, `TPk[]` for ArrayBased). Raw indexes can be used as standalone PK/slot structures. When an index belongs to a collection, prefer `OIMReactiveCollectionIndexManual*`; it binds the collection at construction time so PK writes resolve canonical collection slots without a later lifecycle setter.
 
-For most app-level entity relations, start with `createOIMCollectionContext(...).indexFactory.derivedSetIndex(...)` or `.derivedArrayIndex(...)`. The manual indexes below are the advanced path for externally maintained memberships such as search results, permissions, or server-provided order.
+For most app-level entity relations, start with `createOIMCollectionKit(...).indexFactory.derivedSetIndex(...)` or `.derivedArrayIndex(...)`. The manual indexes below are the advanced path for externally maintained memberships such as search results, permissions, or server-provided order.
 
 #### SetBased Indexes (for incremental updates)
 
@@ -1158,7 +1158,7 @@ npm install @oimdb/react
 Create your collections outside React, wire them up once, then use hooks inside components:
 
 ```typescript
-import { createOIMCollectionContext, OIMEventQueue } from '@oimdb/core';
+import { createOIMCollectionKit, OIMEventQueue } from '@oimdb/core';
 import {
     OIMCollectionsProvider,
     useOIMCollectionsContext,
@@ -1169,7 +1169,7 @@ import {
 // --- store.ts (created once, outside React) ---
 const queue = new OIMEventQueue();
 const { collection: users, indexFactory } =
-    createOIMCollectionContext<User, string>(queue, { selectPk: (u) => u.id });
+    createOIMCollectionKit<User, string>(queue, { selectPk: (u) => u.id });
 const byTeam = indexFactory.derivedSetIndex((u) => [u.teamId]);
 export const collections = { users };
 export { byTeam };
@@ -1268,11 +1268,11 @@ unsubscribe();
 #### `createOIMReactiveCollection<TEntity, TPk>(queue, opts?)`
 Creates an `OIMReactiveCollection<TEntity, TPk>` with less constructor noise.
 
-#### `createOIMCollectionContext<TEntity, TPk>(queue, opts?)`
+#### `createOIMCollectionKit<TEntity, TPk>(queue, opts?)`
 Creates a small facade:
 
 ```typescript
-type TOIMCollectionContext<TEntity, TPk> = {
+type TOIMCollectionKit<TEntity, TPk> = {
     queue: OIMEventQueue;
     collection: OIMReactiveCollection<TEntity, TPk>;
     relations: OIMCollectionRelations<TEntity, TPk>;

package/dist/index.cjs

@@ -93,8 +93,8 @@ __export(index_exports, {
   OIMReactiveIndexSetBased: () => OIMReactiveIndexSetBased,
   OIMReactiveObject: () => OIMReactiveObject,
   OIMSelector: () => OIMSelector,
-  createOIMCollectionContext: () => createOIMCollectionContext,
-  createOIMCollectionIndexFactory: () => createOIMCollectionIndexFactory
+  createOIMCollectionIndexFactory: () => createOIMCollectionIndexFactory,
+  createOIMCollectionKit: () => createOIMCollectionKit
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -879,17 +879,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 = [];
@@ -922,6 +944,11 @@ var OIMCollectionStoreMapDriven = class extends OIMCollectionStore {
     const slot = this.slots.get(pk);
     if (slot) slot.item = void 0;
     this.slots.delete(pk);
+    const reserved = this.reservedSlots.get(pk);
+    if (reserved) {
+      reserved.item = void 0;
+      this.reservedSlots.delete(pk);
+    }
   }
   removeManyByPks(pks) {
     for (const pk of pks) {
@@ -959,6 +986,10 @@ var OIMCollectionStoreMapDriven = class extends OIMCollectionStore {
       slot.item = void 0;
     }
     this.slots.clear();
+    for (const slot of this.reservedSlots.values()) {
+      slot.item = void 0;
+    }
+    this.reservedSlots.clear();
   }
   getAllPks() {
     return Array.from(this.slots.keys());
@@ -1000,6 +1031,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);
   }
@@ -1625,7 +1659,7 @@ 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
     });
@@ -1675,11 +1709,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;
   }
 };
@@ -1747,7 +1777,7 @@ 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
     });
@@ -1801,11 +1831,7 @@ var OIMReactiveCollectionIndexManualSetBased = class extends OIMReactiveIndexMan
   }
   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;
   }
 };
@@ -2967,8 +2993,8 @@ var OIMCollectionSelectors = class {
   }
 };
 
-// src/dx/OIMCollectionContext.ts
-function createOIMCollectionContext(queue, opts) {
+// src/dx/OIMCollectionKit.ts
+function createOIMCollectionKit(queue, opts) {
   const collection = new OIMReactiveCollection(queue, opts);
   const indexFactory = new OIMCollectionIndexFactory(queue, collection);
   const select = new OIMCollectionSelectors(queue, collection);
@@ -3796,6 +3822,6 @@ var OIMIndexPksByKeysArrayBasedSelector = class extends OIMSelector {
   OIMReactiveIndexSetBased,
   OIMReactiveObject,
   OIMSelector,
-  createOIMCollectionContext,
-  createOIMCollectionIndexFactory
+  createOIMCollectionIndexFactory,
+  createOIMCollectionKit
 });

package/dist/index.d.cts

@@ -10,6 +10,13 @@ type TOIMEntitySlotResolver<TPk extends TOIMPk> = (pk: TPk) => TOIMAnyEntitySlot
 declare abstract class OIMCollectionStore<TEntity extends object, TPk extends TOIMPk> {
     abstract setOneByPk(pk: TPk, entity: TEntity): TOIMEntitySlot<TEntity, TPk>;
     abstract getSlotByPk(pk: TPk): TOIMEntitySlot<TEntity, TPk> | undefined;
+    /**
+     * Returns the canonical slot for `pk`, creating a reserved empty slot
+     * (`item: undefined`) if no entity exists yet. The reserved slot is a stable
+     * reference that fills in when the entity is later written, so indexes can
+     * hold it ahead of the entity's arrival without crashing.
+     */
+    abstract getOrReserveSlotByPk(pk: TPk): TOIMEntitySlot<TEntity, TPk>;
     abstract getSlotsByPks(pks: readonly TPk[]): TOIMEntitySlot<TEntity, TPk>[];
     abstract getAllSlots(): TOIMEntitySlot<TEntity, TPk>[];
     abstract removeOneByPk(pk: TPk): void;
@@ -381,6 +388,7 @@ declare class OIMCollection<TEntity extends object, TPk extends TOIMPk> {
     getOneByPk(pk: TPk): TEntity | undefined;
     getManyByPks(pks: readonly TPk[]): TEntity[];
     getSlotByPk(pk: TPk): TOIMEntitySlot<TEntity, TPk> | undefined;
+    getOrReserveSlotByPk(pk: TPk): TOIMEntitySlot<TEntity, TPk>;
     getSlotsByPks(pks: readonly TPk[]): TOIMEntitySlot<TEntity, TPk>[];
     getAllSlots(): TOIMEntitySlot<TEntity, TPk>[];
     upsertOneByPk(pk: TPk, entity: Partial<TEntity>): TOIMEntitySlot<TEntity, TPk>;
@@ -849,7 +857,9 @@ declare class OIMReactiveObject<TKey extends string, TValue> extends OIMObject<T
 
 declare class OIMCollectionStoreMapDriven<TEntity extends object, TPk extends TOIMPk> extends OIMCollectionStore<TEntity, TPk> {
     protected readonly slots: Map<TPk, TOIMEntitySlot<TEntity, TPk>>;
+    protected readonly reservedSlots: Map<TPk, TOIMEntitySlot<TEntity, TPk>>;
     setOneByPk(pk: TPk, entity: TEntity): TOIMEntitySlot<TEntity, TPk>;
+    getOrReserveSlotByPk(pk: TPk): TOIMEntitySlot<TEntity, TPk>;
     setManyByPks(pks: readonly TPk[], entities: TEntity[]): TOIMEntitySlot<TEntity, TPk>[];
     getSlotByPk(pk: TPk): TOIMEntitySlot<TEntity, TPk> | undefined;
     getSlotsByPks(pks: readonly TPk[]): TOIMEntitySlot<TEntity, TPk>[];
@@ -1064,14 +1074,14 @@ declare class OIMCollectionSelectors<TEntity extends object, TPk extends TOIMPk>
 }
 
 type TOIMReactiveCollectionFactoryOptions<TEntity extends object, TPk extends TOIMPk> = TOIMCollectionOptions<TEntity, TPk>;
-type TOIMCollectionContext<TEntity extends object, TPk extends TOIMPk> = {
+type TOIMCollectionKit<TEntity extends object, TPk extends TOIMPk> = {
     queue: OIMEventQueue;
     collection: OIMReactiveCollection<TEntity, TPk>;
     indexFactory: OIMCollectionIndexFactory<TEntity, TPk>;
     select: OIMCollectionSelectors<TEntity, TPk>;
 };
 
-declare function createOIMCollectionContext<TEntity extends object, TPk extends TOIMPk>(queue: OIMEventQueue, opts?: TOIMReactiveCollectionFactoryOptions<TEntity, TPk>): TOIMCollectionContext<TEntity, TPk>;
+declare function createOIMCollectionKit<TEntity extends object, TPk extends TOIMPk>(queue: OIMEventQueue, opts?: TOIMReactiveCollectionFactoryOptions<TEntity, TPk>): TOIMCollectionKit<TEntity, TPk>;
 
 type TOIMFieldKey<TEntity extends object> = keyof TEntity & string;
 /**
@@ -1479,4 +1489,4 @@ declare class OIMEntitiesByIndexKeyArrayBasedSelector<TEntity extends object, TP
     protected areEqual(prev: readonly (TEntity | undefined)[], next: readonly (TEntity | undefined)[]): boolean;
 }
 
-export { EOIMCollectionEventType, EOIMComputedEventType, EOIMEventQueueEventType, EOIMEventQueueSchedulerEventType, EOIMIndexEventType, EOIMObjectEventType, type IOIMComputedEventSource, type IOIMEffectDependency, type IOIMEventQueueSchedulerEvents, type IOIMIndexStore, OIMCollection, OIMCollectionByPkSelector, OIMCollectionByPksSelector, OIMCollectionChangedFields, OIMCollectionIndexFactory, OIMCollectionIndexManualOrderedArrayBased, OIMCollectionOrderedListCommandStream, OIMCollectionSelectors, OIMCollectionStore, OIMCollectionStoreMapDriven, OIMComparatorFactory, OIMComputeRuntime, OIMComputed, OIMDBSettings, OIMDerivedCollectionIndexArrayBased, OIMDerivedCollectionIndexSetBased, OIMEffect, OIMEffectDependencyComputed, OIMEffectDependencyKeyed, OIMEffectDependencyKeyedCollection, OIMEffectDependencyKeyedIndex, OIMEffectDependencyKeyedObject, OIMEntitiesByIndexKeyArrayBasedSelector, OIMEntitiesByIndexKeySetBasedSelector, OIMEntityUpdaterFactory, OIMEventEmitter, OIMEventQueue, OIMEventQueueScheduler, OIMEventQueueSchedulerAnimationFrame, OIMEventQueueSchedulerFactory, OIMEventQueueSchedulerImmediate, OIMEventQueueSchedulerMicrotask, OIMEventQueueSchedulerTimeout, OIMIndex, OIMIndexArrayBased, OIMIndexComparatorFactory, OIMIndexManualArrayBased, OIMIndexManualOrderedArrayBased, OIMIndexManualSetBased, OIMIndexPksByKeyArrayBasedSelector, OIMIndexPksByKeySetBasedSelector, OIMIndexPksByKeysArrayBasedSelector, OIMIndexPksByKeysSetBasedSelector, OIMIndexSetBased, OIMIndexStoreArrayBased, OIMIndexStoreMapDrivenArrayBased, OIMIndexStoreMapDrivenSetBased, OIMIndexStoreSetBased, OIMMap2Keys, OIMObject, OIMObjectStore, OIMObjectStoreMapDriven, OIMObjectStoreRecordDriven, OIMObjectValueByKeySelector, OIMObjectValuesByKeysSelector, OIMOrderedListCommandStream, OIMPkSelectorFactory, OIMReactiveCollection, OIMReactiveCollectionIndexManualArrayBased, OIMReactiveCollectionIndexManualSetBased, OIMReactiveIndex, OIMReactiveIndexArrayBased, OIMReactiveIndexManualArrayBased, OIMReactiveIndexManualSetBased, OIMReactiveIndexSetBased, OIMReactiveObject, OIMSelector, type TOIMAnyEntitySlot, type TOIMCollectionContext, type TOIMCollectionEntitiesSelector, type TOIMCollectionEntitySelector, type TOIMCollectionIndexArrayBasedOptions, type TOIMCollectionIndexSetBasedOptions, type TOIMCollectionOptions, type TOIMCollectionOrderedIndexOptions, type TOIMCollectionOrderedListCommandStreamOptions, type TOIMCollectionUpdatePayload, type TOIMComparator, type TOIMComputedOptions, type TOIMComputedUpdatePayload, type TOIMDerivedCollectionIndexArrayBasedOptions, type TOIMDerivedCollectionIndexSetBasedOptions, type TOIMDerivedEntityComparator, type TOIMDerivedEntityOrderSelector, type TOIMDerivedEntityOrderValue, type TOIMDerivedIndexKeySelector, type TOIMEffectOptions, type TOIMEntitySlot, type TOIMEntitySlotResolver, type TOIMEntityUpdater, type TOIMEventHandler, type TOIMEventQueueOptions, type TOIMIndexComparator, type TOIMIndexKey, type TOIMIndexOptionsArrayBased, type TOIMIndexOptionsSetBased, type TOIMIndexPksUpdatePayload, type TOIMIndexUpdatePayload, type TOIMObjectOptions, type TOIMOrderedListCommand, type TOIMPk, type TOIMPkSelector, type TOIMReactiveCollectionFactoryOptions, type TOIMRelationsArrayIndexOptions, type TOIMRelationsDerivedArrayIndexOptions, type TOIMRelationsDerivedSetIndexOptions, type TOIMRelationsOrderedListOptions, type TOIMRelationsSetIndexOptions, type TOIMSchedulerOptions, type TOIMSchedulerType, type TOIMUpdatePayload, createOIMCollectionContext, createOIMCollectionIndexFactory };
+export { EOIMCollectionEventType, EOIMComputedEventType, EOIMEventQueueEventType, EOIMEventQueueSchedulerEventType, EOIMIndexEventType, EOIMObjectEventType, type IOIMComputedEventSource, type IOIMEffectDependency, type IOIMEventQueueSchedulerEvents, type IOIMIndexStore, OIMCollection, OIMCollectionByPkSelector, OIMCollectionByPksSelector, OIMCollectionChangedFields, OIMCollectionIndexFactory, OIMCollectionIndexManualOrderedArrayBased, OIMCollectionOrderedListCommandStream, OIMCollectionSelectors, OIMCollectionStore, OIMCollectionStoreMapDriven, OIMComparatorFactory, OIMComputeRuntime, OIMComputed, OIMDBSettings, OIMDerivedCollectionIndexArrayBased, OIMDerivedCollectionIndexSetBased, OIMEffect, OIMEffectDependencyComputed, OIMEffectDependencyKeyed, OIMEffectDependencyKeyedCollection, OIMEffectDependencyKeyedIndex, OIMEffectDependencyKeyedObject, OIMEntitiesByIndexKeyArrayBasedSelector, OIMEntitiesByIndexKeySetBasedSelector, OIMEntityUpdaterFactory, OIMEventEmitter, OIMEventQueue, OIMEventQueueScheduler, OIMEventQueueSchedulerAnimationFrame, OIMEventQueueSchedulerFactory, OIMEventQueueSchedulerImmediate, OIMEventQueueSchedulerMicrotask, OIMEventQueueSchedulerTimeout, OIMIndex, OIMIndexArrayBased, OIMIndexComparatorFactory, OIMIndexManualArrayBased, OIMIndexManualOrderedArrayBased, OIMIndexManualSetBased, OIMIndexPksByKeyArrayBasedSelector, OIMIndexPksByKeySetBasedSelector, OIMIndexPksByKeysArrayBasedSelector, OIMIndexPksByKeysSetBasedSelector, OIMIndexSetBased, OIMIndexStoreArrayBased, OIMIndexStoreMapDrivenArrayBased, OIMIndexStoreMapDrivenSetBased, OIMIndexStoreSetBased, OIMMap2Keys, OIMObject, OIMObjectStore, OIMObjectStoreMapDriven, OIMObjectStoreRecordDriven, OIMObjectValueByKeySelector, OIMObjectValuesByKeysSelector, OIMOrderedListCommandStream, OIMPkSelectorFactory, OIMReactiveCollection, OIMReactiveCollectionIndexManualArrayBased, OIMReactiveCollectionIndexManualSetBased, OIMReactiveIndex, OIMReactiveIndexArrayBased, OIMReactiveIndexManualArrayBased, OIMReactiveIndexManualSetBased, OIMReactiveIndexSetBased, OIMReactiveObject, OIMSelector, type TOIMAnyEntitySlot, type TOIMCollectionEntitiesSelector, type TOIMCollectionEntitySelector, type TOIMCollectionIndexArrayBasedOptions, type TOIMCollectionIndexSetBasedOptions, type TOIMCollectionKit, type TOIMCollectionOptions, type TOIMCollectionOrderedIndexOptions, type TOIMCollectionOrderedListCommandStreamOptions, type TOIMCollectionUpdatePayload, type TOIMComparator, type TOIMComputedOptions, type TOIMComputedUpdatePayload, type TOIMDerivedCollectionIndexArrayBasedOptions, type TOIMDerivedCollectionIndexSetBasedOptions, type TOIMDerivedEntityComparator, type TOIMDerivedEntityOrderSelector, type TOIMDerivedEntityOrderValue, type TOIMDerivedIndexKeySelector, type TOIMEffectOptions, type TOIMEntitySlot, type TOIMEntitySlotResolver, type TOIMEntityUpdater, type TOIMEventHandler, type TOIMEventQueueOptions, type TOIMIndexComparator, type TOIMIndexKey, type TOIMIndexOptionsArrayBased, type TOIMIndexOptionsSetBased, type TOIMIndexPksUpdatePayload, type TOIMIndexUpdatePayload, type TOIMObjectOptions, type TOIMOrderedListCommand, type TOIMPk, type TOIMPkSelector, type TOIMReactiveCollectionFactoryOptions, type TOIMRelationsArrayIndexOptions, type TOIMRelationsDerivedArrayIndexOptions, type TOIMRelationsDerivedSetIndexOptions, type TOIMRelationsOrderedListOptions, type TOIMRelationsSetIndexOptions, type TOIMSchedulerOptions, type TOIMSchedulerType, type TOIMUpdatePayload, createOIMCollectionIndexFactory, createOIMCollectionKit };

package/dist/index.d.ts

@@ -10,6 +10,13 @@ type TOIMEntitySlotResolver<TPk extends TOIMPk> = (pk: TPk) => TOIMAnyEntitySlot
 declare abstract class OIMCollectionStore<TEntity extends object, TPk extends TOIMPk> {
     abstract setOneByPk(pk: TPk, entity: TEntity): TOIMEntitySlot<TEntity, TPk>;
     abstract getSlotByPk(pk: TPk): TOIMEntitySlot<TEntity, TPk> | undefined;
+    /**
+     * Returns the canonical slot for `pk`, creating a reserved empty slot
+     * (`item: undefined`) if no entity exists yet. The reserved slot is a stable
+     * reference that fills in when the entity is later written, so indexes can
+     * hold it ahead of the entity's arrival without crashing.
+     */
+    abstract getOrReserveSlotByPk(pk: TPk): TOIMEntitySlot<TEntity, TPk>;
     abstract getSlotsByPks(pks: readonly TPk[]): TOIMEntitySlot<TEntity, TPk>[];
     abstract getAllSlots(): TOIMEntitySlot<TEntity, TPk>[];
     abstract removeOneByPk(pk: TPk): void;
@@ -381,6 +388,7 @@ declare class OIMCollection<TEntity extends object, TPk extends TOIMPk> {
     getOneByPk(pk: TPk): TEntity | undefined;
     getManyByPks(pks: readonly TPk[]): TEntity[];
     getSlotByPk(pk: TPk): TOIMEntitySlot<TEntity, TPk> | undefined;
+    getOrReserveSlotByPk(pk: TPk): TOIMEntitySlot<TEntity, TPk>;
     getSlotsByPks(pks: readonly TPk[]): TOIMEntitySlot<TEntity, TPk>[];
     getAllSlots(): TOIMEntitySlot<TEntity, TPk>[];
     upsertOneByPk(pk: TPk, entity: Partial<TEntity>): TOIMEntitySlot<TEntity, TPk>;
@@ -849,7 +857,9 @@ declare class OIMReactiveObject<TKey extends string, TValue> extends OIMObject<T
 
 declare class OIMCollectionStoreMapDriven<TEntity extends object, TPk extends TOIMPk> extends OIMCollectionStore<TEntity, TPk> {
     protected readonly slots: Map<TPk, TOIMEntitySlot<TEntity, TPk>>;
+    protected readonly reservedSlots: Map<TPk, TOIMEntitySlot<TEntity, TPk>>;
     setOneByPk(pk: TPk, entity: TEntity): TOIMEntitySlot<TEntity, TPk>;
+    getOrReserveSlotByPk(pk: TPk): TOIMEntitySlot<TEntity, TPk>;
     setManyByPks(pks: readonly TPk[], entities: TEntity[]): TOIMEntitySlot<TEntity, TPk>[];
     getSlotByPk(pk: TPk): TOIMEntitySlot<TEntity, TPk> | undefined;
     getSlotsByPks(pks: readonly TPk[]): TOIMEntitySlot<TEntity, TPk>[];
@@ -1064,14 +1074,14 @@ declare class OIMCollectionSelectors<TEntity extends object, TPk extends TOIMPk>
 }
 
 type TOIMReactiveCollectionFactoryOptions<TEntity extends object, TPk extends TOIMPk> = TOIMCollectionOptions<TEntity, TPk>;
-type TOIMCollectionContext<TEntity extends object, TPk extends TOIMPk> = {
+type TOIMCollectionKit<TEntity extends object, TPk extends TOIMPk> = {
     queue: OIMEventQueue;
     collection: OIMReactiveCollection<TEntity, TPk>;
     indexFactory: OIMCollectionIndexFactory<TEntity, TPk>;
     select: OIMCollectionSelectors<TEntity, TPk>;
 };
 
-declare function createOIMCollectionContext<TEntity extends object, TPk extends TOIMPk>(queue: OIMEventQueue, opts?: TOIMReactiveCollectionFactoryOptions<TEntity, TPk>): TOIMCollectionContext<TEntity, TPk>;
+declare function createOIMCollectionKit<TEntity extends object, TPk extends TOIMPk>(queue: OIMEventQueue, opts?: TOIMReactiveCollectionFactoryOptions<TEntity, TPk>): TOIMCollectionKit<TEntity, TPk>;
 
 type TOIMFieldKey<TEntity extends object> = keyof TEntity & string;
 /**
@@ -1479,4 +1489,4 @@ declare class OIMEntitiesByIndexKeyArrayBasedSelector<TEntity extends object, TP
     protected areEqual(prev: readonly (TEntity | undefined)[], next: readonly (TEntity | undefined)[]): boolean;
 }
 
-export { EOIMCollectionEventType, EOIMComputedEventType, EOIMEventQueueEventType, EOIMEventQueueSchedulerEventType, EOIMIndexEventType, EOIMObjectEventType, type IOIMComputedEventSource, type IOIMEffectDependency, type IOIMEventQueueSchedulerEvents, type IOIMIndexStore, OIMCollection, OIMCollectionByPkSelector, OIMCollectionByPksSelector, OIMCollectionChangedFields, OIMCollectionIndexFactory, OIMCollectionIndexManualOrderedArrayBased, OIMCollectionOrderedListCommandStream, OIMCollectionSelectors, OIMCollectionStore, OIMCollectionStoreMapDriven, OIMComparatorFactory, OIMComputeRuntime, OIMComputed, OIMDBSettings, OIMDerivedCollectionIndexArrayBased, OIMDerivedCollectionIndexSetBased, OIMEffect, OIMEffectDependencyComputed, OIMEffectDependencyKeyed, OIMEffectDependencyKeyedCollection, OIMEffectDependencyKeyedIndex, OIMEffectDependencyKeyedObject, OIMEntitiesByIndexKeyArrayBasedSelector, OIMEntitiesByIndexKeySetBasedSelector, OIMEntityUpdaterFactory, OIMEventEmitter, OIMEventQueue, OIMEventQueueScheduler, OIMEventQueueSchedulerAnimationFrame, OIMEventQueueSchedulerFactory, OIMEventQueueSchedulerImmediate, OIMEventQueueSchedulerMicrotask, OIMEventQueueSchedulerTimeout, OIMIndex, OIMIndexArrayBased, OIMIndexComparatorFactory, OIMIndexManualArrayBased, OIMIndexManualOrderedArrayBased, OIMIndexManualSetBased, OIMIndexPksByKeyArrayBasedSelector, OIMIndexPksByKeySetBasedSelector, OIMIndexPksByKeysArrayBasedSelector, OIMIndexPksByKeysSetBasedSelector, OIMIndexSetBased, OIMIndexStoreArrayBased, OIMIndexStoreMapDrivenArrayBased, OIMIndexStoreMapDrivenSetBased, OIMIndexStoreSetBased, OIMMap2Keys, OIMObject, OIMObjectStore, OIMObjectStoreMapDriven, OIMObjectStoreRecordDriven, OIMObjectValueByKeySelector, OIMObjectValuesByKeysSelector, OIMOrderedListCommandStream, OIMPkSelectorFactory, OIMReactiveCollection, OIMReactiveCollectionIndexManualArrayBased, OIMReactiveCollectionIndexManualSetBased, OIMReactiveIndex, OIMReactiveIndexArrayBased, OIMReactiveIndexManualArrayBased, OIMReactiveIndexManualSetBased, OIMReactiveIndexSetBased, OIMReactiveObject, OIMSelector, type TOIMAnyEntitySlot, type TOIMCollectionContext, type TOIMCollectionEntitiesSelector, type TOIMCollectionEntitySelector, type TOIMCollectionIndexArrayBasedOptions, type TOIMCollectionIndexSetBasedOptions, type TOIMCollectionOptions, type TOIMCollectionOrderedIndexOptions, type TOIMCollectionOrderedListCommandStreamOptions, type TOIMCollectionUpdatePayload, type TOIMComparator, type TOIMComputedOptions, type TOIMComputedUpdatePayload, type TOIMDerivedCollectionIndexArrayBasedOptions, type TOIMDerivedCollectionIndexSetBasedOptions, type TOIMDerivedEntityComparator, type TOIMDerivedEntityOrderSelector, type TOIMDerivedEntityOrderValue, type TOIMDerivedIndexKeySelector, type TOIMEffectOptions, type TOIMEntitySlot, type TOIMEntitySlotResolver, type TOIMEntityUpdater, type TOIMEventHandler, type TOIMEventQueueOptions, type TOIMIndexComparator, type TOIMIndexKey, type TOIMIndexOptionsArrayBased, type TOIMIndexOptionsSetBased, type TOIMIndexPksUpdatePayload, type TOIMIndexUpdatePayload, type TOIMObjectOptions, type TOIMOrderedListCommand, type TOIMPk, type TOIMPkSelector, type TOIMReactiveCollectionFactoryOptions, type TOIMRelationsArrayIndexOptions, type TOIMRelationsDerivedArrayIndexOptions, type TOIMRelationsDerivedSetIndexOptions, type TOIMRelationsOrderedListOptions, type TOIMRelationsSetIndexOptions, type TOIMSchedulerOptions, type TOIMSchedulerType, type TOIMUpdatePayload, createOIMCollectionContext, createOIMCollectionIndexFactory };
+export { EOIMCollectionEventType, EOIMComputedEventType, EOIMEventQueueEventType, EOIMEventQueueSchedulerEventType, EOIMIndexEventType, EOIMObjectEventType, type IOIMComputedEventSource, type IOIMEffectDependency, type IOIMEventQueueSchedulerEvents, type IOIMIndexStore, OIMCollection, OIMCollectionByPkSelector, OIMCollectionByPksSelector, OIMCollectionChangedFields, OIMCollectionIndexFactory, OIMCollectionIndexManualOrderedArrayBased, OIMCollectionOrderedListCommandStream, OIMCollectionSelectors, OIMCollectionStore, OIMCollectionStoreMapDriven, OIMComparatorFactory, OIMComputeRuntime, OIMComputed, OIMDBSettings, OIMDerivedCollectionIndexArrayBased, OIMDerivedCollectionIndexSetBased, OIMEffect, OIMEffectDependencyComputed, OIMEffectDependencyKeyed, OIMEffectDependencyKeyedCollection, OIMEffectDependencyKeyedIndex, OIMEffectDependencyKeyedObject, OIMEntitiesByIndexKeyArrayBasedSelector, OIMEntitiesByIndexKeySetBasedSelector, OIMEntityUpdaterFactory, OIMEventEmitter, OIMEventQueue, OIMEventQueueScheduler, OIMEventQueueSchedulerAnimationFrame, OIMEventQueueSchedulerFactory, OIMEventQueueSchedulerImmediate, OIMEventQueueSchedulerMicrotask, OIMEventQueueSchedulerTimeout, OIMIndex, OIMIndexArrayBased, OIMIndexComparatorFactory, OIMIndexManualArrayBased, OIMIndexManualOrderedArrayBased, OIMIndexManualSetBased, OIMIndexPksByKeyArrayBasedSelector, OIMIndexPksByKeySetBasedSelector, OIMIndexPksByKeysArrayBasedSelector, OIMIndexPksByKeysSetBasedSelector, OIMIndexSetBased, OIMIndexStoreArrayBased, OIMIndexStoreMapDrivenArrayBased, OIMIndexStoreMapDrivenSetBased, OIMIndexStoreSetBased, OIMMap2Keys, OIMObject, OIMObjectStore, OIMObjectStoreMapDriven, OIMObjectStoreRecordDriven, OIMObjectValueByKeySelector, OIMObjectValuesByKeysSelector, OIMOrderedListCommandStream, OIMPkSelectorFactory, OIMReactiveCollection, OIMReactiveCollectionIndexManualArrayBased, OIMReactiveCollectionIndexManualSetBased, OIMReactiveIndex, OIMReactiveIndexArrayBased, OIMReactiveIndexManualArrayBased, OIMReactiveIndexManualSetBased, OIMReactiveIndexSetBased, OIMReactiveObject, OIMSelector, type TOIMAnyEntitySlot, type TOIMCollectionEntitiesSelector, type TOIMCollectionEntitySelector, type TOIMCollectionIndexArrayBasedOptions, type TOIMCollectionIndexSetBasedOptions, type TOIMCollectionKit, type TOIMCollectionOptions, type TOIMCollectionOrderedIndexOptions, type TOIMCollectionOrderedListCommandStreamOptions, type TOIMCollectionUpdatePayload, type TOIMComparator, type TOIMComputedOptions, type TOIMComputedUpdatePayload, type TOIMDerivedCollectionIndexArrayBasedOptions, type TOIMDerivedCollectionIndexSetBasedOptions, type TOIMDerivedEntityComparator, type TOIMDerivedEntityOrderSelector, type TOIMDerivedEntityOrderValue, type TOIMDerivedIndexKeySelector, type TOIMEffectOptions, type TOIMEntitySlot, type TOIMEntitySlotResolver, type TOIMEntityUpdater, type TOIMEventHandler, type TOIMEventQueueOptions, type TOIMIndexComparator, type TOIMIndexKey, type TOIMIndexOptionsArrayBased, type TOIMIndexOptionsSetBased, type TOIMIndexPksUpdatePayload, type TOIMIndexUpdatePayload, type TOIMObjectOptions, type TOIMOrderedListCommand, type TOIMPk, type TOIMPkSelector, type TOIMReactiveCollectionFactoryOptions, type TOIMRelationsArrayIndexOptions, type TOIMRelationsDerivedArrayIndexOptions, type TOIMRelationsDerivedSetIndexOptions, type TOIMRelationsOrderedListOptions, type TOIMRelationsSetIndexOptions, type TOIMSchedulerOptions, type TOIMSchedulerType, type TOIMUpdatePayload, createOIMCollectionIndexFactory, createOIMCollectionKit };

package/dist/index.js

@@ -779,17 +779,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 = [];
@@ -822,6 +844,11 @@ var OIMCollectionStoreMapDriven = class extends OIMCollectionStore {
     const slot = this.slots.get(pk);
     if (slot) slot.item = void 0;
     this.slots.delete(pk);
+    const reserved = this.reservedSlots.get(pk);
+    if (reserved) {
+      reserved.item = void 0;
+      this.reservedSlots.delete(pk);
+    }
   }
   removeManyByPks(pks) {
     for (const pk of pks) {
@@ -859,6 +886,10 @@ var OIMCollectionStoreMapDriven = class extends OIMCollectionStore {
       slot.item = void 0;
     }
     this.slots.clear();
+    for (const slot of this.reservedSlots.values()) {
+      slot.item = void 0;
+    }
+    this.reservedSlots.clear();
   }
   getAllPks() {
     return Array.from(this.slots.keys());
@@ -900,6 +931,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);
   }
@@ -1525,7 +1559,7 @@ 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
     });
@@ -1575,11 +1609,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;
   }
 };
@@ -1647,7 +1677,7 @@ 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
     });
@@ -1701,11 +1731,7 @@ var OIMReactiveCollectionIndexManualSetBased = class extends OIMReactiveIndexMan
   }
   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;
   }
 };
@@ -2867,8 +2893,8 @@ var OIMCollectionSelectors = class {
   }
 };
 
-// src/dx/OIMCollectionContext.ts
-function createOIMCollectionContext(queue, opts) {
+// src/dx/OIMCollectionKit.ts
+function createOIMCollectionKit(queue, opts) {
   const collection = new OIMReactiveCollection(queue, opts);
   const indexFactory = new OIMCollectionIndexFactory(queue, collection);
   const select = new OIMCollectionSelectors(queue, collection);
@@ -3695,6 +3721,6 @@ export {
   OIMReactiveIndexSetBased,
   OIMReactiveObject,
   OIMSelector,
-  createOIMCollectionContext,
-  createOIMCollectionIndexFactory
+  createOIMCollectionIndexFactory,
+  createOIMCollectionKit
 };

package/llms.txt

@@ -80,13 +80,13 @@ queue.flush(); // delivers subscription
 
 ### DX Layer — Collection Model
 
-`createOIMCollectionContext` wires queue + collection + index factory + selectors together.
+`createOIMCollectionKit` wires queue + collection + index factory + selectors together.
 
 ```ts
-import { createOIMCollectionContext } from '@oimdb/core';
+import { createOIMCollectionKit } from '@oimdb/core';
 
 const { collection, indexFactory, select } =
-    createOIMCollectionContext<User, string>(queue, { selectPk: (u) => u.id });
+    createOIMCollectionKit<User, string>(queue, { selectPk: (u) => u.id });
 
 // Derived index: built automatically from entity data
 const byRole = indexFactory.derivedSetIndex((u) => [u.role]);
@@ -181,7 +181,7 @@ import {
 // store.ts — outside React
 const queue = new OIMEventQueue();
 const { collection: users, indexFactory } =
-    createOIMCollectionContext<User, string>(queue, { selectPk: (u) => u.id });
+    createOIMCollectionKit<User, string>(queue, { selectPk: (u) => u.id });
 const byTeam = indexFactory.derivedSetIndex((u) => [u.teamId]);
 export const collections = { users };
 
@@ -329,7 +329,7 @@ Variable names: drop the prefix, start lowercase. Context goes first: `prevColle
 const queue = new OIMEventQueue({ scheduler: new OIMEventQueueSchedulerImmediate() });
 
 const { collection: tasks, indexFactory, select } =
-    createOIMCollectionContext<Task, string>(queue, { selectPk: (t) => t.id });
+    createOIMCollectionKit<Task, string>(queue, { selectPk: (t) => t.id });
 
 const byStatus  = indexFactory.derivedSetIndex((t) => [t.status]);
 const byAssignee = indexFactory.derivedSetIndex((t) => [t.assigneeId]);

package/package.json

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