gateParams
Selects and/or projects params keys according to a declarative path schema, returning a NEW object. General-purpose — no cache knowledge. Typically composed into the cache hook's transformParams option as (p) => gateParams(p, schema, opts).
Paths are resolved with getPath/hasPath and written with setPath, so nested values can be picked declaratively ('user.id': true).
params is never mutated: kept values are copied over by reference into the fresh result (safe, since the result is only read/serialized). The one exception is combining a top-level rule with a nested path under the SAME parent in one schema (e.g. { query: true, 'query.x': ... }) — the nested set would then write into the shared parent. Pick one granularity per parent to avoid it.
query is included as-is by DEFAULT (it is always relevant), unless the schema addresses it explicitly — either as query or a nested query.* path.
Keys not mentioned in the schema are KEPT by default, so forgetting a relevant key can only cause a harmless cache miss, never a false hit. Pass dropUnknownParams: true to keep only query and the schema paths.
import { gateParams } from 'feathers-utils/utils';Examples
Example 1
exclude specific params (default): everything except the listed noise
gateParams(params, { rateLimit: false })Example 2
include only specific params
gateParams(params, { 'user.id': true }, { dropUnknownParams: true })Options
Type declaration
Show Type Declarations
/**
* A rule for a single schema path.
* - `true` → include the value as-is
* - `false` → drop the path
* - function → unified predicate/projection (see {@link GateParamsFn})
*/
export type GateParamsRule<P extends Params = Params> =
boolean | GateParamsFn<P>
/**
* The flexible slot — serves as BOTH predicate and projection:
* - returns `true` → include the value as-is
* - returns `false` | `undefined` → drop the path
* - returns any other value `r` → include `r` (projection)
*
* @example predicate: `(value) => value != null`
* @example projection: `(user) => user?.id`
*/
export type GateParamsFn<P extends Params = Params> = (
value: any,
params: P,
) => boolean | undefined | unknown
/**
* Declarative schema keyed by **paths** in dot-notation
* (e.g. `'query'`, `'user.id'`, `'authentication.payload.sub'`). Paths are read
* with `getPath`/`hasPath`; the result is built at the same path with `setPath`.
* Any custom path is allowed.
*/
export type GateParamsSchema<P extends Params = Params> = Record<
string,
GateParamsRule<P>
>
export type GateParamsOptions<P extends Params = Params> = {
/**
* Drop top-level `params` keys that the schema does not address (neither as a
* top-level key nor as the root of a nested path). When `false` (the default)
* those keys are kept, so only the ones you explicitly list with `false` are
* removed; when `true` only `query` and the schema paths remain.
*
* Keeping unknown keys (the default) is the safe direction for cache keys: a
* forgotten key causes at worst a harmless cache miss, never a false hit.
*
* @default false
*/
dropUnknownParams?: boolean
/**
* Optional observer, invoked once with the top-level `params` keys the schema
* did not address (skipped when there are none). The place to `logger.warn(...)`
* about keys you never classified so overlooked params become loud instead of
* silently mis-caching. Purely observational — it does not change what is kept.
*
* @example `(keys) => keys.forEach((k) => logger.warn('undeclared cache param', k))`
*/
onUnknownParams?: (keys: string[], params: P) => void
}
/**
* Selects and/or projects `params` keys according to a declarative path `schema`,
* returning a NEW object. General-purpose — no cache knowledge. Typically composed
* into the cache hook's `transformParams` option as `(p) => gateParams(p, schema, opts)`.
*
* Paths are resolved with `getPath`/`hasPath` and written with `setPath`, so nested
* values can be picked declaratively (`'user.id': true`).
*
* `params` is never mutated: kept values are copied over by reference into the
* fresh result (safe, since the result is only read/serialized). The one exception
* is combining a top-level rule with a nested path under the SAME parent in one
* schema (e.g. `{ query: true, 'query.x': ... }`) — the nested `set` would then
* write into the shared parent. Pick one granularity per parent to avoid it.
*
* `query` is included as-is by DEFAULT (it is always relevant), unless the schema
* addresses it explicitly — either as `query` or a nested `query.*` path.
*
* Keys not mentioned in the schema are KEPT by default, so forgetting a relevant
* key can only cause a harmless cache miss, never a false hit. Pass
* `dropUnknownParams: true` to keep only `query` and the schema paths.
*
* @example exclude specific params (default): everything except the listed noise
* ```ts
* gateParams(params, { rateLimit: false })
* ```
* @example include only specific params
* ```ts
* gateParams(params, { 'user.id': true }, { dropUnknownParams: true })
* ```
*
* @see https://utils.feathersjs.com/utils/gate-params.html
*/
export declare function gateParams<P extends Params = Params>(
params: P,
schema: GateParamsSchema<P>,
options?: GateParamsOptions<P>,
): Params| Argument | Type | Description |
|---|---|---|
| params | P | |
| schema | GateParamsSchema<P> | |
| options | GateParamsOptions<P> |