feathers-utils 10.0.1 → 10.0.2

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)

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

@@ -19,18 +19,20 @@ export const skippable = <H extends HookContext = HookContext>(
   innerHook: HookFunction<H>,
   predicate: PredicateFn<H>,
 ) => {
-  function hook(context: H): void
+  function hook(context: H): H | void | Promise<H | void>
   function hook(context: H, next: NextFunction): Promise<void>
-  function hook(context: H, next?: NextFunction): void | Promise<void> {
+  function hook(context: H, next?: NextFunction): H | void | Promise<H | void> {
     const skip = predicate(context)
 
-    const skipOrRun = (shouldSkip: boolean): void | Promise<void> => {
+    const skipOrRun = (shouldSkip: boolean): H | void | Promise<H | void> => {
       if (shouldSkip) {
         if (next) return next()
         return
       }
       if (next) return innerHook(context, next) as Promise<void>
-      innerHook(context)
+      // 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') {

package/src/hooks/traverse/traverse.hook.ts

@@ -6,6 +6,15 @@ export type TraverseOptions = {
   getObject: (
     context: HookContext,
   ) => Record<string, any> | Record<string, any>[]
+  /**
+   * For `around` hooks only: run the traversal *after* `next()` instead of before.
+   * Required when `getObject` targets `context.result`, which is only populated
+   * once the service method has run. Defaults to `false` (run before `next()`),
+   * which is correct for `context.data`/`context.params.query` targets.
+   *
+   * @default false
+   */
+  runAfter?: boolean
 }
 
 /**
@@ -29,11 +38,21 @@ export type TraverseOptions = {
 export const traverse = <H extends HookContext = HookContext>({
   transformer,
   getObject,
+  runAfter = false,
 }: TraverseOptions) => {
+  const runTraverse = (context: H) => _traverse(getObject(context), transformer)
+
   function hook(context: H): void
   function hook(context: H, next: NextFunction): Promise<void>
   function hook(context: H, next?: NextFunction): void | Promise<void> {
-    _traverse(getObject(context), transformer)
+    if (next && runAfter) {
+      // around hook targeting context.result: transform after the method ran
+      return next().then(() => {
+        runTraverse(context)
+      })
+    }
+
+    runTraverse(context)
 
     if (next) return next()
 

package/src/internal.utils.ts

@@ -9,8 +9,13 @@ export const hasOwnProperty = (
 
 export type MaybeArray<T> = T | readonly T[]
 export type UnpackMaybeArray<T> = T extends readonly (infer E)[] ? E : T
+/**
+ * Normalizes a value or array into an array. The returned array MUST be treated
+ * as read-only — when the input is already an array it is returned as-is (no copy)
+ * to avoid a per-call allocation on hook hot paths.
+ */
 export const toArray = <T>(value: T | readonly T[]): T[] =>
-  Array.isArray(value) ? [...value] : [value as T]
+  Array.isArray(value) ? (value as T[]) : [value as T]
 
 export type Promisable<T> = T | Promise<T>
 export type KeyOf<T> = Extract<keyof T, string>

package/src/predicates/and/and.predicate.ts

@@ -26,8 +26,7 @@ export const and = <H extends HookContext = HookContext>(
   )
 
   return (context: H): boolean | Promise<boolean> => {
-    // same as Array.prototype.every for empty arrays
-    // see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every#description
+    // The identity element of logical AND is `true` (an empty AND is true).
     if (!filtered.length) {
       return true
     }
@@ -36,10 +35,11 @@ export const and = <H extends HookContext = HookContext>(
 
     for (const predicate of filtered) {
       const result = predicate(context)
-      if (result === false) {
-        return false
-      } else if (isPromise(result)) {
+      if (isPromise(result)) {
         promises.push(result)
+      } else if (!result) {
+        // any falsy sync result short-circuits to false
+        return false
       }
     }
 

package/src/predicates/is-context/is-context.predicate.ts

@@ -32,7 +32,7 @@ export const isContext = <H extends HookContext = HookContext>(
   const method = options.method != null ? toArray(options.method) : undefined
 
   return (context: any): boolean => {
-    if (path && !path.some((x) => context.path.includes(x))) {
+    if (path && !path.some((x) => context.path === x)) {
       return false
     }
 

package/src/predicates/or/or.predicate.ts

@@ -26,10 +26,9 @@ export const or = <H extends HookContext = HookContext>(
   )
 
   return (context: H): boolean | Promise<boolean> => {
-    // same as Array.prototype.some for empty arrays
-    // see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/some#description
+    // The identity element of logical OR is `false` (an empty OR is false).
     if (!filtered.length) {
-      return true
+      return false
     }
 
     const promises: Promise<boolean>[] = []
@@ -37,12 +36,11 @@ export const or = <H extends HookContext = HookContext>(
     for (const predicate of filtered) {
       const result = predicate(context)
 
-      if (result === true) {
-        return true
-      } else if (result === false) {
-        continue
-      } else if (isPromise(result)) {
+      if (isPromise(result)) {
         promises.push(result)
+      } else if (result) {
+        // any truthy sync result short-circuits to true
+        return true
       }
     }
 

package/src/transformers/parse-date/parse-date.transformer.ts

@@ -1,3 +1,4 @@
+import { BadRequest } from '@feathersjs/errors'
 import { toArray, type MaybeArray } from '../../internal.utils.js'
 import _get from 'lodash/get.js'
 import _set from 'lodash/set.js'
@@ -25,7 +26,11 @@ export function parseDate<T extends Record<string, any>>(
     const key = fieldNamesArr[i]
     const value = _get(item, key)
     if (value) {
-      _set(item, key, new Date(value))
+      const date = new Date(value)
+      if (Number.isNaN(date.getTime())) {
+        throw new BadRequest(`Expected valid date (parseDate '${key}')`)
+      }
+      _set(item, key, date)
     }
   }
 }

package/src/utils/chunk-find/chunk-find.util.ts

@@ -68,6 +68,13 @@ export async function* chunkFind<
   do {
     result = await (service as any).find(params)
 
+    // Guard against an infinite loop: an empty page never advances $skip, so
+    // `total > $skip` could stay true forever (e.g. $limit:0, or a stale total
+    // when items are concurrently removed / filtered out by hooks).
+    if (!result.data.length) {
+      break
+    }
+
     yield result.data
 
     params.query.$skip = (params.query.$skip ?? 0) + result.data.length

package/src/utils/combine/combine.util.ts

@@ -1,5 +1,6 @@
 import type { HookContext } from '@feathersjs/feathers'
 import type { HookFunction } from '../../types.js'
+import { isPromise } from '../../common/index.js'
 
 /**
  * Sequentially executes multiple hooks, passing the updated context from one to the next.
@@ -42,22 +43,14 @@ export function combine<H extends HookContext = HookContext>(
       return ctx
     }
 
-    // Go through all hooks and chain them into our promise
-
-    // @ts-expect-error TODO
-    const promise = serviceHooks.reduce(async (current, fn) => {
-      // @ts-expect-error TODO
-      const hook = fn.bind(this)
-
-      // Use the returned hook object or the old one
-
-      const currentHook = await current
-      const currentCtx = await hook(currentHook)
-      return updateCurrentHook(currentCtx)
-    }, Promise.resolve(ctx))
-
+    // Run the hooks sequentially, only awaiting when a hook is actually async.
+    // Avoids a microtask hop per hook and a per-hook `bind` allocation.
     try {
-      await promise
+      for (const fn of serviceHooks) {
+        // @ts-expect-error `this` is the bound service-hook context
+        const currentCtx = fn.call(this, ctx)
+        updateCurrentHook(isPromise(currentCtx) ? await currentCtx : currentCtx)
+      }
       return ctx
     } catch (error: any) {
       // Add the hook information to any errors

package/src/utils/get-paginate/get-paginate.util.ts

@@ -23,12 +23,10 @@ export const getPaginate = <H extends HookContext = HookContext>(
   context: H,
 ): PaginationOptions | undefined => {
   if (hasOwnProperty(context.params, 'paginate')) {
+    // covers `paginate: false` too (`false || undefined` -> undefined)
     return (context.params.paginate as PaginationOptions) || undefined
   }
 
-  if (context.params.paginate === false) {
-    return undefined
-  }
   let options = context.service?.options || {}
 
   options = {

package/src/utils/index.ts

@@ -12,6 +12,8 @@ export * from './iterate-find/iterate-find.util.js'
 export * from './mutate-data/mutate-data.util.js'
 export * from './mutate-result/mutate-result.util.js'
 export * from './patch-batch/patch-batch.util.js'
+export * from './replace-data/replace-data.util.js'
+export * from './replace-result/replace-result.util.js'
 export * from './skip-result/skip-result.util.js'
 export * from './to-paginated/to-paginated.util.js'
 export * from './transform-params/transform-params.util.js'

package/src/utils/iterate-find/iterate-find.util.ts

@@ -59,6 +59,7 @@ export async function* iterateFind<
     },
     paginate: {
       default: options?.params?.paginate?.default ?? 10,
+      max: options?.params?.paginate?.max ?? 100,
     },
   }
 
@@ -67,6 +68,13 @@ export async function* iterateFind<
   do {
     result = await (service as any).find(params)
 
+    // Guard against an infinite loop: an empty page never advances $skip, so
+    // `total > $skip` could stay true forever (e.g. $limit:0, or a stale total
+    // when items are concurrently removed / filtered out by hooks).
+    if (!result.data.length) {
+      break
+    }
+
     for (const item of result.data) {
       yield item
     }

package/src/utils/mutate-data/mutate-data.util.ts

@@ -1,5 +1,6 @@
 import type { HookContext } from '@feathersjs/feathers'
 import { getDataIsArray } from '../get-data-is-array/get-data-is-array.util.js'
+import { replaceData } from '../replace-data/replace-data.util.js'
 import { isPromise } from '../../common/index.js'
 import type { Promisable } from '../../internal.utils.js'
 import type { TransformerInputFn } from '../../types.js'
@@ -26,7 +27,24 @@ export function mutateData<H extends HookContext = HookContext>(
     return context
   }
 
-  const { data, isArray } = getDataIsArray(context)
+  // single-item fast path: avoid allocating a wrapper array + a mapped array
+  // for the common single create/update/patch case.
+  if (!Array.isArray(context.data)) {
+    const item = context.data
+    const result = transformer(item, { context, i: 0 })
+
+    if (isPromise(result)) {
+      return result.then((res: any) => {
+        context.data = res ?? item
+        return context
+      })
+    }
+
+    context.data = result ?? item
+    return context
+  }
+
+  const { data } = getDataIsArray(context)
 
   if (!data.length) {
     return context
@@ -46,9 +64,8 @@ export function mutateData<H extends HookContext = HookContext>(
   })
 
   function mutate(data: any) {
-    context.data = isArray ? data : data[0]
-
-    return context
+    // delegate the array writeback (single is handled by the fast path above)
+    return replaceData(context, data)
   }
 
   if (hasPromises) {

package/src/utils/mutate-result/mutate-result.util.ts

@@ -1,5 +1,6 @@
 import type { HookContext, NextFunction } from '@feathersjs/feathers'
 import { getResultIsArray } from '../get-result-is-array/get-result-is-array.util.js'
+import { replaceResult } from '../replace-result/replace-result.util.js'
 import { isPromise } from '../../common/index.js'
 import { copy } from 'fast-copy'
 import type { Promisable } from '../../internal.utils.js'
@@ -35,7 +36,7 @@ export function mutateResult<H extends HookContext = HookContext>(
   }
 
   function forResult(dispatch: boolean): Promisable<H> {
-    const { result, isArray, key } = getResultIsArray(context, { dispatch })
+    const { result } = getResultIsArray(context, { dispatch })
 
     if (!result.length) {
       return context
@@ -59,15 +60,8 @@ export function mutateResult<H extends HookContext = HookContext>(
         r = options.transform(r)
       }
 
-      if (!isArray) {
-        context[key] = r[0]
-      } else if (isArray && !Array.isArray(context[key]) && context[key].data) {
-        context[key].data = r
-      } else {
-        context[key] = r
-      }
-
-      return context
+      // delegate the single/array/paginated writeback to replaceResult
+      return replaceResult(context, r, { dispatch })
     }
 
     if (hasPromises) {

package/src/utils/patch-batch/patch-batch.util.ts

@@ -1,7 +1,22 @@
 import type { Id, Params } from '@feathersjs/feathers'
-import { dequal as deepEqual } from 'dequal'
 import type { KeyOf } from '../../internal.utils.js'
 
+/**
+ * Deterministic, key-order-independent serialization used to group items with
+ * equal patch data in O(1) per item.
+ */
+const stableKey = (value: any): string =>
+  JSON.stringify(value, (_key, val) =>
+    val && typeof val === 'object' && !Array.isArray(val)
+      ? Object.keys(val)
+          .sort()
+          .reduce<Record<string, any>>((acc, k) => {
+            acc[k] = val[k]
+            return acc
+          }, {})
+      : val,
+  )
+
 export type PatchBatchOptions<IdKey extends string> = {
   /** the key of the id property */
   id?: IdKey
@@ -47,27 +62,30 @@ export function patchBatch<
   items: T[],
   options?: PatchBatchOptions<IdKey>,
 ): PatchBatchResultItem<R, P>[] {
-  const map: { ids: Id[]; data: R }[] = []
-
   const idKey = options?.id ?? 'id'
 
-  for (const _data of items) {
-    const data = _data as unknown as R
-    const id = _data[idKey]
-    delete (data as any)[idKey as any]
+  // group items with identical (id-stripped) data in O(n) via a Map keyed by a
+  // stable serialization, instead of an O(n^2) findIndex + deepEqual scan.
+  const groups = new Map<string, { ids: Id[]; data: R }>()
+
+  for (const item of items) {
+    const source = item as Record<string, any>
+    const id = source[idKey] as Id
+    // shallow copy then drop the id key, so the caller's input is never mutated.
+    const data = { ...source }
+    delete data[idKey as any]
 
-    const index = map.findIndex((item) => {
-      return deepEqual(item.data, data)
-    })
+    const key = stableKey(data)
+    const existing = groups.get(key)
 
-    if (index === -1) {
-      map.push({ ids: [id], data })
+    if (existing) {
+      existing.ids.push(id)
     } else {
-      map[index].ids.push(id)
+      groups.set(key, { ids: [id], data: data as unknown as R })
     }
   }
 
-  return map.map(({ ids, data }) => {
+  return [...groups.values()].map(({ ids, data }) => {
     return ids.length === 1
       ? ([ids[0], data, undefined] as PatchBatchResultItem<R, P>)
       : ([

package/src/utils/replace-data/replace-data.util.ts

@@ -0,0 +1,26 @@
+import type { HookContext } from "@feathersjs/feathers";
+import type { DataSingleHookContext } from "../../utility-types/hook-context.js";
+
+/**
+ * Replaces `context.data` wholesale with the given items, preserving the original
+ * single-vs-array shape. This is the explicit inverse of `getDataIsArray`: get the
+ * data as an array, modify or replace the items, then write them back.
+ *
+ * @example
+ * ```ts
+ * import { getDataIsArray, replaceData } from 'feathers-utils/utils'
+ *
+ * const { data } = getDataIsArray(context)
+ * const next = data.map((item) => ({ ...item, slug: slugify(item.name) }))
+ * replaceData(context, next)
+ * ```
+ *
+ * @see https://utils.feathersjs.com/utils/replace-data.html
+ */
+export function replaceData<H extends HookContext = HookContext>(
+  context: H,
+  data: DataSingleHookContext<H>[],
+): H {
+  context.data = Array.isArray(context.data) ? data : data[0];
+  return context;
+}

package/src/utils/replace-result/replace-result.util.ts

@@ -0,0 +1,60 @@
+import type { HookContext } from "@feathersjs/feathers";
+import { copy } from "fast-copy";
+import { getResultIsArray } from "../get-result-is-array/get-result-is-array.util.js";
+import type { DispatchOption } from "../../types.js";
+import type { ResultSingleHookContext } from "../../utility-types/hook-context.js";
+
+export type ReplaceResultOptions = {
+  /**
+   * Also (or only) write to `context.dispatch`. `true` writes dispatch, `'both'`
+   * writes both `result` and `dispatch`. When dispatch is requested and not yet
+   * present, it is seeded from a clone of `context.result`.
+   */
+  dispatch?: DispatchOption;
+};
+
+/**
+ * Replaces `context.result` (and/or `context.dispatch`) wholesale with the given
+ * items, preserving the original shape: single item, array, or paginated `{ data }`.
+ * This is the explicit inverse of `getResultIsArray`.
+ *
+ * @example
+ * ```ts
+ * import { getResultIsArray, replaceResult } from 'feathers-utils/utils'
+ *
+ * const { result } = getResultIsArray(context)
+ * replaceResult(context, result.filter((item) => item.public))
+ * ```
+ *
+ * @see https://utils.feathersjs.com/utils/replace-result.html
+ */
+export function replaceResult<H extends HookContext = HookContext>(
+  context: H,
+  result: ResultSingleHookContext<H>[],
+  options?: ReplaceResultOptions,
+): H {
+  if (!!options?.dispatch && !context.dispatch) {
+    context.dispatch = copy(context.result);
+  }
+
+  const write = (dispatch: boolean) => {
+    const { isArray, key } = getResultIsArray(context, { dispatch });
+
+    if (!isArray) {
+      context[key] = result[0];
+    } else if (!Array.isArray(context[key]) && context[key]?.data) {
+      context[key].data = result;
+    } else {
+      context[key] = result;
+    }
+  };
+
+  if (options?.dispatch === "both") {
+    write(true);
+    write(false);
+  } else {
+    write(!!options?.dispatch);
+  }
+
+  return context;
+}

package/src/utils/sort-query-properties/sort-query-properties.util.ts

@@ -1,8 +1,10 @@
 import type { Query } from '@feathersjs/feathers'
-import isObject from 'lodash/isObject.js'
 
 const arrayOperators = new Set(['$or', '$and', '$nor', '$not', '$in', '$nin'])
 
+const isPlainObjectLike = (value: unknown): value is Record<string, any> =>
+  value !== null && typeof value === 'object'
+
 /**
  * Recursively normalizes a Feathers query object for order-independent comparison.
  * Sorts object keys and sorts arrays within `$or`, `$and`, `$nor`, `$not`, `$in`,
@@ -35,21 +37,26 @@ const normalize = (value: any): any => {
     return value.map(normalize)
   }
 
-  if (!isObject(value)) {
+  if (!isPlainObjectLike(value)) {
     return value
   }
 
   const sorted: Record<string, any> = {}
 
-  for (const key of Object.keys(value as Record<string, any>).sort()) {
-    const val = (value as Record<string, any>)[key]
+  for (const key of Object.keys(value).sort()) {
+    const val = value[key]
 
     if (arrayOperators.has(key) && Array.isArray(val)) {
+      // Schwartzian transform: serialize each normalized element once, sort by
+      // that key, then unwrap. Avoids the O(n log n) repeated JSON.stringify of
+      // the previous comparator (which also returned 1 for equal elements).
       sorted[key] = val
-        .map(normalize)
-        .sort((a: any, b: any) =>
-          JSON.stringify(a) < JSON.stringify(b) ? -1 : 1,
-        )
+        .map((el) => {
+          const normalized = normalize(el)
+          return { k: JSON.stringify(normalized), v: normalized }
+        })
+        .sort((a, b) => (a.k < b.k ? -1 : a.k > b.k ? 1 : 0))
+        .map((entry) => entry.v)
     } else {
       sorted[key] = normalize(val)
     }

package/src/utils/walk-query/walk-query.util.ts

@@ -43,7 +43,7 @@ const _walkQueryUtil = <Q extends Query>(
 
   for (const key in query) {
     if (
-      (key === '$or' || key === '$and' || key === '$nor' || key === '$not') &&
+      (key === '$or' || key === '$and' || key === '$nor') &&
       Array.isArray(query[key])
     ) {
       let array = query[key]
@@ -122,7 +122,7 @@ const _walkQueryUtil = <Q extends Query>(
 }
 
 /**
- * Walks every property of a Feathers query (including nested `$and`/`$or`/`$nor`/`$not` arrays)
+ * Walks every property of a Feathers query (including nested `$and`/`$or`/`$nor` arrays)
  * and calls the `walker` function for each one. The walker receives the property name, operator,
  * value, and path, and can return a replacement value. Returns a new query only if changes were made.
  *