@oimdb/core 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,588 @@
+type TOIMPk = string | number;
+
+declare abstract class OIMCollectionStore<TEntity extends object, TPk extends TOIMPk> {
+    abstract setOneByPk(pk: TPk, entity: TEntity): void;
+    abstract removeOneByPk(pk: TPk): void;
+    abstract removeManyByPks(pks: readonly TPk[]): void;
+    abstract getOneByPk(pk: TPk): TEntity | undefined;
+    abstract getManyByPks(pks: readonly TPk[]): Map<TPk, TEntity | undefined>;
+}
+
+type TOIMEventHandler<T> = (payload: T) => void;
+
+declare class OIMEventEmitter<T extends Record<string, unknown>> {
+    private buckets;
+    private getOrCreateBucket;
+    private compactBucket;
+    on<K extends keyof T>(event: K, handler: TOIMEventHandler<T[K]>): void;
+    emit<K extends keyof T>(event: K, payload: T[K]): void;
+    off<K extends keyof T>(event: K, handler: TOIMEventHandler<T[K]>): void;
+    offAll<K extends keyof T>(event?: K): void;
+}
+
+declare enum EOIMEventQueueSchedulerEventType {
+    FLUSH = 0
+}
+
+/**
+ * Events that can be emitted by the scheduler. */
+interface IOIMEventQueueSchedulerEvents extends Record<string, unknown> {
+    [EOIMEventQueueSchedulerEventType.FLUSH]: void;
+}
+
+/**
+ * Abstract base class for event queue schedulers.
+ * Provides common event emission functionality while leaving scheduling strategy to subclasses.
+ */
+declare abstract class OIMEventQueueScheduler {
+    protected readonly emitter: OIMEventEmitter<IOIMEventQueueSchedulerEvents>;
+    abstract schedule(): void;
+    abstract cancel(): void;
+    on<K extends keyof IOIMEventQueueSchedulerEvents>(event: K, handler: TOIMEventHandler<IOIMEventQueueSchedulerEvents[K]>): void;
+    off<K extends keyof IOIMEventQueueSchedulerEvents>(event: K, handler: TOIMEventHandler<IOIMEventQueueSchedulerEvents[K]>): void;
+    /**
+     * Trigger a flush event. Should be called by subclasses when they execute the scheduled flush.
+     */
+    protected flush(): void;
+}
+
+/**
+ * Payload for index update events containing the keys that were modified */
+interface TOIMIndexUpdatePayload<TKey> {
+    keys: readonly TKey[];
+}
+
+/**
+ * Comparator function for index primary key arrays.
+ * Returns true if the arrays are considered equal, false if they differ. */
+type TOIMIndexComparator<TPk extends TOIMPk> = (existingPks: readonly TPk[], newPks: readonly TPk[]) => boolean;
+
+/**
+ * Configuration options for index instances */
+type TOIMIndexOptions<TPk extends TOIMPk> = {
+    comparePks?: TOIMIndexComparator<TPk>;
+};
+
+/**
+ * Abstract base class for all index types.
+ * Provides common functionality and event system for key-to-PKs mappings.
+ */
+declare abstract class OIMIndex<TKey extends TOIMPk, TPk extends TOIMPk> {
+    protected readonly pks: Map<TKey, Set<TPk>>;
+    protected readonly comparePks?: TOIMIndexComparator<TPk>;
+    readonly emitter: OIMEventEmitter<{
+        0: TOIMIndexUpdatePayload<TKey>;
+    }>;
+    constructor(options?: TOIMIndexOptions<TPk>);
+    /**
+     * Get primary keys for multiple index keys
+     */
+    getPksByKeys(keys: readonly TKey[]): Map<TKey, readonly TPk[]>;
+    /**
+     * @deprecated Use getPksByKey instead
+     * Get primary keys for a specific index key
+     */
+    getPks(key: TKey): readonly TPk[];
+    /**
+     * Get primary keys for a specific index key
+     */
+    getPksByKey(key: TKey): readonly 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: readonly TPk[]): boolean;
+    /**
+     * Emit update event with changed keys
+     */
+    protected emitUpdate(keys: TKey[]): void;
+}
+
+/**
+ * Base abstract coalescer that groups updates by keys and emits consolidated events.
+ * Designed to be extended for different entity types (collections, indexes, etc.).
+ */
+declare abstract class OIMUpdateEventCoalescer<TKey> {
+    readonly emitter: OIMEventEmitter<{
+        0: void;
+    }>;
+    protected updatedKeys: Set<TKey>;
+    private hasEmittedChanges;
+    /**
+     * Get the set of keys that have been updated since last clear
+     */
+    getUpdatedKeys(): Set<TKey>;
+    /**
+     * Clear all updated keys and reset the changed state
+     */
+    clearUpdatedKeys(): void;
+    /**
+     * Add keys to the updated set and emit HAS_CHANGES event if needed
+     */
+    protected addUpdatedKeys(keys: TKey[]): void;
+    /**
+     * Clean up event listeners when coalescer is no longer needed
+     */
+    abstract destroy(): void;
+}
+
+/**
+ * Configuration options for event queue initialization.
+ */
+type TOIMEventQueueOptions = {
+    /**
+     * Optional scheduler for automatic queue flushing.
+     * If provided, the queue will automatically schedule flush operations when items are enqueued.
+     * If not provided, flush() must be called manually.
+     */
+    scheduler?: OIMEventQueueScheduler;
+};
+
+/**
+ * Event queue that can optionally integrate with a scheduler for automatic flushing.
+ */
+declare class OIMEventQueue {
+    protected queue: (() => void)[];
+    protected readonly scheduler?: OIMEventQueueScheduler;
+    protected flushBound?: () => void;
+    constructor(options?: TOIMEventQueueOptions);
+    /**
+     * Add a function to the queue. If scheduler is configured and autoSchedule is enabled,
+     * automatically schedules a flush operation.
+     */
+    enqueue(fn: () => void): void;
+    /**
+     * Execute all queued functions and clear the queue.
+     * This method is safe to call multiple times and handles reentrancy.
+     */
+    flush(): void;
+    /**
+     * Get the current number of queued functions.
+     */
+    get length(): number;
+    /**
+     * Check if the queue is empty.
+     */
+    get isEmpty(): boolean;
+    /**
+     * Clear the queue without executing functions and cancel any scheduled flush.
+     */
+    clear(): void;
+    /**
+     * Clean up scheduler subscription when queue is no longer needed.
+     */
+    destroy(): void;
+}
+
+/**
+ * Options for creating an update event emitter */
+type TOIMUpdateEventEmitterOptions<TKey> = {
+    coalescer: OIMUpdateEventCoalescer<TKey>;
+    queue: OIMEventQueue;
+};
+
+/**
+ * Universal event emitter that handles subscriptions and notifications for any key type.
+ * Optimized for performance with adaptive algorithms and memory management.
+ */
+declare class OIMUpdateEventEmitter<TKey> {
+    protected keyHandlers: Map<TKey, Set<TOIMEventHandler<void>>>;
+    protected coalescer: OIMUpdateEventCoalescer<TKey>;
+    protected queue: OIMEventQueue;
+    constructor(opts: TOIMUpdateEventEmitterOptions<TKey>);
+    protected handleHasChanges: () => void;
+    destroy(): void;
+    /**
+     * Get performance metrics for monitoring and debugging
+     */
+    getMetrics(): {
+        totalKeys: number;
+        totalHandlers: number;
+        averageHandlersPerKey: number;
+        queueLength: number;
+    };
+    /**
+     * Check if there are any active subscriptions
+     */
+    hasSubscriptions(): boolean;
+    /**
+     * Get the number of handlers for a specific key
+     */
+    getHandlerCount(key: TKey): number;
+    subscribeOnKey(key: TKey, handler: TOIMEventHandler<void>): () => void;
+    unsubscribeFromKey(key: TKey, handler: TOIMEventHandler<void>): void;
+    subscribeOnKeys(keys: readonly TKey[], handler: TOIMEventHandler<void>): () => void;
+    unsubscribeFromKeys(keys: readonly TKey[], handler: TOIMEventHandler<void>): void;
+}
+
+declare enum EOIMIndexEventType {
+    UPDATE = 0
+}
+
+/**
+ * Index-specific coalescer that tracks index key updates and emits consolidated change events.
+ * Takes an event emitter directly instead of the whole index to avoid circular dependencies.
+ */
+declare class OIMUpdateEventCoalescerIndex<TIndexKey> extends OIMUpdateEventCoalescer<TIndexKey> {
+    private readonly indexEmitter;
+    constructor(indexEmitter: OIMEventEmitter<{
+        [EOIMIndexEventType.UPDATE]: TOIMIndexUpdatePayload<TIndexKey>;
+    }>);
+    destroy(): void;
+    /**
+     * When the index is updated, we keep track of the updated keys.
+     */
+    private handleUpdate;
+}
+
+declare abstract class OIMReactiveIndex<TKey extends TOIMPk, TPk extends TOIMPk, TIndex extends OIMIndex<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): readonly TPk[];
+    getPksByKeys(keys: readonly TKey[]): Map<TKey, readonly 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;
+
+type TOIMCollectionOptions<TEntity extends object, TPk extends TOIMPk> = {
+    selectPk?: TOIMPkSelector<TEntity, TPk>;
+    store?: OIMCollectionStore<TEntity, TPk>;
+    updateEntity?: TOIMEntityUpdater<TEntity>;
+};
+
+type TOIMCollectionUpdatePayload<TPk extends TOIMPk> = {
+    pks: readonly TPk[];
+};
+
+/** It's like a store - but with event emitter */
+declare class OIMCollection<TEntity extends object, TPk extends TOIMPk> {
+    readonly emitter: OIMEventEmitter<{
+        0: TOIMCollectionUpdatePayload<TPk>;
+    }>;
+    protected readonly selectPk: TOIMPkSelector<TEntity, TPk>;
+    protected readonly store: OIMCollectionStore<TEntity, TPk>;
+    protected readonly updateEntity: TOIMEntityUpdater<TEntity>;
+    constructor(opts?: TOIMCollectionOptions<TEntity, TPk>);
+    getOneByPk(pk: TPk): TEntity | undefined;
+    getManyByPks(pks: readonly TPk[]): Map<TPk, TEntity | undefined>;
+    upsertOne(entity: TEntity): void;
+    upsertMany(entities: TEntity[]): void;
+    removeOne(entity: TEntity): void;
+    removeMany(entities: TEntity[]): void;
+    protected upsertOneWithoutNotifications(entity: TEntity): TPk;
+}
+
+declare enum EOIMCollectionEventType {
+    UPDATE = 0
+}
+
+/**
+ * Collection-specific coalescer that tracks primary key updates and emits consolidated change events.
+ * Takes an event emitter directly instead of the whole collection to avoid circular dependencies.
+ */
+declare class OIMUpdateEventCoalescerCollection<TPk extends TOIMPk> extends OIMUpdateEventCoalescer<TPk> {
+    private readonly collectionEmitter;
+    constructor(collectionEmitter: OIMEventEmitter<{
+        [EOIMCollectionEventType.UPDATE]: TOIMCollectionUpdatePayload<TPk>;
+    }>);
+    destroy(): void;
+    /**
+     * When the collection is updated, we keep track of the updated pks.
+     */
+    private handleUpdate;
+}
+
+declare class OIMReactiveCollection<TEntity extends object, TPk extends TOIMPk> {
+    readonly collection: OIMCollection<TEntity, TPk>;
+    readonly updateEventEmitter: OIMUpdateEventEmitter<TPk>;
+    readonly coalescer: OIMUpdateEventCoalescerCollection<TPk>;
+    constructor(queue: OIMEventQueue, opts?: {
+        collectionOpts?: TOIMCollectionOptions<TEntity, TPk>;
+    });
+    upsertMany(entities: TEntity[]): void;
+    upsertOne(entity: TEntity): void;
+    removeMany(entities: TEntity[]): void;
+    removeOne(entity: TEntity): void;
+    getOneByPk(pk: TPk): TEntity | undefined;
+    getManyByPks(pks: readonly TPk[]): Map<TPk, TEntity | undefined>;
+}
+
+/**
+ * Manual index that allows direct manipulation of key-to-primary-keys mappings.
+ * Extends the abstract OIMIndex with manual control methods and optional comparison.
+ */
+declare class OIMIndexManual<TIndexKey extends TOIMPk, TPk extends TOIMPk> extends OIMIndex<TIndexKey, TPk> {
+    constructor(options?: TOIMIndexOptions<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: readonly 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 OIMReactiveIndexManual<TKey extends TOIMPk, TPk extends TOIMPk> extends OIMReactiveIndex<TKey, TPk, OIMIndexManual<TKey, TPk>> {
+    constructor(queue: OIMEventQueue, opts?: {
+        index: OIMIndexManual<TKey, TPk>;
+    });
+    protected createDefaultIndex(): OIMIndexManual<TKey, TPk>;
+    setPks(key: TKey, pks: readonly 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>> extends OIMReactiveCollection<TEntity, TPk> {
+    readonly indexes: Record<TIndexName, TReactiveIndex>;
+    constructor(queue: OIMEventQueue, opts: {
+        collectionOpts?: TOIMCollectionOptions<TEntity, TPk>;
+        indexes: Record<TIndexName, TReactiveIndex>;
+    });
+}
+
+declare class OIMCollectionStoreMapDriven<TEntity extends object, TPk extends TOIMPk> extends OIMCollectionStore<TEntity, TPk> {
+    protected readonly entities: Map<TPk, TEntity>;
+    setOneByPk(pk: TPk, entity: TEntity): void;
+    setManyByPks(pks: readonly TPk[], entities: TEntity[]): void;
+    removeOneByPk(pk: TPk): void;
+    removeManyByPks(pks: readonly TPk[]): void;
+    getOneByPk(pk: TPk): TEntity | undefined;
+    getManyByPks(pks: readonly TPk[]): Map<TPk, TEntity | undefined>;
+}
+
+type TOIMComparator<TEntity extends object> = (a: TEntity, b: TEntity) => boolean;
+
+declare class OIMComparatorFactory<TEntity extends object> {
+    createShallowComparator(): TOIMComparator<TEntity>;
+}
+
+declare class OIMEntityUpdaterFactory<TEntity extends object> {
+    createMergeEntityUpdater(): TOIMEntityUpdater<TEntity>;
+}
+
+/**
+ * Factory for creating index comparators.
+ * Provides common comparison strategies for primary key arrays.
+ */
+declare class OIMIndexComparatorFactory {
+    /**
+     * Create an element-wise comparator that checks arrays for strict equality.
+     * Compares array lengths and each element using strict equality (===).
+     */
+    static createElementWiseComparator<TPk extends TOIMPk>(): TOIMIndexComparator<TPk>;
+    /**
+     * Create a set-based comparator that checks if arrays contain the same elements.
+     * Order doesn't matter, only the presence of elements.
+     */
+    static createSetBasedComparator<TPk extends TOIMPk>(): TOIMIndexComparator<TPk>;
+    /**
+     * Create a shallow comparator that only checks array references.
+     * Fastest but only works if you're reusing the same array instances.
+     */
+    static createShallowComparator<TPk extends TOIMPk>(): TOIMIndexComparator<TPk>;
+    /**
+     * Create a no-comparison comparator that always returns false (always updates).
+     * Useful for disabling comparison while keeping the same interface.
+     */
+    static createAlwaysUpdateComparator<TPk extends TOIMPk>(): TOIMIndexComparator<TPk>;
+}
+
+declare class OIMMap2Keys<K1, K2, V> {
+    private map;
+    private _size;
+    get size(): number;
+    set(k1: K1, k2: K2, v: V): void;
+    get(k1: K1, k2: K2): V | undefined;
+    has(k1: K1, k2: K2): boolean | undefined;
+    delete(k1: K1, k2: K2): boolean;
+    clear(): void;
+}
+
+declare class OIMPkSelectorFactory<TEntity extends object, TPk extends TOIMPk> {
+    createIdSelector(): TOIMPkSelector<TEntity & {
+        id: TPk;
+    }, TPk>;
+}
+
+/**
+ * Animation frame-based scheduler that executes flushes synchronized with the browser's repaint cycle.
+ * Ideal for UI-related updates that need to be synchronized with rendering.
+ * Falls back to setTimeout in non-browser environments.
+ */
+declare class OIMEventQueueSchedulerAnimationFrame extends OIMEventQueueScheduler {
+    protected frameId?: number;
+    protected readonly useRequestAnimationFrame: boolean;
+    constructor();
+    schedule(): void;
+    cancel(): void;
+}
+
+/**
+ * Available scheduler types for event queue configuration.
+ */
+type TOIMSchedulerType = 'microtask' | 'animationFrame' | 'timeout' | 'immediate';
+
+/**
+ * Configuration options for different scheduler types. */
+type TOIMSchedulerOptions = {
+    microtask: never;
+    animationFrame: never;
+    timeout: {
+        delay?: number;
+    };
+    immediate: never;
+};
+
+/**
+ * Microtask-based scheduler that executes flushes in the next microtask.
+ * Ideal for batching synchronous operations while maintaining immediate execution.
+ */
+declare class OIMEventQueueSchedulerMicrotask extends OIMEventQueueScheduler {
+    protected scheduled: boolean;
+    schedule(): void;
+    cancel(): void;
+}
+
+/**
+ * Timeout-based scheduler that executes flushes after a specified delay.
+ * Useful for debouncing operations or creating custom timing strategies.
+ */
+declare class OIMEventQueueSchedulerTimeout extends OIMEventQueueScheduler {
+    protected timeoutId?: number;
+    protected readonly delay: number;
+    /**
+     * @param delay - Delay in milliseconds before executing the flush (default: 0)
+     */
+    constructor(delay?: number);
+    schedule(): void;
+    cancel(): void;
+}
+
+/**
+ * Immediate-based scheduler that executes flushes using setImmediate or fallback mechanisms.
+ * Provides faster execution than setTimeout(0) in Node.js environments.
+ * Falls back to setTimeout(0) in browsers and MessageChannel in modern browsers for better performance.
+ */
+declare class OIMEventQueueSchedulerImmediate extends OIMEventQueueScheduler {
+    protected immediateId?: number;
+    protected readonly useSetImmediate: boolean;
+    protected readonly useMessageChannel: boolean;
+    protected messageChannel?: MessageChannel;
+    protected pendingCallback?: () => void;
+    constructor();
+    schedule(): void;
+    cancel(): void;
+}
+
+/**
+ * Factory for creating event queue schedulers.
+ * Provides a convenient way to create schedulers with type-safe configuration.
+ */
+declare class OIMEventQueueSchedulerFactory {
+    /**
+     * Create a scheduler of the specified type with optional configuration.
+     */
+    static create<T extends TOIMSchedulerType>(type: T, ...args: TOIMSchedulerOptions[T] extends never ? [] : [TOIMSchedulerOptions[T]]): OIMEventQueueScheduler;
+    /**
+     * Create a microtask scheduler (most common for general use).
+     */
+    static createMicrotask(): OIMEventQueueSchedulerMicrotask;
+    /**
+     * Create an animation frame scheduler (ideal for UI updates).
+     */
+    static createAnimationFrame(): OIMEventQueueSchedulerAnimationFrame;
+    /**
+     * Create a timeout scheduler with optional delay.
+     */
+    static createTimeout(delay?: number): OIMEventQueueSchedulerTimeout;
+    /**
+     * Create an immediate scheduler (fastest execution).
+     */
+    static createImmediate(): OIMEventQueueSchedulerImmediate;
+}
+
+/**
+ * Event types for update coalescers */
+declare enum EOIMUpdateEventCoalescerEventType {
+    HAS_CHANGES = 0
+}
+
+type TOIMIndexKey = string | number | bigint;
+
+type TOIMIndexPksUpdatePayload<TKey extends TOIMPk, TPk extends TOIMPk> = {
+    key: TKey;
+    pks: readonly TPk[];
+};
+
+/**
+ * Payload type for update events that contain keys */
+type TOIMUpdatePayload<TKey> = {
+    keys: readonly TKey[];
+};
+
+export { EOIMCollectionEventType, EOIMEventQueueSchedulerEventType, EOIMIndexEventType, EOIMUpdateEventCoalescerEventType, type IOIMEventQueueSchedulerEvents, OIMCollection, OIMCollectionStore, OIMCollectionStoreMapDriven, OIMComparatorFactory, 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 };