feathers-utils 10.0.0 → 10.0.2

package/src/hooks/disallow/disallow.hook.ts

@@ -28,8 +28,12 @@ export const disallow = <H extends HookContext = HookContext>(
   transports?: MaybeArray<TransportName>,
 ) => {
   const transportsArr = toArray(transports)
-  return (context: H, next?: NextFunction) => {
-    if (!transports) {
+  function hook(context: H): void
+  function hook(context: H, next: NextFunction): Promise<void>
+  function hook(context: H, next?: NextFunction): void | Promise<void> {
+    // No transports (undefined) or an empty list means "block completely".
+    // Fail closed for a guard hook rather than throwing a confusing internal error.
+    if (!transports || transportsArr.length === 0) {
       throw new MethodNotAllowed('Method not allowed')
     }
 
@@ -39,6 +43,9 @@ export const disallow = <H extends HookContext = HookContext>(
       )
     }
 
-    if (next) return next().then(() => context)
+    if (next) return next()
+
+    return
   }
+  return hook
 }

package/src/hooks/on-delete/on-delete.hook.ts

@@ -43,6 +43,12 @@ export interface OnDeleteOptions<
    * @default false
    */
   blocking?: boolean
+  /**
+   * Called when a non-blocking (`blocking: false`) related-service call rejects.
+   * Without this, fire-and-forget rejections are swallowed (but never leak as an
+   * unhandled rejection). In `blocking` mode the error is thrown to the caller instead.
+   */
+  onError?: (error: any, context: H) => void
 }
 
 /**
@@ -72,7 +78,7 @@ export const onDelete = <H extends HookContext = HookContext>(
 ) => {
   const optionsMulti = Array.isArray(options) ? options : [options]
 
-  return async (context: H, next?: NextFunction) => {
+  return async (context: H, next?: NextFunction): Promise<void> => {
     checkContext(context, {
       type: ['after', 'around'],
       method: 'remove',
@@ -89,46 +95,60 @@ export const onDelete = <H extends HookContext = HookContext>(
       return
     }
 
-    const promises: Promise<any>[] = []
-
-    optionsMulti.forEach(
-      async ({ keyHere, keyThere, onDelete, service, blocking, query }) => {
-        let ids = result.map((x) => x[keyHere]).filter((x) => !!x)
-        ids = [...new Set(ids)]
-
-        if (!ids || ids.length <= 0) {
-          return context
-        }
-
-        const params = {
-          query: {
-            ...query,
-            ...(ids.length === 1
-              ? { [keyThere]: ids[0] }
-              : { [keyThere]: { $in: ids } }),
-          },
-          paginate: false,
-        }
-
-        let promise: Promise<any> | undefined = undefined
-
-        if (onDelete === 'cascade') {
-          promise = context.app.service(service as string).remove(null, params)
-        } else if (onDelete === 'set null') {
-          const data = { [keyThere]: null }
-          promise = context.app
-            .service(service as string)
-            .patch(null, data, params)
-        }
-
-        if (promise && blocking) {
-          promises.push(promise)
-        }
-      },
-    )
-
-    if (promises.length) {
-      await Promise.all(promises)
+    const blockingPromises: Promise<any>[] = []
+
+    for (const {
+      keyHere,
+      keyThere,
+      onDelete,
+      service,
+      blocking,
+      query,
+      onError,
+    } of optionsMulti) {
+      let ids = result.map((x) => x[keyHere]).filter((x) => !!x)
+      ids = [...new Set(ids)]
+
+      if (!ids || ids.length <= 0) {
+        continue
+      }
+
+      const params = {
+        query: {
+          ...query,
+          ...(ids.length === 1
+            ? { [keyThere]: ids[0] }
+            : { [keyThere]: { $in: ids } }),
+        },
+        paginate: false,
+      }
+
+      let promise: Promise<any> | undefined = undefined
+
+      if (onDelete === 'cascade') {
+        promise = context.app.service(service as string).remove(null, params)
+      } else if (onDelete === 'set null') {
+        const data = { [keyThere]: null }
+        promise = context.app
+          .service(service as string)
+          .patch(null, data, params)
+      }
+
+      if (!promise) {
+        continue
+      }
+
+      if (blocking) {
+        blockingPromises.push(promise)
+      } else {
+        // fire-and-forget: always attach a catch so a rejection never becomes
+        // an unhandled promise rejection. Surface it via `onError` if provided.
+        promise.catch((error) => onError?.(error, context))
+      }
+    }
+
+    if (blockingPromises.length) {
+      await Promise.all(blockingPromises)
     }
 
     return

package/src/hooks/params-for-server/params-for-server.hook.ts

@@ -35,7 +35,15 @@ export const paramsForServer = (
 
   const { keyToHide = FROM_CLIENT_FOR_SERVER_DEFAULT_KEY } = options || {}
 
-  return <H extends HookContext>(context: H, next?: NextFunction) => {
+  function hook<H extends HookContext>(context: H): void
+  function hook<H extends HookContext>(
+    context: H,
+    next: NextFunction,
+  ): Promise<void>
+  function hook<H extends HookContext>(
+    context: H,
+    next?: NextFunction,
+  ): void | Promise<void> {
     // clone params on demand
     let clonedParams: any
 
@@ -56,6 +64,10 @@ export const paramsForServer = (
 
         if (!clonedParams.query[keyToHide]) {
           clonedParams.query[keyToHide] = {}
+        } else {
+          // The shallow query copy still aliases a pre-existing key object;
+          // clone it so we don't mutate the caller's original params.
+          clonedParams.query[keyToHide] = { ...clonedParams.query[keyToHide] }
         }
 
         clonedParams.query[keyToHide][key] = clonedParams[key]
@@ -67,10 +79,9 @@ export const paramsForServer = (
       context.params = clonedParams
     }
 
-    if (next) {
-      return next()
-    }
+    if (next) return next()
 
-    return context
+    return
   }
+  return hook
 }

package/src/hooks/params-from-client/params-from-client.hook.ts

@@ -33,13 +33,18 @@ export const paramsFromClient = (
 ) => {
   const whitelistArr = toArray(whitelist)
   const { keyToHide = FROM_CLIENT_FOR_SERVER_DEFAULT_KEY } = options || {}
-  return (context: HookContext, next?: NextFunction) => {
+  function hook(context: HookContext): void
+  function hook(context: HookContext, next: NextFunction): Promise<void>
+  function hook(
+    context: HookContext,
+    next?: NextFunction,
+  ): void | Promise<void> {
     if (
       !context.params?.query?.[keyToHide] ||
       typeof context.params.query[keyToHide] !== 'object'
     ) {
       if (next) return next()
-      return context
+      return
     }
 
     const params = {
@@ -67,10 +72,9 @@ export const paramsFromClient = (
 
     context.params = params
 
-    if (next) {
-      return next()
-    }
+    if (next) return next()
 
-    return context
+    return
   }
+  return hook
 }

package/src/hooks/rate-limit/rate-limit.hook.ts

@@ -37,7 +37,7 @@ export const rateLimit = <H extends HookContext = HookContext>(
   const key = options?.key ?? ((context: HookContext) => context.path)
   const points = options?.points ?? (() => 1)
 
-  return async (context: H, next?: NextFunction) => {
+  return async (context: H, next?: NextFunction): Promise<void> => {
     checkContext(context, { type: ['before', 'around'], label: 'rateLimit' })
 
     const resolvedKey = await key(context)
@@ -53,6 +53,6 @@ export const rateLimit = <H extends HookContext = HookContext>(
       })
     }
 
-    if (next) return await next()
+    if (next) await next()
   }
 }

package/src/hooks/set-data/set-data.hook.ts

@@ -68,7 +68,9 @@ export function setData<H extends HookContext = HookContext>(
 ) {
   const { allowUndefined = false, overwrite = true } = options ?? {}
 
-  return (context: H, next?: NextFunction) => {
+  function hook(context: H): void
+  function hook(context: H, next: NextFunction): Promise<void>
+  function hook(context: H, next?: NextFunction): void | Promise<void> {
     const { data } = getDataIsArray(context)
 
     const contextJson = contextToJson(context)
@@ -76,7 +78,7 @@ export function setData<H extends HookContext = HookContext>(
     if (!_has(contextJson, from)) {
       if (!context.params?.provider || allowUndefined === true) {
         if (next) return next()
-        return context
+        return
       }
 
       if (
@@ -84,7 +86,7 @@ export function setData<H extends HookContext = HookContext>(
         data.every((item: Record<string, unknown>) => _has(item, to))
       ) {
         if (next) return next()
-        return context
+        return
       }
 
       throw options?.error
@@ -107,10 +109,9 @@ export function setData<H extends HookContext = HookContext>(
       _set(item, to, val)
     }
 
-    if (next) {
-      return next()
-    }
+    if (next) return next()
 
-    return context
+    return
   }
+  return hook
 }

package/src/hooks/set-field/set-field.hook.ts

@@ -6,9 +6,23 @@ import type { FeathersError } from '@feathersjs/errors'
 import { Forbidden } from '@feathersjs/errors'
 import type { HookContext, NextFunction } from '@feathersjs/feathers'
 
-export interface SetFieldOptions {
-  as: string
-  from: string
+export interface SetFieldOptions<H extends HookContext = HookContext> {
+  /**
+   * The target path(s) to set. Pass an array to write the same value to several
+   * paths (e.g. multiple query keys).
+   *
+   * @example 'params.query.userId'
+   * @example ['params.query.userId', 'params.query.ownerId']
+   */
+  as: string | string[]
+  /**
+   * The source of the value: a `dot.notation` path on the context, or a function
+   * that derives the value from the context.
+   *
+   * @example 'params.user.id'
+   * @example (context) => context.params.user?.id
+   */
+  from: string | ((context: H) => unknown)
   /**
    * If set to `true`, allows the field to be undefined.
    * If the field is not available and this is `true`, the hook will not throw an error.
@@ -23,7 +37,10 @@ export interface SetFieldOptions {
    *
    * If not provided, throws a `Forbidden` error with a message indicating the missing field.
    */
-  error?: (context: HookContext, from: string) => FeathersError
+  error?: (
+    context: H,
+    from: string | ((context: H) => unknown),
+  ) => FeathersError
 }
 
 /**
@@ -42,34 +59,42 @@ export interface SetFieldOptions {
  *
  * @see https://utils.feathersjs.com/hooks/set-field.html
  */
-export const setField =
-  <H extends HookContext = HookContext>({
-    as,
-    from,
-    allowUndefined = false,
-    error,
-  }: SetFieldOptions) =>
-  (context: H, next?: NextFunction) => {
+export const setField = <H extends HookContext = HookContext>({
+  as,
+  from,
+  allowUndefined = false,
+  error,
+}: SetFieldOptions<H>) => {
+  const targets = Array.isArray(as) ? as : [as]
+
+  function hook(context: H): void
+  function hook(context: H, next: NextFunction): Promise<void>
+  function hook(context: H, next?: NextFunction): void | Promise<void> {
     const { params } = context
 
     checkContext(context, { type: ['before', 'around'], label: 'setField' })
 
-    const value = _get(context, from)
+    const value =
+      typeof from === 'function' ? from(context) : _get(context, from)
 
     if (value === undefined) {
       if (!params.provider || allowUndefined) {
         if (next) return next()
-        return context
+        return
       }
 
       throw error
         ? error(context, from)
-        : new Forbidden(`Expected field ${as} not available`)
+        : new Forbidden(`Expected field ${targets.join(', ')} not available`)
     }
 
-    context = _setWith(context, as, value, _clone)
+    for (const target of targets) {
+      _setWith(context, target, value, _clone)
+    }
 
     if (next) return next()
 
-    return context
+    return
   }
+  return hook
+}

package/src/hooks/set-result/set-result.hook.ts

@@ -1,6 +1,7 @@
 import _get from 'lodash/get.js'
 import _set from 'lodash/set.js'
 import _has from 'lodash/has.js'
+import { copy } from 'fast-copy'
 
 import type { FeathersError } from '@feathersjs/errors'
 import { Forbidden } from '@feathersjs/errors'
@@ -110,6 +111,12 @@ export function setResult<H extends HookContext = HookContext>(
   }
 
   const fn = (context: H) => {
+    // Seed context.dispatch from result so the dispatch branch mutates (and
+    // persists to) a real object instead of a throwaway copy. Mirrors mutateResult.
+    if (!!options?.dispatch && !context.dispatch) {
+      context.dispatch = copy(context.result)
+    }
+
     if (options?.dispatch === 'both') {
       forResultOrDispatch(context, true)
       return forResultOrDispatch(context, false)
@@ -118,11 +125,17 @@ export function setResult<H extends HookContext = HookContext>(
     return forResultOrDispatch(context, !!options?.dispatch)
   }
 
-  return (context: H, next?: NextFunction) => {
+  function hook(context: H): void
+  function hook(context: H, next: NextFunction): Promise<void>
+  function hook(context: H, next?: NextFunction): void | Promise<void> {
     if (next) {
-      return next().then(() => fn(context))
+      return next().then(() => {
+        fn(context)
+      })
     }
 
-    return fn(context)
+    fn(context)
+    return
   }
+  return hook
 }

package/src/hooks/set-slug/set-slug.hook.ts

@@ -21,20 +21,22 @@ export const setSlug = <H extends HookContext = HookContext>(
   slug: string,
   fieldName?: string,
 ) => {
-  if (typeof fieldName !== 'string') {
-    fieldName = `query.${slug}`
-  }
+  const targetField: string =
+    typeof fieldName === 'string' ? fieldName : `query.${slug}`
 
-  return (context: H, next?: NextFunction) => {
+  function hook(context: H): void
+  function hook(context: H, next: NextFunction): Promise<void>
+  function hook(context: H, next?: NextFunction): void | Promise<void> {
     if (context.params && context.params.provider === 'rest') {
       const value = context.params.route[slug]
       if (typeof value === 'string' && value[0] !== ':') {
-        _set(context.params, fieldName, value)
+        _set(context.params, targetField, value)
       }
     }
 
     if (next) return next()
 
-    return context
+    return
   }
+  return hook
 }

package/src/hooks/skippable/skippable.hook.ts

@@ -15,26 +15,31 @@ import type { HookFunction, PredicateFn } from '../../types.js'
  *
  * @see https://utils.feathersjs.com/hooks/skippable.html
  */
-export const skippable =
-  <H extends HookContext = HookContext>(
-    hook: HookFunction<H>,
-    predicate: PredicateFn<H>,
-  ) =>
-  (context: H, next?: NextFunction) => {
+export const skippable = <H extends HookContext = HookContext>(
+  innerHook: HookFunction<H>,
+  predicate: PredicateFn<H>,
+) => {
+  function hook(context: H): H | void | Promise<H | void>
+  function hook(context: H, next: NextFunction): Promise<void>
+  function hook(context: H, next?: NextFunction): H | void | Promise<H | void> {
     const skip = predicate(context)
 
-    function skipOrRun(skip: boolean) {
-      if (skip) {
+    const skipOrRun = (shouldSkip: boolean): H | void | Promise<H | void> => {
+      if (shouldSkip) {
         if (next) return next()
-        return context
-      } else {
-        return hook(context, next)
+        return
       }
+      if (next) return innerHook(context, next) as Promise<void>
+      // before/after mode: return the inner hook's result so an async hook is
+      // awaited and a returned/modified context is propagated to the pipeline.
+      return innerHook(context)
     }
 
     if (!skip || typeof skip === 'boolean') {
       return skipOrRun(skip)
     }
 
-    return skip.then(skipOrRun)
+    return skip.then(skipOrRun) as Promise<void>
   }
+  return hook
+}

package/src/hooks/soft-delete/soft-delete.hook.ts

@@ -65,13 +65,14 @@ export const softDelete = <H extends HookContext = HookContext>(
     )
   }
 
-  return async (context: H, next?: NextFunction) => {
+  return async (context: H, next?: NextFunction): Promise<void> => {
     checkContext(context, { type: ['before', 'around'], label: 'softDelete' })
 
     const { disableSoftDeleteKey = 'disableSoftDelete' } = options
 
     if (context.params[disableSoftDeleteKey]) {
-      return early(context, next)
+      await early(context, next)
+      return
     }
 
     const { deletedQuery, removeData } = options
@@ -105,10 +106,8 @@ export const softDelete = <H extends HookContext = HookContext>(
     }
 
     if (next) {
-      return await next()
+      await next()
     }
-
-    return context
   }
 }
 

package/src/hooks/stashable/stashable.hook.ts

@@ -44,17 +44,16 @@ const defaultStashFunc = (context: HookContext) => {
  */
 export function stashable<H extends HookContext = HookContext>(
   options?: StashableOptions,
-): {
-  (context: H, next: NextFunction): Promise<void>
-  (context: H): H
-} {
+) {
   const propName = options?.propName ?? 'stashed'
   const stashFunc = options?.stashFunc ?? defaultStashFunc
 
-  return ((context: H, next?: NextFunction) => {
+  function hook(context: H): void
+  function hook(context: H, next: NextFunction): Promise<void>
+  function hook(context: H, next?: NextFunction): void | Promise<void> {
     if (context.params._stashable) {
       if (next) return next()
-      return context
+      return
     }
 
     checkContext(context, {
@@ -68,6 +67,8 @@ export function stashable<H extends HookContext = HookContext>(
     context.params[propName] = () => promise
 
     if (next) return next()
-    return context
-  }) as any
+
+    return
+  }
+  return hook
 }

package/src/hooks/throw-if/throw-if.hook.ts

@@ -32,7 +32,7 @@ export const throwIf = <H extends HookContext = HookContext>(
   predicate: PredicateFn,
   options?: ThrowIfOptions,
 ) => {
-  return async (context: H, next?: NextFunction) => {
+  return async (context: H, next?: NextFunction): Promise<void> => {
     const result = await predicate(context)
 
     if (result) {
@@ -42,7 +42,7 @@ export const throwIf = <H extends HookContext = HookContext>(
     }
 
     if (next) {
-      return await next()
+      await next()
     }
   }
 }

package/src/hooks/transform-data/transform-data.hook.ts

@@ -29,12 +29,10 @@ export const transformData =
   <H extends HookContext = HookContext, D = Data<H>>(
     transformer: TransformerInputFn<D, H>,
   ) =>
-  async (context: H, next?: NextFunction) => {
+  async (context: H, next?: NextFunction): Promise<void> => {
     await mutateData(context, transformer)
 
     if (next) {
-      return next()
+      await next()
     }
-
-    return context
   }

package/src/hooks/transform-query/transform-query.hook.ts

@@ -23,16 +23,17 @@ export const transformQuery = <
 >(
   transformer: TransformerFn<Q, H>,
 ) => {
-  return (context: H, next?: NextFunction) => {
+  function hook(context: H): void
+  function hook(context: H, next: NextFunction): Promise<void>
+  function hook(context: H, next?: NextFunction): void | Promise<void> {
     context.params.query = transformer(context.params.query ?? {}, {
       context,
       i: 0,
     })
 
-    if (next) {
-      return next().then(() => context)
-    }
+    if (next) return next()
 
-    return context
+    return
   }
+  return hook
 }

package/src/hooks/transform-result/transform-result.hook.ts

@@ -1,10 +1,6 @@
 import type { HookContext, NextFunction } from '@feathersjs/feathers'
 import { mutateResult } from '../../utils/mutate-result/mutate-result.util.js'
-import type {
-  DispatchOption,
-  HookFunction,
-  TransformerInputFn,
-} from '../../types.js'
+import type { DispatchOption, TransformerInputFn } from '../../types.js'
 import type { ResultSingleHookContext } from '../../utility-types/hook-context.js'
 import type { AnyFallback } from '../../internal.utils.js'
 
@@ -37,9 +33,10 @@ export const transformResult =
   <H extends HookContext = HookContext, R = Result<H>>(
     transformer: TransformerInputFn<R, H>,
     options?: TransformResultOptions,
-  ): HookFunction<H> =>
-  (context: H, next?: NextFunction) =>
-    mutateResult(context, transformer, {
+  ) =>
+  async (context: H, next?: NextFunction): Promise<void> => {
+    await mutateResult(context, transformer, {
       next,
       dispatch: options?.dispatch,
-    }) as Promise<H>
+    })
+  }