@resolveio/server-lib 22.3.219 → 22.3.221

package/src/util/subscription-dependency-context.ts

@@ -0,0 +1,1096 @@
+import { AsyncLocalStorage } from 'async_hooks';
+import { deepCopy } from './common';
+
+export interface QueryMeta {
+	limit?: number;
+	skip?: number;
+	sort?: any;
+}
+
+export interface DependencyContextSnapshot {
+	dependencies: Map<string, Set<string>>;
+	filters: Map<string, any[]>;
+	watchAllCollections: Set<string>;
+	queryMetadata: Map<string, QueryMeta[]>;
+}
+
+export interface SerializedDependencySnapshot {
+	dependencies: Array<[string, string[]]>;
+	filters: Array<[string, any[]]>;
+	watchAllCollections: string[];
+	queryMetadata: Array<[string, QueryMeta[]]>;
+}
+
+export interface PublicationContext {
+	publication?: string;
+	subscriptionData?: any[];
+	userId?: string;
+}
+
+interface LookupTarget {
+	from: string;
+	as: string;
+	localField?: string;
+	foreignField?: string;
+	let?: Record<string, any>;
+	pipeline?: any[];
+}
+
+interface DependencyContext extends DependencyContextSnapshot, PublicationContext {}
+
+const dependencyStorage = new AsyncLocalStorage<DependencyContext>();
+
+export async function withDependencyTracking<T>(fn: () => Promise<T>, metadata?: PublicationContext): Promise<{ result: T; snapshot: DependencyContextSnapshot }> {
+	const context: DependencyContext = {
+		dependencies: new Map(),
+		filters: new Map(),
+		watchAllCollections: new Set(),
+		queryMetadata: new Map()
+	};
+
+	if (metadata?.publication) {
+		context.publication = metadata.publication;
+	}
+
+	if (Array.isArray(metadata?.subscriptionData)) {
+		context.subscriptionData = metadata.subscriptionData.slice();
+	}
+
+	if (metadata?.userId) {
+		context.userId = metadata.userId;
+	}
+
+	let result: T;
+
+	await dependencyStorage.run(context, async () => {
+		result = await fn();
+	});
+
+	return {
+		result,
+		snapshot: {
+			dependencies: cloneDependencyMap(context.dependencies),
+			filters: cloneFilterMap(context.filters),
+			watchAllCollections: new Set(context.watchAllCollections),
+			queryMetadata: cloneQueryMetaMap(context.queryMetadata)
+		}
+	};
+}
+
+export function serializeDependencySnapshot(snapshot: DependencyContextSnapshot): SerializedDependencySnapshot {
+	return {
+		dependencies: Array.from(snapshot.dependencies.entries()).map(([collection, ids]) => [collection, Array.from(ids)]),
+		filters: Array.from(snapshot.filters.entries()).map(([collection, filters]) => [collection, deepCopy(filters)]),
+		watchAllCollections: Array.from(snapshot.watchAllCollections),
+		queryMetadata: Array.from(snapshot.queryMetadata.entries()).map(([collection, meta]) => [collection, deepCopy(meta)])
+	};
+}
+
+export function deserializeDependencySnapshot(snapshot: SerializedDependencySnapshot): DependencyContextSnapshot {
+	return {
+		dependencies: new Map(snapshot.dependencies.map(([collection, ids]) => [collection, new Set(ids)])),
+		filters: new Map(snapshot.filters.map(([collection, filters]) => [collection, deepCopy(filters)])),
+		watchAllCollections: new Set(snapshot.watchAllCollections),
+		queryMetadata: new Map(snapshot.queryMetadata.map(([collection, meta]) => [collection, deepCopy(meta)]))
+	};
+}
+
+export function getPublicationContext(): PublicationContext {
+	const context = dependencyStorage.getStore();
+	if (!context) {
+		return {};
+	}
+
+	const snapshot: PublicationContext = {};
+
+	if (context.publication) {
+		snapshot.publication = context.publication;
+	}
+
+	if (Array.isArray(context.subscriptionData)) {
+		snapshot.subscriptionData = context.subscriptionData.slice();
+	}
+
+	if (context.userId) {
+		snapshot.userId = context.userId;
+	}
+
+	return snapshot;
+}
+
+export function recordDependencyResult(collection: string, result: unknown, options?: { filter?: any, meta?: QueryMeta }) {
+	const context = dependencyStorage.getStore();
+
+	if (!context) {
+		return;
+	}
+
+	if (options?.filter) {
+		let filterList = context.filters.get(collection);
+
+		if (!filterList) {
+			filterList = [];
+			context.filters.set(collection, filterList);
+		}
+
+		filterList.push(deepCopy(options.filter));
+		context.watchAllCollections.delete(collection);
+	}
+
+	if (options?.meta) {
+		let metaList = context.queryMetadata.get(collection);
+
+		if (!metaList) {
+			metaList = [];
+			context.queryMetadata.set(collection, metaList);
+		}
+
+		metaList.push(deepCopy(options.meta));
+	}
+
+	const ids = new Set<string>();
+	collectIdsFromResult(result, ids);
+
+	if (!ids.size && options?.filter) {
+		collectIdsFromFilter(options.filter, ids);
+	}
+
+	if (ids.size) {
+		context.watchAllCollections.delete(collection);
+		let existing = context.dependencies.get(collection);
+
+		if (!existing) {
+			existing = new Set();
+			context.dependencies.set(collection, existing);
+		}
+
+		for (const id of ids) {
+			existing.add(id);
+		}
+	}
+	else if (!options?.filter) {
+		context.watchAllCollections.add(collection);
+	}
+}
+
+export function recordAggregateDependencies(collection: string, pipeline: any[], result: unknown) {
+	const context = dependencyStorage.getStore();
+
+	if (!context) {
+		return;
+	}
+
+	const lookupTargets = extractLookupTargets(pipeline);
+	const lookupAliases = new Set<string>(lookupTargets.map(target => target.as).filter(Boolean));
+	const matchFilter = sanitizeMatchFilter(extractMatchFilter(pipeline), lookupAliases);
+	const meta = extractAggregateMeta(pipeline);
+	recordDependencyResult(collection, result, {
+		filter: matchFilter || undefined,
+		meta
+	});
+
+	if (!matchFilter) {
+		context.watchAllCollections.add(collection);
+	}
+
+	if (shouldWatchAllForAggregatePipeline(pipeline)) {
+		context.watchAllCollections.add(collection);
+	}
+
+	if (!lookupTargets.length) {
+		return;
+	}
+
+	for (const target of lookupTargets) {
+		const nestedValues: unknown[] = [];
+		collectLookupValues(result, target.as, nestedValues);
+		const rootDocs = Array.isArray(result) ? result : [result];
+		const pipelineFilters: any[] = [];
+		let pipelineUnresolved = false;
+
+		for (const rootDoc of rootDocs) {
+			const { filters: filtersFromPipeline, unresolved } = buildLookupPipelineFilters(rootDoc, target);
+			if (unresolved) {
+				pipelineUnresolved = true;
+			}
+			if (filtersFromPipeline?.length) {
+				pipelineFilters.push(...filtersFromPipeline);
+			}
+		}
+
+		const filter = buildLookupFilter(result, target.localField, target.foreignField);
+
+		const uniquePipelineFilters = dedupeFilters(pipelineFilters);
+
+		if (nestedValues.length) {
+			recordDependencyResult(target.from, nestedValues, filter ? { filter } : undefined);
+		}
+
+		if (uniquePipelineFilters.length) {
+			const pipelineMeta = extractAggregationMetaFromPipeline(target.pipeline);
+			for (const pipelineFilter of uniquePipelineFilters) {
+				recordDependencyResult(target.from, [], { filter: pipelineFilter, meta: pipelineMeta });
+			}
+			continue;
+		}
+
+		if (!nestedValues.length && filter) {
+			recordDependencyResult(target.from, [], { filter });
+			continue;
+		}
+
+		if (!nestedValues.length) {
+			if (pipelineUnresolved) {
+				context.watchAllCollections.add(target.from);
+			}
+			else if (!target.pipeline || !target.pipeline.length) {
+				context.watchAllCollections.add(target.from);
+			}
+			else {
+				// Lookup pipeline exists, but we could not derive stable filters/ids.
+				context.watchAllCollections.add(target.from);
+			}
+		}
+	}
+}
+
+function shouldWatchAllForAggregatePipeline(pipeline: any[]): boolean {
+	if (!Array.isArray(pipeline)) {
+		return false;
+	}
+
+	return pipeline.some(stage => isCardinalityChangingStage(stage));
+}
+
+function isCardinalityChangingStage(stage: any): boolean {
+	if (!stage || typeof stage !== 'object') {
+		return false;
+	}
+
+	if (stage.$group && typeof stage.$group === 'object') {
+		return true;
+	}
+
+	if (stage.$count !== undefined) {
+		return true;
+	}
+
+	if (stage.$facet && typeof stage.$facet === 'object') {
+		return true;
+	}
+
+	if (stage.$bucket && typeof stage.$bucket === 'object') {
+		return true;
+	}
+
+	if (stage.$bucketAuto && typeof stage.$bucketAuto === 'object') {
+		return true;
+	}
+
+	if (stage.$sortByCount !== undefined) {
+		return true;
+	}
+
+	return false;
+}
+
+function extractLookupTargets(pipeline: any[]): LookupTarget[] {
+	const lookups: LookupTarget[] = [];
+
+	if (!Array.isArray(pipeline)) {
+		return lookups;
+	}
+
+	for (const stage of pipeline) {
+		if (stage && stage.$lookup && typeof stage.$lookup === 'object') {
+			const lookup = stage.$lookup;
+			if (typeof lookup.from === 'string' && typeof lookup.as === 'string') {
+				lookups.push({
+					from: lookup.from,
+					as: lookup.as,
+					localField: typeof lookup.localField === 'string' ? lookup.localField : undefined,
+					foreignField: typeof lookup.foreignField === 'string' ? lookup.foreignField : undefined,
+					let: lookup.let && typeof lookup.let === 'object' ? lookup.let : undefined,
+					pipeline: Array.isArray(lookup.pipeline) ? lookup.pipeline : undefined
+				});
+			}
+		}
+	}
+
+	return lookups;
+}
+
+function extractMatchFilter(pipeline: any[]): any {
+	if (!Array.isArray(pipeline)) {
+		return null;
+	}
+
+	const filters: any[] = [];
+
+	for (const stage of pipeline) {
+		if (stage && stage.$match && typeof stage.$match === 'object') {
+			filters.push(deepCopy(stage.$match));
+		}
+	}
+
+	if (!filters.length) {
+		return null;
+	}
+
+	if (filters.length === 1) {
+		return filters[0];
+	}
+
+	return { $and: filters };
+}
+
+function sanitizeMatchFilter(filter: any, lookupAliases: Set<string>) {
+	if (!filter || !lookupAliases?.size) {
+		return filter;
+	}
+
+	return sanitizeFilterNode(filter, lookupAliases);
+}
+
+function sanitizeFilterNode(node: any, lookupAliases: Set<string>): any {
+	if (!node) {
+		return null;
+	}
+
+	if (Array.isArray(node)) {
+		const sanitizedArray = node
+			.map(entry => sanitizeFilterNode(entry, lookupAliases))
+			.filter(isMeaningfulFilterNode);
+
+		return sanitizedArray.length ? sanitizedArray : null;
+	}
+
+	if (typeof node !== 'object') {
+		return node;
+	}
+
+	const result = {};
+
+	for (const [key, value] of Object.entries(node)) {
+		if (key === '$and' || key === '$or' || key === '$nor') {
+			if (Array.isArray(value)) {
+				const sanitizedChildren = value
+					.map(entry => sanitizeFilterNode(entry, lookupAliases))
+					.filter(isMeaningfulFilterNode);
+
+				if (sanitizedChildren.length) {
+					result[key] = sanitizedChildren;
+				}
+			}
+
+			continue;
+		}
+
+		const rootKey = key.split('.')[0];
+
+		if (lookupAliases.has(rootKey)) {
+			continue;
+		}
+
+		result[key] = value;
+	}
+
+	return Object.keys(result).length ? result : null;
+}
+
+function isMeaningfulFilterNode(node: any) {
+	if (!node) {
+		return false;
+	}
+
+	if (Array.isArray(node)) {
+		return node.length > 0;
+	}
+
+	if (typeof node !== 'object') {
+		return true;
+	}
+
+	return Object.keys(node).length > 0;
+}
+
+function extractAggregateMeta(pipeline: any[]): QueryMeta {
+	if (!Array.isArray(pipeline)) {
+		return null;
+	}
+
+	let limit = undefined;
+	let skip = undefined;
+	let sort = null;
+
+	for (const stage of pipeline) {
+		if (stage?.$limit !== undefined && typeof stage.$limit === 'number') {
+			limit = stage.$limit;
+		}
+		else if (stage?.$skip !== undefined && typeof stage.$skip === 'number') {
+			skip = stage.$skip;
+		}
+		else if (stage?.$sort && typeof stage.$sort === 'object') {
+			sort = deepCopy(stage.$sort);
+		}
+	}
+
+	const meta: QueryMeta = {};
+
+	if (limit !== undefined) {
+		meta.limit = limit;
+	}
+
+	if (skip !== undefined) {
+		meta.skip = skip;
+	}
+
+	if (sort) {
+		meta.sort = sort;
+	}
+
+	return Object.keys(meta).length ? meta : null;
+}
+
+function extractAggregationMetaFromPipeline(pipeline: any[]): QueryMeta {
+	if (!Array.isArray(pipeline)) {
+		return null;
+	}
+
+	let limit = undefined;
+	let skip = undefined;
+	let sort = null;
+
+	for (const stage of pipeline) {
+		if (stage?.$limit !== undefined && typeof stage.$limit === 'number') {
+			limit = stage.$limit;
+		}
+		else if (stage?.$skip !== undefined && typeof stage.$skip === 'number') {
+			skip = stage.$skip;
+		}
+		else if (stage?.$sort && typeof stage.$sort === 'object') {
+			sort = deepCopy(stage.$sort);
+		}
+	}
+
+	const meta: QueryMeta = {};
+
+	if (limit !== undefined) {
+		meta.limit = limit;
+	}
+
+	if (skip !== undefined) {
+		meta.skip = skip;
+	}
+
+	if (sort) {
+		meta.sort = sort;
+	}
+
+	return Object.keys(meta).length ? meta : null;
+}
+
+function collectLookupValues(source: unknown, path: string, output: unknown[]) {
+	if (!source) {
+		return;
+	}
+
+	if (Array.isArray(source)) {
+		for (const item of source) {
+			collectLookupValues(item, path, output);
+		}
+		return;
+	}
+
+	if (typeof source !== 'object') {
+		return;
+	}
+
+	const pathSegments = path.split('.');
+	collectLookupPathValues(source as Record<string, unknown>, pathSegments, 0, output);
+}
+
+function collectLookupPathValues(value: Record<string, unknown>, path: string[], index: number, output: unknown[]) {
+	if (!value) {
+		return;
+	}
+
+	const current = value[path[index]];
+
+	if (current === undefined) {
+		return;
+	}
+
+	if (index === path.length - 1) {
+		output.push(current);
+		return;
+	}
+
+	if (Array.isArray(current)) {
+		for (const item of current) {
+			if (item && typeof item === 'object') {
+				collectLookupPathValues(item as Record<string, unknown>, path, index + 1, output);
+			}
+		}
+	}
+	else if (current && typeof current === 'object') {
+		collectLookupPathValues(current as Record<string, unknown>, path, index + 1, output);
+	}
+}
+
+function buildLookupFilter(result: unknown, localField?: string, foreignField?: string) {
+	if (!localField || !foreignField) {
+		return null;
+	}
+
+	const values: any[] = [];
+	const segments = localField.split('.');
+	collectFieldValues(result, segments, 0, values);
+
+	const uniqueValues = dedupeFilterValues(values);
+
+	if (!uniqueValues.length) {
+		return null;
+	}
+
+	return {
+		[foreignField]: {
+			$in: uniqueValues
+		}
+	};
+}
+
+function collectFieldValues(source: unknown, path: string[], index: number, output: any[]) {
+	if (!source) {
+		return;
+	}
+
+	if (Array.isArray(source)) {
+		for (const item of source) {
+			collectFieldValues(item, path, index, output);
+		}
+		return;
+	}
+
+	if (typeof source !== 'object') {
+		return;
+	}
+
+	const obj = source as Record<string, unknown>;
+	const key = path[index];
+	const current = obj[key];
+
+	if (current === undefined) {
+		return;
+	}
+
+	if (index === path.length - 1) {
+		appendFilterValue(output, current);
+		return;
+	}
+
+	if (Array.isArray(current)) {
+		for (const item of current) {
+			collectFieldValues(item, path, index + 1, output);
+		}
+	}
+	else {
+		collectFieldValues(current, path, index + 1, output);
+	}
+}
+
+function appendFilterValue(output: any[], value: any) {
+	if (value === undefined || value === null) {
+		return;
+	}
+
+	if (Array.isArray(value)) {
+		for (const item of value) {
+			appendFilterValue(output, item);
+		}
+		return;
+	}
+
+	output.push(value);
+}
+
+function dedupeFilterValues(values: any[]): any[] {
+	const unique = new Map<string, any>();
+
+	for (const value of values) {
+		const key = serializeFilterValue(value);
+		if (!unique.has(key)) {
+			unique.set(key, value);
+		}
+	}
+
+	return Array.from(unique.values());
+}
+
+function serializeFilterValue(value: any): string {
+	if (value === null || value === undefined) {
+		return 'null';
+	}
+
+	if (typeof value === 'object') {
+		if (typeof value.toHexString === 'function') {
+			return value.toHexString();
+		}
+
+		if (value instanceof Date) {
+			return value.toISOString();
+		}
+
+		if (typeof value.toString === 'function' && value.toString !== Object.prototype.toString) {
+			return value.toString();
+		}
+
+		try {
+			return JSON.stringify(value);
+		}
+		catch {
+			return '[object]';
+		}
+	}
+
+	return String(value);
+}
+
+function collectIdsFromResult(source: unknown, ids: Set<string>, visited = new WeakSet<object>()) {
+	if (!source) {
+		return;
+	}
+
+	if (Array.isArray(source)) {
+		for (const item of source) {
+			collectIdsFromResult(item, ids, visited);
+		}
+		return;
+	}
+
+	if (typeof source !== 'object') {
+		return;
+	}
+
+	const objectSource = source as Record<string, unknown>;
+
+	if (visited.has(objectSource)) {
+		return;
+	}
+
+	visited.add(objectSource);
+
+	const normalizedId = normalizeId(objectSource._id);
+
+	if (normalizedId) {
+		ids.add(normalizedId);
+	}
+
+	for (const value of Object.values(objectSource)) {
+		if (value && (typeof value === 'object' || Array.isArray(value))) {
+			collectIdsFromResult(value, ids, visited);
+		}
+	}
+}
+
+function collectIdsFromFilter(filter: unknown, ids: Set<string>) {
+	if (!filter) {
+		return;
+	}
+
+	if (Array.isArray(filter)) {
+		for (const item of filter) {
+			collectIdsFromFilter(item, ids);
+		}
+		return;
+	}
+
+	if (typeof filter !== 'object') {
+		return;
+	}
+
+	const filterObject = filter as Record<string, unknown>;
+
+	if (filterObject._id !== undefined) {
+		collectIdsFromFilterValue(filterObject._id, ids);
+	}
+
+	for (const [key, value] of Object.entries(filterObject)) {
+		if (key === '$or' || key === '$and' || key === '$nor') {
+			if (Array.isArray(value)) {
+				for (const item of value) {
+					collectIdsFromFilter(item, ids);
+				}
+			}
+		}
+		else if (key !== '_id' && value && typeof value === 'object') {
+			collectIdsFromFilter(value, ids);
+		}
+	}
+}
+
+function collectIdsFromFilterValue(value: unknown, ids: Set<string>) {
+	if (value === null || value === undefined) {
+		return;
+	}
+
+	if (Array.isArray(value)) {
+		for (const item of value) {
+			collectIdsFromFilterValue(item, ids);
+		}
+		return;
+	}
+
+	if (typeof value === 'object') {
+		for (const [key, inner] of Object.entries(value as Record<string, unknown>)) {
+			if (key === '$in' || key === '$nin' || key === '$all') {
+				collectIdsFromFilterValue(inner, ids);
+			}
+			else if (key === '$eq' || key === '$ne') {
+				collectIdsFromFilterValue(inner, ids);
+			}
+			else if (key === '$or' || key === '$and' || key === '$nor') {
+				collectIdsFromFilterValue(inner, ids);
+			}
+			else {
+				collectIdsFromFilterValue(inner, ids);
+			}
+		}
+		return;
+	}
+
+	const normalized = normalizeId(value);
+
+	if (normalized) {
+		ids.add(normalized);
+	}
+}
+
+function normalizeId(value: unknown): string {
+	if (value === null || value === undefined) {
+		return null;
+	}
+
+	if (typeof value === 'string') {
+		const trimmed = value.trim();
+		return trimmed.length ? trimmed : null;
+	}
+
+	if (typeof value === 'number' || typeof value === 'bigint') {
+		return value.toString();
+	}
+
+	if (typeof value === 'object') {
+		const objValue = value as { toHexString?: () => string, toString?: () => string };
+
+		if (typeof objValue.toHexString === 'function') {
+			return objValue.toHexString();
+		}
+
+		if (value instanceof Date) {
+			return value.toISOString();
+		}
+
+		if (typeof objValue.toString === 'function') {
+			const str = objValue.toString();
+			if (str && str !== '[object Object]') {
+				return str;
+			}
+		}
+	}
+
+	return null;
+}
+
+function cloneDependencyMap(original: Map<string, Set<string>>): Map<string, Set<string>> {
+	const cloned = new Map<string, Set<string>>();
+
+	for (const [collection, ids] of original.entries()) {
+		cloned.set(collection, new Set(ids));
+	}
+
+	return cloned;
+}
+
+function cloneFilterMap(original: Map<string, any[]>): Map<string, any[]> {
+	const cloned = new Map<string, any[]>();
+
+	for (const [collection, filters] of original.entries()) {
+		cloned.set(collection, filters.map(filter => deepCopy(filter)));
+	}
+
+	return cloned;
+}
+
+function cloneQueryMetaMap(original: Map<string, QueryMeta[]>): Map<string, QueryMeta[]> {
+	const cloned = new Map<string, QueryMeta[]>();
+
+	for (const [collection, metaList] of original.entries()) {
+		cloned.set(collection, metaList.map(meta => deepCopy(meta)));
+	}
+
+	return cloned;
+}
+
+
+function buildLookupPipelineFilters(rootDoc: any, target: LookupTarget): { filters: any[], unresolved: boolean } {
+	if (!target.pipeline || !target.pipeline.length) {
+		return { filters: [], unresolved: false };
+	}
+
+const matchStages = target.pipeline.map(stage => ({ stage, base: stage.$match })).filter(entry => entry.base);
+
+	if (!matchStages.length) {
+		return buildLookupPipelineFromStack(target.pipeline, [], rootDoc, target.let);
+	}
+
+	const letValuesResult = resolveLetVariables(rootDoc, target.let);
+
+	if (!letValuesResult.resolved) {
+		return { filters: [], unresolved: true };
+	}
+
+	const combinedMatches = [];
+
+	for (const { base } of matchStages) {
+		const substitutionState = { unresolved: false };
+		const substituted = substituteLetVariables(base, letValuesResult.values, rootDoc, substitutionState);
+
+		if (substitutionState.unresolved || containsUnresolvedLetReference(substituted)) {
+			return { filters: [], unresolved: true };
+		}
+
+		combinedMatches.push(substituted);
+	}
+
+	if (!combinedMatches.length) {
+		return buildLookupPipelineFromStack(target.pipeline, [], rootDoc, target.let);
+	}
+
+	if (combinedMatches.length === 1) {
+		return { filters: [combinedMatches[0]], unresolved: false };
+	}
+
+	return { filters: [{ $and: combinedMatches }], unresolved: false };
+}
+
+function buildLookupPipelineFromStack(pipeline: any[], initialFilters: any[], rootDoc: any, letMap: Record<string, any>) {
+	let currentFilters = initialFilters.slice();
+	let unresolved = false;
+
+	const entries = pipeline.map(stage => stage ? Object.keys(stage)[0] : null);
+
+	for (let i = 0; i < pipeline.length; i++) {
+		const stage = pipeline[i];
+		const stageType = entries[i];
+
+		if (stageType === '$match' && stage.$match) {
+			const letValuesResult = resolveLetVariables(rootDoc, letMap);
+			if (!letValuesResult.resolved) {
+				unresolved = true;
+				break;
+			}
+
+			const substitutionState = { unresolved: false };
+			const substituted = substituteLetVariables(stage.$match, letValuesResult.values, rootDoc, substitutionState);
+
+			if (substitutionState.unresolved || containsUnresolvedLetReference(substituted)) {
+				unresolved = true;
+				break;
+			}
+
+			currentFilters.push(substituted);
+		}
+		else if (stageType === '$match') {
+			unresolved = true;
+			break;
+		}
+		else if (stageType === '$facet') {
+			unresolved = true;
+			break;
+		}
+	}
+
+	if (!currentFilters.length) {
+		return { filters: [], unresolved };
+	}
+
+	if (currentFilters.length === 1) {
+		return { filters: currentFilters, unresolved };
+	}
+
+	return { filters: [{ $and: currentFilters }], unresolved };
+}
+
+function resolveLetVariables(rootDoc: any, letMap: Record<string, any>) {
+	if (!letMap || typeof letMap !== 'object') {
+		return { resolved: true, values: {} };
+	}
+
+	const values = {};
+
+	for (const [key, expression] of Object.entries(letMap)) {
+		const evaluation = evaluateLetExpression(rootDoc, expression);
+
+		if (!evaluation.resolved) {
+			return { resolved: false, values: null };
+		}
+
+		values[key] = evaluation.value;
+	}
+
+	return { resolved: true, values };
+}
+
+function evaluateLetExpression(rootDoc: any, expression: any): { resolved: boolean, value: any } {
+	if (typeof expression === 'string') {
+		if (expression.startsWith('$$ROOT.')) {
+			const path = expression.slice('$$ROOT.'.length);
+			return { resolved: true, value: getValueByPath(rootDoc, path) };
+		}
+		else if (expression === '$$ROOT') {
+			return { resolved: true, value: rootDoc };
+		}
+		else if (expression.startsWith('$$')) {
+			return { resolved: false, value: null };
+		}
+		else if (expression.startsWith('$')) {
+			const path = expression.slice(1);
+			return { resolved: true, value: getValueByPath(rootDoc, path) };
+		}
+		else {
+			return { resolved: true, value: expression };
+		}
+	}
+	else if (Array.isArray(expression)) {
+		return { resolved: false, value: null };
+	}
+	else if (expression && typeof expression === 'object') {
+		return { resolved: false, value: null };
+	}
+
+	return { resolved: true, value: expression };
+}
+
+function substituteLetVariables(node: any, letValues: Record<string, any>, rootDoc: any, state: { unresolved: boolean }) {
+	if (Array.isArray(node)) {
+		return node.map(item => substituteLetVariables(item, letValues, rootDoc, state));
+	}
+
+	if (node && typeof node === 'object') {
+		const output = {};
+
+		for (const [key, value] of Object.entries(node)) {
+			output[key] = substituteLetVariables(value, letValues, rootDoc, state);
+		}
+
+		return output;
+	}
+
+	if (typeof node === 'string') {
+		if (node.startsWith('$$ROOT.')) {
+			const path = node.slice('$$ROOT.'.length);
+			return getValueByPath(rootDoc, path);
+		}
+
+		if (node === '$$ROOT') {
+			return rootDoc;
+		}
+
+		if (node.startsWith('$$')) {
+			const varName = node.slice(2);
+
+			if (Object.prototype.hasOwnProperty.call(letValues, varName)) {
+				return letValues[varName];
+			}
+
+			state.unresolved = true;
+			return node;
+		}
+	}
+
+	return node;
+}
+
+function containsUnresolvedLetReference(node: any): boolean {
+	if (typeof node === 'string') {
+		return node.includes('$$');
+	}
+
+	if (Array.isArray(node)) {
+		return node.some(item => containsUnresolvedLetReference(item));
+	}
+
+	if (node && typeof node === 'object') {
+		return Object.values(node).some(value => containsUnresolvedLetReference(value));
+	}
+
+	return false;
+}
+
+function getValueByPath(source: any, path: string) {
+	if (!source || !path) {
+		return undefined;
+	}
+
+	const segments = path.split('.');
+	let current = source;
+
+	for (const segment of segments) {
+		if (current === null || current === undefined) {
+			return undefined;
+		}
+
+		if (Array.isArray(current)) {
+			const index = parseInt(segment, 10);
+
+			if (isNaN(index) || index < 0 || index >= current.length) {
+				return undefined;
+			}
+
+			current = current[index];
+		}
+		else {
+			current = current[segment];
+		}
+	}
+
+	return current;
+}
+
+function canonicalizeFilter(filter: any): string {
+	return JSON.stringify(sortKeys(filter));
+}
+
+function sortKeys(value: any): any {
+	if (Array.isArray(value)) {
+		return value.map(item => sortKeys(item));
+	}
+
+	if (value && typeof value === 'object') {
+		const sorted = {};
+		const keys = Object.keys(value).sort();
+
+		for (const key of keys) {
+			sorted[key] = sortKeys(value[key]);
+		}
+
+		return sorted;
+	}
+
+	return value;
+}
+
+function dedupeFilters(filters: any[]): any[] {
+	const map = new Map<string, any>();
+
+	for (const filter of filters) {
+		const key = canonicalizeFilter(filter);
+
+		if (!map.has(key)) {
+			map.set(key, filter);
+		}
+	}
+
+	return Array.from(map.values());
+}