@devisfuture/mega-collection 1.0.8 → 1.0.10

package/README.md

@@ -2,7 +2,7 @@
   <img src="./illustration.png" alt="electron-modular illustration" width="640" />
 </p>
 
-[![codecov](https://codecov.io/gh/trae-op/mega-collection/branch/main/graph/badge.svg?token=MZHSKKPV79)](https://codecov.io/gh/trae-op/mega-collection) [![TypeScript](https://img.shields.io/badge/TypeScript-%233178C6.svg?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![npm version](https://img.shields.io/npm/v/@devisfuture/mega-collection.svg)](https://www.npmjs.com/package/@devisfuture/mega-collection) [![codecov](https://codecov.io/gh/trae-op/mega-collection/branch/main/graph/badge.svg?token=MZHSKKPV79)](https://codecov.io/gh/trae-op/mega-collection) [![TypeScript](https://img.shields.io/badge/TypeScript-%233178C6.svg?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 
 # @devisfuture/mega-collection
 

package/dist/filter/index.d.mts

@@ -1,117 +1,35 @@
-import { C as CollectionItem, F as FilterCriterion } from '../types-BlZO_NQA.mjs';
-export { I as IndexableKey } from '../types-BlZO_NQA.mjs';
+import { C as CollectionItem, F as FilterCriterion } from '../types-D24zQWME.mjs';
+export { I as IndexableKey } from '../types-D24zQWME.mjs';
 
 /**
- * FilterEngine — multi-criteria filtering optimised for 10 M+ rows.
- *
- * Strategy:
- *  1. If hash-map indexes exist (built via buildIndex), use O(1) lookups per
- *     value and intersect results across fields.  This is the *fast path*.
- *
- *  2. If no index is available for a field, fall back to a single-pass linear
- *     scan using a `Set` for each criterion (O(n) but with O(1) membership
- *     test per item).
- *
- *  Multiple criteria are combined with AND logic: an item must satisfy
- *  ALL criteria to be included.
+ * FilterEngine class for filtering collections by multiple criteria,
+ * supporting indexed lookups and linear scans for large datasets.
  */
 
 interface FilterEngineOptions<T extends CollectionItem = CollectionItem> {
-    /**
-     * The dataset to index. When provided together with `fields`, all indexes
-     * are built automatically inside the constructor — no manual `buildIndex`
-     * calls needed.
-     *
-     * @example
-     * ```ts
-     * const engine = new FilterEngine<User>({ data: users, fields: ["city", "age"] });
-     * engine.filter(users, [{ field: "city", values: ["Kyiv"] }]);
-     * ```
-     */
     data?: T[];
-    /**
-     * Fields to build a hash-map index for. Requires `data` to be set as well.
-     * When both are present, `buildIndex` is called for each field in the constructor.
-     */
     fields?: (keyof T & string)[];
-    /**
-     * Enables sequential filtering by the previous filter result.
-     *
-     * When `true`, each call to `filter(criteria)` (without explicit `data`)
-     * uses the previous filter output as the next input dataset.
-     *
-     * @default false
-     */
     filterByPreviousResult?: boolean;
 }
 declare class FilterEngine<T extends CollectionItem> {
     private indexer;
     private readonly filterByPreviousResult;
-    /** Reference to the full dataset (set via the constructor or `buildIndex`). */
     private data;
-    /** Last filter output used as the next input in sequential mode. */
     private previousResult;
-    /** Last criteria used in sequential mode. */
     private previousCriteria;
-    /** Dataset reference used to compute previous sequential result. */
     private previousBaseData;
     constructor(options?: FilterEngineOptions<T>);
-    /**
-     * Build a hash-map index for a field to enable O(1) fast-path filtering.
-     *
-     * Two call signatures are supported:
-     *  - `buildIndex(data, field)` — explicit dataset (original API)
-     *  - `buildIndex(field)`       — reuses the dataset supplied in the constructor
-     *
-     * @returns `this` for chaining.
-     */
     private buildIndex;
-    /**
-     * Free all index memory.
-     */
     clearIndexes(): void;
-    /**
-     * Reset sequential filtering state.
-     *
-     * Useful when `filterByPreviousResult` is enabled and you want
-     * the next `filter(criteria)` call to start from the full dataset.
-     */
     resetFilterState(): void;
-    /**
-     * Apply multiple filter criteria (AND logic).
-     *
-     * Two call signatures:
-     *  - `filter(criteria)`       — uses the dataset supplied in the constructor.
-     *  - `filter(data, criteria)` — explicit dataset (original API).
-     *
-     * @returns Filtered array.
-     */
     filter(criteria: FilterCriterion<T>[]): T[];
     filter(data: T[], criteria: FilterCriterion<T>[]): T[];
     private cloneCriteria;
     private hasCriteriaAdditions;
     private hasCriteriaRemovals;
     private getAddedCriteria;
-    /**
-     * Single-pass linear filter using pre-indexed criteria value Sets.
-     * O(n × k) where n = data.length, k = criteria count.
-     * Each criterion check is O(1) via Map + Set lookup — no nested data iteration.
-     */
     private linearFilter;
-    /**
-     * Pure index-based filtering with selectivity-driven pruning.
-     *
-     * Strategy:
-     *  1. Sort criteria by estimated result-set size (smallest first).
-     *  2. Materialise only the most selective criterion via the index.
-     *  3. Pre-index remaining criteria values into Sets for O(1) checks.
-     *  4. Single-pass filter over candidates — no nested collection iteration.
-     */
     private filterViaIndex;
-    /**
-     * Estimate the number of items an indexed criterion would return.
-     * Used to sort criteria by selectivity for faster intersection.
-     */
     private estimateIndexSize;
 }
 

package/dist/index.d.mts

@@ -1,75 +1,31 @@
 import { TextSearchEngine, TextSearchEngineOptions } from './search/index.mjs';
 import { FilterEngine } from './filter/index.mjs';
 import { SortEngine } from './sort/index.mjs';
-import { C as CollectionItem, S as SortDescriptor, F as FilterCriterion } from './types-BlZO_NQA.mjs';
-export { I as IndexableKey, a as SortDirection } from './types-BlZO_NQA.mjs';
+import { C as CollectionItem, S as SortDescriptor, F as FilterCriterion } from './types-D24zQWME.mjs';
+export { I as IndexableKey, a as SortDirection } from './types-D24zQWME.mjs';
 
 /**
- * MergeEngines — unified facade that composes TextSearchEngine, SortEngine
- * and FilterEngine into a single entry point.
- *
- * Design:
- *  - The `imports` array declares which sub-engines to activate.
- *  - Each sub-engine is initialised lazily only when its constructor appears
- *    in `imports` AND the corresponding config section is provided.
- *  - Delegates `search`, `sort` and `filter` calls directly to the underlying
- *    engines — zero logic duplication.
- *
- * @example
- * ```ts
- * import { MergeEngines } from "@devisfuture/mega-collection";
- * import { TextSearchEngine } from "@devisfuture/mega-collection/search";
- * import { SortEngine }       from "@devisfuture/mega-collection/sort";
- * import { FilterEngine }     from "@devisfuture/mega-collection/filter";
- *
- * const engine = new MergeEngines<User>({
- *   imports: [TextSearchEngine, SortEngine, FilterEngine],
- *   data: users,
- *   search: { fields: ["city", "name"], minQueryLength: 2 },
- *   filter: { fields: ["city", "age"] },
- *   sort:   { fields: ["age", "name", "city"] },
- * });
- *
- * engine.search("john");
- * engine.sort([{ field: "age", direction: "asc" }]);
- * engine.filter([{ field: "city", values: ["Kyiv"] }]);
- * ```
+ * MergeEngines class that provides a unified interface for text search,
+ * sorting, and filtering operations on collections.
  */
 
-/** Search-specific configuration (excludes `data` — shared at the top level). */
 interface MergeSearchConfig<T extends CollectionItem> {
     fields: (keyof T & string)[];
     minQueryLength?: TextSearchEngineOptions<T>["minQueryLength"];
 }
-/** Filter-specific configuration (excludes `data` — shared at the top level). */
 interface MergeFilterConfig<T extends CollectionItem> {
     fields: (keyof T & string)[];
     filterByPreviousResult?: boolean;
 }
-/** Sort-specific configuration (excludes `data` — shared at the top level). */
 interface MergeSortConfig<T extends CollectionItem> {
     fields: (keyof T & string)[];
 }
-/** Union of the three engine constructors accepted in `imports`. */
 type EngineConstructor = typeof TextSearchEngine | typeof SortEngine | typeof FilterEngine;
 interface MergeEnginesOptions<T extends CollectionItem> {
-    /**
-     * List of engine classes to activate.
-     * Only engines present in this array will be initialised.
-     *
-     * @example
-     * ```ts
-     * imports: [TextSearchEngine, SortEngine, FilterEngine]
-     * ```
-     */
     imports: EngineConstructor[];
-    /** Shared dataset — passed to every activated engine. */
     data: T[];
-    /** Config for TextSearchEngine (requires `TextSearchEngine` in `imports`). */
     search?: MergeSearchConfig<T>;
-    /** Config for FilterEngine (requires `FilterEngine` in `imports`). */
     filter?: MergeFilterConfig<T>;
-    /** Config for SortEngine (requires `SortEngine` in `imports`). */
     sort?: MergeSortConfig<T>;
 }
 declare class MergeEngines<T extends CollectionItem> {
@@ -77,33 +33,10 @@ declare class MergeEngines<T extends CollectionItem> {
     private readonly sortEngine;
     private readonly filterEngine;
     constructor(options: MergeEnginesOptions<T>);
-    /**
-     * Search items by substring across all indexed fields.
-     *
-     * Delegates to `TextSearchEngine.search`.
-     *
-     * @throws {Error} If `TextSearchEngine` was not included in `imports`.
-     */
     search(query: string): T[];
     search(field: keyof T & string, query: string): T[];
-    /**
-     * Sort items by one or more fields.
-     *
-     * Delegates to `SortEngine.sort`.
-     * Uses the shared dataset from the constructor when called without `data`.
-     *
-     * @throws {Error} If `SortEngine` was not included in `imports`.
-     */
     sort(descriptors: SortDescriptor<T>[]): T[];
     sort(data: T[], descriptors: SortDescriptor<T>[], inPlace?: boolean): T[];
-    /**
-     * Filter items by multiple criteria (AND logic).
-     *
-     * Delegates to `FilterEngine.filter`.
-     * Uses the shared dataset from the constructor when called without `data`.
-     *
-     * @throws {Error} If `FilterEngine` was not included in `imports`.
-     */
     filter(criteria: FilterCriterion<T>[]): T[];
     filter(data: T[], criteria: FilterCriterion<T>[]): T[];
 }

package/dist/merge/index.d.mts

@@ -1,5 +1,5 @@
 export { EngineConstructor, MergeEngines, MergeEnginesOptions, MergeFilterConfig, MergeSearchConfig, MergeSortConfig } from '../index.mjs';
-export { C as CollectionItem, F as FilterCriterion, I as IndexableKey, S as SortDescriptor, a as SortDirection } from '../types-BlZO_NQA.mjs';
+export { C as CollectionItem, F as FilterCriterion, I as IndexableKey, S as SortDescriptor, a as SortDirection } from '../types-D24zQWME.mjs';
 import '../search/index.mjs';
 import '../filter/index.mjs';
 import '../sort/index.mjs';

package/dist/search/index.d.mts

@@ -1,97 +1,27 @@
-import { C as CollectionItem } from '../types-BlZO_NQA.mjs';
-export { I as IndexableKey } from '../types-BlZO_NQA.mjs';
+import { C as CollectionItem } from '../types-D24zQWME.mjs';
+export { I as IndexableKey } from '../types-D24zQWME.mjs';
 
 /**
- * TextSearchEngine — fast substring search on 10 M+ string fields.
- *
- * Strategy:
- *  1. **N-gram index (1..3 chars)** — every string is split into overlapping
- *     1/2/3-character grams. Each gram maps to a Set of item indexes.
- *     At query time we intersect posting lists to get *candidates*, then verify
- *     with `String.includes` (which is very fast on a small candidate set).
- *
- *  Building the trigram index is O(n·L) where L is average string length.
- *  Query time is roughly O(|candidates| + |postingList intersections|).
+ * TextSearchEngine class for performing fast substring search on string fields
+ * using n-gram indexing and intersection.
  */
 
 interface TextSearchEngineOptions<T extends CollectionItem = CollectionItem> {
-    /**
-     * The dataset to index. When provided together with `fields`, all indexes
-     * are built automatically inside the constructor — no manual `buildIndex`
-     * calls needed.
-     *
-     * @example
-     * ```ts
-     * const engine = new TextSearchEngine<User>({ data: users, fields: ["name", "city"] });
-     * engine.search("john"); // searches both fields, deduplicated
-     * ```
-     */
     data?: T[];
-    /**
-     * Fields to build a trigram index for. Requires `data` to be set as well.
-     * When both are present, `buildIndex` is called for each field in the constructor.
-     */
     fields?: (keyof T & string)[];
-    /**
-     * Minimum number of characters required before a search is executed.
-     * Queries shorter than this return an empty array immediately.
-     *
-     * Why this matters: a single-character query uses 1-grams whose posting
-     * lists can span the majority of the dataset (e.g. "a" matches 70–80 % of
-     * names/cities), forcing `String.includes` verification over tens of
-     * thousands of candidates.  Setting this to 2 or 3 dramatically reduces
-     * the candidate set and keeps searches fast even with 100 k+ items.
-     *
-     * @default 1  (backwards-compatible; set to 2 or 3 for better perf)
-     */
     minQueryLength?: number;
 }
 declare class TextSearchEngine<T extends CollectionItem> {
-    /**
-     * field → ngram → Set<index in data[]>
-     * We store *indexes into the data array* (not the objects) to save memory.
-     */
     private ngramIndexes;
-    /** Reference to the full dataset (set once via `buildIndex` or the constructor). */
     private data;
-    /** Minimum query length before the engine executes a search. */
     private readonly minQueryLength;
     constructor(options?: TextSearchEngineOptions<T>);
-    /**
-     * Build n-gram index (1..3 chars) for one field. O(n·L).
-     *
-     * Two call signatures are supported:
-     *  - `buildIndex(data, field)` — explicit dataset (original API)
-     *  - `buildIndex(field)`       — reuses the dataset supplied in the constructor
-     *
-     * Trigram extraction is inlined to avoid allocating a temporary array
-     * and a deduplication Set per item.  Posting lists are `Set<number>`,
-     * so duplicate `.add()` calls for the same itemIndex are no-ops — we
-     * get correctness without per-item deduplication overhead.
-     *
-     * For 10 M+ items this eliminates ~20 M transient object allocations
-     * and dramatically reduces GC pressure.
-     */
     private buildIndex;
-    /**
-     * Search items by substring (contains) using the trigram index.
-     *
-     * Two call signatures are supported:
-     *  - `search(query)`        — searches **all** indexed fields and returns a
-     *                             deduplicated union (preserves field order).
-     *  - `search(field, query)` — searches a single specific field.
-     *
-     * Both paths return only items whose field value actually contains the query
-     * (trigram candidates are verified with `String.includes`).
-     */
     search(query: string): T[];
     search(field: keyof T & string, query: string): T[];
-    /** Search across every indexed field and return a deduplicated union. */
     private searchAllFields;
-    /** Core search implementation for a single field. */
     private searchField;
     private searchFieldWithPreparedQuery;
-    /** Free memory. */
     clear(): void;
 }
 

package/dist/sort/index.d.mts

@@ -1,105 +1,26 @@
-import { C as CollectionItem, S as SortDescriptor } from '../types-BlZO_NQA.mjs';
-export { a as SortDirection } from '../types-BlZO_NQA.mjs';
+import { C as CollectionItem, S as SortDescriptor } from '../types-D24zQWME.mjs';
+export { a as SortDirection } from '../types-D24zQWME.mjs';
 
 /**
- * SortEngine — high-performance sorting for 10 M+ rows.
- *
- * Strategy:
- *  1. **Pre-sorted index cache** (fastest): `buildIndex` pre-computes a sorted
- *     `Uint32Array` of item positions once — O(n log n). Every subsequent
- *     `sort` call on that field is O(n) reconstruction (no comparison at all).
- *     Reversing direction is also O(n) — just walk the index backwards.
- *
- *  2. **In-place sort** using the native V8 TimSort (`Array.prototype.sort`)
- *     which is O(n log n) and very cache-friendly for large arrays.
- *
- *  3. **Pre-compiled comparator**: we build a single comparator function that
- *     handles multi-field sorting with correct direction, avoiding per-compare
- *     overhead of dynamic field resolution.
- *
- *  4. **Typed-array radix sort** (fallback for single numeric field):
- *     O(n) index-sort using `Float64Array` for extreme speed on numeric data.
- *
- *  5. Returns a **new array** by default to keep the original intact.
- *     Pass `inPlace: true` to mutate.
+ * SortEngine class for sorting large datasets using pre-built indexes
+ * for O(n) performance or fallback to in-place sorting.
  */
 
 interface SortEngineOptions<T extends CollectionItem = CollectionItem> {
-    /**
-     * The dataset to index. When provided together with `fields`, all indexes
-     * are built automatically inside the constructor — no manual `buildIndex`
-     * calls needed.
-     *
-     * @example
-     * ```ts
-     * const engine = new SortEngine<User>({ data: users, fields: ["age", "name", "city"] });
-     * engine.sort(users, [{ field: "age", direction: "asc" }]);
-     * ```
-     */
     data?: T[];
-    /**
-     * Fields to pre-sort and cache. Requires `data` to be set as well.
-     * When both are present, `buildIndex` is called for each field in the constructor.
-     */
     fields?: (keyof T & string)[];
 }
 declare class SortEngine<T extends CollectionItem> {
-    /** field → cached ascending sort index */
     private cache;
-    /** Reference to the full dataset (set via the constructor or `buildIndex`). */
     private data;
     constructor(options?: SortEngineOptions<T>);
-    /**
-     * Pre-compute and cache a sorted index for a field.
-     *
-     * Two call signatures are supported:
-     *  - `buildIndex(data, field)` — explicit dataset (original API)
-     *  - `buildIndex(field)`       — reuses the dataset supplied in the constructor
-     *
-     * Call this once per field; all subsequent `sort` calls on that field
-     * will use the cache — O(n) instead of O(n log n).
-     *
-     * @returns `this` for chaining.
-     */
     private buildIndex;
-    /**
-     * Free all cached sort indexes.
-     */
     clearIndexes(): void;
-    /**
-     * Sort items by one or more fields.
-     *
-     * Two call signatures:
-     *  - `sort(descriptors)`            — uses the dataset supplied in the constructor.
-     *  - `sort(data, descriptors)`       — explicit dataset (original API).
-     *
-     * If `buildIndex` was called for the leading sort field and the dataset
-     * reference matches, sorting is O(n) via cached indexes regardless of
-     * direction. Otherwise falls back to O(n log n) TimSort.
-     *
-     * @returns The sorted array.
-     */
     sort(descriptors: SortDescriptor<T>[]): T[];
     sort(data: T[], descriptors: SortDescriptor<T>[], inPlace?: boolean): T[];
-    /**
-     * Reconstruct a sorted array from a pre-built ascending index.
-     * O(n) — no comparisons, just array reads.
-     */
     private reconstructFromIndex;
     private isFieldSnapshotValid;
-    /**
-     * Build a single comparator function for multi-field sorting.
-     * Captures field names and direction multipliers in closure for speed.
-     */
     private buildComparator;
-    /**
-     * Radix sort for a single numeric field.
-     * Uses index-array approach: sort an auxiliary index array by the numeric
-     * values, then reorder items by those indexes.
-     * O(n) time for integers; O(n) for floats via float-to-int encoding.
-     *
-     * Falls back to native sort if the range is too large (sparse data).
-     */
     private radixSortNumeric;
 }
 

package/dist/types-D24zQWME.d.mts

@@ -0,0 +1,15 @@
+type CollectionItem = Record<string, any>;
+type IndexableKey<T> = {
+    [K in keyof T]: T[K] extends string | number ? K : never;
+}[keyof T];
+interface FilterCriterion<T extends CollectionItem> {
+    field: keyof T & string;
+    values: any[];
+}
+type SortDirection = "asc" | "desc";
+interface SortDescriptor<T extends CollectionItem> {
+    field: keyof T & string;
+    direction: SortDirection;
+}
+
+export type { CollectionItem as C, FilterCriterion as F, IndexableKey as I, SortDescriptor as S, SortDirection as a };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devisfuture/mega-collection",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "High-performance search, filter & sort engine for 100K+ item collections in JavaScript/TypeScript",
   "exports": {
     ".": {

package/dist/types-BlZO_NQA.d.mts

@@ -1,29 +0,0 @@
-/**
- * Core type definitions for MegaCollection.
- *
- * All generics use `T` for the item type and constrain it to `Record<string, any>`
- * so that every item is an indexable plain object.
- */
-/** Any plain object whose values can be indexed. */
-type CollectionItem = Record<string, any>;
-/**
- * Extract only the keys of T whose values are `string | number`.
- * Used to restrict indexing / sorting to primitive-comparable fields.
- */
-type IndexableKey<T> = {
-    [K in keyof T]: T[K] extends string | number ? K : never;
-}[keyof T];
-/** A single filter criterion: field name → set of acceptable values. */
-interface FilterCriterion<T extends CollectionItem> {
-    field: keyof T & string;
-    values: any[];
-}
-/** Sorting direction. */
-type SortDirection = "asc" | "desc";
-/** Sorting descriptor. */
-interface SortDescriptor<T extends CollectionItem> {
-    field: keyof T & string;
-    direction: SortDirection;
-}
-
-export type { CollectionItem as C, FilterCriterion as F, IndexableKey as I, SortDescriptor as S, SortDirection as a };