feathers-utils 10.1.0 → 10.3.0

package/dist/{utils-Br6DNQ1B.mjs → utils-DByCpAsf.mjs}

@@ -1,5 +1,6 @@
-import { d as isPaginated, m as isContext, p as isMulti } from "./predicates-puYa4nkf.mjs";
-import { a as getResultIsArray, o as getDataIsArray } from "./mutate-result.util-Dqzepn1M.mjs";
+import { a as isEmptyObject, r as toArray } from "./internal.utils-BBB-b6Ud.mjs";
+import { d as isPaginated, m as isContext, p as isMulti } from "./predicates-NOnUyMic.mjs";
+import { a as getResultIsArray, o as getDataIsArray } from "./mutate-result.util-C0nY6L7i.mjs";
 import { dequal } from "dequal";
 import * as feathers from "@feathersjs/feathers";
 //#region src/utils/sort-query-properties/sort-query-properties.util.ts
@@ -88,58 +89,13 @@ const addSkip = (context, hooks) => {
 	}
 };
 //#endregion
-//#region src/utils/chunk-find/chunk-find.util.ts
-/**
-* Use `for await` to iterate over chunks (pages) of results from a `find` method.
-*
-* This function is useful for processing large datasets in batches without loading everything into memory at once.
-* It uses pagination to fetch results in chunks, yielding each page's data array.
-*
-* @example
-* ```ts
-* import { chunkFind } from 'feathers-utils/utils'
-*
-* const app = feathers()
-*
-* // Assuming 'users' service has many records
-* for await (const users of chunkFind(app, 'users', {
-*  params: { query: { active: true }, // Custom query parameters
-* } })) {
-*  console.log(users) // Process each chunk of user records
-* }
-* ```
-*
-* @see https://utils.feathersjs.com/utils/chunk-find.html
-*/
-async function* chunkFind(app, servicePath, options) {
-	const service = app.service(servicePath);
-	if (!service || !("find" in service)) throw new Error(`Service '${servicePath}' does not have a 'find' method.`);
-	const params = {
-		...options?.params,
-		query: {
-			...options?.params?.query ?? {},
-			$limit: options?.params?.query?.$limit ?? 10,
-			$skip: options?.params?.query?.$skip ?? 0
-		},
-		paginate: {
-			default: options?.params?.paginate?.default ?? 10,
-			max: options?.params?.paginate?.max ?? 100
-		}
-	};
-	let result;
-	do {
-		result = await service.find(params);
-		if (!result.data.length) break;
-		yield result.data;
-		params.query.$skip = (params.query.$skip ?? 0) + result.data.length;
-	} while (result.total > params.query.$skip);
-}
-//#endregion
 //#region src/utils/add-to-query/add-to-query.util.ts
 /**
 * Safely merges properties into a Feathers query object. If a property already exists
 * with a different value, it wraps both in a `$and` array to preserve both conditions.
-* If the exact same key-value pair already exists, no changes are made.
+* If the exact same key-value pair already exists, no changes are made. When the added
+* query is itself a pure `$and` (`{ $and: [...] }`), its branches are flattened into the
+* target's `$and` rather than nested.
 *
 * @example
 * ```ts
@@ -164,6 +120,15 @@ function addToQuery(targetQuery, query) {
 		return entries.every(([property, value]) => property in targetQuery && dequal(targetQuery[property], value));
 	}
 	if (isAlreadyInQuery(targetQuery, entries)) return targetQuery;
+	if (entries.length === 1 && Array.isArray(query.$and)) {
+		const existing = targetQuery.$and ?? [];
+		const newBranches = query.$and.filter((branch) => !existing.some((q) => dequal(q, branch)));
+		if (newBranches.length === 0) return targetQuery;
+		return {
+			...targetQuery,
+			$and: [...existing, ...newBranches]
+		};
+	}
 	if (!targetQuery.$and) return {
 		...targetQuery,
 		$and: [{ ...query }]
@@ -199,6 +164,53 @@ function checkContext(context, typeOrOptions, methods, label = "anonymous") {
 	}
 }
 //#endregion
+//#region src/utils/chunk-find/chunk-find.util.ts
+/**
+* Use `for await` to iterate over chunks (pages) of results from a `find` method.
+*
+* This function is useful for processing large datasets in batches without loading everything into memory at once.
+* It uses pagination to fetch results in chunks, yielding each page's data array.
+*
+* @example
+* ```ts
+* import { chunkFind } from 'feathers-utils/utils'
+*
+* const app = feathers()
+*
+* // Assuming 'users' service has many records
+* for await (const users of chunkFind(app, 'users', {
+*  params: { query: { active: true }, // Custom query parameters
+* } })) {
+*  console.log(users) // Process each chunk of user records
+* }
+* ```
+*
+* @see https://utils.feathersjs.com/utils/chunk-find.html
+*/
+async function* chunkFind(app, servicePath, options) {
+	const service = app.service(servicePath);
+	if (!service || !("find" in service)) throw new Error(`Service '${servicePath}' does not have a 'find' method.`);
+	const params = {
+		...options?.params,
+		query: {
+			...options?.params?.query ?? {},
+			$limit: options?.params?.query?.$limit ?? 10,
+			$skip: options?.params?.query?.$skip ?? 0
+		},
+		paginate: {
+			default: options?.params?.paginate?.default ?? 10,
+			max: options?.params?.paginate?.max ?? 100
+		}
+	};
+	let result;
+	do {
+		result = await service.find(params);
+		if (!result.data.length) break;
+		yield result.data;
+		params.query.$skip = (params.query.$skip ?? 0) + result.data.length;
+	} while (result.total > params.query.$skip);
+}
+//#endregion
 //#region src/utils/context-to-json/context-to-json.util.ts
 /**
 * Converts a FeathersJS HookContext to a plain JSON object by calling `toJSON()` if available.
@@ -314,6 +326,172 @@ async function* iterateFind(app, servicePath, options) {
 	} while (result.total > params.query.$skip);
 }
 //#endregion
+//#region src/utils/merge-query/extract-query-filters.ts
+/**
+* Splits a query into its special filters ($select, $limit, $skip, $sort) and the
+* remaining query body. Internal helper for {@link mergeQuery} — not part of the
+* public API.
+*/
+function extractQueryFilters(providedQuery) {
+	providedQuery ??= {};
+	const { $select, $limit, $skip, $sort, ...query } = providedQuery;
+	const result = { query };
+	if ("$select" in providedQuery) result.$select = $select;
+	if ("$limit" in providedQuery) result.$limit = $limit;
+	if ("$skip" in providedQuery) result.$skip = $skip;
+	if ("$sort" in providedQuery) result.$sort = $sort;
+	return result;
+}
+//#endregion
+//#region src/utils/merge-query/logical-branches.ts
+/**
+* Returns the branches of a logical-only query (a query whose single key is `op`),
+* or `null` when the query is not purely `{ [op]: [...] }`. Internal helper for
+* {@link mergeQuery}.
+*/
+function logicalBranches(query, op) {
+	const keys = Object.keys(query);
+	if (keys.length === 1 && keys[0] === op && Array.isArray(query[op])) return query[op];
+	return null;
+}
+//#endregion
+//#region src/utils/merge-query/dedupe-branches.ts
+/**
+* Removes empty (`{}`) and deep-equal duplicate branches, preserving order.
+* Internal helper for {@link mergeQuery}.
+*/
+function dedupeBranches(branches) {
+	const result = [];
+	for (const branch of branches) {
+		if (isEmptyObject(branch)) continue;
+		if (!result.some((existing) => dequal(existing, branch))) result.push(branch);
+	}
+	return result;
+}
+//#endregion
+//#region src/utils/merge-query/has-conflict.ts
+/**
+* Two query bodies conflict when they share at least one key whose values are not
+* deep-equal. Internal helper for {@link mergeQuery}.
+*/
+function hasConflict(target, source) {
+	for (const key of Object.keys(target)) if (key in source && !dequal(target[key], source[key])) return true;
+	return false;
+}
+//#endregion
+//#region src/utils/merge-query/merge-query-bodies.ts
+/**
+* Merges two query bodies (filters already removed) according to the mode.
+* Internal helper for {@link mergeQuery}.
+*
+* - `target` / `source`: precedence merge (that side wins on conflict).
+* - `combine`: the two bodies always become branches of a single `$or`.
+* - `intersect`: non-conflicting bodies merge flat; on conflict they become
+*   branches of a single `$and`.
+*
+* Logical-only bodies (`{ $or: [...] }` for combine, `{ $and: [...] }` for
+* intersect) are flattened into the result and their branches de-duplicated.
+*/
+function mergeQueryBodies(target, source, mode) {
+	if (mode === "target") return {
+		...source,
+		...target
+	};
+	if (mode === "source") return {
+		...target,
+		...source
+	};
+	if (isEmptyObject(target)) return { ...source };
+	if (isEmptyObject(source)) return { ...target };
+	const op = mode === "combine" ? "$or" : "$and";
+	const targetBranches = logicalBranches(target, op);
+	const sourceBranches = logicalBranches(source, op);
+	if (op === "$and" && !targetBranches && !sourceBranches && !hasConflict(target, source)) return {
+		...target,
+		...source
+	};
+	const branches = dedupeBranches([...targetBranches ?? [target], ...sourceBranches ?? [source]]);
+	if (branches.length === 0) return {};
+	if (branches.length === 1) return { ...branches[0] };
+	return { [op]: branches };
+}
+//#endregion
+//#region src/utils/merge-query/merge-select.ts
+/**
+* Merges two `$select` filters according to the mode: `combine` → union,
+* `intersect` → intersection, `target`/`source` → that side. When only one side
+* provides a `$select`, that one is used. Internal helper for {@link mergeQuery}.
+*/
+function mergeSelect(target, source, mode) {
+	if (target === void 0) return source;
+	if (source === void 0) return target;
+	if (mode === "target") return target;
+	if (mode === "source") return source;
+	const targetArr = Array.isArray(target) ? target : [target];
+	const sourceArr = Array.isArray(source) ? source : [source];
+	if (mode === "combine") return [...new Set([...targetArr, ...sourceArr])];
+	return targetArr.filter((value) => sourceArr.includes(value));
+}
+//#endregion
+//#region src/utils/merge-query/merge-query.util.ts
+/**
+* Properties are combined with a logical operator rather than merged at the value
+* level, so the result is always a valid query: `combine` always wraps the two
+* queries in `$or` (broaden — OR has no flat form), while `intersect` merges
+* non-conflicting properties flat and wraps conflicts in `$and` (narrow). The
+* special filters `$select`, `$limit`, `$skip` and `$sort` are merged separately.
+* Inputs are never mutated.
+*
+* This is well suited to merging a client-provided query with a server-side
+* restriction inside a hook.
+*
+* @param target Query to be merged into
+* @param source Query to be merged from
+* @param options
+* @returns the merged query
+*
+* @example
+* ```ts
+* import { mergeQuery } from 'feathers-utils/utils'
+*
+* // combine (default): the two queries always become an $or
+* mergeQuery({ id: 1 }, { id: 2 })
+* // => { $or: [{ id: 1 }, { id: 2 }] }
+*
+* mergeQuery({ status: 'active' }, { authorId: 5 })
+* // => { $or: [{ status: 'active' }, { authorId: 5 }] }
+* ```
+*
+* @example
+* ```ts
+* // intersect: non-conflicting properties merge flat, conflicts become an $and
+* mergeQuery({ status: 'active' }, { authorId: 5 }, { mode: 'intersect' })
+* // => { status: 'active', authorId: 5 }
+*
+* mergeQuery({ id: 1 }, { id: 2 }, { mode: 'intersect' })
+* // => { $and: [{ id: 1 }, { id: 2 }] }
+* ```
+*
+* @see https://utils.feathersjs.com/utils/merge-query.html
+*/
+function mergeQuery(target, source, options) {
+	const mode = options?.mode ?? "combine";
+	const targetFilters = extractQueryFilters(target);
+	const sourceFilters = extractQueryFilters(source);
+	const result = mergeQueryBodies(targetFilters.query, sourceFilters.query, mode);
+	const $select = mergeSelect(targetFilters.$select, sourceFilters.$select, mode);
+	if ($select !== void 0) result.$select = $select;
+	if ("$limit" in sourceFilters) result.$limit = sourceFilters.$limit;
+	else if ("$limit" in targetFilters) result.$limit = targetFilters.$limit;
+	if ("$skip" in sourceFilters) result.$skip = sourceFilters.$skip;
+	else if ("$skip" in targetFilters) result.$skip = targetFilters.$skip;
+	if ("$sort" in targetFilters || "$sort" in sourceFilters) result.$sort = {
+		...targetFilters.$sort,
+		...sourceFilters.$sort
+	};
+	return result;
+}
+//#endregion
 //#region src/utils/patch-batch/patch-batch.util.ts
 /**
 * Deterministic, key-order-independent serialization used to group items with
@@ -377,6 +555,183 @@ function patchBatch(items, options) {
 	});
 }
 //#endregion
+//#region src/utils/walk-query/walk-query.util.ts
+const _walkQueryUtil = (query, walker, state, options) => {
+	const stop = () => {
+		state.stopped = true;
+	};
+	let cloned = false;
+	const clonedSecond = {};
+	function set(key, value, secondKey) {
+		if (!cloned) {
+			query = { ...query };
+			cloned = true;
+		}
+		if (secondKey !== void 0) {
+			if (!clonedSecond[key]) {
+				query[key] = { ...query[key] };
+				clonedSecond[key] = true;
+			}
+			query[key][secondKey] = value;
+			return;
+		}
+		query[key] = value;
+	}
+	for (const key in query) {
+		if (state.stopped) break;
+		if ((key === "$or" || key === "$and" || key === "$nor") && Array.isArray(query[key])) {
+			let array = query[key];
+			let copiedArray = false;
+			for (let i = 0, n = array.length; i < n; i++) {
+				if (state.stopped) break;
+				const nestedQuery = array[i];
+				const transformed = _walkQueryUtil(nestedQuery, walker, state, {
+					...options,
+					path: [
+						...options?.path || [],
+						key,
+						i
+					]
+				});
+				if (transformed !== nestedQuery) {
+					if (!copiedArray) {
+						array = [...array];
+						copiedArray = true;
+					}
+					array[i] = transformed;
+				}
+			}
+			if (copiedArray) set(key, array);
+		} else if (typeof query[key] === "object" && query[key] !== null && !Array.isArray(query[key])) {
+			let hasOperator = false;
+			for (const operator in query[key]) {
+				if (state.stopped) break;
+				if (operator.startsWith("$")) {
+					hasOperator = true;
+					const value = walker({
+						operator,
+						path: [...options?.path ?? [], key],
+						property: key,
+						value: query[key][operator],
+						stop
+					});
+					if (value !== void 0 && value !== query[key][operator]) set(key, value, operator);
+				}
+			}
+			if (!hasOperator) {
+				const value = walker({
+					operator: void 0,
+					path: [...options?.path ?? [], key],
+					property: key,
+					value: query[key],
+					stop
+				});
+				if (value !== void 0 && value !== query[key]) set(key, value);
+			}
+		} else {
+			const value = walker({
+				operator: void 0,
+				path: [...options?.path ?? [], key],
+				property: key,
+				value: query[key],
+				stop
+			});
+			if (value !== void 0 && value !== query[key]) set(key, value);
+		}
+	}
+	return query;
+};
+/**
+* Walks every property of a Feathers query (including nested `$and`/`$or`/`$nor` arrays)
+* and calls the `walker` function for each one. The walker receives the property name, operator,
+* value, path, and a `stop` function, and can return a replacement value. Calling `stop()` halts
+* the traversal early. Returns a new query only if changes were made.
+*
+* @example
+* ```ts
+* import { walkQuery } from 'feathers-utils/utils'
+*
+* const query = walkQuery({ age: { $gt: '18' } }, ({ value, operator }) => {
+*   if (operator === '$gt') return Number(value)
+* })
+* // => { age: { $gt: 18 } }
+* ```
+*
+* @example
+* ```ts
+* // stop early once a property is found
+* let found = false
+* walkQuery(query, ({ property, stop }) => {
+*   if (property === 'isTemplate') {
+*     found = true
+*     stop()
+*   }
+* })
+* ```
+*
+* @see https://utils.feathersjs.com/utils/walk-query.html
+*/
+const walkQuery = (query, walker) => {
+	return _walkQueryUtil(query, walker, { stopped: false });
+};
+//#endregion
+//#region src/utils/query-has-property/query-has-property.util.ts
+/**
+* Checks whether a Feathers query contains one or more properties — including
+* properties nested inside `$and`/`$or`/`$nor` arrays. Returns `true` as soon as
+* any of the given property names is found. The query is not mutated.
+*
+* @example
+* ```ts
+* import { queryHasProperty } from 'feathers-utils/utils'
+*
+* queryHasProperty({ isTemplate: true }, 'isTemplate') // true
+* queryHasProperty({ $or: [{ isTemplate: true }] }, 'isTemplate') // true
+* queryHasProperty({ age: { $gt: 18 } }, ['isTemplate', 'status']) // false
+* ```
+*
+* @see https://utils.feathersjs.com/utils/query-has-property.html
+*/
+const queryHasProperty = (query, property) => {
+	const properties = new Set(toArray(property));
+	let found = false;
+	walkQuery(query, ({ property: key, stop }) => {
+		if (properties.has(key)) {
+			found = true;
+			stop();
+		}
+	});
+	return found;
+};
+//#endregion
+//#region src/utils/query-defaults/query-defaults.util.ts
+/**
+* Adds default properties to a Feathers query — but only for fields the query does
+* not already constrain. Presence is checked with {@link queryHasProperty}, so a field
+* referenced anywhere (including nested in `$and`/`$or`/`$nor`) is left untouched and
+* the caller keeps control over it. The query is treated as the `data` equivalent of
+* the `defaults` transformer. Each default is applied independently (per-field).
+*
+* @example
+* ```ts
+* import { queryDefaults } from 'feathers-utils/utils'
+*
+* queryDefaults({ status: 'active' }, { isTemplate: false })
+* // => { status: 'active', isTemplate: false }
+*
+* queryDefaults({ $or: [{ isTemplate: true }] }, { isTemplate: false })
+* // => { $or: [{ isTemplate: true }] } (untouched — already referenced)
+* ```
+*
+* @see https://utils.feathersjs.com/utils/query-defaults.html
+*/
+const queryDefaults = (query, defaults) => {
+	const source = query ?? {};
+	const toAdd = {};
+	for (const key in defaults) if (!queryHasProperty(source, key)) toAdd[key] = defaults[key];
+	return addToQuery(source, toAdd);
+};
+//#endregion
 //#region src/utils/skip-result/skip-result.util.ts
 /**
 * Sets `context.result` to an appropriate empty value based on the hook method.
@@ -533,100 +888,6 @@ function waitForServiceEvent(app, defaultOptions) {
 	};
 }
 //#endregion
-//#region src/utils/walk-query/walk-query.util.ts
-const _walkQueryUtil = (query, walker, options) => {
-	let cloned = false;
-	const clonedSecond = {};
-	function set(key, value, secondKey) {
-		if (!cloned) {
-			query = { ...query };
-			cloned = true;
-		}
-		if (secondKey !== void 0) {
-			if (!clonedSecond[key]) {
-				query[key] = { ...query[key] };
-				clonedSecond[key] = true;
-			}
-			query[key][secondKey] = value;
-			return;
-		}
-		query[key] = value;
-	}
-	for (const key in query) if ((key === "$or" || key === "$and" || key === "$nor") && Array.isArray(query[key])) {
-		let array = query[key];
-		let copiedArray = false;
-		for (let i = 0, n = array.length; i < n; i++) {
-			const nestedQuery = array[i];
-			const transformed = _walkQueryUtil(nestedQuery, walker, {
-				...options,
-				path: [
-					...options?.path || [],
-					key,
-					i
-				]
-			});
-			if (transformed !== nestedQuery) {
-				if (!copiedArray) {
-					array = [...array];
-					copiedArray = true;
-				}
-				array[i] = transformed;
-			}
-		}
-		if (copiedArray) set(key, array);
-	} else if (typeof query[key] === "object" && query[key] !== null && !Array.isArray(query[key])) {
-		let hasOperator = false;
-		for (const operator in query[key]) if (operator.startsWith("$")) {
-			hasOperator = true;
-			const value = walker({
-				operator,
-				path: [...options?.path ?? [], key],
-				property: key,
-				value: query[key][operator]
-			});
-			if (value !== void 0 && value !== query[key][operator]) set(key, value, operator);
-		}
-		if (!hasOperator) {
-			const value = walker({
-				operator: void 0,
-				path: [...options?.path ?? [], key],
-				property: key,
-				value: query[key]
-			});
-			if (value !== void 0 && value !== query[key]) set(key, value);
-		}
-	} else {
-		const value = walker({
-			operator: void 0,
-			path: [...options?.path ?? [], key],
-			property: key,
-			value: query[key]
-		});
-		if (value !== void 0 && value !== query[key]) set(key, value);
-	}
-	return query;
-};
-/**
-* Walks every property of a Feathers query (including nested `$and`/`$or`/`$nor` arrays)
-* and calls the `walker` function for each one. The walker receives the property name, operator,
-* value, and path, and can return a replacement value. Returns a new query only if changes were made.
-*
-* @example
-* ```ts
-* import { walkQuery } from 'feathers-utils/utils'
-*
-* const query = walkQuery({ age: { $gt: '18' } }, ({ value, operator }) => {
-*   if (operator === '$gt') return Number(value)
-* })
-* // => { age: { $gt: 18 } }
-* ```
-*
-* @see https://utils.feathersjs.com/utils/walk-query.html
-*/
-const walkQuery = (query, walker) => {
-	return _walkQueryUtil(query, walker);
-};
-//#endregion
 //#region src/utils/zip-data-result/zip-data-result.util.ts
 /**
 * Pairs each item in `context.data` with its corresponding item in `context.result` by index.
@@ -665,6 +926,6 @@ function zipDataResult(context, options) {
 	return result;
 }
 //#endregion
-export { toPaginated as a, iterateFind as c, contextToJson as d, checkContext as f, sortQueryProperties as g, addSkip as h, transformParams as i, getExposedMethods as l, chunkFind as m, walkQuery as n, skipResult as o, addToQuery as p, waitForServiceEvent as r, patchBatch as s, zipDataResult as t, defineHooks as u };
+export { addToQuery as _, skipResult as a, walkQuery as c, iterateFind as d, getExposedMethods as f, checkContext as g, chunkFind as h, toPaginated as i, patchBatch as l, contextToJson as m, waitForServiceEvent as n, queryDefaults as o, defineHooks as p, transformParams as r, queryHasProperty as s, zipDataResult as t, mergeQuery as u, addSkip as v, sortQueryProperties as y };
 
-//# sourceMappingURL=utils-Br6DNQ1B.mjs.map
+//# sourceMappingURL=utils-DByCpAsf.mjs.map