@devisfuture/mega-collection 2.3.3 → 2.4.1

package/README.md

@@ -10,11 +10,14 @@ If this package saved you some time, a ⭐ on GitHub would be much appreciated.
 
 - [What does this package solve](#what-does-this-package-solve) – what problem this package helps with
 - [Features](#features) – what the package can do
+- [How it works](#how-it-works) – plain-English explanation of how each engine works internally
+- [Benchmarks](#benchmarks) – performance numbers and how to run them
 - [React demo](#react-demo) – example project and live demo
 - [Install](#install) – how to install the package
 - [Quick Start](#quick-start) – basic usage examples
   - [All-in-one: `MergeEngines`](#all-in-one-mergeengines) – use search, filter, and sort from one engine
   - [Add items with `add([])`](#add-items-with-add) – append multiple items to stored data
+  - [Update items with `update(...)`](#update-items-with-update) – replace one stored item by unique field
   - [Search only](#search-only) – use only text search
     - [Flat collections search](#flat-collections-search) – search simple fields like `name` or `city`
     - [Nested collections search](#nested-collections-search) – search inside nested arrays like `orders.status`
@@ -38,11 +41,19 @@ If this package saved you some time, a ⭐ on GitHub would be much appreciated.
 
 ## What does this package solve
 
-Sometimes the server returns a very large array, for example 100K+ items.
-Most often you then need to search, filter, or sort this data.
+When your API returns thousands of items, you usually need to let the user search, filter, or sort them on the client side.
 
-This package helps do these operations faster than plain JavaScript methods.
-Usually this happens before data is shown in the UI.
+The typical way to do this is with built-in array methods:
+
+```ts
+const results = users.filter((u) => u.city === "New York");
+const sorted = [...users].sort((a, b) => a.age - b.age);
+const found = users.filter((u) => u.name.toLowerCase().includes(query));
+```
+
+This works fine for small arrays. But with 10 000–100 000+ items, every call to `filter` or `sort` scans the whole array from scratch. If you run it on every keystroke, it adds up.
+
+This package solves this by building indexes ahead of time — special data structures that let you look up results without scanning the full array every time. You pay the cost once when the data arrives, and then each search, filter, or sort is much cheaper.
 
 The package has no dependencies.
 You can import only the parts you need.
@@ -53,14 +64,67 @@ Unused modules are not 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 |
-| **Nested collection filter** | Pre-built nested index + `Set` lookup  | **O(k)** indexed / **O(n)** linear |
-| **Text search** (contains)   | Trigram inverted index + verify        | **O(candidates)**                  |
-| **Nested collection search** | Nested trigram index + verify          | **O(candidates)**                  |
-| **Sorting**                  | Pre-sorted index (cached) / V8 TimSort | **O(n)** cached / **O(n log n)**   |
+| 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 |
+| **Nested collection filter** | Pre-built nested index + `Set` lookup      | **O(k)** indexed / **O(n)** linear |
+| **Text search** (contains)   | N-gram (2–3 chars) inverted index + verify | **O(candidates)**                  |
+| **Nested collection search** | Nested n-gram index + verify               | **O(candidates)**                  |
+| **Sorting**                  | Pre-sorted index (cached) / radix sort     | **O(n)** cached / **O(n log n)**   |
+
+## How it works
+
+### Search
+
+Native `Array.prototype.filter` with `String.includes` checks every item in the array on each keystroke. For 50 000 items that's 50 000 string comparisons per call.
+
+`TextSearchEngine` avoids this by building an **n-gram inverted index** upfront:
+
+1. Each string value is split into overlapping 2- and 3-character pieces called n-grams. For example, `"hello"` produces `"he"`, `"hel"`, `"el"`, `"ell"`, `"ll"`, `"llo"`, `"lo"`.
+2. For every n-gram the engine keeps a set of item positions that contain it.
+3. When you search for `"john"`, the engine splits that query into the same n-gram pieces, then intersects the sets — only items that share all query n-grams survive. This candidate set is usually tiny even for 100 000 items.
+4. Each surviving candidate is checked with a fast `String.includes` to confirm the full substring match.
+
+For very short queries (fewer than 2 characters) the engine falls back to a linear scan — n-grams that short would match too many items to be useful.
+
+### Filter
+
+Native `Array.prototype.filter` with `===` still checks every item on every call.
+
+`FilterEngine` builds a **hash-map** for each indexed field:
+
+```
+field "city" → { "New York": [item0, item4, ...], "Miami": [item1, ...], ... }
+```
+
+A filter call becomes a map lookup: `index.get("New York")` returns the array of matches in O(1). Multiple values from the same field are concatenated. Multiple fields are intersected using a `Set`.
+
+When the `fields` option is not provided, the engine falls back to a linear scan — which works but is slower.
+
+### Sort
+
+Native `Array.prototype.sort` re-sorts the whole array from scratch every call.
+
+`SortEngine` pre-sorts and stores results in a `Uint32Array` of positions:
+
+```
+cache["age"] = [index of youngest item, index of next, ..., index of oldest]
+```
+
+The first sort call builds this index. Subsequent calls just read it in O(n). The cache is invalidated on mutations and rebuilt lazily on the next sort call.
+
+---
+
+## Benchmarks
+
+Benchmarks for `TextSearchEngine`, `FilterEngine`, and `SortEngine` are collected in [`BENCHMARKS`](./BENCHMARKS.md).
+
+Run the benchmark scripts locally to regenerate the numbers:
+
+- `npm run search-bench`
+- `npm run filter-bench`
+- `npm run sort-bench`
 
 ## React demo
 
@@ -103,12 +167,12 @@ Use `MergeEngines` when you want one class that works with one dataset.
 Add needed engines to `imports`. Only those engines will be created.
 
 You can create many engine instances in one project for different collections.
-Each instance stores its own data and indexes, so they do not affect each other.
+Each instance keeps its own dataset and runtime indexes inside an internal shared `State`, so separate instances do not affect each other.
 
 Each engine can receive an optional `fields` array through `search`, `filter`, or `sort` options.
 These fields are used for indexes.
 
-Indexes are built lazily on first use, so engine creation stays fast.
+Indexes are built lazily on first use inside that shared state, so engine creation stays fast.
 If you skip `fields`, everything still works, but the engine may scan the full array.
 
 ```ts
@@ -120,8 +184,9 @@ import { FilterEngine } from "@devisfuture/mega-collection/filter";
 const engine = new MergeEngines<User>({
   imports: [TextSearchEngine, SortEngine, FilterEngine],
   data: users,
+  filterByPreviousResult: true,
   search: { fields: ["name", "city"], minQueryLength: 2 },
-  filter: { fields: ["city", "age"], filterByPreviousResult: true },
+  filter: { fields: ["city", "age"] },
   sort: { fields: ["age", "name", "city"] },
 });
 
@@ -137,10 +202,19 @@ engine
   .sort([{ field: "age", direction: "asc" }])
   .filter([{ field: "city", values: ["Miami", "New York"] }]);
 
+// Separate calls also continue from the last result when
+// `filterByPreviousResult` is enabled on MergeEngines.
+const searchResult = engine.search("john");
+const filteredResult = engine.filter([
+  { field: "city", values: ["Miami", "New York"] },
+]);
+const sortedResult = engine.sort([{ field: "age", direction: "asc" }]);
+
 // Example with nested fields, for example `orders` inside each user.
 const nestedEngine = new MergeEngines<UserWithOrders>({
   imports: [TextSearchEngine, SortEngine, FilterEngine],
   data: usersWithOrders,
+  filterByPreviousResult: true,
   search: {
     fields: ["name", "city"],
     nestedFields: ["orders.status"],
@@ -149,7 +223,6 @@ const nestedEngine = new MergeEngines<UserWithOrders>({
   filter: {
     fields: ["city", "age"],
     nestedFields: ["orders.status"],
-    filterByPreviousResult: true,
   },
   sort: { fields: ["age", "name", "city"] },
 });
@@ -188,7 +261,12 @@ This is different from `data(...)`:
 - `data(...)` replaces the whole stored dataset.
 - `add([])` appends new items to the existing stored dataset.
 
-If indexes are already built, the engine updates only the new items instead of rebuilding the whole dataset.
+If indexes are already built, `add()` updates them incrementally for the new items only:
+
+- **TextSearchEngine / FilterEngine**: O(k) — only the new items are written into the n-gram or hash-map index (existing index entries are untouched).
+- **SortEngine**: the sort cache for each configured field is invalidated on `add()` and rebuilt lazily on the next `sort()` call. This avoids O(N) work per add and is optimal when multiple adds happen between sorts.
+
+If indexes have not been built yet (first `sort()` has not been called), `add()` appends the items without touching any index.
 If you cleared indexes with `clearIndexes()`, `add([])` does not rebuild them automatically.
 
 ```ts
@@ -255,6 +333,62 @@ sortEngine.add([
 
 ---
 
+### Update items with `update(...)`
+
+Use `update(...)` when you need to replace one stored item by a unique field such as `id`.
+
+- `update(...)` keeps the same stored array reference.
+- `update(...)` replaces only the matched item in stored data.
+- configured indexes or caches refresh only the affected item instead of rebuilding the whole dataset.
+
+> **Notes on `update()`:**
+>
+> - The lookup field value in `data[field]` must already exist in the stored dataset. If it is `null`, `undefined`, or not found, `update()` is a silent no-op — no error is thrown and no data is changed.
+> - The lookup field value must not change between the old and new item. For example, calling `update({ field: 'id', data: { id: 99, ... } })` when no item has `id: 99` will do nothing. Always use the current value of the lookup field.
+> - When using `FilterEngine` with `filterByPreviousResult: true`, every `update()` resets the sequential criteria cache, so the next `filter()` will re-evaluate from the full dataset.
+
+```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 merge = new MergeEngines<User>({
+  imports: [TextSearchEngine, SortEngine, FilterEngine],
+  data: users,
+  search: { fields: ["name", "city"], minQueryLength: 2 },
+  filter: { fields: ["city", "age"] },
+  sort: { fields: ["age", "name"] },
+});
+
+merge.update({
+  field: "id",
+  data: { id: 2, name: "Bob", city: "Paris", age: 19 },
+});
+
+merge.search("Paris");
+merge.filter([{ field: "city", values: ["Paris"] }]);
+merge.sort([{ field: "age", direction: "asc" }]);
+```
+
+The same method works in each engine:
+
+```ts
+import { TextSearchEngine } from "@devisfuture/mega-collection/search";
+
+const searchEngine = new TextSearchEngine<User>({
+  data: users,
+  fields: ["name", "city"],
+});
+
+searchEngine.update({
+  field: "id",
+  data: { id: 2, name: "Bob", city: "Paris", age: 19 },
+});
+```
+
+---
+
 ### Search only
 
 Use `TextSearchEngine` when you only need text search.
@@ -279,10 +413,17 @@ const engine = new TextSearchEngine<User>({
 
 engine.search("john"); // searches all indexed fields, deduplicated
 engine.search("name", "john"); // searches a specific field
+engine.search("john", { limit: 20, offset: 20 }); // paginate broad result sets
 
 // replace dataset without re-initializing
 engine.data(users);
 
+// replace one stored item by unique field
+engine.update({
+  field: "id",
+  data: { id: 2, name: "Bob", city: "Paris", age: 19 },
+});
+
 // access original dataset stored in the engine
 engine.getOriginData();
 
@@ -335,6 +476,12 @@ engine.filter([
 // Replace dataset without creating a new engine.
 engine.data(users);
 
+// Replace one stored item by unique field.
+engine.update({
+  field: "id",
+  data: { id: 2, name: "Bob", city: "Paris", age: 19, active: true },
+});
+
 // Get original stored dataset.
 engine.getOriginData();
 
@@ -487,6 +634,12 @@ engine.sort([{ field: "age", direction: "asc" }]);
 // replace dataset without re-initializing
 engine.data(users);
 
+// replace one stored item by unique field
+engine.update({
+  field: "id",
+  data: { id: 2, name: "Bob", city: "Paris", age: 19 },
+});
+
 // access original dataset stored in the engine
 engine.getOriginData();
 
@@ -511,13 +664,14 @@ One class that combines search, filter, and sort for the same dataset.
 
 **Constructor options:**
 
-| Option    | Type                                                                       | Description                                  |
-| --------- | -------------------------------------------------------------------------- | -------------------------------------------- |
-| `imports` | `(typeof TextSearchEngine \| SortEngine \| FilterEngine)[]`                | Engine classes to create                     |
-| `data`    | `T[]`                                                                      | Shared dataset — passed once at construction |
-| `search`  | `{ fields, nestedFields?, minQueryLength? }`                               | Config for TextSearchEngine                  |
-| `filter`  | `{ fields, nestedFields?, filterByPreviousResult?, mutableExcludeField? }` | Config for FilterEngine                      |
-| `sort`    | `{ fields }`                                                               | Config for SortEngine                        |
+| Option                   | Type                                                        | Description                                                                                                    |
+| ------------------------ | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `imports`                | `(typeof TextSearchEngine \| SortEngine \| FilterEngine)[]` | Engine classes to create                                                                                       |
+| `data`                   | `T[]`                                                       | Shared dataset — passed once at construction                                                                   |
+| `filterByPreviousResult` | `boolean`                                                   | When `true`, separate `filter(...)` and `sort(...)` calls continue from the last result stored in shared State |
+| `search`                 | `{ fields, nestedFields?, minQueryLength? }`                | Config for TextSearchEngine                                                                                    |
+| `filter`                 | `{ fields, nestedFields?, mutableExcludeField? }`           | Config for FilterEngine                                                                                        |
+| `sort`                   | `{ fields }`                                                | Config for SortEngine                                                                                          |
 
 **Methods:**
 
@@ -531,13 +685,16 @@ One class that combines search, filter, and sort for the same dataset.
 | `filter(data, criteria)`            | Filter with an explicit dataset                                                                                            |
 | `getOriginData()`                   | Get the shared original dataset                                                                                            |
 | `add(items)`                        | Append multiple items to the stored dataset and update existing indexes or caches for new items only                       |
+| `update({ field, data })`           | Replace one stored item by a unique field and refresh only the affected cached or indexed data                             |
 | `data(data)`                        | Replace stored dataset for all imported modules, rebuilding configured indexes and resetting filter state where applicable |
 | `clearIndexes(module)`              | Clear indexes for one module (`"search"`, `"sort"`, `"filter"`)                                                            |
-| `clearData(module)`                 | Clear stored data for one module (`"search"`, `"sort"`, `"filter"`)                                                        |
+| `clearData(module)`                 | Clear the shared stored dataset through one imported module (`"search"`, `"sort"`, `"filter"`)                             |
 
 If `filter.mutableExcludeField` is configured, `filter([{ field, exclude }])` on that field removes items from the stored filter dataset with swap-pop.
 This changes the stored filter dataset and does not preserve order.
 
+`filter.filterByPreviousResult` is not supported inside `MergeEngines`. Use the root `filterByPreviousResult` option instead.
+
 ---
 
 ### `TextSearchEngine<T>` (search module)
@@ -546,15 +703,27 @@ Text search engine.
 It supports `nestedFields` if you need to search inside nested collections such as `["orders.status"]`.
 Search methods return plain arrays.
 
-| Method                 | Description                                                |
-| ---------------------- | ---------------------------------------------------------- |
-| `search(query)`        | Search all indexed fields (including nested), deduplicated |
-| `search(field, query)` | Search a specific indexed field or nested field path       |
-| `getOriginData()`      | Get the original stored dataset                            |
-| `add(items)`           | Append multiple items to the stored dataset                |
-| `data(data)`           | Replace stored dataset and rebuild configured indexes      |
-| `clearIndexes()`       | Clear n-gram indexes (including nested)                    |
-| `clearData()`          | Clear stored data                                          |
+Main constructor options:
+
+| Option                   | Type       | Description                                                                                                                                                                     |
+| ------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `filterByPreviousResult` | `boolean`  | When `true`, a query that narrows the previous one (new query includes old query) searches only the previous result instead of the full dataset. Any mutation resets the state. |
+| `nestedFields`           | `string[]` | Nested field paths in dot notation, for example `["orders.status"]`.                                                                                                            |
+
+| Method                           | Description                                                          |
+| -------------------------------- | -------------------------------------------------------------------- |
+| `search(query, options?)`        | Search all indexed fields (including nested), deduplicated           |
+| `search(field, query, options?)` | Search a specific indexed field or nested field path                 |
+| `searchAll(query, options?)`     | Explicit all-fields alias when you want pagination on broad searches |
+| `resetSearchState()`             | Reset previous-result state for sequential narrowing search          |
+| `getOriginData()`                | Get the original stored dataset                                      |
+| `add(items)`                     | Append multiple items to the stored dataset                          |
+| `update({ field, data })`        | Replace one stored item by a unique field                            |
+| `data(data)`                     | Replace stored dataset and rebuild configured indexes                |
+| `clearIndexes()`                 | Clear n-gram indexes (including nested)                              |
+| `clearData()`                    | Clear stored data                                                    |
+
+`options.limit` and `options.offset` are useful for broad result sets where you only need the current page.
 
 ### `FilterEngine<T>` (filter module)
 
@@ -570,16 +739,17 @@ Main constructor options:
 | `mutableExcludeField`    | `string`   | Optional field for removing items from stored data with swap-pop. This changes the stored dataset and does not preserve order.     |
 | `nestedFields`           | `string[]` | Nested field paths in dot notation, for example `["orders.status"]`.                                                               |
 
-| Method                   | Description                                                                |
-| ------------------------ | -------------------------------------------------------------------------- |
-| `filter(criteria)`       | Filter using stored dataset (supports nested field criteria)               |
-| `filter(data, criteria)` | Filter with an explicit dataset                                            |
-| `getOriginData()`        | Get the original stored dataset                                            |
-| `add(items)`             | Append multiple items to the stored dataset                                |
-| `data(data)`             | Replace stored dataset, rebuild configured indexes, and reset filter state |
-| `resetFilterState()`     | Reset previous-result state for sequential filtering                       |
-| `clearIndexes()`         | Free all index memory (including nested indexes)                           |
-| `clearData()`            | Clear stored data                                                          |
+| Method                    | Description                                                                |
+| ------------------------- | -------------------------------------------------------------------------- |
+| `filter(criteria)`        | Filter using stored dataset (supports nested field criteria)               |
+| `filter(data, criteria)`  | Filter with an explicit dataset                                            |
+| `getOriginData()`         | Get the original stored dataset                                            |
+| `add(items)`              | Append multiple items to the stored dataset                                |
+| `update({ field, data })` | Replace one stored item by a unique field                                  |
+| `data(data)`              | Replace stored dataset, rebuild configured indexes, and reset filter state |
+| `resetFilterState()`      | Reset previous-result state for sequential filtering                       |
+| `clearIndexes()`          | Free all index memory (including nested indexes)                           |
+| `clearData()`             | Clear stored data                                                          |
 
 ### `SortEngine<T>` (sort module)
 
@@ -592,6 +762,7 @@ Sort methods return plain arrays.
 | `sort(data, descriptors, inPlace?)` | Sort with an explicit dataset                         |
 | `getOriginData()`                   | Get the original stored dataset                       |
 | `add(items)`                        | Append multiple items to the stored dataset           |
+| `update({ field, data })`           | Replace one stored item by a unique field             |
 | `data(data)`                        | Replace stored dataset and rebuild configured indexes |
 | `clearIndexes()`                    | Free all cached indexes                               |
 | `clearData()`                       | Clear stored data                                     |
@@ -611,6 +782,7 @@ import type {
   FilterCriterion,
   SortDescriptor,
   SortDirection,
+  UpdateDescriptor,
   MergeEnginesOptions,
 } from "@devisfuture/mega-collection";
 ```

package/dist/State-2vKzwNrQ.d.mts

@@ -0,0 +1,44 @@
+import { C as CollectionItem, S as StateOptions, a as StateListener, b as StatePreviousResult, c as StateRegistryFactory, U as UpdateDescriptor, I as IndexableKey } from './types-DONld7xY.mjs';
+
+declare class State<T extends CollectionItem> {
+    private originData;
+    private filterByPreviousResult;
+    private itemIndexLookup;
+    private mutationVersion;
+    private namespaceSequence;
+    private previousResultState;
+    private readonly indexMaps;
+    private readonly scopedRegistry;
+    private readonly listeners;
+    constructor(data?: T[], options?: StateOptions);
+    subscribe(listener: StateListener<T>): () => void;
+    getOriginData(): T[];
+    getItemIndex(item: T): number | undefined;
+    getMutationVersion(): number;
+    isFilterByPreviousResultEnabled(): boolean;
+    setFilterByPreviousResult(enabled: boolean): void;
+    getPreviousResult(): T[] | null;
+    getPreviousResultState(): StatePreviousResult<T> | null;
+    setPreviousResult(result: T[], sourceData: T[]): void;
+    clearPreviousResult(): void;
+    createNamespace(prefix?: string): string;
+    getScopedValue<TValue>(namespace: string, key: string): TValue | undefined;
+    getOrCreateScopedValue<TValue>(namespace: string, key: string, createValue: StateRegistryFactory<TValue>): TValue;
+    setScopedValue<TValue>(namespace: string, key: string, value: TValue): TValue;
+    deleteScopedValue(namespace: string, key: string): void;
+    clearScope(namespace: string): void;
+    data(data: T[]): void;
+    add(items: T[]): void;
+    update(descriptor: UpdateDescriptor<T>): void;
+    clearData(): void;
+    removeByFieldValue(field: IndexableKey<T> & string, value: any): void;
+    removeByFieldValues(field: IndexableKey<T> & string, values: any[]): void;
+    private emit;
+    private getOrCreateScope;
+    private bumpMutationVersion;
+    private getOrCreateIndexMap;
+    private rebuildIndexMap;
+    private rebuildItemIndexLookup;
+}
+
+export { State as S };

package/dist/chunk-IZXO22NQ.mjs

@@ -0,0 +1 @@
+import {a,b}from'./chunk-MB56OSRQ.mjs';function p(o){return {value:o,enumerable:false,configurable:true,writable:true}}var f=class{constructor(e){this.callbacks=e;}create(e){let t=e;return Object.defineProperties(t,{search:p((i,r)=>r===void 0?this.callbacks.search(i):this.callbacks.search(i,r)),sort:p((i,r,n)=>r===void 0?this.callbacks.sort(e,i,n):this.callbacks.sort(i,r,n)),filter:p((i,r)=>r===void 0?this.callbacks.filter(e,i):this.callbacks.filter(i,r)),add:p(i=>this.callbacks.add(i)),update:p(i=>this.callbacks.update(i)),clearIndexes:p(i=>(this.callbacks.clearIndexes(i),this.create(e))),clearData:p(i=>(this.callbacks.clearData(i),this.create(e))),data:p(i=>this.callbacks.data(i)),getOriginData:p(()=>this.callbacks.getOriginData())}),t}};function T(o){return typeof o=="object"&&o!==null}function M(o,e){return T(o)&&typeof o[e]=="function"}function F(o){return M(o,"search")&&M(o,"getOriginData")}function m(o){return M(o,"sort")&&M(o,"getOriginData")}function D(o){return M(o,"rawFilter")&&M(o,"getOriginData")}var I=o=>{let{prototype:e}=o;return D(e)?"filter":m(e)?"sort":F(e)?"search":null},x=(o,e,t,i)=>{let r=new o({data:e,state:t,...i});return D(r)?{moduleName:"filter",executeFilter:(n,s)=>s===void 0?r.rawFilter(n):r.rawFilter(n,s),clearIndexes:()=>r.clearIndexes()}:m(r)?{moduleName:"sort",executeSort:(n,s,l)=>s===void 0?r.sort(n):r.sort(n,s,l),clearIndexes:()=>r.clearIndexes()}:F(r)?{moduleName:"search",executeSearch:(n,s)=>s===void 0?r.search(n):r.search(n,s),clearIndexes:()=>r.clearIndexes()}:null};var y="deferSortMutationCacheUpdates",P="deferSearchMutationIndexUpdates",R="deferFilterMutationIndexUpdates",w={search:"TextSearchEngine",sort:"SortEngine",filter:"FilterEngine"};var d=class o extends Error{constructor(e){super(e),this.name="MergeEnginesError";}static unavailableEngine(e){let t=w[e];return new o(`MergeEngines: ${t} is not available.`)}static unavailableGetOriginData(){return new o("MergeEngines: getOriginData is not available.")}static invalidFilterByPreviousResultOption(){return new o('MergeEngines: "filter.filterByPreviousResult" is not supported. Configure "filterByPreviousResult" on the MergeEngines root options.')}};var C=class{constructor(e){this.previousSearchState=null;this.previousFilterState=null;this.previousSortState=null;let{imports:t,data:i,filterByPreviousResult:r=false,...n}=e;this.validateFilterByPreviousResultOptions(n.filter),this.state=new a(i,{filterByPreviousResult:r});let s=new Set(t),l=null,u=null,c=null;for(let a of s){let h=I(a);if(!h)continue;let v=this.getModuleInitOptions(h,a.name,n),g=x(a,i,this.state,v);g&&(g.moduleName==="search"&&!l&&(l=g),g.moduleName==="sort"&&!u&&(u=g),g.moduleName==="filter"&&!c&&(c=g));}this.searchModule=l,this.sortModule=u,this.filterModule=c,this.sortModule&&this.state.setScopedValue(b,y,true),this.searchModule&&this.state.setScopedValue(b,P,true),this.filterModule&&this.state.setScopedValue(b,R,true),this.state.subscribe(a=>this.handleStateMutation(a)),this.chainBuilder=new f({search:(a,h)=>h===void 0?this.search(a):this.search(a,h),sort:(a,h,v)=>this.sort(a,h,v),filter:(a,h)=>this.filter(a,h),getOriginData:()=>this.getOriginData(),add:a=>this.add(a),update:a=>this.update(a),data:a=>this.data(a),clearIndexes:a=>this.clearIndexes(a),clearData:a=>this.clearData(a)});}getAdapter(e){return e==="search"?this.searchModule:e==="sort"?this.sortModule:this.filterModule}getModuleInitOptions(e,t,i){let r={};for(let n of [e,t]){let s=i[n];T(s)&&Object.assign(r,s);}return r}validateFilterByPreviousResultOptions(e){if(T(e)&&Object.prototype.hasOwnProperty.call(e,"filterByPreviousResult"))throw d.invalidFilterByPreviousResultOption()}isPreviousResultEnabled(){return this.state.isFilterByPreviousResultEnabled()}getPreviousResultInput(){return this.isPreviousResultEnabled()?this.state.getPreviousResult():null}trackPreviousResult(e,t){return this.isPreviousResultEnabled()&&this.state.setPreviousResult(e,t),e}clearOperationState(e){(!e||e==="search")&&(this.previousSearchState=null),(!e||e==="filter")&&(this.previousFilterState=null),(!e||e==="sort")&&(this.previousSortState=null);}createSearchCacheKey(e,t){return JSON.stringify([e,t??null])}createSortCacheKey(e,t){return JSON.stringify({descriptors:e,inPlace:t??false})}createFilterCacheKey(e){return JSON.stringify(e)}handleStateMutation(e){switch(e.type){case "add":this.queueSearchCacheMutation(e),this.queueFilterCacheMutation(e),this.queueSortCacheMutation(e);return;case "update":this.queueSearchCacheMutation(e),this.queueFilterCacheMutation(e),this.queueSortCacheMutation(e);return;case "remove":this.previousSearchState=null,this.previousFilterState=null,this.queueSortCacheMutation(e);return;case "removeMany":this.previousSearchState=null,this.previousFilterState=null,this.queueSortCacheMutation(e);return;case "data":case "clearData":this.previousSearchState=null,this.previousFilterState=null,this.previousSortState=null;return}}queueSearchCacheMutation(e){let t=this.previousSearchState;if(t!==null){if(!this.canPatchStoredDatasetSearch(t)){this.previousSearchState=null;return}this.previousSearchState={...t,version:this.state.getMutationVersion(),pendingMutations:t.pendingMutations.concat(e)};}}queueFilterCacheMutation(e){let t=this.previousFilterState;if(t!==null){if(!this.canPatchStoredDatasetFilter(t)){this.previousFilterState=null;return}this.previousFilterState={...t,version:this.state.getMutationVersion(),pendingMutations:t.pendingMutations.concat(e)};}}queueSortCacheMutation(e){let t=this.previousSortState;if(t!==null){if(!this.canPatchStoredDatasetSort(t)){this.previousSortState=null;return}this.previousSortState={...t,version:this.state.getMutationVersion(),pendingMutations:t.pendingMutations.concat(e)};}}resolvePendingSortCache(e){if(e.pendingMutations.length===0)return e;let t={...e,pendingMutations:[]};for(let i=0;i<e.pendingMutations.length;i++)if(t=this.applySortCacheMutation(t,e.pendingMutations[i]),t===null)return null;return t}resolvePendingSearchCache(e){if(e.pendingMutations.length===0)return e;let t={...e,pendingMutations:[]};for(let i=0;i<e.pendingMutations.length;i++)if(t=this.applySearchCacheMutation(t,e.pendingMutations[i]),t===null)return null;return t}resolvePendingFilterCache(e){if(e.pendingMutations.length===0)return e;let t={...e,pendingMutations:[]};for(let i=0;i<e.pendingMutations.length;i++)if(t=this.applyFilterCacheMutation(t,e.pendingMutations[i]),t===null)return null;return t}applySortCacheMutation(e,t){switch(t.type){case "add":return this.patchSortCacheForAddedItems(e,t.items);case "update":return this.patchSortCacheForUpdatedItem(e,t.previousItem,t.nextItem);case "remove":return this.patchSortCacheForRemovedItems(e,[t.removedItem]);case "removeMany":return this.patchSortCacheForRemovedItems(e,t.entries.map(i=>i.removedItem));case "data":case "clearData":return null}}applySearchCacheMutation(e,t){switch(t.type){case "add":return this.patchSearchCacheForAddedItems(e,t.items);case "update":return this.patchSearchCacheForUpdatedItem(e,t.previousItem,t.nextItem);case "remove":case "removeMany":case "data":case "clearData":return null}}applyFilterCacheMutation(e,t){switch(t.type){case "add":return this.patchFilterCacheForAddedItems(e,t.items);case "update":return this.patchFilterCacheForUpdatedItem(e,t.previousItem,t.nextItem);case "remove":case "removeMany":case "data":case "clearData":return null}}canPatchStoredDatasetSearch(e){return e.originData===this.state.getOriginData()&&e.field!==null}canPatchStoredDatasetFilter(e){if(e.sourceData!==this.state.getOriginData())return  false;for(let t=0;t<e.criteria.length;t++)if(!this.isPatchableFilterCriterion(e.criteria[t]))return  false;return  true}canPatchStoredDatasetSort(e){return e.sourceData===this.state.getOriginData()}compareItemsByDescriptors(e,t,i){for(let r=0;r<i.length;r++){let{field:n,direction:s}=i[r],l=e[n],u=t[n];if(l<u)return s==="asc"?-1:1;if(l>u)return s==="asc"?1:-1}return (this.state.getItemIndex(e)??-1)-(this.state.getItemIndex(t)??-1)}findSortInsertPosition(e,t,i){let r=0,n=e.length;for(;r<n;){let s=r+n>>1;this.compareItemsByDescriptors(e[s],t,i)<=0?r=s+1:n=s;}return r}findDatasetInsertPosition(e,t){let i=this.state.getItemIndex(t)??Number.MAX_SAFE_INTEGER;for(let r=0;r<e.length;r++)if((this.state.getItemIndex(e[r])??Number.MAX_SAFE_INTEGER)>i)return r;return e.length}doesItemMatchSearchCache(e,t){if(e.field===null||e.lowerQuery.length===0)return  false;let i=t[e.field];return typeof i=="string"&&i.toLowerCase().includes(e.lowerQuery)}patchSearchCacheForAddedItems(e,t){if(!this.canPatchStoredDatasetSearch(e))return null;let i=e.result.slice();for(let r=0;r<t.length;r++){let n=t[r];this.doesItemMatchSearchCache(e,n)&&i.push(n);}return {...e,result:i,pendingMutations:[],version:this.state.getMutationVersion()}}patchSearchCacheForUpdatedItem(e,t,i){if(!this.canPatchStoredDatasetSearch(e))return null;let r=e.result.slice(),n=r.indexOf(t),s=this.doesItemMatchSearchCache(e,i);if(n!==-1)s?r[n]=i:r.splice(n,1);else if(s){let l=this.findDatasetInsertPosition(r,i);r.splice(l,0,i);}return {...e,result:r,pendingMutations:[],version:this.state.getMutationVersion()}}isPatchableFilterCriterion(e){return !String(e.field).includes(".")}doesItemMatchFilterCache(e,t){for(let i=0;i<e.criteria.length;i++){let r=e.criteria[i];if(!this.isPatchableFilterCriterion(r))return  false;let n=t[r.field];if(r.values!==void 0&&r.values.length>0&&!r.values.includes(n)||r.exclude!==void 0&&r.exclude.length>0&&r.exclude.includes(n))return  false}return  true}patchFilterCacheForAddedItems(e,t){if(!this.canPatchStoredDatasetFilter(e))return null;let i=e.result.slice();for(let r=0;r<t.length;r++){let n=t[r];this.doesItemMatchFilterCache(e,n)&&i.push(n);}return {...e,result:i,pendingMutations:[],version:this.state.getMutationVersion()}}patchFilterCacheForUpdatedItem(e,t,i){if(!this.canPatchStoredDatasetFilter(e))return null;let r=e.result.slice(),n=r.indexOf(t),s=this.doesItemMatchFilterCache(e,i);if(n!==-1)s?r[n]=i:r.splice(n,1);else if(s){let l=this.findDatasetInsertPosition(r,i);r.splice(l,0,i);}return {...e,result:r,pendingMutations:[],version:this.state.getMutationVersion()}}patchSortCacheForAddedItems(e,t){if(!this.canPatchStoredDatasetSort(e))return null;let i=e.result.slice();for(let r=0;r<t.length;r++){let n=t[r],s=this.findSortInsertPosition(i,n,e.descriptors);i.splice(s,0,n);}return {...e,result:i,pendingMutations:[],version:this.state.getMutationVersion()}}patchSortCacheForUpdatedItem(e,t,i){if(!this.canPatchStoredDatasetSort(e))return null;let r=e.result.slice(),n=r.indexOf(t);if(n===-1)return e.result.indexOf(i)!==-1?{...e,pendingMutations:[],version:this.state.getMutationVersion()}:null;if(!e.descriptors.some(({field:u})=>t[u]!==i[u]))return r[n]=i,{...e,result:r,pendingMutations:[],version:this.state.getMutationVersion()};r.splice(n,1);let l=this.findSortInsertPosition(r,i,e.descriptors);return r.splice(l,0,i),{...e,result:r,pendingMutations:[],version:this.state.getMutationVersion()}}patchSortCacheForRemovedItems(e,t){if(!this.canPatchStoredDatasetSort(e))return null;let i=new Set(t);return {...e,result:Array.prototype.filter.call(e.result,r=>!i.has(r)),pendingMutations:[],version:this.state.getMutationVersion()}}search(e,t){if(!this.searchModule)throw d.unavailableEngine("search");let i=this.state.getOriginData(),r=this.state.getMutationVersion(),n=this.createSearchCacheKey(e,t),s=this.previousSearchState;if(s?.originData===i&&s.key===n&&s.version===r){let u=this.resolvePendingSearchCache(s);if(u!==null)return this.previousSearchState=u,this.withChain(this.trackPreviousResult(u.result,i));this.previousSearchState=null;}let l=t===void 0?this.searchModule.executeSearch(e):this.searchModule.executeSearch(e,t);return this.previousSearchState={key:n,originData:i,result:l,version:r,field:t===void 0?null:e,lowerQuery:(t??e).trim().toLowerCase(),pendingMutations:[]},this.withChain(this.trackPreviousResult(l,i))}sort(e,t,i){if(!this.sortModule)throw d.unavailableEngine("sort");let r,n;if(t===void 0?(n=e,r=this.getPreviousResultInput()??this.state.getOriginData()):(r=e,n=t),!i){let s=this.state.getMutationVersion(),l=this.createSortCacheKey(n,i),u=this.previousSortState;if(u?.sourceData===r&&u.key===l&&u.version===s){let a=this.resolvePendingSortCache(u);if(a!==null)return this.previousSortState=a,this.withChain(this.trackPreviousResult(a.result,r));this.previousSortState=null;}let c=t===void 0&&r===this.state.getOriginData()?this.sortModule.executeSort(n):this.sortModule.executeSort(r,n,i);return this.previousSortState={key:l,sourceData:r,result:c,version:s,descriptors:n,pendingMutations:[]},this.withChain(this.trackPreviousResult(c,r))}return this.withChain(this.trackPreviousResult(this.sortModule.executeSort(r,n,i),r))}filter(e,t){if(!this.filterModule)throw d.unavailableEngine("filter");if(t===void 0){let r=this.getPreviousResultInput(),n=r??this.state.getOriginData(),s=e,l=this.state.getMutationVersion(),u=this.createFilterCacheKey(s),c=this.previousFilterState;if(c?.sourceData===n&&c.key===u&&c.version===l){let h=this.resolvePendingFilterCache(c);if(h!==null)return this.previousFilterState=h,this.withChain(this.trackPreviousResult(h.result,n));this.previousFilterState=null;}let a=r===null?this.filterModule.executeFilter(s):this.filterModule.executeFilter(r,s);return this.previousFilterState={key:u,sourceData:n,result:a,version:l,criteria:s,pendingMutations:[]},this.withChain(this.trackPreviousResult(a,n))}let i=e;return this.withChain(this.trackPreviousResult(this.filterModule.executeFilter(i,t),i))}withChain(e){return this.chainBuilder.create(e)}getOriginData(){if(this.searchModule||this.sortModule||this.filterModule)return this.state.getOriginData();throw d.unavailableGetOriginData()}add(e){return e.length===0?this:(this.state.add(e),this)}update(e){return this.state.update(e),this}clearIndexes(e){let t=this.getAdapter(e);if(t)return t.clearIndexes(),this.clearOperationState(e),this;throw d.unavailableEngine(e)}data(e){return this.state.data(e),this}clearData(e){if(this.getAdapter(e))return this.state.clearData(),this;throw d.unavailableEngine(e)}};export{C as a};

package/dist/chunk-MB56OSRQ.mjs

@@ -0,0 +1 @@
+var g=class{constructor(e=[],t={}){this.itemIndexLookup=new WeakMap;this.mutationVersion=0;this.namespaceSequence=0;this.previousResultState=null;this.indexMaps=new Map;this.scopedRegistry=new Map;this.listeners=new Set;this.originData=e,this.filterByPreviousResult=t.filterByPreviousResult??false,this.rebuildItemIndexLookup();}subscribe(e){return this.listeners.add(e),()=>{this.listeners.delete(e);}}getOriginData(){return this.originData}getItemIndex(e){return this.itemIndexLookup.get(e)}getMutationVersion(){return this.mutationVersion}isFilterByPreviousResultEnabled(){return this.filterByPreviousResult}setFilterByPreviousResult(e){this.filterByPreviousResult=e,e||this.clearPreviousResult();}getPreviousResult(){return this.getPreviousResultState()?.result??null}getPreviousResultState(){return this.previousResultState===null||this.previousResultState.version!==this.mutationVersion?null:this.previousResultState}setPreviousResult(e,t){this.previousResultState={result:e,sourceData:t,version:this.mutationVersion};}clearPreviousResult(){this.previousResultState=null;}createNamespace(e="scope"){return this.namespaceSequence+=1,`${e}:${this.namespaceSequence}`}getScopedValue(e,t){return this.scopedRegistry.get(e)?.get(t)}getOrCreateScopedValue(e,t,i){let n=this.getScopedValue(e,t);if(n!==void 0)return n;let o=this.getOrCreateScope(e),r=i();return o.set(t,r),r}setScopedValue(e,t,i){return this.getOrCreateScope(e).set(t,i),i}deleteScopedValue(e,t){let i=this.scopedRegistry.get(e);i&&(i.delete(t),i.size===0&&this.scopedRegistry.delete(e));}clearScope(e){this.scopedRegistry.delete(e);}data(e){this.originData=e,this.bumpMutationVersion(),this.rebuildItemIndexLookup();for(let t of this.indexMaps.keys())this.rebuildIndexMap(t);this.emit({type:"data",data:e});}add(e){if(e.length===0)return;let t=this.originData.length;for(let i=0;i<e.length;i++)this.originData.push(e[i]),this.itemIndexLookup.set(e[i],t+i);this.bumpMutationVersion();for(let[i,n]of this.indexMaps)for(let o=0;o<e.length;o++)n.set(e[o][i],t+o);this.emit({type:"add",items:e,startIndex:t});}update(e){let{field:t,data:i}=e,n=i[t];if(n==null)return;let r=this.getOrCreateIndexMap(t).get(n);if(r===void 0)return;let s=this.originData[r];this.originData[r]=i,this.itemIndexLookup.delete(s),this.itemIndexLookup.set(i,r),this.bumpMutationVersion();for(let[d,u]of this.indexMaps){let a=s[d],l=i[d];a!==l&&(u.get(a)===r&&u.delete(a),u.set(l,r));}this.emit({type:"update",field:t,index:r,previousItem:s,nextItem:i});}clearData(){let e=[];this.originData=e,this.itemIndexLookup=new WeakMap,this.bumpMutationVersion();for(let t of this.indexMaps.values())t.clear();this.emit({type:"clearData",data:e});}removeByFieldValue(e,t){let n=this.getOrCreateIndexMap(e).get(t);if(n===void 0)return;let o=this.originData.length-1,r=this.originData[n],s=n===o?null:this.originData[o];n!==o&&s&&(this.originData[n]=s,this.itemIndexLookup.set(s,n)),this.originData.pop(),this.itemIndexLookup.delete(r),this.bumpMutationVersion();for(let[d,u]of this.indexMaps){let a=r[d];u.get(a)===n&&u.delete(a),s&&u.set(s[d],n);}this.emit({type:"remove",field:e,value:t,removedItem:r,removedIndex:n,movedItem:s,movedFromIndex:s?o:null});}removeByFieldValues(e,t){if(t.length===0)return;let i=this.getOrCreateIndexMap(e),n=[];for(let o=0;o<t.length;o++){let r=t[o],s=i.get(r);if(s===void 0)continue;let d=this.originData.length-1,u=this.originData[s],a=s===d?null:this.originData[d];s!==d&&a&&(this.originData[s]=a,this.itemIndexLookup.set(a,s)),this.originData.pop(),this.itemIndexLookup.delete(u);for(let[l,p]of this.indexMaps){let h=u[l];p.get(h)===s&&p.delete(h),a&&p.set(a[l],s);}n.push({value:r,removedItem:u,removedIndex:s,movedItem:a,movedFromIndex:a?d:null});}n.length!==0&&(this.bumpMutationVersion(),this.emit({type:"removeMany",field:e,entries:n}));}emit(e){for(let t of this.listeners)t(e);}getOrCreateScope(e){let t=this.scopedRegistry.get(e);if(t)return t;let i=new Map;return this.scopedRegistry.set(e,i),i}bumpMutationVersion(){this.mutationVersion+=1,this.clearPreviousResult();}getOrCreateIndexMap(e){let t=this.indexMaps.get(e);return t||this.rebuildIndexMap(e)}rebuildIndexMap(e){let t=new Map;for(let i=0;i<this.originData.length;i++)t.set(this.originData[i][e],i);return this.indexMaps.set(e,t),t}rebuildItemIndexLookup(){this.itemIndexLookup=new WeakMap;for(let e=0;e<this.originData.length;e++)this.itemIndexLookup.set(this.originData[e],e);}};var m="__merge__";export{g as a,m as b};

package/dist/filter/index.d.mts

@@ -1,11 +1,13 @@
-import { C as CollectionItem, F as FilterCriterion } from '../types-4YEflcxU.mjs';
-export { I as IndexableKey } from '../types-4YEflcxU.mjs';
+import { S as State } from '../State-2vKzwNrQ.mjs';
+import { C as CollectionItem, F as FilterCriterion, U as UpdateDescriptor } from '../types-DONld7xY.mjs';
+export { I as IndexableKey } from '../types-DONld7xY.mjs';
 
 interface FilterEngineChain<T extends CollectionItem> {
     filter(criteria: FilterCriterion<T>[]): T[] & FilterEngineChain<T>;
     filter(data: T[], criteria: FilterCriterion<T>[]): T[] & FilterEngineChain<T>;
     getOriginData(): T[];
     add(items: T[]): FilterEngine<T>;
+    update(descriptor: UpdateDescriptor<T>): FilterEngine<T>;
     data(data: T[]): FilterEngine<T>;
     clearIndexes(): FilterEngine<T>;
     clearData(): FilterEngine<T>;
@@ -25,23 +27,27 @@ interface FilterEngineOptions<T extends CollectionItem = CollectionItem> {
  */
 
 declare class FilterEngine<T extends CollectionItem> {
-    private indexer;
+    private readonly indexer;
     private readonly filterByPreviousResult;
     private readonly mutableExcludeField;
-    private dataset;
-    private readonly datasetPositions;
-    private hasDuplicateMutableExcludeValues;
-    private readonly indexedFields;
+    private readonly state;
+    private readonly namespace;
     private readonly nestedCollection;
-    private previousResult;
-    private previousCriteria;
-    private previousBaseData;
-    private readonly previousResultsByCriteria;
     private readonly chainBuilder;
     /**
      * Creates a new FilterEngine with optional data and fields to index.
      */
-    constructor(options?: FilterEngineOptions<T>);
+    constructor(options?: FilterEngineOptions<T> & {
+        state?: State<T>;
+    });
+    private get dataset();
+    private get runtime();
+    private get mutableExcludeState();
+    private get indexedFields();
+    private get sequentialCache();
+    private shouldDeferMutationIndexUpdates;
+    private markDeferredMutationState;
+    private ensureRuntimeReady;
     private rebuildConfiguredIndexes;
     /**
      * Builds an index for the given field.
@@ -52,6 +58,7 @@ declare class FilterEngine<T extends CollectionItem> {
     clearData(): this;
     data(data: T[]): this;
     add(items: T[]): this;
+    update(descriptor: UpdateDescriptor<T>): this;
     private applyAddedItems;
     getOriginData(): T[];
     /**
@@ -61,11 +68,19 @@ declare class FilterEngine<T extends CollectionItem> {
     filter(data: T[], criteria: FilterCriterion<T>[]): T[] & FilterEngineChain<T>;
     rawFilter(criteria: FilterCriterion<T>[]): T[];
     rawFilter(data: T[], criteria: FilterCriterion<T>[]): T[];
+    private resolveWithSequentialCache;
     private withChain;
+    private handleStateMutation;
     private rebuildMutableExcludeState;
     private updateMutableExcludeStateForAddedItems;
     private applyMutableExclude;
-    private removeStoredItem;
+    private applyUpdatedItem;
+    private applyRemovedItem;
+    private applyRemovedItems;
+    private updateMutableExcludeStateForUpdatedItem;
+    private clearMutableExcludeState;
+    private registerMutableExcludeValue;
+    private unregisterMutableExcludeValue;
     /**
      * Filters data linearly without index.
      */
@@ -82,6 +97,7 @@ declare class FilterEngine<T extends CollectionItem> {
     private createEmptyResult;
     private storePreviousResult;
     private createCriteriaCacheKey;
+    private createSequentialCacheEntry;
     private createSequentialExecutionCriteria;
     private hasCriteriaBacktrack;
     private canApplySequentiallyToEmptyResult;