addToQuery
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. When the added query is itself a pure $and ({ $and: [...] }), its branches are flattened into the target's $and rather than nested.
The added query narrows the target — every condition is kept, so the result matches at most what the target matched. Two conditions on the same property are therefore intersected, never unioned: adding { role: 'b' } to { role: 'a' } matches nothing, it does not become { role: { $in: ['a', 'b'] } }. Use mergeQuery with its default combine mode when you want to broaden a query instead.
The query filters $select, $limit, $skip and $sort are split off and merged separately, never wrapped in an $and where no adapter would evaluate them. Since addToQuery narrows, they follow the same rules as mergeQuery in intersect mode: the added query wins for $limit and $skip, $sort is merged key by key (the added query wins per key, the target keeps the leading sort order), and $select becomes the intersection of both. A filter only one side provides is kept as it is.
import { addToQuery } from 'feathers-utils/utils';Examples
Example 1
import { addToQuery } from 'feathers-utils/utils'
const query = { status: 'active' }
addToQuery(query, { role: 'admin' })
// => { status: 'active', role: 'admin' }
// both conditions are kept (an intersection), even a contradicting one
addToQuery({ something: 1 }, { something: { $in: [2] } })
// => { something: 1, $and: [{ something: { $in: [2] } }] }Example 2
// filters never end up in the $and — the added query wins
addToQuery({ $limit: 10 }, { $limit: 20 })
// => { $limit: 20 }
addToQuery({ $sort: { a: 1 } }, { $sort: { b: -1 } })
// => { $sort: { a: 1, b: -1 } }
// $select narrows to what both sides allow
addToQuery({ $select: ['a', 'b'] }, { $select: ['b'] })
// => { $select: ['b'] }Type declaration
Show Type Declarations
/**
* 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. When the added
* query is itself a pure `$and` (`{ $and: [...] }`), its branches are flattened into the
* target's `$and` rather than nested.
*
* The added query narrows the target — every condition is kept, so the result matches
* at most what the target matched. Two conditions on the same property are therefore
* intersected, never unioned: adding `{ role: 'b' }` to `{ role: 'a' }` matches nothing,
* it does not become `{ role: { $in: ['a', 'b'] } }`. Use {@link mergeQuery} with its
* default `combine` mode when you want to broaden a query instead.
*
* The query filters `$select`, `$limit`, `$skip` and `$sort` are split off and merged
* separately, never wrapped in an `$and` where no adapter would evaluate them. Since
* `addToQuery` narrows, they follow the same rules as {@link mergeQuery} in `intersect`
* mode: the added query wins for `$limit` and `$skip`, `$sort` is merged key by key
* (the added query wins per key, the target keeps the leading sort order), and
* `$select` becomes the intersection of both. A filter only one side provides is kept
* as it is.
*
* @example
* ```ts
*
*
* const query = { status: 'active' }
* addToQuery(query, { role: 'admin' })
* // => { status: 'active', role: 'admin' }
*
* // both conditions are kept (an intersection), even a contradicting one
* addToQuery({ something: 1 }, { something: { $in: [2] } })
* // => { something: 1, $and: [{ something: { $in: [2] } }] }
* ```
*
* @example
* ```ts
* // filters never end up in the $and — the added query wins
* addToQuery({ $limit: 10 }, { $limit: 20 })
* // => { $limit: 20 }
*
* addToQuery({ $sort: { a: 1 } }, { $sort: { b: -1 } })
* // => { $sort: { a: 1, b: -1 } }
*
* // $select narrows to what both sides allow
* addToQuery({ $select: ['a', 'b'] }, { $select: ['b'] })
* // => { $select: ['b'] }
* ```
*
* @see https://utils.feathersjs.com/utils/add-to-query.html
*/
export declare function addToQuery<Q extends Query>(targetQuery: Q, query: Q): Q| Argument | Type | Description |
|---|---|---|
| targetQuery | Q | |
| query | Q |