feathersjs · fratzinger · Feb 16, 2026 · Feb 16, 2026
diff --git a/docs/.vitepress/plugins/utility.ts b/docs/.vitepress/plugins/utility.ts
@@ -72,9 +72,15 @@ ${utility.examples.join('\n\n')}
 
   if (utility.dts) {
     code.push(`## Type declaration
+<details>
+<summary class="opacity-50 italic cursor-pointer select-none">Show Type Declarations</summary>
+
 \`\`\`ts
 ${utility.dts}
-\`\`\` `)
+\`\`\`
+
+</details>
+`)
   }
 
   if (utility.args?.length) {

diff --git a/src/common/clone.ts b/src/common/clone.ts
@@ -1,3 +1,13 @@
+/**
+ * Deep-clones an object using `JSON.parse(JSON.stringify(...))`.
+ * Simple and fast for JSON-serializable data, but does not handle
+ * `Date` objects, `undefined` values, functions, or circular references.
+ *
+ * @example
+ * ```ts
+ * const copy = clone({ name: 'Alice', nested: { value: 1 } })
+ * ```
+ */
 export function clone(obj: any) {
   return JSON.parse(JSON.stringify(obj))
 }
diff --git a/src/common/index.ts b/src/common/index.ts
@@ -1,3 +1,14 @@
+/**
+ * Type guard that checks if a value is a `Promise` instance.
+ *
+ * @example
+ * ```ts
+ * const result = maybeSyncFn()
+ * if (isPromise(result)) {
+ *   await result
+ * }
+ * ```
+ */
 export function isPromise(p: any): p is Promise<any> {
   return p instanceof Promise
 }

diff --git a/src/common/traverse.ts b/src/common/traverse.ts
@@ -1,5 +1,14 @@
 import _traverse from 'neotraverse'
 
+/**
+ * Recursively traverses items (or an array of items) and applies a converter function
+ * to every node using `neotraverse`. Modifications happen in place.
+ *
+ * @example
+ * ```ts
+ * traverse(items, function () { if (this.key === 'secret') this.remove() })
+ * ```
+ */
 export function traverse<T extends Record<string, any>>(
   items: T | T[],
   converter: (item: T) => void,

diff --git a/src/hooks/cache/cache.hook.ts b/src/hooks/cache/cache.hook.ts
@@ -32,7 +32,22 @@ export type CacheOptions = {
 }
 
 /**
- * A hook to cache `get` and `find` method results based on `params`.
+ * Caches `get` and `find` results based on `params`. On mutating methods (`create`, `update`,
+ * `patch`, `remove`), affected cache entries are automatically invalidated.
+ * Works as a `before`, `after`, or `around` hook.
+ *
+ * @example
+ * ```ts
+ * import { cache } from 'feathers-utils/hooks'
+ *
+ * const myCache = new Map()
+ *
+ * app.service('users').hooks({
+ *   around: {
+ *     all: [cache({ map: myCache, transformParams: (params) => ({ query: params.query }) })]
+ *   }
+ * })
+ * ```
  *
  * @see https://utils.feathersjs.com/hooks/cache.html
  */

diff --git a/src/hooks/check-multi/check-multi.hook.ts b/src/hooks/check-multi/check-multi.hook.ts
@@ -13,7 +13,18 @@ export type CheckMultiOptions = {
 }
 
 /**
- * Check if the 'multi' option is set for a method. You can use this to early throw an error if 'multi' is not set.
+ * Checks if the `multi` option is enabled for the current method and throws a
+ * `MethodNotAllowed` error if multi operations are not permitted.
+ * Useful to guard against accidental bulk `create`, `patch`, or `remove` calls.
+ *
+ * @example
+ * ```ts
+ * import { checkMulti } from 'feathers-utils/hooks'
+ *
+ * app.service('users').hooks({
+ *   before: { create: [checkMulti()] }
+ * })
+ * ```
  *
  * @see https://utils.feathersjs.com/hooks/check-multi.html
  */

diff --git a/src/hooks/check-required/check-required.hook.ts b/src/hooks/check-required/check-required.hook.ts
@@ -8,7 +8,18 @@ import type { MaybeArray } from '../../internal.utils.js'
 import { toArray } from '../../internal.utils.js'
 
 /**
- * Check selected fields exist and are not falsey. Numeric 0 is acceptable.
+ * Validates that the specified fields exist on `context.data` and are not falsy.
+ * Numeric `0` and boolean `false` are treated as valid values.
+ * Throws a `BadRequest` error if any required field is missing or null.
+ *
+ * @example
+ * ```ts
+ * import { checkRequired } from 'feathers-utils/hooks'
+ *
+ * app.service('users').hooks({
+ *   before: { create: [checkRequired(['email', 'password'])] }
+ * })
+ * ```
  *
  * @see https://utils.feathersjs.com/hooks/check-required.html
  */

diff --git a/src/hooks/create-related/create-related.hook.ts b/src/hooks/create-related/create-related.hook.ts
@@ -20,7 +20,20 @@ export interface CreateRelatedOptions<S = Record<string, any>> {
 }
 
 /**
- * Create related records in other services.
+ * Creates related records in other services after a successful `create` call.
+ * For each result item, a `data` function produces the record to create in the target service.
+ * Supports creating records one-by-one or in a single multi-create when `multi: true`.
+ *
+ * @example
+ * ```ts
+ * import { createRelated } from 'feathers-utils/hooks'
+ *
+ * app.service('users').hooks({
+ *   after: {
+ *     create: [createRelated({ service: 'profiles', data: (user) => ({ userId: user.id }) })]
+ *   }
+ * })
+ * ```
  *
  * @see https://utils.feathersjs.com/hooks/create-related.html
  */

diff --git a/src/hooks/debug/debug.hook.ts b/src/hooks/debug/debug.hook.ts
@@ -1,7 +1,18 @@
 import type { HookContext, NextFunction } from '@feathersjs/feathers'
 
 /**
- * Display the current hook context for debugging.
+ * Logs the current hook context to the console for debugging purposes.
+ * Displays timestamp, service path, method, type, id, data, query, result, and
+ * any additional param fields you specify.
+ *
+ * @example
+ * ```ts
+ * import { debug } from 'feathers-utils/hooks'
+ *
+ * app.service('users').hooks({
+ *   before: { find: [debug('before find', 'user')] }
+ * })
+ * ```
  *
  * @see https://utils.feathersjs.com/hooks/debug.html
  */

diff --git a/src/hooks/disable-pagination/disable-pagination.hook.ts b/src/hooks/disable-pagination/disable-pagination.hook.ts
@@ -3,6 +3,18 @@ import { checkContext } from '../../utils/index.js'
 
 /**
  * Disables pagination when `query.$limit` is `-1` or `'-1'`.
+ * Removes the `$limit` from the query and sets `params.paginate = false`.
+ * Must be used as a `before` or `around` hook on the `find` method.
+ *
+ * @example
+ * ```ts
+ * import { disablePagination } from 'feathers-utils/hooks'
+ *
+ * app.service('users').hooks({
+ *   before: { find: [disablePagination()] }
+ * })
+ * // Then call: app.service('users').find({ query: { $limit: -1 } })
+ * ```
  *
  * @see https://utils.feathersjs.com/hooks/disable-pagination.html
  */

diff --git a/src/hooks/disallow/disallow.hook.ts b/src/hooks/disallow/disallow.hook.ts
@@ -7,6 +7,20 @@ import { toArray } from '../../internal.utils.js'
 
 /**
  * Prevents access to a service method completely or for specific transports.
+ * When called without arguments, the method is blocked for all callers.
+ * When called with transport names, only those transports are blocked.
+ *
+ * @example
+ * ```ts
+ * import { disallow } from 'feathers-utils/hooks'
+ *
+ * app.service('users').hooks({
+ *   before: {
+ *     remove: [disallow('external')], // block external access
+ *     update: [disallow()],           // block completely
+ *   }
+ * })
+ * ```
  *
  * @see https://utils.feathersjs.com/hooks/disallow.html
  */

diff --git a/src/hooks/iff-else/iff-else.hook.ts b/src/hooks/iff-else/iff-else.hook.ts
@@ -4,7 +4,20 @@ import { combine } from '../../utils/combine/combine.util.js'
 import type { HookFunction, PredicateFn } from '../../types.js'
 
 /**
- * Execute one array of hooks or another based on a sync or async predicate.
+ * Executes one array of hooks when the predicate is truthy, or another array when it is falsy.
+ * The predicate can be a boolean or a sync/async function.
+ * Unlike `iff`, both branches are provided upfront without chaining.
+ *
+ * @example
+ * ```ts
+ * import { iffElse, isProvider } from 'feathers-utils/predicates'
+ *
+ * app.service('users').hooks({
+ *   before: {
+ *     find: [iffElse(isProvider('external'), [hook1()], [hook2()])]
+ *   }
+ * })
+ * ```
  *
  * @see https://utils.feathersjs.com/hooks/iff-else.html
  */

diff --git a/src/hooks/params-for-server/params-for-server.hook.ts b/src/hooks/params-for-server/params-for-server.hook.ts
@@ -11,10 +11,19 @@ export type ParamsForServerOptions = {
 }
 
 /**
- * a hook to move params to query._$client
- * the server only receives 'query' from params. All other params are ignored.
- * So, to use `$populateParams` on the server, we need to move the params to query._$client
- * the server will move them back to params
+ * Client-side hook that moves whitelisted `params` properties into `query._$client`
+ * so they survive the client-to-server transport. The server only receives `query`
+ * from params — use `paramsFromClient` on the server to restore them.
+ *
+ * @example
+ * ```ts
+ * import { paramsForServer } from 'feathers-utils/hooks'
+ *
+ * // Client-side
+ * app.service('users').hooks({
+ *   before: { all: [paramsForServer('populateParams')] }
+ * })
+ * ```
  *
  * @see https://utils.feathersjs.com/hooks/params-for-server.html
  */

diff --git a/src/hooks/params-from-client/params-from-client.hook.ts b/src/hooks/params-from-client/params-from-client.hook.ts
@@ -11,7 +11,19 @@ export type paramsFromClientOptions = {
 }
 
 /**
- * Pass `context.params` from client to server. Server hook.
+ * Server-side hook that extracts whitelisted properties from `query._$client` back
+ * into `context.params`. This is the counterpart to `paramsForServer`, which encodes
+ * params on the client side for transport.
+ *
+ * @example
+ * ```ts
+ * import { paramsFromClient } from 'feathers-utils/hooks'
+ *
+ * // Server-side
+ * app.service('users').hooks({
+ *   before: { all: [paramsFromClient('populateParams')] }
+ * })
+ * ```
  *
  * @see https://utils.feathersjs.com/hooks/params-from-client.html
  */

diff --git a/src/hooks/prevent-changes/prevent-changes.hook.ts b/src/hooks/prevent-changes/prevent-changes.hook.ts
@@ -16,7 +16,18 @@ export type PreventChangesOptions = {
 }
 
 /**
- * Prevent patch service calls from changing certain fields.
+ * Prevents `patch` calls from modifying certain fields. By default, the protected
+ * fields are silently removed from `context.data`. When `error` is set, a `BadRequest`
+ * is thrown if any protected field is present.
+ *
+ * @example
+ * ```ts
+ * import { preventChanges } from 'feathers-utils/hooks'
+ *
+ * app.service('users').hooks({
+ *   before: { patch: [preventChanges(['email', 'role'], { error: true })] }
+ * })
+ * ```
  *
  * @see https://utils.feathersjs.com/hooks/prevent-changes.html
  */

diff --git a/src/hooks/set-data/set-data.hook.ts b/src/hooks/set-data/set-data.hook.ts
@@ -30,7 +30,18 @@ export interface HookSetDataOptions {
 }
 
 /**
- * hook to set properties on `context.data`
+ * Sets a property on each item in `context.data` from another property on the hook context.
+ * Supports dot-notation paths for both source and target. Throws a `Forbidden` error
+ * if the source field is missing (unless `allowUndefined` is `true`).
+ *
+ * @example
+ * ```ts
+ * import { setData } from 'feathers-utils/hooks'
+ *
+ * app.service('posts').hooks({
+ *   before: { create: [setData('params.user.id', 'userId')] }
+ * })
+ * ```
  *
  * @see https://utils.feathersjs.com/hooks/set-data.html
  */

diff --git a/src/hooks/set-field/set-field.hook.ts b/src/hooks/set-field/set-field.hook.ts
@@ -27,7 +27,18 @@ export interface SetFieldOptions {
 }
 
 /**
- * The `setField` hook allows to set a field on the hook context based on the value of another field on the hook context.
+ * Sets a field on the hook context (e.g. `params.query`) based on the value of another
+ * context field (e.g. `params.user.id`). Useful for scoping queries to the authenticated user.
+ * Throws a `Forbidden` error if the source field is missing (unless `allowUndefined` is `true`).
+ *
+ * @example
+ * ```ts
+ * import { setField } from 'feathers-utils/hooks'
+ *
+ * app.service('posts').hooks({
+ *   before: { all: [setField({ from: 'params.user.id', as: 'params.query.userId' })] }
+ * })
+ * ```
  *
  * @see https://utils.feathersjs.com/hooks/set-field.html
  */

diff --git a/src/hooks/set-result/set-result.hook.ts b/src/hooks/set-result/set-result.hook.ts
@@ -31,7 +31,18 @@ export interface SetResultOptions {
 }
 
 /**
- * hook to set properties on `context.result`
+ * Sets a property on each item in `context.result` from another property on the hook context.
+ * Supports dot-notation paths for both source and target, and can optionally
+ * operate on `context.dispatch` as well.
+ *
+ * @example
+ * ```ts
+ * import { setResult } from 'feathers-utils/hooks'
+ *
+ * app.service('posts').hooks({
+ *   after: { all: [setResult('params.user.id', 'currentUserId')] }
+ * })
+ * ```
  *
  * @see https://utils.feathersjs.com/hooks/set-result.html
  */

diff --git a/src/hooks/set-slug/set-slug.hook.ts b/src/hooks/set-slug/set-slug.hook.ts
@@ -2,7 +2,18 @@ import _set from 'lodash/set.js'
 import type { HookContext, NextFunction } from '@feathersjs/feathers'
 
 /**
- * Fix slugs in URL, e.g. /stores/:storeId.
+ * Extracts URL route parameters (slugs) and sets them on `params.query`.
+ * For example, given a route `/stores/:storeId`, this hook copies the resolved
+ * `storeId` value from `params.route` into the query. Only applies to the `rest` provider.
+ *
+ * @example
+ * ```ts
+ * import { setSlug } from 'feathers-utils/hooks'
+ *
+ * app.service('stores/:storeId/products').hooks({
+ *   before: { all: [setSlug('storeId')] }
+ * })
+ * ```
  *
  * @see https://utils.feathersjs.com/hooks/set-slug.html
  */

diff --git a/src/hooks/skippable/skippable.hook.ts b/src/hooks/skippable/skippable.hook.ts
@@ -2,7 +2,16 @@ import type { HookContext, NextFunction } from '@feathersjs/feathers'
 import type { HookFunction, PredicateFn } from '../../types.js'
 
 /**
- * Wrap a hook to make it skippable
+ * Wraps a hook so it can be conditionally skipped based on a predicate.
+ * When the predicate returns `true`, the wrapped hook is skipped entirely.
+ * Commonly used with `shouldSkip` and `addSkip` for runtime hook control.
+ *
+ * @example
+ * ```ts
+ * import { skippable, shouldSkip } from 'feathers-utils/predicates'
+ *
+ * const myHook = skippable(someHook(), shouldSkip('someHook'))
+ * ```
  *
  * @see https://utils.feathersjs.com/hooks/skippable.html
  */