@oimdb/core 1.2.2 → 1.3.0

package/README.md

@@ -15,7 +15,8 @@ This package exports all the core classes, interfaces, and types needed to build
 ### Core Classes
 - **OIMReactiveCollection**: Reactive entity storage with automatic change notifications
 - **OIMRICollection**: Reactive collection with integrated indexing capabilities
-- **OIMReactiveIndexManual**: Reactive index with manual key-to-entity mapping
+- **OIMReactiveIndexManualSetBased**: Reactive index with Set-based storage (efficient for incremental updates)
+- **OIMReactiveIndexManualArrayBased**: Reactive index with Array-based storage (efficient for full replacements)
 - **OIMEventQueue**: Configurable event processing queue with scheduler integration
 - **OIMCollection**: Base collection with CRUD operations and event emission
 
@@ -27,14 +28,19 @@ This package exports all the core classes, interfaces, and types needed to build
 
 ### Storage & Indexing
 - **OIMCollectionStoreMapDriven**: Map-based storage backend
-- **OIMIndexManual**: Manual index management with custom comparison logic
+- **OIMIndexManualSetBased**: Set-based manual index (returns `Set<TPk>`)
+- **OIMIndexManualArrayBased**: Array-based manual index (returns `TPk[]`)
+- **OIMIndexStoreMapDrivenSetBased**: Set-based index storage backend
+- **OIMIndexStoreMapDrivenArrayBased**: Array-based index storage backend
 - **OIMMap2Keys**: Two-key mapping utilities for complex indexing
 
 ### Abstract Classes & Interfaces
 - **OIMCollectionStore**: Storage backend interface
 - **OIMEventQueueScheduler**: Event processing scheduler interface
-- **OIMIndex**: Base index interface
-- **OIMReactiveIndex**: Reactive index interface
+- **OIMIndexSetBased**: Base Set-based index interface (returns `Set<TPk>`)
+- **OIMIndexArrayBased**: Base Array-based index interface (returns `TPk[]`)
+- **OIMReactiveIndexSetBased**: Reactive Set-based index interface
+- **OIMReactiveIndexArrayBased**: Reactive Array-based index interface
 
 ### Types & Enums
 - **TOIM\***: Generic types for collections, indices, events, and schedulers
@@ -92,36 +98,72 @@ const multipleUsers = users.getManyByPks(['user1', 'user2']);
 
 ### Creating a Reactive Index
 
+OIMDB provides two types of indexes optimized for different use cases:
+
+#### SetBased Indexes (for incremental updates)
+
 ```typescript
-import { OIMReactiveIndexManual, OIMEventQueue } from '@oimdb/core';
+import { OIMReactiveIndexManualSetBased, OIMEventQueue } from '@oimdb/core';
 
-// Create reactive index for user roles
+// Create Set-based reactive index for user roles
 const queue = new OIMEventQueue({
     scheduler: OIMEventQueueSchedulerFactory.createMicrotask()
 });
 
-const userRoleIndex = new OIMReactiveIndexManual<string, string>(queue);
+const userRoleIndex = new OIMReactiveIndexManualSetBased<string, string>(queue);
 
 // Subscribe to specific index key changes
 userRoleIndex.updateEventEmitter.subscribeOnKey('admin', (pks) => {
-    console.log('Admin users changed:', pks);
+    console.log('Admin users changed:', pks); // pks is Set<string>
 });
 
 // Build the index manually
 userRoleIndex.setPks('admin', ['user1']);
 userRoleIndex.setPks('user', ['user2', 'user3']);
 
-// Add more users to existing roles
+// Add more users to existing roles (efficient for Set-based)
 userRoleIndex.addPks('admin', ['user2']);
 
-// Query the index
-const adminUsers = userRoleIndex.index.getPksByKey('admin'); // ['user1', 'user2']
-const regularUsers = userRoleIndex.index.getPksByKey('user'); // ['user2', 'user3']
+// Query the index - returns Set
+const adminUsers = userRoleIndex.index.getPksByKey('admin'); // Set(['user1', 'user2'])
+const regularUsers = userRoleIndex.index.getPksByKey('user'); // Set(['user2', 'user3'])
 
-// Remove users from roles
+// Remove users from roles (efficient for Set-based)
 userRoleIndex.removePks('admin', ['user1']);
 ```
 
+#### ArrayBased Indexes (for full replacements)
+
+```typescript
+import { OIMReactiveIndexManualArrayBased, OIMEventQueue } from '@oimdb/core';
+
+// Create Array-based reactive index for deck cards
+const queue = new OIMEventQueue({
+    scheduler: OIMEventQueueSchedulerFactory.createMicrotask()
+});
+
+const cardsByDeckIndex = new OIMReactiveIndexManualArrayBased<string, string>(queue);
+
+// Subscribe to specific index key changes
+cardsByDeckIndex.updateEventEmitter.subscribeOnKey('deck1', (pks) => {
+    console.log('Deck cards changed:', pks); // pks is string[]
+});
+
+// Build the index manually - set full array
+cardsByDeckIndex.setPks('deck1', ['card1', 'card2', 'card3']);
+
+// Query the index - returns Array
+const deckCards = cardsByDeckIndex.index.getPksByKey('deck1'); // ['card1', 'card2', 'card3']
+
+// For Array-based indexes, prefer setPks for updates (addPks/removePks are available but less efficient)
+cardsByDeckIndex.setPks('deck1', ['card1', 'card2', 'card4']); // Full replacement (recommended)
+// cardsByDeckIndex.addPks('deck1', ['card5']); // Works but less efficient than SetBased
+```
+
+**When to use which:**
+- **SetBased**: Use when you frequently add/remove individual items (`addPks`/`removePks` are efficient) and order doesn't matter
+- **ArrayBased**: Use when you typically replace the entire array (`setPks` is more efficient, no diff computation needed) or when you need to preserve element order/sorting
+
 ### Event Queue and Schedulers
 
 ```typescript
@@ -187,9 +229,9 @@ const queue = new OIMEventQueue({
     scheduler: OIMEventQueueSchedulerFactory.createMicrotask()
 });
 
-// Create indexes
-const teamIndex = new OIMReactiveIndexManual<string, string>(queue);
-const roleIndex = new OIMReactiveIndexManual<string, string>(queue);
+// Create indexes (choose SetBased or ArrayBased based on your needs)
+const teamIndex = new OIMReactiveIndexManualSetBased<string, string>(queue);
+const roleIndex = new OIMReactiveIndexManualArrayBased<string, string>(queue);
 
 // Create collection with indexes
 const users = new OIMRICollection(queue, {
@@ -334,9 +376,13 @@ OIMCollection (base)
 ├── OIMReactiveCollection (adds event emitter + coalescing)
 └── OIMRICollection (reactive collection + indexes)
 
-OIMIndex (base)
-├── OIMIndexManual (manual index management)
-└── OIMReactiveIndexManual (reactive index with event emitter)
+OIMIndexSetBased (base for Set-based)
+├── OIMIndexManualSetBased (manual Set-based index)
+└── OIMReactiveIndexManualSetBased (reactive Set-based index with event emitter)
+
+OIMIndexArrayBased (base for Array-based)
+├── OIMIndexManualArrayBased (manual Array-based index)
+└── OIMReactiveIndexManualArrayBased (reactive Array-based index with event emitter)
 ```
 
 ## ⚡ Performance Characteristics
@@ -352,6 +398,21 @@ OIMIndex (base)
   - **Timeout**: Custom delay for batching strategies
   - **AnimationFrame**: 16ms, synced with 60fps rendering
 
+### Index Performance
+
+**SetBased Indexes** (`OIMReactiveIndexManualSetBased`):
+- **Returns**: `Set<TPk>` for efficient membership checks
+- **Best for**: Frequent incremental updates using `addPks`/`removePks`
+- **Performance**: O(1) add/remove operations, O(n) for `setPks` (requires Set creation)
+- **Use case**: When you need to frequently add/remove individual items
+
+**ArrayBased Indexes** (`OIMReactiveIndexManualArrayBased`):
+- **Returns**: `TPk[]` for direct array access
+- **Best for**: Full array replacements using `setPks`
+- **Performance**: O(1) `setPks` operation (direct assignment, no diff computation)
+- **Use case**: When you typically replace the entire array (e.g., deck cards, ordered lists) or when you need to preserve element order/sorting
+- **Note**: While `addPks`/`removePks` are available, they are less efficient (O(n)) than for SetBased indexes. For ArrayBased indexes, prefer `setPks` for better performance.
+
 ## 🔗 Integration Patterns
 
 ### With React (@oimdb/react)
@@ -462,26 +523,54 @@ new OIMRICollection(queue: OIMEventQueue, opts: {
 - `indexes: TReactiveIndexMap` - Named reactive indexes preserving index-to-name mapping
 - *(inherits all OIMReactiveCollection properties)*
 
-#### `OIMReactiveIndexManual<TKey, TPk>`
-Reactive index with manual key-to-entity mapping and change notifications.
+#### `OIMReactiveIndexManualSetBased<TKey, TPk>`
+Reactive Set-based index with manual key-to-entity mapping and change notifications. Returns `Set<TPk>` for efficient membership checks.
+
+**Constructor:**
+```typescript
+new OIMReactiveIndexManualSetBased(queue: OIMEventQueue, opts?: {
+    index?: OIMIndexManualSetBased<TKey, TPk>
+})
+```
+
+**Properties:**
+- `index: OIMIndexManualSetBased<TKey, TPk>` - Underlying Set-based index
+- `updateEventEmitter: OIMUpdateEventEmitter<TKey>` - Key-specific subscriptions
+
+**Methods:**
+- `setPks(key: TKey, pks: readonly TPk[]): void` - Set primary keys for index key (replaces entire Set)
+- `addPks(key: TKey, pks: readonly TPk[]): void` - Add primary keys to index key (efficient)
+- `removePks(key: TKey, pks: readonly TPk[]): void` - Remove primary keys from index key (efficient)
+- `clear(key?: TKey): void` - Clear all keys or specific key
+
+**Query:**
+- `index.getPksByKey(key: TKey): Set<TPk>` - Returns Set of primary keys
+
+#### `OIMReactiveIndexManualArrayBased<TKey, TPk>`
+Reactive Array-based index with manual key-to-entity mapping and change notifications. Returns `TPk[]` for direct array access.
 
 **Constructor:**
 ```typescript
-new OIMReactiveIndexManual(queue: OIMEventQueue, opts?: {
-    index?: OIMIndexManual<TKey, TPk>
+new OIMReactiveIndexManualArrayBased(queue: OIMEventQueue, opts?: {
+    index?: OIMIndexManualArrayBased<TKey, TPk>
 })
 ```
 
 **Properties:**
-- `index: OIMIndexManual<TKey, TPk>` - Underlying index
+- `index: OIMIndexManualArrayBased<TKey, TPk>` - Underlying Array-based index
 - `updateEventEmitter: OIMUpdateEventEmitter<TKey>` - Key-specific subscriptions
 
 **Methods:**
-- `setPks(key: TKey, pks: readonly TPk[]): void` - Set primary keys for index key
-- `addPks(key: TKey, pks: readonly TPk[]): void` - Add primary keys to index key
-- `removePks(key: TKey, pks: readonly TPk[]): void` - Remove primary keys from index key
+- `setPks(key: TKey, pks: readonly TPk[]): void` - Set primary keys for index key (direct assignment, no diff) - **Recommended for ArrayBased**
+- `addPks(key: TKey, pks: readonly TPk[]): void` - Add primary keys to index key (O(n) operation, less efficient than SetBased)
+- `removePks(key: TKey, pks: readonly TPk[]): void` - Remove primary keys from index key (O(n) operation, less efficient than SetBased)
 - `clear(key?: TKey): void` - Clear all keys or specific key
 
+**Query:**
+- `index.getPksByKey(key: TKey): TPk[]` - Returns Array of primary keys
+
+**Note**: While `addPks`/`removePks` are available, they require array operations (Set creation, filtering) making them O(n) compared to O(1) for SetBased indexes. For ArrayBased indexes, prefer `setPks` for better performance when replacing the entire array.
+
 #### `OIMEventQueue`
 Event processing queue with configurable scheduling.
 

package/dist/index.cjs

@@ -39,15 +39,23 @@ __export(index_exports, {
   OIMEventQueueSchedulerImmediate: () => OIMEventQueueSchedulerImmediate,
   OIMEventQueueSchedulerMicrotask: () => OIMEventQueueSchedulerMicrotask,
   OIMEventQueueSchedulerTimeout: () => OIMEventQueueSchedulerTimeout,
-  OIMIndex: () => OIMIndex,
+  OIMIndexArrayBased: () => OIMIndexArrayBased,
   OIMIndexComparatorFactory: () => OIMIndexComparatorFactory,
-  OIMIndexManual: () => OIMIndexManual,
+  OIMIndexManualArrayBased: () => OIMIndexManualArrayBased,
+  OIMIndexManualSetBased: () => OIMIndexManualSetBased,
+  OIMIndexSetBased: () => OIMIndexSetBased,
+  OIMIndexStoreArrayBased: () => OIMIndexStoreArrayBased,
+  OIMIndexStoreMapDrivenArrayBased: () => OIMIndexStoreMapDrivenArrayBased,
+  OIMIndexStoreMapDrivenSetBased: () => OIMIndexStoreMapDrivenSetBased,
+  OIMIndexStoreSetBased: () => OIMIndexStoreSetBased,
   OIMMap2Keys: () => OIMMap2Keys,
   OIMPkSelectorFactory: () => OIMPkSelectorFactory,
   OIMRICollection: () => OIMRICollection,
   OIMReactiveCollection: () => OIMReactiveCollection,
-  OIMReactiveIndex: () => OIMReactiveIndex,
-  OIMReactiveIndexManual: () => OIMReactiveIndexManual,
+  OIMReactiveIndexArrayBased: () => OIMReactiveIndexArrayBased,
+  OIMReactiveIndexManualArrayBased: () => OIMReactiveIndexManualArrayBased,
+  OIMReactiveIndexManualSetBased: () => OIMReactiveIndexManualSetBased,
+  OIMReactiveIndexSetBased: () => OIMReactiveIndexSetBased,
   OIMUpdateEventCoalescer: () => OIMUpdateEventCoalescer,
   OIMUpdateEventCoalescerCollection: () => OIMUpdateEventCoalescerCollection,
   OIMUpdateEventCoalescerIndex: () => OIMUpdateEventCoalescerIndex,
@@ -59,6 +67,14 @@ module.exports = __toCommonJS(index_exports);
 var OIMCollectionStore = class {
 };
 
+// src/abstract/OIMIndexStoreSetBased.ts
+var OIMIndexStoreSetBased = class {
+};
+
+// src/abstract/OIMIndexStoreArrayBased.ts
+var OIMIndexStoreArrayBased = class {
+};
+
 // src/core/OIMEventEmitter.ts
 var OIMEventEmitter = class {
   constructor() {
@@ -184,12 +200,8 @@ var EOIMIndexEventType = /* @__PURE__ */ ((EOIMIndexEventType2) => {
   return EOIMIndexEventType2;
 })(EOIMIndexEventType || {});
 
-// src/abstract/OIMIndexStore.ts
-var OIMIndexStore = class {
-};
-
-// src/core/OIMIndexStoreMapDriven.ts
-var OIMIndexStoreMapDriven = class extends OIMIndexStore {
+// src/core/OIMIndexStoreMapDrivenSetBased.ts
+var OIMIndexStoreMapDrivenSetBased = class extends OIMIndexStoreSetBased {
   constructor() {
     super(...arguments);
     this.pks = /* @__PURE__ */ new Map();
@@ -232,12 +244,12 @@ var OIMIndexStoreMapDriven = class extends OIMIndexStore {
   }
 };
 
-// src/abstract/OIMIndex.ts
-var OIMIndex = class {
+// src/abstract/OIMIndexSetBased.ts
+var OIMIndexSetBased = class {
   constructor(options = {}) {
     this.emitter = new OIMEventEmitter();
     this.comparePks = options.comparePks;
-    this.store = options.store ?? new OIMIndexStoreMapDriven();
+    this.store = options.store ?? new OIMIndexStoreMapDrivenSetBased();
   }
   /**
    * Get primary keys for multiple index keys
@@ -346,6 +358,155 @@ var OIMIndex = class {
   }
 };
 
+// src/core/OIMIndexStoreMapDrivenArrayBased.ts
+var OIMIndexStoreMapDrivenArrayBased = class extends OIMIndexStoreArrayBased {
+  constructor() {
+    super(...arguments);
+    this.pks = /* @__PURE__ */ new Map();
+  }
+  setOneByKey(key, pks) {
+    this.pks.set(key, pks);
+  }
+  removeOneByKey(key) {
+    this.pks.delete(key);
+  }
+  removeManyByKeys(keys) {
+    for (const key of keys) {
+      this.pks.delete(key);
+    }
+  }
+  getOneByKey(key) {
+    return this.pks.get(key);
+  }
+  getManyByKeys(keys) {
+    const result = /* @__PURE__ */ new Map();
+    for (const key of keys) {
+      const pks = this.getOneByKey(key);
+      if (pks !== void 0) {
+        result.set(key, pks);
+      }
+    }
+    return result;
+  }
+  getAllKeys() {
+    return Array.from(this.pks.keys());
+  }
+  getAll() {
+    return new Map(this.pks);
+  }
+  countAll() {
+    return this.pks.size;
+  }
+  clear() {
+    this.pks.clear();
+  }
+};
+
+// src/abstract/OIMIndexArrayBased.ts
+var OIMIndexArrayBased = class {
+  constructor(options = {}) {
+    this.emitter = new OIMEventEmitter();
+    this.comparePks = options.comparePks;
+    this.store = options.store ?? new OIMIndexStoreMapDrivenArrayBased();
+  }
+  /**
+   * Get primary keys for multiple index keys
+   */
+  getPksByKeys(keys) {
+    return this.store.getManyByKeys(keys);
+  }
+  /**
+   * Get primary keys for a specific index key
+   */
+  getPksByKey(key) {
+    const pksArray = this.store.getOneByKey(key);
+    return pksArray ? pksArray : [];
+  }
+  /**
+   * Check if an index key exists
+   */
+  hasKey(key) {
+    return this.store.getOneByKey(key) !== void 0;
+  }
+  /**
+   * Get all index keys
+   */
+  getKeys() {
+    return this.store.getAllKeys();
+  }
+  /**
+   * Get the number of primary keys for a specific index key
+   */
+  getKeySize(key) {
+    const pksArray = this.store.getOneByKey(key);
+    return pksArray ? pksArray.length : 0;
+  }
+  /**
+   * Get total number of index keys
+   */
+  get size() {
+    return this.store.countAll();
+  }
+  /**
+   * Check if the index is empty
+   */
+  get isEmpty() {
+    return this.store.countAll() === 0;
+  }
+  /**
+   * Get performance metrics for monitoring and debugging
+   */
+  getMetrics() {
+    let totalPks = 0;
+    let maxBucketSize = 0;
+    let minBucketSize = Infinity;
+    const allPks = this.store.getAll();
+    for (const pksArray of allPks.values()) {
+      totalPks += pksArray.length;
+      maxBucketSize = Math.max(maxBucketSize, pksArray.length);
+      minBucketSize = Math.min(minBucketSize, pksArray.length);
+    }
+    return {
+      totalKeys: allPks.size,
+      totalPks,
+      averagePksPerKey: allPks.size > 0 ? totalPks / allPks.size : 0,
+      maxBucketSize: maxBucketSize === -Infinity ? 0 : maxBucketSize,
+      minBucketSize: minBucketSize === Infinity ? 0 : minBucketSize
+    };
+  }
+  /**
+   * Clean up event listeners when index is no longer needed
+   */
+  destroy() {
+    this.emitter.offAll();
+    this.store.clear();
+  }
+  /**
+   * Set primary keys for a specific index key with optional comparison.
+   * If comparator is provided and returns true (no changes), skip the update.
+   */
+  setPksWithComparison(key, newPks) {
+    if (this.comparePks) {
+      const existingPksArray = this.store.getOneByKey(key);
+      if (existingPksArray && existingPksArray.length === newPks.length) {
+        if (this.comparePks(existingPksArray, newPks)) {
+          return false;
+        }
+      } else if (!existingPksArray && newPks.length === 0) {
+        return false;
+      }
+    }
+    this.store.setOneByKey(key, newPks);
+    return true;
+  }
+  /**
+   * Emit update event with changed keys
+   */
+  emitUpdate(keys) {
+    this.emitter.emit(0 /* UPDATE */, { keys });
+  }
+};
+
 // src/enum/EOIMUpdateEventCoalescerEventType.ts
 var EOIMUpdateEventCoalescerEventType = /* @__PURE__ */ ((EOIMUpdateEventCoalescerEventType2) => {
   EOIMUpdateEventCoalescerEventType2[EOIMUpdateEventCoalescerEventType2["HAS_CHANGES"] = 0] = "HAS_CHANGES";
@@ -472,8 +633,8 @@ var OIMUpdateEventEmitter = class {
   }
 };
 
-// src/core/OIMIndexManual.ts
-var OIMIndexManual = class extends OIMIndex {
+// src/core/OIMIndexManualSetBased.ts
+var OIMIndexManualSetBased = class extends OIMIndexSetBased {
   constructor(options = {}) {
     super(options);
   }
@@ -565,8 +726,8 @@ var OIMUpdateEventCoalescer = class {
   constructor(index) {
     this.emitter = new OIMEventEmitter();
     this.hasEmittedChanges = false;
-    this.updatedKeysIndex = index ?? new OIMIndexManual({
-      store: new OIMIndexStoreMapDriven()
+    this.updatedKeysIndex = index ?? new OIMIndexManualSetBased({
+      store: new OIMIndexStoreMapDrivenSetBased()
     });
     if (!this.updatedKeysIndex.hasKey(OIMDBSettings.UPDATED_KEYS_INDEX_KEY)) {
       this.updatedKeysIndex.setPks(
@@ -636,8 +797,49 @@ var OIMUpdateEventCoalescerIndex = class extends OIMUpdateEventCoalescer {
   }
 };
 
-// src/abstract/OIMReactiveIndex.ts
-var OIMReactiveIndex = class {
+// src/abstract/OIMReactiveIndexSetBased.ts
+var OIMReactiveIndexSetBased = class {
+  constructor(queue, opts) {
+    this.index = opts?.index ?? this.createDefaultIndex();
+    this.coalescer = new OIMUpdateEventCoalescerIndex(
+      this.index.emitter
+    );
+    this.updateEventEmitter = new OIMUpdateEventEmitter({
+      coalescer: this.coalescer,
+      queue
+    });
+  }
+  getPksByKey(key) {
+    return this.index.getPksByKey(key);
+  }
+  getPksByKeys(keys) {
+    return this.index.getPksByKeys(keys);
+  }
+  hasKey(key) {
+    return this.index.hasKey(key);
+  }
+  getKeys() {
+    return this.index.getKeys();
+  }
+  getKeySize(key) {
+    return this.index.getKeySize(key);
+  }
+  get size() {
+    return this.index.size;
+  }
+  get isEmpty() {
+    return this.index.isEmpty;
+  }
+  getMetrics() {
+    return this.index.getMetrics();
+  }
+  destroy() {
+    this.index.destroy();
+  }
+};
+
+// src/abstract/OIMReactiveIndexArrayBased.ts
+var OIMReactiveIndexArrayBased = class {
   constructor(queue, opts) {
     this.index = opts?.index ?? this.createDefaultIndex();
     this.coalescer = new OIMUpdateEventCoalescerIndex(
@@ -873,13 +1075,111 @@ var OIMReactiveCollection = class extends OIMCollection {
   }
 };
 
-// src/core/OIMReactiveIndexManual.ts
-var OIMReactiveIndexManual = class extends OIMReactiveIndex {
+// src/core/OIMReactiveIndexManualSetBased.ts
+var OIMReactiveIndexManualSetBased = class extends OIMReactiveIndexSetBased {
+  constructor(queue, opts) {
+    super(queue, opts);
+  }
+  createDefaultIndex() {
+    return new OIMIndexManualSetBased();
+  }
+  setPks(key, pks) {
+    this.index.setPks(key, pks);
+  }
+  addPks(key, pks) {
+    this.index.addPks(key, pks);
+  }
+  removePks(key, pks) {
+    this.index.removePks(key, pks);
+  }
+  clear(key) {
+    this.index.clear(key);
+  }
+};
+
+// src/core/OIMIndexManualArrayBased.ts
+var OIMIndexManualArrayBased = class extends OIMIndexArrayBased {
+  constructor(options = {}) {
+    super(options);
+  }
+  /**
+   * 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, pks) {
+    const hasChanges = this.setPksWithComparison(key, pks);
+    if (hasChanges) {
+      this.emitUpdate([key]);
+    }
+  }
+  /**
+   * Add primary keys to a specific index key
+   */
+  addPks(key, pks) {
+    if (pks.length === 0) return;
+    let pksArray = this.store.getOneByKey(key);
+    if (!pksArray) {
+      pksArray = [];
+      this.store.setOneByKey(key, pksArray);
+    }
+    const pksSet = new Set(pksArray);
+    let hasChanges = false;
+    for (const pk of pks) {
+      if (!pksSet.has(pk)) {
+        pksSet.add(pk);
+        hasChanges = true;
+      }
+    }
+    if (hasChanges) {
+      this.store.setOneByKey(key, Array.from(pksSet));
+      this.emitUpdate([key]);
+    }
+  }
+  /**
+   * Remove primary keys from a specific index key
+   */
+  removePks(key, pks) {
+    if (pks.length === 0) return;
+    const pksArray = this.store.getOneByKey(key);
+    if (!pksArray) return;
+    const pksSet = new Set(pks);
+    const filtered = pksArray.filter((pk) => !pksSet.has(pk));
+    const hasChanges = filtered.length !== pksArray.length;
+    if (hasChanges) {
+      if (filtered.length === 0) {
+        this.store.removeOneByKey(key);
+      } else {
+        this.store.setOneByKey(key, filtered);
+      }
+      this.emitUpdate([key]);
+    }
+  }
+  /**
+   * Clear all primary keys for a specific index key, or all keys if no key specified
+   */
+  clear(key) {
+    if (key === void 0) {
+      const allKeys = this.store.getAllKeys();
+      if (allKeys.length > 0) {
+        this.store.clear();
+        this.emitUpdate(allKeys);
+      }
+    } else {
+      if (this.store.getOneByKey(key) !== void 0) {
+        this.store.removeOneByKey(key);
+        this.emitUpdate([key]);
+      }
+    }
+  }
+};
+
+// src/core/OIMReactiveIndexManualArrayBased.ts
+var OIMReactiveIndexManualArrayBased = class extends OIMReactiveIndexArrayBased {
   constructor(queue, opts) {
     super(queue, opts);
   }
   createDefaultIndex() {
-    return new OIMIndexManual();
+    return new OIMIndexManualArrayBased();
   }
   setPks(key, pks) {
     this.index.setPks(key, pks);
@@ -1287,15 +1587,23 @@ var OIMEventQueueSchedulerFactory = class {
   OIMEventQueueSchedulerImmediate,
   OIMEventQueueSchedulerMicrotask,
   OIMEventQueueSchedulerTimeout,
-  OIMIndex,
+  OIMIndexArrayBased,
   OIMIndexComparatorFactory,
-  OIMIndexManual,
+  OIMIndexManualArrayBased,
+  OIMIndexManualSetBased,
+  OIMIndexSetBased,
+  OIMIndexStoreArrayBased,
+  OIMIndexStoreMapDrivenArrayBased,
+  OIMIndexStoreMapDrivenSetBased,
+  OIMIndexStoreSetBased,
   OIMMap2Keys,
   OIMPkSelectorFactory,
   OIMRICollection,
   OIMReactiveCollection,
-  OIMReactiveIndex,
-  OIMReactiveIndexManual,
+  OIMReactiveIndexArrayBased,
+  OIMReactiveIndexManualArrayBased,
+  OIMReactiveIndexManualSetBased,
+  OIMReactiveIndexSetBased,
   OIMUpdateEventCoalescer,
   OIMUpdateEventCoalescerCollection,
   OIMUpdateEventCoalescerIndex,