@devisfuture/mega-collection 2.4.6 → 2.4.8

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { EngineApi, EngineConstructor, MergeEngines, MergeEnginesChain, MergeEnginesOptions, MergeModuleName } from './merge/index.js';
+export { C as CollectionItem, F as FilterCriterion, I as IndexableKey, d as SortDescriptor, e as SortDirection, U as UpdateDescriptor } from './types-DONld7xY.js';

package/dist/index.mjs

@@ -1,2 +1 @@
-import { t as e } from "./chunk-BURK5sks.mjs";
-export { e as MergeEngines };
+import{t as m}from"./chunks/merge-BRXHTBZ0.mjs";export{m as MergeEngines};

package/dist/merge/index.d.ts

@@ -0,0 +1,128 @@
+import { C as CollectionItem, d as SortDescriptor, F as FilterCriterion, U as UpdateDescriptor } from '../types-DONld7xY.js';
+export { I as IndexableKey, e as SortDirection } from '../types-DONld7xY.js';
+
+type MergeModuleName = "search" | "sort" | "filter";
+interface MergeSearchOptions<T extends CollectionItem = CollectionItem> {
+    data?: T[];
+    fields?: (keyof T & string)[];
+    nestedFields?: string[];
+    minQueryLength?: number;
+    filterByPreviousResult?: boolean;
+}
+interface MergeSortOptions<T extends CollectionItem = CollectionItem> {
+    data?: T[];
+    fields?: (keyof T & string)[];
+}
+interface MergeFilterOptions<T extends CollectionItem = CollectionItem> {
+    data?: T[];
+    mutableExcludeField?: keyof T & string;
+    fields?: (keyof T & string)[];
+    nestedFields?: string[];
+}
+interface MergeEnginesChain<T extends CollectionItem> {
+    search(query: string): T[] & MergeEnginesChain<T>;
+    search(field: (keyof T & string) | (string & {}), query: string): T[] & MergeEnginesChain<T>;
+    sort(descriptors: SortDescriptor<T>[]): T[] & MergeEnginesChain<T>;
+    sort(data: T[], descriptors: SortDescriptor<T>[], inPlace?: boolean): T[] & MergeEnginesChain<T>;
+    filter(criteria: FilterCriterion<T>[]): T[] & MergeEnginesChain<T>;
+    filter(data: T[], criteria: FilterCriterion<T>[]): T[] & MergeEnginesChain<T>;
+    getOriginData(): T[];
+    add(items: T[]): MergeEngines<T>;
+    update(descriptor: UpdateDescriptor<T>): MergeEngines<T>;
+    data(data: T[]): MergeEngines<T>;
+    clearIndexes(module: MergeModuleName): T[] & MergeEnginesChain<T>;
+    clearData(module: MergeModuleName): T[] & MergeEnginesChain<T>;
+}
+interface EngineConstructor {
+    new (options: Record<string, unknown>): object;
+    prototype: object;
+    name: string;
+}
+interface EngineApi {
+    [methodName: string]: ((...args: unknown[]) => unknown) | undefined;
+}
+interface MergeEnginesOptions<T extends CollectionItem> {
+    imports: EngineConstructor[];
+    data: T[];
+    filterByPreviousResult?: boolean;
+    search?: MergeSearchOptions<T>;
+    filter?: MergeFilterOptions<T>;
+    sort?: MergeSortOptions<T>;
+    [key: string]: unknown;
+}
+
+/**
+ * MergeEngines class that provides a unified interface for text search,
+ * sorting, and filtering operations on collections.
+ */
+
+declare class MergeEngines<T extends CollectionItem> {
+    private readonly state;
+    private previousSearchState;
+    private previousFilterState;
+    private previousSortState;
+    private readonly searchModule;
+    private readonly sortModule;
+    private readonly filterModule;
+    private readonly chainBuilder;
+    /**
+     * Creates a new MergeEngines instance with the given options.
+     * Collects all modules from imports.
+     */
+    constructor(options: MergeEnginesOptions<T>);
+    private getAdapter;
+    /**
+     * Gets the initialization options for a module.
+     */
+    private getModuleInitOptions;
+    private validateFilterByPreviousResultOptions;
+    private isPreviousResultEnabled;
+    private getPreviousResultInput;
+    private trackPreviousResult;
+    private clearOperationState;
+    private createSearchCacheKey;
+    private createSortCacheKey;
+    private createFilterCacheKey;
+    private handleStateMutation;
+    private queueSearchCacheMutation;
+    private queueFilterCacheMutation;
+    private queueSortCacheMutation;
+    private resolvePendingSortCache;
+    private resolvePendingSearchCache;
+    private resolvePendingFilterCache;
+    private applySortCacheMutation;
+    private applySearchCacheMutation;
+    private applyFilterCacheMutation;
+    private canPatchStoredDatasetSearch;
+    private canPatchStoredDatasetFilter;
+    private canPatchStoredDatasetSort;
+    private compareItemsByDescriptors;
+    private findSortInsertPosition;
+    private findDatasetInsertPosition;
+    private doesItemMatchSearchCache;
+    private patchSearchCacheForAddedItems;
+    private patchSearchCacheForUpdatedItem;
+    private isPatchableFilterCriterion;
+    private doesItemMatchFilterCache;
+    private patchFilterCacheForAddedItems;
+    private patchFilterCacheForUpdatedItem;
+    private patchSortCacheForAddedItems;
+    private patchSortCacheForUpdatedItem;
+    private patchSortCacheForRemovedItems;
+    search(query: string): T[] & MergeEnginesChain<T>;
+    search(field: (keyof T & string) | (string & {}), query: string): T[] & MergeEnginesChain<T>;
+    sort(descriptors: SortDescriptor<T>[]): T[] & MergeEnginesChain<T>;
+    sort(data: T[], descriptors: SortDescriptor<T>[], inPlace?: boolean): T[] & MergeEnginesChain<T>;
+    filter(criteria: FilterCriterion<T>[]): T[] & MergeEnginesChain<T>;
+    filter(data: T[], criteria: FilterCriterion<T>[]): T[] & MergeEnginesChain<T>;
+    private withChain;
+    getOriginData(): T[];
+    add(items: T[]): this;
+    update(descriptor: UpdateDescriptor<T>): this;
+    clearIndexes(module: MergeModuleName): this;
+    data(data: T[]): this;
+    clearData(module: MergeModuleName): this;
+}
+
+export { CollectionItem, FilterCriterion, MergeEngines, SortDescriptor };
+export type { EngineApi, EngineConstructor, MergeEnginesChain, MergeEnginesOptions, MergeFilterOptions, MergeModuleName, MergeSearchOptions, MergeSortOptions };

package/dist/merge/index.mjs

@@ -1,2 +1 @@
-import { t as e } from "../chunk-BURK5sks.mjs";
-export { e as MergeEngines };
+import{t as m}from"../chunks/merge-BRXHTBZ0.mjs";export{m as MergeEngines};

package/dist/search/index.d.ts

@@ -0,0 +1,190 @@
+import { S as State } from '../State-CYIe-3He.js';
+import { C as CollectionItem, U as UpdateDescriptor } from '../types-DONld7xY.js';
+export { I as IndexableKey } from '../types-DONld7xY.js';
+
+interface TextSearchEngineOptions<T extends CollectionItem = CollectionItem> {
+    data?: T[];
+    fields?: (keyof T & string)[];
+    nestedFields?: string[];
+    /**
+     * Minimum query length required to trigger a search. Defaults to `1`.
+     *
+     * Queries shorter than the trigram length (3) always use a linear scan even
+     * when an index is configured, because the index only stores trigrams. Set
+     * `minQueryLength` to `3` or higher to skip sub-trigram queries entirely and
+     * guarantee that every accepted query hits the index.
+     */
+    minQueryLength?: number;
+    /**
+     * When `true`, each search narrows its source to the previous result if the
+     * new query includes the previous query as a prefix/substring. Useful for
+     * search-as-you-type scenarios where the user incrementally refines the query.
+     *
+     * Call {@link TextSearchEngine.resetSearchState} to discard the saved result
+     * and force the next search to scan the full dataset.
+     */
+    filterByPreviousResult?: boolean;
+    /**
+     * Suppresses non-production fallback warnings.
+     * Diagnostic warnings also stop accumulating in {@link TextSearchEngine.getWarnings}.
+     */
+    silent?: boolean;
+}
+interface SearchQueryOptions {
+    limit?: number;
+    offset?: number;
+}
+interface TextSearchEngineStats {
+    totalQueries: number;
+    indexedQueries: number;
+    fallbackQueries: number;
+    fallbackRate: number;
+    fallbackFields: Record<string, number>;
+}
+
+/**
+ * TextSearchEngine class for performing fast substring search on string fields
+ * using n-gram indexing and intersection.
+ */
+
+declare class TextSearchEngine<T extends CollectionItem> {
+    private readonly state;
+    private readonly namespace;
+    private readonly nestedCollection;
+    private readonly minQueryLength;
+    private readonly silent;
+    private cachedIndexedFieldsList;
+    private cachedLinearSearchFieldsList;
+    private readonly emittedWarningKeys;
+    private readonly warnings;
+    /**
+     * Lightweight normalizedValues-only cache for fields without n-gram index.
+     * Built lazily on first full-dataset linear scan for non-indexed fields.
+     */
+    private normalizedValuesCache;
+    private combinedNormalizedValuesCache;
+    /**
+     * Creates a new TextSearchEngine with optional data and fields to index.
+     */
+    constructor(options?: TextSearchEngineOptions<T> & {
+        state?: State<T>;
+    });
+    private get dataset();
+    private get runtime();
+    private get flatIndexes();
+    private get indexedFields();
+    private shouldDeferMutationIndexUpdates;
+    private markDeferredMutationState;
+    private ensureConfiguredIndexesReady;
+    private rebuildConfiguredIndexes;
+    /**
+     * Builds an n-gram index for the given field from arbitrary data.
+     */
+    private buildIndexFromData;
+    search(query: string, options?: SearchQueryOptions): T[];
+    search(field: (keyof T & string) | (string & {}), query: string, options?: SearchQueryOptions): T[];
+    searchAll(query: string, options?: SearchQueryOptions): T[];
+    private normalizeQuery;
+    private normalizeSearchWindow;
+    private shouldTrackPreviousResult;
+    private hasReachedWindowLimit;
+    private sliceItems;
+    private collectItemsFromIndices;
+    private createLookup;
+    private getRestrictionLookup;
+    /**
+     * Returns the data source for search based on filterByPreviousResult setting.
+     * When the new query narrows the previous one, returns previousResult with indices.
+     * Otherwise resets previous state and returns the full dataset.
+     */
+    private getSearchSource;
+    /**
+     * Saves the search result for potential reuse on subsequent narrowing queries.
+     */
+    private saveSearchResult;
+    private persistSearchResult;
+    /**
+     * Resets the previous search result, forcing the next search to use the full dataset.
+     *
+     * @see {@link TextSearchEngineOptions.filterByPreviousResult}
+     */
+    resetSearchState(): this;
+    getWarnings(): string[];
+    getStats(): TextSearchEngineStats;
+    resetStats(): this;
+    private clearPreviousSearchState;
+    private recordIndexedQuery;
+    private recordFallbackQuery;
+    private shouldEmitFallbackWarning;
+    private warnAboutFallback;
+    private getResolvedFlatIndex;
+    private getQueryGrams;
+    /**
+     * Searches all indexed fields.
+     */
+    private searchAllFields;
+    private searchAllFieldsIndexed;
+    private searchAllFieldsIndexedInCandidates;
+    /**
+     * Searches a specific field.
+     */
+    private searchField;
+    /**
+     * Searches a field using prepared query grams, returning matched items and indices.
+     * Delegates to searchFieldWithPreparedQueryIndices for the core intersection logic.
+     */
+    private searchFieldWithPreparedQuery;
+    /**
+     * Core indexed search: returns dataset indices of matching items.
+     * If the cached index is stale (version mismatch), rebuilds it lazily.
+     */
+    private searchFieldWithPreparedQueryIndices;
+    /**
+     * Returns the cached list of indexed field names, rebuilding if stale.
+     */
+    private getIndexedFieldsList;
+    private materializeIndicesResult;
+    private getLinearSearchFields;
+    /**
+     * Eagerly builds normalizedValues for a field without n-gram overhead.
+     * Stores in a lightweight cache so subsequent linear scans reuse it.
+     */
+    private buildNormalizedValuesOnly;
+    private buildCombinedNormalizedValues;
+    private buildCombinedNormalizedValue;
+    private getCombinedNormalizedValues;
+    /**
+     * Updates only the entry at `index` in every cached normalizedValues array,
+     * avoiding a full O(n) rebuild when a single item is updated.
+     */
+    private invalidateNormalizedValuesCacheEntry;
+    /**
+     * Searches all fields linearly, using pre-normalized values when available.
+     * When `sourceIndices` is provided, iterates only those dataset positions
+     * (previousResult narrowing path) and resolves items via this.dataset[idx].
+     */
+    private searchLinearAllFields;
+    /**
+     * Searches a specific field linearly, using pre-normalized values when available.
+     * When `sourceIndices` is provided, resolves items via this.dataset[idx].
+     */
+    private searchLinearSingleField;
+    clearIndexes(): this;
+    getOriginData(): T[];
+    data(data: T[]): this;
+    add(items: T[]): this;
+    update(descriptor: UpdateDescriptor<T>): this;
+    private applyAddedItems;
+    clearData(): this;
+    private handleStateMutation;
+    private addItemsToField;
+    private applyUpdatedItem;
+    private applyRemovedItem;
+    private updateIndexedField;
+    private removeIndexedFieldValue;
+    private moveIndexedFieldValue;
+    private getNormalizedFieldValue;
+}
+
+export { CollectionItem, TextSearchEngine };
+export type { SearchQueryOptions, TextSearchEngineOptions, TextSearchEngineStats };