@oimdb/core 1.2.1 → 1.3.0

package/dist/index.d.ts

@@ -12,6 +12,30 @@ declare abstract class OIMCollectionStore<TEntity extends object, TPk extends TO
     abstract clear(): void;
 }
 
+declare abstract class OIMIndexStoreSetBased<TKey extends TOIMPk, TPk extends TOIMPk> {
+    abstract setOneByKey(key: TKey, pks: Set<TPk>): void;
+    abstract removeOneByKey(key: TKey): void;
+    abstract removeManyByKeys(keys: readonly TKey[]): void;
+    abstract getOneByKey(key: TKey): Set<TPk> | undefined;
+    abstract getManyByKeys(keys: readonly TKey[]): Map<TKey, Set<TPk>>;
+    abstract getAllKeys(): TKey[];
+    abstract getAll(): Map<TKey, Set<TPk>>;
+    abstract countAll(): number;
+    abstract clear(): void;
+}
+
+declare abstract class OIMIndexStoreArrayBased<TKey extends TOIMPk, TPk extends TOIMPk> {
+    abstract setOneByKey(key: TKey, pks: TPk[]): void;
+    abstract removeOneByKey(key: TKey): void;
+    abstract removeManyByKeys(keys: readonly TKey[]): void;
+    abstract getOneByKey(key: TKey): TPk[] | undefined;
+    abstract getManyByKeys(keys: readonly TKey[]): Map<TKey, TPk[]>;
+    abstract getAllKeys(): TKey[];
+    abstract getAll(): Map<TKey, TPk[]>;
+    abstract countAll(): number;
+    abstract clear(): void;
+}
+
 type TOIMEventHandler<T> = (payload: T) => void;
 
 declare class OIMEventEmitter<T extends Record<string, unknown>> {
@@ -61,36 +85,20 @@ interface TOIMIndexUpdatePayload<TKey> {
  * Returns true if the arrays are considered equal, false if they differ. */
 type TOIMIndexComparator<TPk extends TOIMPk> = (existingPks: readonly TPk[], newPks: readonly TPk[]) => boolean;
 
-declare abstract class OIMIndexStore<TKey extends TOIMPk, TPk extends TOIMPk> {
-    abstract setOneByKey(key: TKey, pks: Set<TPk>): void;
-    abstract removeOneByKey(key: TKey): void;
-    abstract removeManyByKeys(keys: readonly TKey[]): void;
-    abstract getOneByKey(key: TKey): Set<TPk> | undefined;
-    abstract getManyByKeys(keys: readonly TKey[]): Map<TKey, Set<TPk>>;
-    abstract getAllKeys(): TKey[];
-    abstract getAll(): Map<TKey, Set<TPk>>;
-    abstract countAll(): number;
-    abstract clear(): void;
-}
-
-/**
- * Configuration options for index instances */
-type TOIMIndexOptions<TIndexKey extends TOIMPk, TPk extends TOIMPk> = {
-    comparePks?: TOIMIndexComparator<TPk>;
-    store?: OIMIndexStore<TIndexKey, TPk>;
-};
-
 /**
- * Abstract base class for all index types.
- * Provides common functionality and event system for key-to-PKs mappings.
+ * Abstract base class for Set-based index types.
+ * Provides common functionality and event system for key-to-PKs mappings using Set storage.
  */
-declare abstract class OIMIndex<TKey extends TOIMPk, TPk extends TOIMPk> {
+declare abstract class OIMIndexSetBased<TKey extends TOIMPk, TPk extends TOIMPk> {
     protected readonly comparePks?: TOIMIndexComparator<TPk>;
-    protected readonly store: OIMIndexStore<TKey, TPk>;
+    protected readonly store: OIMIndexStoreSetBased<TKey, TPk>;
     readonly emitter: OIMEventEmitter<{
         0: TOIMIndexUpdatePayload<TKey>;
     }>;
-    constructor(options?: TOIMIndexOptions<TKey, TPk>);
+    constructor(options?: {
+        comparePks?: TOIMIndexComparator<TPk>;
+        store?: OIMIndexStoreSetBased<TKey, TPk>;
+    });
     /**
      * Get primary keys for multiple index keys
      */
@@ -150,11 +158,81 @@ declare abstract class OIMIndex<TKey extends TOIMPk, TPk extends TOIMPk> {
 }
 
 /**
- * Manual index that allows direct manipulation of key-to-primary-keys mappings.
- * Extends the abstract OIMIndex with manual control methods and optional comparison.
+ * Abstract base class for Array-based index types.
+ * Provides common functionality and event system for key-to-PKs mappings using Array storage.
+ */
+declare abstract class OIMIndexArrayBased<TKey extends TOIMPk, TPk extends TOIMPk> {
+    protected readonly comparePks?: TOIMIndexComparator<TPk>;
+    protected readonly store: OIMIndexStoreArrayBased<TKey, TPk>;
+    readonly emitter: OIMEventEmitter<{
+        0: TOIMIndexUpdatePayload<TKey>;
+    }>;
+    constructor(options?: {
+        comparePks?: TOIMIndexComparator<TPk>;
+        store?: OIMIndexStoreArrayBased<TKey, TPk>;
+    });
+    /**
+     * Get primary keys for multiple index keys
+     */
+    getPksByKeys(keys: readonly TKey[]): Map<TKey, TPk[]>;
+    /**
+     * Get primary keys for a specific index key
+     */
+    getPksByKey(key: TKey): TPk[];
+    /**
+     * Check if an index key exists
+     */
+    hasKey(key: TKey): boolean;
+    /**
+     * Get all index keys
+     */
+    getKeys(): readonly TKey[];
+    /**
+     * Get the number of primary keys for a specific index key
+     */
+    getKeySize(key: TKey): number;
+    /**
+     * Get total number of index keys
+     */
+    get size(): number;
+    /**
+     * Check if the index is empty
+     */
+    get isEmpty(): boolean;
+    /**
+     * Get performance metrics for monitoring and debugging
+     */
+    getMetrics(): {
+        totalKeys: number;
+        totalPks: number;
+        averagePksPerKey: number;
+        maxBucketSize: number;
+        minBucketSize: number;
+    };
+    /**
+     * Clean up event listeners when index is no longer needed
+     */
+    destroy(): void;
+    /**
+     * Set primary keys for a specific index key with optional comparison.
+     * If comparator is provided and returns true (no changes), skip the update.
+     */
+    protected setPksWithComparison(key: TKey, newPks: TPk[]): boolean;
+    /**
+     * Emit update event with changed keys
+     */
+    protected emitUpdate(keys: TKey[]): void;
+}
+
+/**
+ * Manual Set-based index that allows direct manipulation of key-to-primary-keys mappings.
+ * Extends the abstract OIMIndexSetBased with manual control methods and optional comparison.
  */
-declare class OIMIndexManual<TIndexKey extends TOIMPk, TPk extends TOIMPk> extends OIMIndex<TIndexKey, TPk> {
-    constructor(options?: TOIMIndexOptions<TIndexKey, TPk>);
+declare class OIMIndexManualSetBased<TIndexKey extends TOIMPk, TPk extends TOIMPk> extends OIMIndexSetBased<TIndexKey, TPk> {
+    constructor(options?: {
+        comparePks?: TOIMIndexComparator<TPk>;
+        store?: OIMIndexStoreSetBased<TIndexKey, TPk>;
+    });
     /**
      * Set primary keys for a specific index key, replacing any existing values.
      * Uses optional comparator to skip updates if PKs haven't actually changed.
@@ -189,6 +267,7 @@ declare class OIMDBSettings {
 /**
  * Base abstract coalescer that groups updates by keys and emits consolidated events.
  * Designed to be extended for different entity types (collections, indexes, etc.).
+ * Uses SetBased indexes for efficient key tracking.
  */
 declare abstract class OIMUpdateEventCoalescer<TKey extends TOIMPk> {
     readonly emitter: OIMEventEmitter<{
@@ -196,9 +275,9 @@ declare abstract class OIMUpdateEventCoalescer<TKey extends TOIMPk> {
         1: void;
         2: void;
     }>;
-    protected readonly updatedKeysIndex: OIMIndexManual<typeof OIMDBSettings.UPDATED_KEYS_INDEX_KEY, TKey>;
+    protected readonly updatedKeysIndex: OIMIndexManualSetBased<typeof OIMDBSettings.UPDATED_KEYS_INDEX_KEY, TKey>;
     private hasEmittedChanges;
-    constructor(index?: OIMIndexManual<typeof OIMDBSettings.UPDATED_KEYS_INDEX_KEY, TKey>);
+    constructor(index?: OIMIndexManualSetBased<typeof OIMDBSettings.UPDATED_KEYS_INDEX_KEY, TKey>);
     /**
      * Get the set of keys that have been updated since last clear
      */
@@ -332,7 +411,7 @@ declare class OIMUpdateEventCoalescerIndex<TIndexKey extends TOIMPk> extends OIM
     private handleUpdate;
 }
 
-declare abstract class OIMReactiveIndex<TKey extends TOIMPk, TPk extends TOIMPk, TIndex extends OIMIndex<TKey, TPk>> {
+declare abstract class OIMReactiveIndexSetBased<TKey extends TOIMPk, TPk extends TOIMPk, TIndex extends OIMIndexSetBased<TKey, TPk>> {
     readonly index: TIndex;
     readonly updateEventEmitter: OIMUpdateEventEmitter<TKey>;
     readonly coalescer: OIMUpdateEventCoalescerIndex<TKey>;
@@ -357,6 +436,31 @@ declare abstract class OIMReactiveIndex<TKey extends TOIMPk, TPk extends TOIMPk,
     destroy(): void;
 }
 
+declare abstract class OIMReactiveIndexArrayBased<TKey extends TOIMPk, TPk extends TOIMPk, TIndex extends OIMIndexArrayBased<TKey, TPk>> {
+    readonly index: TIndex;
+    readonly updateEventEmitter: OIMUpdateEventEmitter<TKey>;
+    readonly coalescer: OIMUpdateEventCoalescerIndex<TKey>;
+    constructor(queue: OIMEventQueue, opts?: {
+        index: TIndex;
+    });
+    protected abstract createDefaultIndex(): TIndex;
+    getPksByKey(key: TKey): TPk[];
+    getPksByKeys(keys: readonly TKey[]): Map<TKey, TPk[]>;
+    hasKey(key: TKey): boolean;
+    getKeys(): readonly TKey[];
+    getKeySize(key: TKey): number;
+    get size(): number;
+    get isEmpty(): boolean;
+    getMetrics(): {
+        totalKeys: number;
+        totalPks: number;
+        averagePksPerKey: number;
+        maxBucketSize: number;
+        minBucketSize: number;
+    };
+    destroy(): void;
+}
+
 type TOIMPkSelector<TEntity extends object, TPk extends TOIMPk> = (entity: TEntity) => TPk;
 
 type TOIMEntityUpdater<TEntity extends object> = (draft: Partial<TEntity>, prevEntity: TEntity) => TEntity;
@@ -382,8 +486,9 @@ declare class OIMCollection<TEntity extends object, TPk extends TOIMPk> {
     constructor(opts?: TOIMCollectionOptions<TEntity, TPk>);
     getOneByPk(pk: TPk): TEntity | undefined;
     getManyByPks(pks: readonly TPk[]): TEntity[];
-    upsertOne(entity: TEntity): void;
-    upsertMany(entities: TEntity[]): void;
+    upsertOneByPk(pk: TPk, entity: Partial<TEntity>): void;
+    upsertOne(entity: TEntity | Partial<TEntity>): void;
+    upsertMany(entities: (TEntity | Partial<TEntity>)[]): void;
     removeOne(entity: TEntity): void;
     removeMany(entities: TEntity[]): void;
     removeOneByPk(pk: TPk): void;
@@ -392,7 +497,8 @@ declare class OIMCollection<TEntity extends object, TPk extends TOIMPk> {
     countAll(): number;
     getAll(): TEntity[];
     getAllPks(): TPk[];
-    protected upsertOneWithoutNotifications(entity: TEntity): TPk;
+    protected upsertOneWithoutNotifications(entity: TEntity | Partial<TEntity>): TPk;
+    protected upsertOneWithoutNotificationsByPk(pk: TPk, entity: Partial<TEntity> | TEntity): void;
 }
 
 declare enum EOIMCollectionEventType {
@@ -421,18 +527,57 @@ declare class OIMReactiveCollection<TEntity extends object, TPk extends TOIMPk>
     constructor(queue: OIMEventQueue, opts?: TOIMCollectionOptions<TEntity, TPk>);
 }
 
-declare class OIMReactiveIndexManual<TKey extends TOIMPk, TPk extends TOIMPk> extends OIMReactiveIndex<TKey, TPk, OIMIndexManual<TKey, TPk>> {
+declare class OIMReactiveIndexManualSetBased<TKey extends TOIMPk, TPk extends TOIMPk> extends OIMReactiveIndexSetBased<TKey, TPk, OIMIndexManualSetBased<TKey, TPk>> {
     constructor(queue: OIMEventQueue, opts?: {
-        index: OIMIndexManual<TKey, TPk>;
+        index: OIMIndexManualSetBased<TKey, TPk>;
     });
-    protected createDefaultIndex(): OIMIndexManual<TKey, TPk>;
+    protected createDefaultIndex(): OIMIndexManualSetBased<TKey, TPk>;
     setPks(key: TKey, pks: TPk[]): void;
     addPks(key: TKey, pks: readonly TPk[]): void;
     removePks(key: TKey, pks: readonly TPk[]): void;
     clear(key?: TKey): void;
 }
 
-declare class OIMRICollection<TEntity extends object, TPk extends TOIMPk, TIndexName extends string, TIndexKey extends TOIMPk, TIndex extends OIMIndex<TIndexKey, TPk>, TReactiveIndex extends OIMReactiveIndex<TIndexKey, TPk, TIndex>, TReactiveIndexMap extends Record<TIndexName, TReactiveIndex> = Record<TIndexName, TReactiveIndex>> extends OIMReactiveCollection<TEntity, TPk> {
+/**
+ * Manual Array-based index that allows direct manipulation of key-to-primary-keys mappings.
+ * Extends the abstract OIMIndexArrayBased with manual control methods and optional comparison.
+ */
+declare class OIMIndexManualArrayBased<TIndexKey extends TOIMPk, TPk extends TOIMPk> extends OIMIndexArrayBased<TIndexKey, TPk> {
+    constructor(options?: {
+        comparePks?: TOIMIndexComparator<TPk>;
+        store?: OIMIndexStoreArrayBased<TIndexKey, TPk>;
+    });
+    /**
+     * Set primary keys for a specific index key, replacing any existing values.
+     * Uses optional comparator to skip updates if PKs haven't actually changed.
+     */
+    setPks(key: TIndexKey, pks: TPk[]): void;
+    /**
+     * Add primary keys to a specific index key
+     */
+    addPks(key: TIndexKey, pks: readonly TPk[]): void;
+    /**
+     * Remove primary keys from a specific index key
+     */
+    removePks(key: TIndexKey, pks: readonly TPk[]): void;
+    /**
+     * Clear all primary keys for a specific index key, or all keys if no key specified
+     */
+    clear(key?: TIndexKey): void;
+}
+
+declare class OIMReactiveIndexManualArrayBased<TKey extends TOIMPk, TPk extends TOIMPk> extends OIMReactiveIndexArrayBased<TKey, TPk, OIMIndexManualArrayBased<TKey, TPk>> {
+    constructor(queue: OIMEventQueue, opts?: {
+        index: OIMIndexManualArrayBased<TKey, TPk>;
+    });
+    protected createDefaultIndex(): OIMIndexManualArrayBased<TKey, TPk>;
+    setPks(key: TKey, pks: TPk[]): void;
+    addPks(key: TKey, pks: readonly TPk[]): void;
+    removePks(key: TKey, pks: readonly TPk[]): void;
+    clear(key?: TKey): void;
+}
+
+declare class OIMRICollection<TEntity extends object, TPk extends TOIMPk, TIndexName extends string, TIndexKey extends TOIMPk, TReactiveIndex extends OIMReactiveIndexSetBased<TIndexKey, TPk, OIMIndexSetBased<TIndexKey, TPk>> | OIMReactiveIndexArrayBased<TIndexKey, TPk, OIMIndexArrayBased<TIndexKey, TPk>>, TReactiveIndexMap extends Record<TIndexName, TReactiveIndex> = Record<TIndexName, TReactiveIndex>> extends OIMReactiveCollection<TEntity, TPk> {
     readonly indexes?: TReactiveIndexMap;
     constructor(queue: OIMEventQueue, opts: {
         collectionOpts?: TOIMCollectionOptions<TEntity, TPk>;
@@ -454,6 +599,32 @@ declare class OIMCollectionStoreMapDriven<TEntity extends object, TPk extends TO
     getAllPks(): TPk[];
 }
 
+declare class OIMIndexStoreMapDrivenSetBased<TKey extends TOIMPk, TPk extends TOIMPk> extends OIMIndexStoreSetBased<TKey, TPk> {
+    protected readonly pks: Map<TKey, Set<TPk>>;
+    setOneByKey(key: TKey, pks: Set<TPk>): void;
+    removeOneByKey(key: TKey): void;
+    removeManyByKeys(keys: readonly TKey[]): void;
+    getOneByKey(key: TKey): Set<TPk> | undefined;
+    getManyByKeys(keys: readonly TKey[]): Map<TKey, Set<TPk>>;
+    getAllKeys(): TKey[];
+    getAll(): Map<TKey, Set<TPk>>;
+    countAll(): number;
+    clear(): void;
+}
+
+declare class OIMIndexStoreMapDrivenArrayBased<TKey extends TOIMPk, TPk extends TOIMPk> extends OIMIndexStoreArrayBased<TKey, TPk> {
+    protected readonly pks: Map<TKey, TPk[]>;
+    setOneByKey(key: TKey, pks: TPk[]): void;
+    removeOneByKey(key: TKey): void;
+    removeManyByKeys(keys: readonly TKey[]): void;
+    getOneByKey(key: TKey): TPk[] | undefined;
+    getManyByKeys(keys: readonly TKey[]): Map<TKey, TPk[]>;
+    getAllKeys(): TKey[];
+    getAll(): Map<TKey, TPk[]>;
+    countAll(): number;
+    clear(): void;
+}
+
 type TOIMComparator<TEntity extends object> = (a: TEntity, b: TEntity) => boolean;
 
 declare class OIMComparatorFactory<TEntity extends object> {
@@ -615,6 +786,23 @@ declare enum EOIMUpdateEventCoalescerEventType {
 
 type TOIMIndexKey = string | number | bigint;
 
+/**
+ * Configuration options for Set-based index instances */
+type TOIMIndexOptionsSetBased<TIndexKey extends TOIMPk, TPk extends TOIMPk> = {
+    comparePks?: TOIMIndexComparator<TPk>;
+    store?: OIMIndexStoreSetBased<TIndexKey, TPk>;
+};
+/**
+ * Configuration options for Array-based index instances */
+type TOIMIndexOptionsArrayBased<TIndexKey extends TOIMPk, TPk extends TOIMPk> = {
+    comparePks?: TOIMIndexComparator<TPk>;
+    store?: OIMIndexStoreArrayBased<TIndexKey, TPk>;
+};
+/**
+ * @deprecated Use TOIMIndexOptionsSetBased or TOIMIndexOptionsArrayBased instead
+ * Configuration options for index instances */
+type TOIMIndexOptions<TIndexKey extends TOIMPk, TPk extends TOIMPk> = TOIMIndexOptionsSetBased<TIndexKey, TPk>;
+
 type TOIMIndexPksUpdatePayload<TKey extends TOIMPk, TPk extends TOIMPk> = {
     key: TKey;
     pks: readonly TPk[];
@@ -626,4 +814,4 @@ type TOIMUpdatePayload<TKey> = {
     keys: readonly TKey[];
 };
 
-export { EOIMCollectionEventType, EOIMEventQueueEventType, EOIMEventQueueSchedulerEventType, EOIMIndexEventType, EOIMUpdateEventCoalescerEventType, type IOIMEventQueueSchedulerEvents, OIMCollection, OIMCollectionStore, OIMCollectionStoreMapDriven, OIMComparatorFactory, OIMDBSettings, OIMEntityUpdaterFactory, OIMEventEmitter, OIMEventQueue, OIMEventQueueScheduler, OIMEventQueueSchedulerAnimationFrame, OIMEventQueueSchedulerFactory, OIMEventQueueSchedulerImmediate, OIMEventQueueSchedulerMicrotask, OIMEventQueueSchedulerTimeout, OIMIndex, OIMIndexComparatorFactory, OIMIndexManual, OIMMap2Keys, OIMPkSelectorFactory, OIMRICollection, OIMReactiveCollection, OIMReactiveIndex, OIMReactiveIndexManual, OIMUpdateEventCoalescer, OIMUpdateEventCoalescerCollection, OIMUpdateEventCoalescerIndex, OIMUpdateEventEmitter, type TOIMCollectionOptions, type TOIMCollectionUpdatePayload, type TOIMComparator, type TOIMEntityUpdater, type TOIMEventHandler, type TOIMEventQueueOptions, type TOIMIndexComparator, type TOIMIndexKey, type TOIMIndexOptions, type TOIMIndexPksUpdatePayload, type TOIMIndexUpdatePayload, type TOIMPk, type TOIMPkSelector, type TOIMSchedulerOptions, type TOIMSchedulerType, type TOIMUpdateEventEmitterOptions, type TOIMUpdatePayload };
+export { EOIMCollectionEventType, EOIMEventQueueEventType, EOIMEventQueueSchedulerEventType, EOIMIndexEventType, EOIMUpdateEventCoalescerEventType, type IOIMEventQueueSchedulerEvents, OIMCollection, OIMCollectionStore, OIMCollectionStoreMapDriven, OIMComparatorFactory, OIMDBSettings, OIMEntityUpdaterFactory, OIMEventEmitter, OIMEventQueue, OIMEventQueueScheduler, OIMEventQueueSchedulerAnimationFrame, OIMEventQueueSchedulerFactory, OIMEventQueueSchedulerImmediate, OIMEventQueueSchedulerMicrotask, OIMEventQueueSchedulerTimeout, OIMIndexArrayBased, OIMIndexComparatorFactory, OIMIndexManualArrayBased, OIMIndexManualSetBased, OIMIndexSetBased, OIMIndexStoreArrayBased, OIMIndexStoreMapDrivenArrayBased, OIMIndexStoreMapDrivenSetBased, OIMIndexStoreSetBased, OIMMap2Keys, OIMPkSelectorFactory, OIMRICollection, OIMReactiveCollection, OIMReactiveIndexArrayBased, OIMReactiveIndexManualArrayBased, OIMReactiveIndexManualSetBased, OIMReactiveIndexSetBased, OIMUpdateEventCoalescer, OIMUpdateEventCoalescerCollection, OIMUpdateEventCoalescerIndex, OIMUpdateEventEmitter, type TOIMCollectionOptions, type TOIMCollectionUpdatePayload, type TOIMComparator, type TOIMEntityUpdater, type TOIMEventHandler, type TOIMEventQueueOptions, type TOIMIndexComparator, type TOIMIndexKey, type TOIMIndexOptions, type TOIMIndexOptionsArrayBased, type TOIMIndexOptionsSetBased, type TOIMIndexPksUpdatePayload, type TOIMIndexUpdatePayload, type TOIMPk, type TOIMPkSelector, type TOIMSchedulerOptions, type TOIMSchedulerType, type TOIMUpdateEventEmitterOptions, type TOIMUpdatePayload };