@devisfuture/mega-collection 1.0.18 → 1.1.1

package/README.md

@@ -60,6 +60,12 @@ interface User {
 Use `MergeEngines` to combine search, filter and sort around a single shared dataset.
 Declare which engines you need in `imports` — only those are initialised.
 
+Each engine accepts an optional `fields` array (set via the `search`,
+`filter` or `sort` option) which tells it which properties should be indexed up
+front. Indexes power the fast paths used throughout the library; you can leave
+these options out and everything still works, but the code will fall back to
+simple linear scans.
+
 ```ts
 import { MergeEngines } from "@devisfuture/mega-collection";
 import { TextSearchEngine } from "@devisfuture/mega-collection/search";
@@ -87,6 +93,9 @@ engine.filter([{ field: "city", values: ["Kyiv", "Lviv"] }]);
 ```ts
 import { TextSearchEngine } from "@devisfuture/mega-collection/search";
 
+// `fields` tells the engine which properties to index for fast lookups. The
+// index is built once during construction; if you omit `fields` the engine
+// still works but every search will scan the entire dataset.
 const engine = new TextSearchEngine<User>({
   data: users,
   fields: ["name", "city"],
@@ -102,6 +111,10 @@ engine.search("name", "john"); // searches a specific field
 ```ts
 import { FilterEngine } from "@devisfuture/mega-collection/filter";
 
+// `fields` config tells the filter engine which properties should have an
+// index built. Indexed lookups are O(1) per value, so multi-criteria queries
+// can be orders of magnitude faster. Without `fields` the engine still filters
+// correctly but always does a linear scan.
 const engine = new FilterEngine<User>({
   data: users,
   fields: ["city", "age"],
@@ -125,6 +138,11 @@ const byCityAndAge = engine.filter([{ field: "age", values: [22] }]);
 ```ts
 import { SortEngine } from "@devisfuture/mega-collection/sort";
 
+// `fields` instructs the engine to pre-build a sorted index for each property.
+// When you later run a single-field sort the result can be pulled directly
+// from that index in linear time. If you leave out `fields` the engine still
+// sorts correctly, it merely falls back to standard `Array.prototype.sort`
+// (O(n log n)).
 const engine = new SortEngine<User>({
   data: users,
   fields: ["age", "name", "city"],

package/dist/chunk-KMSFPZKF.mjs

@@ -0,0 +1 @@
+var l=class{constructor(n){let{imports:t,data:e,...i}=n,s=new Set(t),r={};for(let o of s){let d=o.prototype,a=this.getMethodNames(d);if(a.length===0)continue;let u=this.getModuleInitOptions(o.name,a,i),g=new o({data:e,...u});for(let c of a)r[c]||this.hasMethod(g,c)&&(r[c]=g[c].bind(g));}this.engine=Object.keys(r).length>0?r:null;}getModuleInitOptions(n,t,e){let i={},s=e[n];this.isRecord(s)&&Object.assign(i,s);for(let r of t){let o=e[r];this.isRecord(o)&&Object.assign(i,o);}return i}getMethodNames(n){let t=n;return Object.getOwnPropertyNames(t).filter(e=>e==="constructor"?false:typeof t[e]=="function")}hasMethod(n,t){return typeof n=="object"&&n!==null&&typeof n[t]=="function"}isRecord(n){return typeof n=="object"&&n!==null}callEngineMethod(n,t){let e=this.engine?.[n];if(!e)throw new Error(`MergeEngines: Method "${n}" is not available. Add module with method "${n}" to the \`imports\` array.`);return e(...t)}search(n,t){if(!this.engine?.search)throw new Error("MergeEngines: TextSearchEngine is not available. Add TextSearchEngine to the `imports` array.");return t===void 0?this.callEngineMethod("search",[n]):this.callEngineMethod("search",[n,t])}sort(n,t,e){if(!this.engine?.sort)throw new Error("MergeEngines: SortEngine is not available. Add SortEngine to the `imports` array.");return t===void 0?this.callEngineMethod("sort",[n]):this.callEngineMethod("sort",[n,t,e])}filter(n,t){if(!this.engine?.filter)throw new Error("MergeEngines: FilterEngine is not available. Add FilterEngine to the `imports` array.");return t===void 0?this.callEngineMethod("filter",[n]):this.callEngineMethod("filter",[n,t])}};export{l as a};

package/dist/chunk-VSCCECO2.mjs

@@ -0,0 +1 @@
+var T=3,f=12;function x(h){let e=h.toLowerCase(),n=Math.min(T,e.length),t=e.length-n+1,r=new Array(t);for(let s=0;s<t;s++)r[s]=e.substring(s,s+n);return r}function m(h){let e=x(h);if(e.length<=f)return new Set(e);let n=new Set,t=e.length-1,r=f-1;for(let s=0;s<=r;s++){let i=Math.round(s*t/r);n.add(e[i]);}return n}function L(h,e){let n=h.get(e);if(n)return n;let t=new Set;return h.set(e,t),t}var y=class{constructor(e={}){this.ngramIndexes=new Map;this.data=[];if(this.minQueryLength=e.minQueryLength??1,!!e.data&&(this.data=e.data,!!e.fields?.length))for(let n of e.fields)this.buildIndex(e.data,n);}buildIndex(e,n){let t,r;if(Array.isArray(e))t=e,r=n;else {if(!this.data.length)throw new Error("TextSearchEngine: no dataset in memory. Either pass `data` in the constructor options, or call buildIndex(data, field).");t=this.data,r=e;}this.data=t;let s=new Map;for(let i=0,u=t.length;i<u;i++){let l=t[i][r];if(typeof l!="string")continue;let o=l.toLowerCase();for(let a=0,d=o.length;a<d;a++){let c=d-a,p=Math.min(T,c);for(let g=1;g<=p;g++){let I=o.substring(a,a+g);L(s,I).add(i);}}}return this.ngramIndexes.set(r,s),this}search(e,n){return n===void 0?this.searchAllFields(e):this.searchField(e,n)}normalizeQuery(e){return e.trim().toLowerCase()}isQuerySearchable(e){return !(!e||e.length<this.minQueryLength)}searchAllFields(e){let n=[...this.ngramIndexes.keys()],t=this.normalizeQuery(e);if(!this.isQuerySearchable(t))return [];if(!n.length)return this.searchAllFieldsLinear(t);let r=m(t);if(!r.size)return [];let s=new Set,i=[];for(let u of n)for(let l of this.searchFieldWithPreparedQuery(u,t,r))s.has(l)||(s.add(l),i.push(l));return i}searchField(e,n){let t=this.normalizeQuery(n);if(!this.isQuerySearchable(t))return [];if(!this.ngramIndexes.size)return this.searchFieldLinear(e,t);let r=m(t);return r.size?this.searchFieldWithPreparedQuery(e,t,r):[]}searchFieldWithPreparedQuery(e,n,t){let r=this.ngramIndexes.get(e);if(!r)return [];let s=[];for(let o of t){let a=r.get(o);if(!a)return [];s.push(a);}s.sort((o,a)=>o.size-a.size);let i=s[0],u=s.length,l=[];for(let o of i){let a=true;for(let c=1;c<u;c++)if(!s[c].has(o)){a=false;break}if(!a)continue;let d=this.data[o][e];typeof d=="string"&&d.toLowerCase().includes(n)&&l.push(this.data[o]);}return l}searchAllFieldsLinear(e){if(!this.data.length)return [];let n=[];for(let t=0;t<this.data.length;t++){let r=this.data[t],s=false;for(let i of Object.values(r))if(typeof i=="string"&&i.toLowerCase().includes(e)){s=true;break}s&&n.push(r);}return n}searchFieldLinear(e,n){if(!this.data.length)return [];let t=[];for(let r=0;r<this.data.length;r++){let s=this.data[r][e];typeof s=="string"&&s.toLowerCase().includes(n)&&t.push(this.data[r]);}return t}clear(){this.ngramIndexes.clear(),this.data=[];}};export{y as a};

package/dist/filter/index.d.mts

@@ -18,18 +18,45 @@ declare class FilterEngine<T extends CollectionItem> {
     private previousResult;
     private previousCriteria;
     private previousBaseData;
+    /**
+     * Creates a new FilterEngine with optional data and fields to index.
+     */
     constructor(options?: FilterEngineOptions<T>);
+    /**
+     * Builds an index for the given field.
+     */
     private buildIndex;
     clearIndexes(): void;
     resetFilterState(): void;
+    /**
+     * Filters the data based on the given criteria.
+     */
     filter(criteria: FilterCriterion<T>[]): T[];
     filter(data: T[], criteria: FilterCriterion<T>[]): T[];
     private cloneCriteria;
+    /**
+     * Checks if there are new criteria added.
+     */
     private hasCriteriaAdditions;
+    /**
+     * Checks if there are criteria removed.
+     */
     private hasCriteriaRemovals;
+    /**
+     * Gets the newly added criteria.
+     */
     private getAddedCriteria;
+    /**
+     * Filters data linearly without index.
+     */
     private linearFilter;
+    /**
+     * Filters data using the index.
+     */
     private filterViaIndex;
+    /**
+     * Estimates the size of the index for a criterion.
+     */
     private estimateIndexSize;
 }
 

package/dist/index.d.mts

@@ -1,44 +1,5 @@
-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-D24zQWME.mjs';
-export { I as IndexableKey, a as SortDirection } from './types-D24zQWME.mjs';
-
-/**
- * MergeEngines class that provides a unified interface for text search,
- * sorting, and filtering operations on collections.
- */
-
-interface MergeSearchConfig<T extends CollectionItem> {
-    fields: (keyof T & string)[];
-    minQueryLength?: TextSearchEngineOptions<T>["minQueryLength"];
-}
-interface MergeFilterConfig<T extends CollectionItem> {
-    fields: (keyof T & string)[];
-    filterByPreviousResult?: boolean;
-}
-interface MergeSortConfig<T extends CollectionItem> {
-    fields: (keyof T & string)[];
-}
-type EngineConstructor = typeof TextSearchEngine | typeof SortEngine | typeof FilterEngine;
-interface MergeEnginesOptions<T extends CollectionItem> {
-    imports: EngineConstructor[];
-    data: T[];
-    search?: MergeSearchConfig<T>;
-    filter?: MergeFilterConfig<T>;
-    sort?: MergeSortConfig<T>;
-}
-declare class MergeEngines<T extends CollectionItem> {
-    private readonly searchEngine;
-    private readonly sortEngine;
-    private readonly filterEngine;
-    constructor(options: MergeEnginesOptions<T>);
-    search(query: string): T[];
-    search(field: keyof T & string, query: string): T[];
-    sort(descriptors: SortDescriptor<T>[]): T[];
-    sort(data: T[], descriptors: SortDescriptor<T>[], inPlace?: boolean): T[];
-    filter(criteria: FilterCriterion<T>[]): T[];
-    filter(data: T[], criteria: FilterCriterion<T>[]): T[];
-}
-
-export { CollectionItem, type EngineConstructor, FilterCriterion, FilterEngine, MergeEngines, type MergeEnginesOptions, type MergeFilterConfig, type MergeSearchConfig, type MergeSortConfig, SortDescriptor, SortEngine, TextSearchEngine };
+export { TextSearchEngine } from './search/index.mjs';
+export { FilterEngine } from './filter/index.mjs';
+export { SortEngine } from './sort/index.mjs';
+export { EngineApi, EngineConstructor, MergeEngines, MergeEnginesOptions } from './merge/index.mjs';
+export { C as CollectionItem, F as FilterCriterion, I as IndexableKey, S as SortDescriptor, a as SortDirection } from './types-D24zQWME.mjs';

package/dist/index.mjs

@@ -1 +1 @@
-export{a as MergeEngines}from'./chunk-OE5GVXOE.mjs';export{a as TextSearchEngine}from'./chunk-4TBU4VWK.mjs';export{a as FilterEngine}from'./chunk-XFQ56UZU.mjs';export{a as SortEngine}from'./chunk-DBAABXBP.mjs';
+export{a as TextSearchEngine}from'./chunk-VSCCECO2.mjs';export{a as FilterEngine}from'./chunk-XFQ56UZU.mjs';export{a as SortEngine}from'./chunk-DBAABXBP.mjs';export{a as MergeEngines}from'./chunk-KMSFPZKF.mjs';

package/dist/merge/index.d.mts

@@ -1,5 +1,54 @@
-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-D24zQWME.mjs';
-import '../search/index.mjs';
-import '../filter/index.mjs';
-import '../sort/index.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 class that provides a unified interface for text search,
+ * sorting, and filtering operations on collections.
+ */
+
+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[];
+    [key: string]: unknown;
+}
+declare class MergeEngines<T extends CollectionItem> {
+    private readonly engine;
+    /**
+     * Creates a new MergeEngines instance with the given options.
+     * Collects all modules from imports.
+     */
+    constructor(options: MergeEnginesOptions<T>);
+    /**
+     * Gets the initialization options for a module.
+     */
+    private getModuleInitOptions;
+    /**
+     * Gets the method names from a prototype.
+     */
+    private getMethodNames;
+    /**
+     * Checks if an object has a specific method.
+     */
+    private hasMethod;
+    private isRecord;
+    /**
+     * Calls a method on the engine.
+     */
+    private callEngineMethod;
+    search(query: string): T[];
+    search(field: keyof T & string, query: string): T[];
+    sort(descriptors: SortDescriptor<T>[]): T[];
+    sort(data: T[], descriptors: SortDescriptor<T>[], inPlace?: boolean): T[];
+    filter(criteria: FilterCriterion<T>[]): T[];
+    filter(data: T[], criteria: FilterCriterion<T>[]): T[];
+}
+
+export { CollectionItem, type EngineApi, type EngineConstructor, FilterCriterion, MergeEngines, type MergeEnginesOptions, SortDescriptor };

package/dist/merge/index.mjs

@@ -1 +1 @@
-export{a as MergeEngines}from'../chunk-OE5GVXOE.mjs';import'../chunk-4TBU4VWK.mjs';import'../chunk-XFQ56UZU.mjs';import'../chunk-DBAABXBP.mjs';
+export{a as MergeEngines}from'../chunk-KMSFPZKF.mjs';

package/dist/search/index.d.mts

@@ -15,13 +15,41 @@ declare class TextSearchEngine<T extends CollectionItem> {
     private ngramIndexes;
     private data;
     private readonly minQueryLength;
+    /**
+     * Creates a new TextSearchEngine with optional data and fields to index.
+     */
     constructor(options?: TextSearchEngineOptions<T>);
+    /**
+     * Builds an n-gram index for the given field.
+     */
     private buildIndex;
     search(query: string): T[];
     search(field: keyof T & string, query: string): T[];
+    private normalizeQuery;
+    /**
+     * Checks if the query is long enough to search.
+     */
+    private isQuerySearchable;
+    /**
+     * Searches all indexed fields.
+     */
     private searchAllFields;
+    /**
+     * Searches a specific field.
+     */
     private searchField;
+    /**
+     * Searches a field using prepared query grams.
+     */
     private searchFieldWithPreparedQuery;
+    /**
+     * Searches all fields linearly without index.
+     */
+    private searchAllFieldsLinear;
+    /**
+     * Searches a specific field linearly without index.
+     */
+    private searchFieldLinear;
     clear(): void;
 }
 

package/dist/search/index.mjs

@@ -1 +1 @@
-export{a as TextSearchEngine}from'../chunk-4TBU4VWK.mjs';
+export{a as TextSearchEngine}from'../chunk-VSCCECO2.mjs';

package/dist/sort/index.d.mts

@@ -13,14 +13,38 @@ interface SortEngineOptions<T extends CollectionItem = CollectionItem> {
 declare class SortEngine<T extends CollectionItem> {
     private cache;
     private data;
+    /**
+     * Creates a new SortEngine with optional data and fields to index.
+     */
     constructor(options?: SortEngineOptions<T>);
+    /**
+     * Builds an index for sorting the given field.
+     */
     private buildIndex;
+    /**
+     * Clears all cached indexes.
+     */
     clearIndexes(): void;
+    /**
+     * Sorts the data based on the given descriptors.
+     */
     sort(descriptors: SortDescriptor<T>[]): T[];
     sort(data: T[], descriptors: SortDescriptor<T>[], inPlace?: boolean): T[];
+    /**
+     * Reconstructs the sorted array from the cached index.
+     */
     private reconstructFromIndex;
+    /**
+     * Checks if the field snapshot is still valid.
+     */
     private isFieldSnapshotValid;
+    /**
+     * Builds a comparator function for sorting.
+     */
     private buildComparator;
+    /**
+     * Sorts numeric data using radix sort.
+     */
     private radixSortNumeric;
 }
 

package/package.json

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

package/dist/chunk-4TBU4VWK.mjs

@@ -1 +0,0 @@
-var T=3,f=12;function I(d){let t=d.toLowerCase(),n=Math.min(T,t.length),e=t.length-n+1,s=new Array(e);for(let r=0;r<e;r++)s[r]=t.substring(r,r+n);return s}function m(d){let t=I(d);if(t.length<=f)return new Set(t);let n=new Set,e=t.length-1,s=f-1;for(let r=0;r<=s;r++){let a=Math.round(r*e/s);n.add(t[a]);}return n}function L(d,t){let n=d.get(t);if(n)return n;let e=new Set;return d.set(t,e),e}var y=class{constructor(t={}){this.ngramIndexes=new Map;this.data=[];if(this.minQueryLength=t.minQueryLength??1,!!t.data&&(this.data=t.data,!!t.fields?.length))for(let n of t.fields)this.buildIndex(t.data,n);}buildIndex(t,n){let e,s;if(Array.isArray(t))e=t,s=n;else {if(!this.data.length)throw new Error("TextSearchEngine: no dataset in memory. Either pass `data` in the constructor options, or call buildIndex(data, field).");e=this.data,s=t;}this.data=e;let r=new Map;for(let a=0,l=e.length;a<l;a++){let g=e[a][s];if(typeof g!="string")continue;let o=g.toLowerCase();for(let i=0,u=o.length;i<u;i++){let c=u-i,p=Math.min(T,c);for(let h=1;h<=p;h++){let x=o.substring(i,i+h);L(r,x).add(a);}}}return this.ngramIndexes.set(s,r),this}search(t,n){return n===void 0?this.searchAllFields(t):this.searchField(t,n)}searchAllFields(t){let n=[...this.ngramIndexes.keys()];if(!n.length)return [];let e=t.trim().toLowerCase();if(!e)return [];if(e.length<this.minQueryLength)return [];let s=m(e);if(!s.size)return [];let r=new Set,a=[];for(let l of n)for(let g of this.searchFieldWithPreparedQuery(l,e,s))r.has(g)||(r.add(g),a.push(g));return a}searchField(t,n){let e=n.trim().toLowerCase();if(!e)return [];if(e.length<this.minQueryLength)return [];let s=m(e);return s.size?this.searchFieldWithPreparedQuery(t,e,s):[]}searchFieldWithPreparedQuery(t,n,e){let s=this.ngramIndexes.get(t);if(!s)return [];let r=[];for(let o of e){let i=s.get(o);if(!i)return [];r.push(i);}r.sort((o,i)=>o.size-i.size);let a=r[0],l=r.length,g=[];for(let o of a){let i=true;for(let c=1;c<l;c++)if(!r[c].has(o)){i=false;break}if(!i)continue;let u=this.data[o][t];typeof u=="string"&&u.toLowerCase().includes(n)&&g.push(this.data[o]);}return g}clear(){this.ngramIndexes.clear(),this.data=[];}};export{y as a};

package/dist/chunk-OE5GVXOE.mjs

@@ -1 +0,0 @@
-import {a as a$1}from'./chunk-4TBU4VWK.mjs';import {a as a$3}from'./chunk-XFQ56UZU.mjs';import {a as a$2}from'./chunk-DBAABXBP.mjs';var a=class{constructor(e){let{imports:r,data:t,search:l,filter:g,sort:f}=e,i=new Set(r),T=i.has(a$1),c=i.has(a$2),h=i.has(a$3);this.searchEngine=T?new a$1({data:t,fields:l?.fields,minQueryLength:l?.minQueryLength}):null,this.sortEngine=c?new a$2({data:t,fields:f?.fields}):null,this.filterEngine=h?new a$3({data:t,fields:g?.fields,filterByPreviousResult:g?.filterByPreviousResult}):null;}search(e,r){if(!this.searchEngine)throw new Error("MergeEngines: TextSearchEngine is not available. Add TextSearchEngine to the `imports` array.");return r===void 0?this.searchEngine.search(e):this.searchEngine.search(e,r)}sort(e,r,t){if(!this.sortEngine)throw new Error("MergeEngines: SortEngine is not available. Add SortEngine to the `imports` array.");return r===void 0?this.sortEngine.sort(e):this.sortEngine.sort(e,r,t)}filter(e,r){if(!this.filterEngine)throw new Error("MergeEngines: FilterEngine is not available. Add FilterEngine to the `imports` array.");return r===void 0?this.filterEngine.filter(e):this.filterEngine.filter(e,r)}};export{a};