@devisfuture/mega-collection 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 devisfuture
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,285 @@
+<p align="center">
+  <img src="./illustration.png" alt="electron-modular illustration" width="640" />
+</p>
+
+[![codecov](https://codecov.io/gh/trae-op/mega-collection/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
+
+> Search, filter & sort engine for **50 K+** item collections in JavaScript / TypeScript.
+
+What does this package solve?
+
+Sometimes in projects, you need to iterate through huge collections (20,000, 40,000, 80,000 elements in an array) that have come from the server. Usually, the most common features are searching, filtering, and sorting.
+So, this package helps to perform searching, filtering, and sorting of large collections faster than standard JavaScript methods. This operation is performed before rendering the UI content.
+
+Zero dependencies. Tree-shakeable. Import only what you need.
+
+Each engine lives in its own entry point (`/search`, `/filter`, `/sort`).
+Importing just `@devisfuture/mega-collection/search` or the other sub-modules means
+only that code ends up in your bundle — unused engines stay out. For example, if
+you only pull in `TextSearchEngine` the filter and sort logic won’t be included.
+
+## Features
+
+| Capability                 | Strategy                               | Complexity                         |
+| -------------------------- | -------------------------------------- | ---------------------------------- |
+| **Indexed filter**         | Hash-Map index (`Map<value, T[]>`)     | **O(1)**                           |
+| **Multi-value filter**     | Index intersection + `Set` membership  | **O(k)** indexed / **O(n)** linear |
+| **Text search** (contains) | Trigram inverted index + verify        | **O(candidates)**                  |
+| **Sorting**                | Pre-sorted index (cached) / V8 TimSort | **O(n)** cached / **O(n log n)**   |
+
+## React demo
+
+A small repository demonstrates using `@devisfuture/mega-collection` in a React project:
+
+https://github.com/trae-op/quick-start_react_mega-collection
+
+The example shows search, filter, sort and merge all modules setups with a minimal UI.
+
+## Install
+
+```bash
+npm install @devisfuture/mega-collection
+```
+
+_This package is framework-agnostic and works in all popular front‑end frameworks including React, Angular, Vue and so on._
+
+## Quick Start
+
+```ts
+interface User {
+  id: number;
+  name: string;
+  city: string;
+  age: number;
+}
+```
+
+### All-in-one: `MergeEngines`
+
+Use `MergeEngines` to combine search, filter and sort around a single shared dataset.
+Declare which engines you need in `imports` — only those are initialised.
+
+```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: ["name", "city"], minQueryLength: 2 },
+  filter: { fields: ["city", "age"], filterByPreviousResult: true },
+  sort: { fields: ["age", "name", "city"] },
+});
+
+// dataset is passed once at init — no need to repeat it in every call
+engine.search("john");
+engine.sort([{ field: "age", direction: "asc" }]);
+engine.filter([{ field: "city", values: ["Kyiv", "Lviv"] }]);
+```
+
+---
+
+### Search only
+
+```ts
+import { TextSearchEngine } from "@devisfuture/mega-collection/search";
+
+const engine = new TextSearchEngine<User>({
+  data: users,
+  fields: ["name", "city"],
+  minQueryLength: 2,
+});
+
+engine.search("john"); // searches all indexed fields, deduplicated
+engine.search("name", "john"); // searches a specific field
+```
+
+### Filter only
+
+```ts
+import { FilterEngine } from "@devisfuture/mega-collection/filter";
+
+const engine = new FilterEngine<User>({
+  data: users,
+  fields: ["city", "age"],
+  filterByPreviousResult: true,
+});
+
+engine.filter([
+  { field: "city", values: ["Kyiv", "Lviv"] },
+  { field: "age", values: [25, 30, 35] },
+]);
+
+// Sequential mode example:
+// 1) First call filters by city
+const byCity = engine.filter([{ field: "city", values: ["Dnipro"] }]);
+// 2) Second call filters only inside previous result
+const byCityAndAge = engine.filter([{ field: "age", values: [22] }]);
+```
+
+### Sort only
+
+```ts
+import { SortEngine } from "@devisfuture/mega-collection/sort";
+
+const engine = new SortEngine<User>({
+  data: users,
+  fields: ["age", "name", "city"],
+});
+
+// Single-field sort — O(n) via cached index
+engine.sort([{ field: "age", direction: "asc" }]);
+
+// Multi-field sort — O(n log n)
+engine.sort([
+  { field: "age", direction: "asc" },
+  { field: "name", direction: "desc" },
+]);
+```
+
+---
+
+## API Reference
+
+### `MergeEngines<T>` (root module)
+
+Unified facade that composes all three engines around a shared dataset.
+
+**Constructor options:**
+
+| Option    | Type                                                        | Description                                  |
+| --------- | ----------------------------------------------------------- | -------------------------------------------- |
+| `imports` | `(typeof TextSearchEngine \| SortEngine \| FilterEngine)[]` | Engine classes to activate                   |
+| `data`    | `T[]`                                                       | Shared dataset — passed once at construction |
+| `search`  | `{ fields, minQueryLength? }`                               | Config for TextSearchEngine                  |
+| `filter`  | `{ fields, filterByPreviousResult? }`                       | Config for FilterEngine                      |
+| `sort`    | `{ fields }`                                                | Config for SortEngine                        |
+
+**Methods:**
+
+| Method                              | Description                     |
+| ----------------------------------- | ------------------------------- |
+| `search(query)`                     | Search all indexed fields       |
+| `search(field, query)`              | Search a specific field         |
+| `sort(descriptors)`                 | Sort using stored dataset       |
+| `sort(data, descriptors, inPlace?)` | Sort with an explicit dataset   |
+| `filter(criteria)`                  | Filter using stored dataset     |
+| `filter(data, criteria)`            | Filter with an explicit dataset |
+
+---
+
+### `TextSearchEngine<T>` (search module)
+
+Trigram-based text search engine.
+
+| Method                 | Description                             |
+| ---------------------- | --------------------------------------- |
+| `search(query)`        | Search all indexed fields, deduplicated |
+| `search(field, query)` | Search a specific indexed field         |
+| `clear()`              | Free memory                             |
+
+### `FilterEngine<T>` (filter module)
+
+Multi-criteria AND filter with index-accelerated fast path.
+
+Constructor option highlights:
+
+| Option                   | Type      | Description                                                                                                                               |
+| ------------------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `filterByPreviousResult` | `boolean` | When `true`, each `filter(criteria)` call filters from previous result. Defaults to `false` (each call starts from the original dataset). |
+
+| Method                   | Description                                          |
+| ------------------------ | ---------------------------------------------------- |
+| `filter(criteria)`       | Filter using stored dataset                          |
+| `filter(data, criteria)` | Filter with an explicit dataset                      |
+| `resetFilterState()`     | Reset previous-result state for sequential filtering |
+| `clearIndexes()`         | Free all index memory                                |
+
+### `SortEngine<T>` (sort module)
+
+Sorting with pre-compiled comparators and cached sort indexes.
+
+| Method                              | Description                   |
+| ----------------------------------- | ----------------------------- |
+| `sort(descriptors)`                 | Sort using stored dataset     |
+| `sort(data, descriptors, inPlace?)` | Sort with an explicit dataset |
+| `clearIndexes()`                    | Free all cached indexes       |
+
+---
+
+## Types
+
+All types are exported from the root package and from each sub-module:
+
+```ts
+import type {
+  CollectionItem,
+  IndexableKey,
+  FilterCriterion,
+  SortDescriptor,
+  SortDirection,
+  MergeEnginesOptions,
+} from "@devisfuture/mega-collection";
+```
+
+Or from individual sub-modules:
+
+```ts
+import type {
+  CollectionItem,
+  IndexableKey,
+} from "@devisfuture/mega-collection/search";
+import type { FilterCriterion } from "@devisfuture/mega-collection/filter";
+import type {
+  SortDescriptor,
+  SortDirection,
+} from "@devisfuture/mega-collection/sort";
+```
+
+---
+
+## Architecture
+
+```
+src/
+  types.ts               — Shared type definitions
+  indexer.ts             — Hash-Map index engine (internal, O(1) lookups)
+  search/
+    text-search.ts       — Trigram inverted index engine
+    index.ts             — Search module entry point
+  filter/
+    filter.ts            — Multi-criteria filter engine (owns Indexer internally)
+    index.ts             — Filter module entry point
+  sort/
+    sorter.ts            — Sort engine (TimSort + index-sort)
+    index.ts             — Sort module entry point
+  merge/
+    merge-engines.ts     — MergeEngines unified facade
+    index.ts             — Merge module entry point
+  index.ts               — Root barrel export
+```
+
+## Build
+
+```bash
+npm install
+npm run build          # Build ESM + declarations
+npm run typecheck      # Type-check without emitting
+npm run dev            # Watch mode
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for our security policy.
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

package/dist/chunk-4TBU4VWK.mjs

@@ -0,0 +1 @@
+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-DBAABXBP.mjs

@@ -0,0 +1 @@
+var u=class{constructor(n={}){this.cache=new Map;this.data=[];if(n.data&&(this.data=n.data,!!n.fields?.length))for(let a of n.fields)this.buildIndex(n.data,a);}buildIndex(n,a){let l,t;if(Array.isArray(n))l=n,t=a;else {if(!this.data.length)throw new Error("SortEngine: no dataset in memory. Either pass `data` in the constructor options, or call buildIndex(data, field).");l=this.data,t=n;}this.data=l;let e=l.length,i=new Uint32Array(e);for(let o=0;o<e;o++)i[o]=o;let s=l.map(o=>o[t]);if(typeof s[0]=="number"){let o=new Float64Array(e);for(let c=0;c<e;c++)o[c]=s[c];i.sort((c,d)=>o[c]-o[d]);}else i.sort((o,c)=>{let d=s[o],f=s[c];return d<f?-1:d>f?1:0});return this.cache.set(t,{indexes:i,dataRef:l,itemCount:e,fieldSnapshot:s}),this}clearIndexes(){this.cache.clear();}sort(n,a,l=false){let t,e;if(a===void 0){if(!this.data.length)throw new Error("SortEngine: no dataset in memory. Either pass `data` in the constructor options, or call sort(data, descriptors).");t=this.data,e=n;}else t=n,e=a;if(e.length===0||t.length===0)return t;if(e.length===1){let{field:r,direction:o}=e[0],c=this.cache.get(r);if(c&&c.dataRef===t&&c.itemCount===t.length&&this.isFieldSnapshotValid(t,r,c.fieldSnapshot))return this.reconstructFromIndex(t,c.indexes,o)}let i=l?t:t.slice();if(e.length===1&&t.length>0&&typeof t[0][e[0].field]=="number")return this.radixSortNumeric(i,e[0].field,e[0].direction);let s=this.buildComparator(e);return i.sort(s),i}reconstructFromIndex(n,a,l){let t=n.length,e=new Array(t);if(l==="asc")for(let i=0;i<t;i++)e[i]=n[a[i]];else for(let i=0;i<t;i++)e[i]=n[a[t-1-i]];return e}isFieldSnapshotValid(n,a,l){for(let t=0;t<n.length;t++)if(n[t][a]!==l[t])return  false;return  true}buildComparator(n){let a=n.map(({field:e})=>e),l=n.map(({direction:e})=>e==="asc"?1:-1),t=a.length;return (e,i)=>{for(let s=0;s<t;s++){let r=e[a[s]],o=i[a[s]];if(r<o)return -l[s];if(r>o)return l[s]}return 0}}radixSortNumeric(n,a,l){let t=n.length,e=new Float64Array(t);for(let r=0;r<t;r++)e[r]=n[r][a];let i=new Uint32Array(t);for(let r=0;r<t;r++)i[r]=r;i.sort((r,o)=>e[r]-e[o]);let s=new Array(t);if(l==="asc")for(let r=0;r<t;r++)s[r]=n[i[r]];else for(let r=0;r<t;r++)s[t-1-r]=n[i[r]];return s}};export{u as a};

package/dist/chunk-OE5GVXOE.mjs

@@ -0,0 +1 @@
+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};

package/dist/chunk-XFQ56UZU.mjs

@@ -0,0 +1 @@
+var c=class{constructor(){this.indexes=new Map;}buildIndex(t,s){let n=new Map;for(let r=0,e=t.length;r<e;r++){let i=t[r],l=i[s];if(l==null)continue;let a=n.get(l);a?a.push(i):n.set(l,[i]);}this.indexes.set(s,n);}getByValue(t,s){let n=this.indexes.get(t);return n?n.get(s)??[]:[]}getByValues(t,s){let n=this.indexes.get(t);if(!n)return [];if(s.length===1)return n.get(s[0])??[];let r=new Set,e=[];for(let i=0;i<s.length;i++){let l=n.get(s[i]);if(l!==void 0)for(let a=0;a<l.length;a++){let o=l[a];r.has(o)||(r.add(o),e.push(o));}}return e}hasIndex(t){return this.indexes.has(t)}clear(){this.indexes.clear();}getIndexMap(t){return this.indexes.get(t)}};var C=class{constructor(t={}){this.data=[];this.previousResult=null;this.previousCriteria=null;this.previousBaseData=null;if(this.indexer=new c,this.filterByPreviousResult=t.filterByPreviousResult??false,!!t.data&&(this.data=t.data,!!t.fields?.length))for(let s of t.fields)this.buildIndex(t.data,s);}buildIndex(t,s){if(!Array.isArray(t)){if(!this.data.length)throw new Error("FilterEngine: no dataset in memory. Either pass `data` in the constructor options, or call buildIndex(data, field).");return this.indexer.buildIndex(this.data,t),this}return this.data=t,this.previousResult=null,this.previousCriteria=null,this.previousBaseData=null,this.indexer.buildIndex(t,s),this}clearIndexes(){this.indexer.clear();}resetFilterState(){this.previousResult=null,this.previousCriteria=null,this.previousBaseData=null;}filter(t,s){let n=s===void 0,r,e,i;if(n){if(!this.data.length)throw new Error("FilterEngine: no dataset in memory. Either pass `data` in the constructor options, or call filter(data, criteria).");if(e=t,this.filterByPreviousResult&&this.previousResult!==null&&this.previousCriteria!==null&&this.previousBaseData===this.data){let u=this.hasCriteriaAdditions(this.previousCriteria,e),h=this.hasCriteriaRemovals(this.previousCriteria,e);if(!u&&!h)return this.previousResult;u&&!h?(r=this.previousResult,i=this.getAddedCriteria(this.previousCriteria,e)):(r=this.data,i=e);}else r=this.data,i=e;}else if(e=s,r=t,this.filterByPreviousResult&&this.previousResult!==null&&this.previousCriteria!==null&&this.previousBaseData===r){let u=this.hasCriteriaAdditions(this.previousCriteria,e),h=this.hasCriteriaRemovals(this.previousCriteria,e);if(!u&&!h)return this.previousResult;u&&!h?(r=this.previousResult,i=this.getAddedCriteria(this.previousCriteria,e)):i=e;}else i=e;if(e.length===0)return this.filterByPreviousResult&&(this.previousResult=null,this.previousCriteria=null,this.previousBaseData=null),n?this.data:r;n&&!i&&(i=e);let{indexedCriteria:l,linearCriteria:a}=i.reduce((u,h)=>(this.indexer.hasIndex(h.field)?u.indexedCriteria.push(h):u.linearCriteria.push(h),u),{indexedCriteria:[],linearCriteria:[]}),o;if(l.length>0&&a.length===0)return o=this.filterViaIndex(l,r),this.filterByPreviousResult&&(this.previousResult=o,this.previousCriteria=this.cloneCriteria(e),this.previousBaseData=n?this.data:t),o;if(l.length>0&&a.length>0){let u=this.filterViaIndex(l,r);return o=this.linearFilter(u,a),this.filterByPreviousResult&&(this.previousResult=o,this.previousCriteria=this.cloneCriteria(e),this.previousBaseData=n?this.data:t),o}return o=this.linearFilter(r,i),this.filterByPreviousResult&&(this.previousResult=o,this.previousCriteria=this.cloneCriteria(e),this.previousBaseData=n?this.data:t),o}cloneCriteria(t){return t.map(({field:s,values:n})=>({field:s,values:[...n]}))}hasCriteriaAdditions(t,s){let n=new Map(t.map(({field:e,values:i})=>[e,new Set(i)])),r=new Map(s.map(({field:e,values:i})=>[e,new Set(i)]));for(let[e,i]of r){let l=n.get(e);if(!l)return  true;for(let a of i)if(!l.has(a))return  true}return  false}hasCriteriaRemovals(t,s){let n=new Map(t.map(({field:e,values:i})=>[e,new Set(i)])),r=new Map(s.map(({field:e,values:i})=>[e,new Set(i)]));for(let[e,i]of n){let l=r.get(e);if(!l)return  true;for(let a of i)if(!l.has(a))return  true}return  false}getAddedCriteria(t,s){let n=new Map(t.map(({field:e,values:i})=>[e,new Set(i)])),r=[];for(let{field:e,values:i}of s){let l=n.get(e);if(!l){r.push({field:e,values:[...i]});continue}let a=i.filter(o=>!l.has(o));a.length>0&&r.push({field:e,values:a});}return r}linearFilter(t,s){let n=new Map(s.map(({field:i,values:l})=>[i,new Set(l)])),r=s.map(({field:i})=>i),e=[];for(let i=0;i<t.length;i++){let l=t[i],a=true;for(let o=0;o<r.length;o++){let u=r[o];if(!n.get(u).has(l[u])){a=false;break}}a&&e.push(l);}return e}filterViaIndex(t,s){let r=s!==this.data?new Set(s):null;if(t.length===1){let d=this.indexer.getByValues(t[0].field,t[0].values);return r?d.filter(f=>r.has(f)):d}let e=t.map(d=>({criterion:d,size:this.estimateIndexSize(d)})).sort((d,f)=>d.size-f.size),{field:i,values:l}=e[0].criterion,a=this.indexer.getByValues(i,l);if(a.length===0)return [];let o=new Map(e.slice(1).map(({criterion:{field:d,values:f}})=>[d,new Set(f)])),u=Array.from(o.keys()),h=[];for(let d=0;d<a.length;d++){let f=a[d],p=true;for(let v=0;v<u.length;v++){let g=u[v];if(!o.get(g).has(f[g])){p=false;break}}p&&r&&!r.has(f)&&(p=false),p&&h.push(f);}return h}estimateIndexSize(t){let s=this.indexer.getIndexMap(t.field);return s?t.values.reduce((n,r)=>{let e=s.get(r);return e?n+e.length:n},0):1/0}};export{C as a};

package/dist/filter/index.d.mts

@@ -0,0 +1,118 @@
+import { C as CollectionItem, F as FilterCriterion } from '../types-BlZO_NQA.mjs';
+export { I as IndexableKey } from '../types-BlZO_NQA.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.
+ */
+
+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;
+}
+
+export { CollectionItem, FilterCriterion, FilterEngine, type FilterEngineOptions };

package/dist/filter/index.mjs

@@ -0,0 +1 @@
+export{a as FilterEngine}from'../chunk-XFQ56UZU.mjs';

package/dist/index.d.mts

@@ -0,0 +1,111 @@
+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';
+
+/**
+ * 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"] }]);
+ * ```
+ */
+
+/** 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> {
+    private readonly searchEngine;
+    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[];
+}
+
+export { CollectionItem, type EngineConstructor, FilterCriterion, FilterEngine, MergeEngines, type MergeEnginesOptions, type MergeFilterConfig, type MergeSearchConfig, type MergeSortConfig, SortDescriptor, SortEngine, TextSearchEngine };

package/dist/index.mjs

@@ -0,0 +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';

package/dist/merge/index.d.mts

@@ -0,0 +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';
+import '../search/index.mjs';
+import '../filter/index.mjs';
+import '../sort/index.mjs';

package/dist/merge/index.mjs

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

package/dist/search/index.d.mts

@@ -0,0 +1,98 @@
+import { C as CollectionItem } from '../types-BlZO_NQA.mjs';
+export { I as IndexableKey } from '../types-BlZO_NQA.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|).
+ */
+
+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;
+}
+
+export { CollectionItem, TextSearchEngine, type TextSearchEngineOptions };

package/dist/search/index.mjs

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

package/dist/sort/index.d.mts

@@ -0,0 +1,106 @@
+import { C as CollectionItem, S as SortDescriptor } from '../types-BlZO_NQA.mjs';
+export { a as SortDirection } from '../types-BlZO_NQA.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.
+ */
+
+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;
+}
+
+export { CollectionItem, SortDescriptor, SortEngine, type SortEngineOptions };

package/dist/sort/index.mjs

@@ -0,0 +1 @@
+export{a as SortEngine}from'../chunk-DBAABXBP.mjs';

package/dist/types-BlZO_NQA.d.mts

@@ -0,0 +1,29 @@
+/**
+ * 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 };

package/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "@devisfuture/mega-collection",
+  "version": "1.0.2",
+  "description": "High-performance search, filter & sort engine for 10M+ item collections in JavaScript/TypeScript",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./search": {
+      "types": "./dist/search/index.d.mts",
+      "default": "./dist/search/index.mjs"
+    },
+    "./filter": {
+      "types": "./dist/filter/index.d.mts",
+      "default": "./dist/filter/index.mjs"
+    },
+    "./sort": {
+      "types": "./dist/sort/index.d.mts",
+      "default": "./dist/sort/index.mjs"
+    },
+    "./merge": {
+      "types": "./dist/merge/index.d.mts",
+      "default": "./dist/merge/index.mjs"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "search": [
+        "./dist/search/index.d.mts"
+      ],
+      "filter": [
+        "./dist/filter/index.d.mts"
+      ],
+      "sort": [
+        "./dist/sort/index.d.mts"
+      ],
+      "merge": [
+        "./dist/merge/index.d.mts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "build:watch": "tsup --watch",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:ci": "vitest run --coverage --reporter=verbose --reporter=json",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "search",
+    "filter",
+    "sort",
+    "collection",
+    "performance",
+    "trigram",
+    "inverted-index",
+    "hashmap",
+    "large-dataset",
+    "big-data",
+    "typescript",
+    "zero-dependencies",
+    "tree-shakeable",
+    "esm",
+    "indexer",
+    "50k",
+    "100k",
+    "text-search",
+    "multi-filter",
+    "sort-engine",
+    "merge-engines",
+    "o1-lookup"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/trae-op/mega-collection.git"
+  },
+  "bugs": {
+    "url": "https://github.com/trae-op/mega-collection/issues"
+  },
+  "homepage": "https://github.com/trae-op/mega-collection#readme",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^3.2.4",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^3.2.4"
+  }
+}