"@parcel/watcher": true

esbuild: true

unrs-resolver: true

minimumReleaseAgeExclude:

- '@feathers-community/eslint-config@0.2.0'

title: cache

category: hooks

hook:

type: ['before', 'after']

method: ['find', 'get', 'create', 'update', 'patch', 'remove']

multi: true

| Option | Type | Description |

| ----------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

| `map` | `Cache` | The cache implementation. Must implement `get`, `set`, `delete`, `clear`, and `keys`. |

| `id` | `string` | The id field to use. Defaults to `service.options.id`, then `'id'`. |

| `transformParams` | `(params) => params` | Transform params before they are used as cache key. Compose it with [`passParams`](/utils/pass-params) to declaratively pick/drop keys and avoid false hits — see [Choosing Cache-Relevant Params](#choosing-cache-relevant-params-with-passparams). |

// For production use, consider maintaining a local Set of active keys.

throw new Error(

'Synchronous keys iteration is not supported with Redis. ' +

'Use clear() for full invalidation instead.',

)

},

}

})

Deciding which `params` keys form the cache key is the trickiest part of caching, and the two failure modes are asymmetric:

- **False hits (dangerous):** if a key that affects the result is left out (e.g. `user`/tenant, `provider`), two semantically different requests collapse to the same key — one user can be served another user's cached data.

- **False misses (wasteful):** if a per-request/metrics key is included (e.g. `rateLimit`), every request produces a unique key and the cache never hits. A function-valued key (e.g. `stashed` from `stashable`) would even make serialization throw.

The [`passParams`](/utils/pass-params) utility makes this explicit and safe. It takes a declarative path schema (`true` include, `false` drop, or a predicate/projection function). `query` is always included by default, and keys you never classified are **kept by default** — the safe direction, since a forgotten key causes at worst a harmless cache miss, never a false hit.

Cache on everything except the keys you explicitly drop with `false`. This is the default direction — safe against false hits:

import { passParams } from 'feathers-utils/utils'

cache({

map: new Map(),

transformParams: (params) =>

passParams(params, { rateLimit: false, skipHooks: false }),

})

Set `dropUnknownParams: true` so only `query` (always) and the listed paths form the cache key. `user.id` is picked via dot-notation so different tenants never collide and per-request `user` fields don't bloat the key. Use `onUnknownParams` to log anything that was dropped:

import { passParams } from 'feathers-utils/utils'

cache({

map: new Map(),

transformParams: (params) =>

passParams(

params,

{ 'user.id': true }, // `query` is included automatically

{

dropUnknownParams: true,

onUnknownParams: (keys) =>

keys.forEach((key) => logger.warn('undeclared cache param', key)),

},

),

})

import { MemoryService } from '@feathersjs/memory'

import { expect, expectTypeOf } from 'vitest'

import { copy } from 'fast-copy'

import { passParams } from '../../utils/pass-params/pass-params.util.js'

const setup = (options: CacheOptions, serviceOptions?: { id?: string }) => {

const app = feathers<{

expect(getSpy).toHaveBeenCalledTimes(2)

})

describe('cache hook with passParams', () => {

it('prevents false hits across users and collapses non-id user fields (whitelist)', async () => {

const { usersService, before } = setup({

map: new Map(),

// `query` is included by default; only `user.id` is added explicitly.

transformParams: (params) => passParams(params, { 'user.id': true }),

})

await usersService.create({ id: 1, name: 'John' })

// user a -> miss

await usersService.find({

query: {},

user: { id: 'a', updatedAt: 1 },

} as any)

expect(before.find).toHaveBeenCalledTimes(1)

// same user id, different transient timestamp -> hit (projection collapses it)

await usersService.find({

query: {},

user: { id: 'a', updatedAt: 999 },

} as any)

expect(before.find).toHaveBeenCalledTimes(1)

// different user id -> miss (no cross-user leak)

await usersService.find({

query: {},

user: { id: 'b', updatedAt: 1 },

} as any)

expect(before.find).toHaveBeenCalledTimes(2)

})

it('strips transient metric keys so the cache still hits (blacklist)', async () => {

const { usersService, before } = setup({

map: new Map(),

// keep everything except the transient `rateLimit` metric.

transformParams: (params) => passParams(params, { rateLimit: false }),

})

await usersService.create({ id: 1, name: 'John' })

await usersService.find({

query: { name: 'John' },

rateLimit: { remainingPoints: 9 },

} as any)

expect(before.find).toHaveBeenCalledTimes(1)

// identical query, different rate-limit metrics -> still a cache hit

await usersService.find({

query: { name: 'John' },

rateLimit: { remainingPoints: 8 },

} as any)

expect(before.find).toHaveBeenCalledTimes(1)

})

it('drops function-valued params under a whitelist so serialization never throws', async () => {

const { usersService, before } = setup({

map: new Map(),

// keep only `query` (default); `stashed` (a function) is dropped.

transformParams: (params) =>

passParams(params, {}, { dropUnknownParams: true }),

})

await usersService.create({ id: 1, name: 'John' })

// `stashed` is a function; if it reached stableStringify it would throw.

await expect(

usersService.find({

query: { name: 'John' },

stashed: () => Promise.resolve(),

} as any),

).resolves.toBeDefined()

expect(before.find).toHaveBeenCalledTimes(1)

await usersService.find({

query: { name: 'John' },

stashed: () => Promise.resolve('other'),

} as any)

expect(before.find).toHaveBeenCalledTimes(1) // cache hit

})

it('reports undeclared params keys via onUnknownParams', async () => {

const onUnknownParams = vi.fn()

const { usersService } = setup({

map: new Map(),

transformParams: (params) =>

passParams(params, { query: true }, { onUnknownParams }),

})

await usersService.create({ id: 1, name: 'John' })

await usersService.find({ query: {}, mystery: 1 } as any)

expect(onUnknownParams).toHaveBeenCalledWith(['mystery'], expect.anything())

})

export * from './merge-query/merge-query.util.js'

export * from './mutate-data/mutate-data.util.js'

export * from './mutate-result/mutate-result.util.js'

export * from './pass-params/pass-params.util.js'

export * from './patch-batch/patch-batch.util.js'

export * from './query-defaults/query-defaults.util.js'

export * from './query-has-property/query-has-property.util.js'

title: passParams

category: utils

see:

- hooks/cache

- utils/transform-params

import type { Params } from '@feathersjs/feathers'

import { expectTypeOf } from 'vitest'

import { passParams } from './pass-params.util.js'

it('returns a Params object', () => {

const out = passParams({ query: {} }, { query: true })

expectTypeOf(out).toEqualTypeOf<Params>()

it('accepts boolean and function rules, including nested paths and custom keys', () => {

passParams({ query: {}, user: { id: 1 }, custom: 1 } as Params, {

query: true,

paginate: false,

'user.id': true,

user: (value, params) => {

expectTypeOf(value).toBeAny()

expectTypeOf(params).toEqualTypeOf<Params>()

return value?.id

},

custom: true,

})

it('types onUnknownParams and dropUnknownParams', () => {

passParams(

{ query: {} } as Params,

{ query: true },

{

dropUnknownParams: true,

onUnknownParams: (keys, params) => {

expectTypeOf(keys).toEqualTypeOf<string[]>()

expectTypeOf(params).toEqualTypeOf<Params>()

},

},

)