@devisfuture/mega-collection 2.4.5 → 2.4.7

package/README.md

@@ -52,9 +52,9 @@ This works fine for small arrays. But with 10 000–100 000+ items, every call t
 
 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.
+### Important
 
+The package has no dependencies. You can import only the parts you need.
 Each engine has its own entry point: `/search`, `/filter`, `/sort`.
 If you import only `@devisfuture/mega-collection/search`, only search code goes into the bundle.
 Unused modules are not included.

package/dist/State.d.ts

@@ -0,0 +1,42 @@
+import type { CollectionItem, IndexableKey, StateListener, StateOptions, StatePreviousResult, StateRegistryFactory, UpdateDescriptor } from "./types";
+export 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;
+}
+//# sourceMappingURL=State.d.ts.map

package/dist/{chunk-BJZg_1dI.mjs → State.mjs}

@@ -178,6 +178,6 @@ var e = class {
 		this.itemIndexLookup = /* @__PURE__ */ new WeakMap();
 		for (let e = 0; e < this.originData.length; e++) this.itemIndexLookup.set(this.originData[e], e);
 	}
-}, t = "__merge__", n = "deferFilterMutationIndexUpdates", r = "deferSearchMutationIndexUpdates", i = "deferSortMutationCacheUpdates";
+};
 //#endregion
-export { e as a, t as i, r as n, i as r, n as t };
+export { e as State };

package/dist/constants.d.ts

@@ -0,0 +1,5 @@
+export declare const MERGE_SHARED_SCOPE = "__merge__";
+export declare const DEFER_FILTER_MUTATION_INDEX_UPDATES_KEY = "deferFilterMutationIndexUpdates";
+export declare const DEFER_SEARCH_MUTATION_INDEX_UPDATES_KEY = "deferSearchMutationIndexUpdates";
+export declare const DEFER_SORT_MUTATION_CACHE_UPDATES_KEY = "deferSortMutationCacheUpdates";
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.mjs

@@ -0,0 +1,4 @@
+//#region src/constants.ts
+var e = "__merge__", t = "deferFilterMutationIndexUpdates", n = "deferSearchMutationIndexUpdates", r = "deferSortMutationCacheUpdates";
+//#endregion
+export { t as DEFER_FILTER_MUTATION_INDEX_UPDATES_KEY, n as DEFER_SEARCH_MUTATION_INDEX_UPDATES_KEY, r as DEFER_SORT_MUTATION_CACHE_UPDATES_KEY, e as MERGE_SHARED_SCOPE };

package/dist/filter/chain.d.ts

@@ -0,0 +1,9 @@
+import type { CollectionItem } from "../types";
+import type { FilterEngineChain, FilterEngineChainCallbacks } from "./types";
+export type { FilterEngineChain } from "./types";
+export declare class FilterEngineChainBuilder<T extends CollectionItem> {
+    private readonly callbacks;
+    constructor(callbacks: FilterEngineChainCallbacks<T>);
+    create(result: T[]): T[] & FilterEngineChain<T>;
+}
+//# sourceMappingURL=chain.d.ts.map

package/dist/filter/chain.mjs

@@ -0,0 +1,22 @@
+import { createChainMethodDescriptor as e } from "../internal.mjs";
+//#region src/filter/chain.ts
+var t = class {
+	constructor(e) {
+		this.callbacks = e;
+	}
+	create(t) {
+		let n = t;
+		return Object.defineProperties(n, {
+			filter: e((e, n) => n === void 0 ? this.callbacks.filter(t, e) : this.callbacks.filter(e, n)),
+			add: e((e) => this.callbacks.add(e)),
+			update: e((e) => this.callbacks.update(e)),
+			clearIndexes: e(() => this.callbacks.clearIndexes()),
+			data: e((e) => this.callbacks.data(e)),
+			getOriginData: e(() => this.callbacks.getOriginData()),
+			clearData: e(() => this.callbacks.clearData()),
+			resetFilterState: e(() => this.callbacks.resetFilterState())
+		}), n;
+	}
+};
+//#endregion
+export { t as FilterEngineChainBuilder };

package/dist/filter/constants.d.ts

@@ -0,0 +1,2 @@
+export { DEFER_FILTER_MUTATION_INDEX_UPDATES_KEY } from "../constants";
+//# sourceMappingURL=constants.d.ts.map

package/dist/filter/criterion.d.ts

@@ -0,0 +1,6 @@
+import type { CollectionItem, FilterCriterion } from "../types";
+import type { ResolvedFilterCriterion } from "./types";
+export declare function resolveCriteria<T extends CollectionItem>(criteria: FilterCriterion<T>[]): ResolvedFilterCriterion<T>[];
+export declare function matchesCriterionValue<T extends CollectionItem>(criterion: ResolvedFilterCriterion<T>, value: any): boolean;
+export declare function isCriterionUnsatisfiable<T extends CollectionItem>(criterion: ResolvedFilterCriterion<T>): boolean;
+//# sourceMappingURL=criterion.d.ts.map

package/dist/filter/criterion.mjs

@@ -0,0 +1,64 @@
+//#region src/filter/criterion.ts
+function e(e) {
+	let t = /* @__PURE__ */ new Map();
+	for (let n = 0; n < e.length; n++) {
+		let a = e[n], o = Array.isArray(a.values), s = r(a.exclude), c = s !== null, l = o ? i(a.values, s) : null;
+		if (!o && !c) continue;
+		let u = a.field, d = t.get(u);
+		if (!d) {
+			t.set(u, {
+				field: a.field,
+				values: [],
+				exclude: [],
+				hasValues: o,
+				hasExclude: c,
+				includedValues: l ? new Set(l) : null,
+				excludedValues: s ? new Set(s) : null,
+				cacheKeySegment: ""
+			});
+			continue;
+		}
+		if (o) if (!d.hasValues) d.hasValues = !0, d.includedValues = new Set(l);
+		else for (let e of d.includedValues) l.has(e) || d.includedValues.delete(e);
+		if (c) if (!d.hasExclude) d.hasExclude = !0, d.excludedValues = new Set(s);
+		else for (let e of s) d.excludedValues.add(e);
+	}
+	let n = [...t.values()].sort((e, t) => e.field.localeCompare(t.field));
+	for (let e = 0; e < n.length; e++) a(n[e]);
+	return n;
+}
+function t(e, t) {
+	return !(e.hasValues && !e.includedValues.has(t) || e.hasExclude && e.excludedValues.has(t));
+}
+function n(e) {
+	return e.hasValues && e.values.length === 0;
+}
+function r(e) {
+	return !Array.isArray(e) || e.length === 0 ? null : new Set(e);
+}
+function i(e, t) {
+	let n = /* @__PURE__ */ new Set();
+	for (let r = 0; r < e.length; r++) {
+		let i = e[r];
+		t?.has(i) || n.add(i);
+	}
+	return n;
+}
+function a(e) {
+	if (e.hasValues && e.hasExclude) for (let t of e.excludedValues) e.includedValues.delete(t);
+	e.values = e.includedValues ? [...e.includedValues] : [], e.exclude = e.excludedValues ? [...e.excludedValues] : [], e.cacheKeySegment = o(e);
+}
+function o(e) {
+	let t = e.field;
+	return t += `|hv:${e.hasValues ? "1" : "0"}|v:`, e.hasValues && (t += s(e.values)), t += `|hx:${e.hasExclude ? "1" : "0"}|x:`, e.hasExclude && (t += s(e.exclude)), t;
+}
+function s(e) {
+	return e.length === 0 ? "" : e.map((e) => c(e)).sort().join(",");
+}
+function c(e) {
+	if (e === null) return "null:null";
+	let t = typeof e;
+	return t === "object" ? `object:${JSON.stringify(e)}` : `${t}:${String(e)}`;
+}
+//#endregion
+export { n as isCriterionUnsatisfiable, t as matchesCriterionValue, e as resolveCriteria };

package/dist/filter/errors.d.ts

@@ -0,0 +1,7 @@
+export declare class FilterEngineError extends Error {
+    constructor(message: string);
+    static missingDatasetForBuildIndex(): FilterEngineError;
+    static missingDatasetForFilter(): FilterEngineError;
+    static duplicateMutableExcludeField(field: string): FilterEngineError;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/filter/errors.mjs

@@ -0,0 +1,17 @@
+//#region src/filter/errors.ts
+var e = class e extends Error {
+	constructor(e) {
+		super(e), this.name = "FilterEngineError";
+	}
+	static missingDatasetForBuildIndex() {
+		return new e("FilterEngine: no dataset in memory. Call data() or add() before buildIndex().");
+	}
+	static missingDatasetForFilter() {
+		return new e("FilterEngine: no dataset in memory. Call data() or add() before filter().");
+	}
+	static duplicateMutableExcludeField(t) {
+		return new e(`FilterEngine: cannot use mutable exclude on field \`${t}\` because it contains duplicate values.`);
+	}
+};
+//#endregion
+export { e as FilterEngineError };

package/dist/filter/filter.d.ts

@@ -0,0 +1,89 @@
+/**
+ * FilterEngine class for filtering collections by multiple criteria,
+ * supporting indexed lookups and linear scans for large datasets.
+ */
+import { State } from "../State";
+import { CollectionItem, FilterCriterion, type UpdateDescriptor } from "../types";
+import { FilterEngineChain } from "./chain";
+import type { FilterEngineOptions } from "./types";
+export declare class FilterEngine<T extends CollectionItem> {
+    private readonly indexer;
+    private readonly filterByPreviousResult;
+    private readonly mutableExcludeField;
+    private readonly state;
+    private readonly namespace;
+    private readonly nestedCollection;
+    private readonly chainBuilder;
+    /**
+     * Creates a new FilterEngine with optional data and fields to index.
+     */
+    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.
+     */
+    private buildIndex;
+    clearIndexes(): this;
+    resetFilterState(): this;
+    clearData(): this;
+    data(data: T[]): this;
+    add(items: T[]): this;
+    update(descriptor: UpdateDescriptor<T>): this;
+    private applyAddedItems;
+    getOriginData(): T[];
+    /**
+     * Filters the data based on the given criteria.
+     */
+    filter(criteria: FilterCriterion<T>[]): T[] & FilterEngineChain<T>;
+    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 applyUpdatedItem;
+    private applyRemovedItem;
+    private applyRemovedItems;
+    private updateMutableExcludeStateForUpdatedItem;
+    private clearMutableExcludeState;
+    private registerMutableExcludeValue;
+    private unregisterMutableExcludeValue;
+    /**
+     * Filters data linearly without index.
+     */
+    private linearFilter;
+    /**
+     * Filters data using the index.
+     */
+    private filterViaIndex;
+    /**
+     * Estimates the size of the index for a criterion.
+     */
+    private estimateIndexSize;
+    private applyIndexedExclusions;
+    private createEmptyResult;
+    private storePreviousResult;
+    private createCriteriaCacheKey;
+    private createSequentialCacheEntry;
+    private createSequentialExecutionCriteria;
+    private hasCriteriaBacktrack;
+    private canApplySequentiallyToEmptyResult;
+    private createCriteriaStateMap;
+    private isCriterionBacktracked;
+    private isSubset;
+    private areSetsEqual;
+}
+//# sourceMappingURL=filter.d.ts.map