feathers-utils 10.1.0 → 10.3.0

package/src/utils/merge-query/has-conflict.ts

@@ -0,0 +1,39 @@
+import { dequal as deepEqual } from 'dequal'
+
+type QueryRecord = Record<string, any>
+
+/**
+ * Two query bodies conflict when they share at least one key whose values are not
+ * deep-equal. Internal helper for {@link mergeQuery}.
+ */
+export function hasConflict(target: QueryRecord, source: QueryRecord): boolean {
+  for (const key of Object.keys(target)) {
+    if (key in source && !deepEqual(target[key], source[key])) {
+      return true
+    }
+  }
+  return false
+}
+
+if (import.meta.vitest) {
+  const { describe, it, expect } = import.meta.vitest
+
+  describe('hasConflict', () => {
+    it('is false for disjoint keys', () => {
+      expect(hasConflict({ a: 1 }, { b: 2 })).toBe(false)
+    })
+
+    it('is false for shared equal values', () => {
+      expect(hasConflict({ a: 1 }, { a: 1, b: 2 })).toBe(false)
+    })
+
+    it('is true for shared differing values', () => {
+      expect(hasConflict({ a: 1 }, { a: 2 })).toBe(true)
+    })
+
+    it('compares values deeply', () => {
+      expect(hasConflict({ a: { x: 1 } }, { a: { x: 1 } })).toBe(false)
+      expect(hasConflict({ a: { x: 1 } }, { a: { x: 2 } })).toBe(true)
+    })
+  })
+}

package/src/utils/merge-query/logical-branches.ts

@@ -0,0 +1,39 @@
+type QueryRecord = Record<string, any>
+
+/**
+ * Returns the branches of a logical-only query (a query whose single key is `op`),
+ * or `null` when the query is not purely `{ [op]: [...] }`. Internal helper for
+ * {@link mergeQuery}.
+ */
+export function logicalBranches(
+  query: QueryRecord,
+  op: '$or' | '$and',
+): QueryRecord[] | null {
+  const keys = Object.keys(query)
+  if (keys.length === 1 && keys[0] === op && Array.isArray(query[op])) {
+    return query[op] as QueryRecord[]
+  }
+  return null
+}
+
+if (import.meta.vitest) {
+  const { describe, it, expect } = import.meta.vitest
+
+  describe('logicalBranches', () => {
+    it('returns branches for a logical-only query', () => {
+      expect(logicalBranches({ $or: [{ id: 1 }] }, '$or')).toEqual([{ id: 1 }])
+    })
+
+    it('returns null when the operator is mixed with other keys', () => {
+      expect(logicalBranches({ $or: [{ id: 1 }], a: 1 }, '$or')).toBeNull()
+    })
+
+    it('returns null for the wrong operator', () => {
+      expect(logicalBranches({ $and: [{ id: 1 }] }, '$or')).toBeNull()
+    })
+
+    it('returns null when the operator value is not an array', () => {
+      expect(logicalBranches({ $or: { id: 1 } }, '$or')).toBeNull()
+    })
+  })
+}

package/src/utils/merge-query/merge-query-bodies.ts

@@ -0,0 +1,136 @@
+import type { MergeQueryMode } from './merge-query.util.js'
+import { isEmptyObject } from '../../common/is-empty-object.js'
+import { logicalBranches } from './logical-branches.js'
+import { dedupeBranches } from './dedupe-branches.js'
+import { hasConflict } from './has-conflict.js'
+
+type QueryRecord = Record<string, any>
+
+/**
+ * Merges two query bodies (filters already removed) according to the mode.
+ * Internal helper for {@link mergeQuery}.
+ *
+ * - `target` / `source`: precedence merge (that side wins on conflict).
+ * - `combine`: the two bodies always become branches of a single `$or`.
+ * - `intersect`: non-conflicting bodies merge flat; on conflict they become
+ *   branches of a single `$and`.
+ *
+ * Logical-only bodies (`{ $or: [...] }` for combine, `{ $and: [...] }` for
+ * intersect) are flattened into the result and their branches de-duplicated.
+ */
+export function mergeQueryBodies(
+  target: QueryRecord,
+  source: QueryRecord,
+  mode: MergeQueryMode,
+): QueryRecord {
+  if (mode === 'target') {
+    return { ...source, ...target }
+  }
+  if (mode === 'source') {
+    return { ...target, ...source }
+  }
+
+  if (isEmptyObject(target)) {
+    return { ...source }
+  }
+  if (isEmptyObject(source)) {
+    return { ...target }
+  }
+
+  const op = mode === 'combine' ? '$or' : '$and'
+
+  const targetBranches = logicalBranches(target, op)
+  const sourceBranches = logicalBranches(source, op)
+
+  // For intersect (AND) the top level is itself an implicit AND, so two
+  // conflict-free bodies can be merged flat. For combine (OR) there is no flat
+  // representation — combine always produces an `$or`.
+  if (
+    op === '$and' &&
+    !targetBranches &&
+    !sourceBranches &&
+    !hasConflict(target, source)
+  ) {
+    return { ...target, ...source }
+  }
+
+  const branches = dedupeBranches([
+    ...(targetBranches ?? [target]),
+    ...(sourceBranches ?? [source]),
+  ])
+
+  if (branches.length === 0) {
+    return {}
+  }
+  if (branches.length === 1) {
+    return { ...branches[0] }
+  }
+  return { [op]: branches }
+}
+
+if (import.meta.vitest) {
+  const { describe, it, expect } = import.meta.vitest
+
+  describe('mergeQueryBodies', () => {
+    it('target / source precedence', () => {
+      expect(mergeQueryBodies({ id: 1 }, { id: 2, a: 3 }, 'target')).toEqual({
+        id: 1,
+        a: 3,
+      })
+      expect(mergeQueryBodies({ id: 1 }, { id: 2, a: 3 }, 'source')).toEqual({
+        id: 2,
+        a: 3,
+      })
+    })
+
+    it('returns the other side when one is empty', () => {
+      expect(mergeQueryBodies({}, { id: 1 }, 'combine')).toEqual({ id: 1 })
+      expect(mergeQueryBodies({ id: 1 }, {}, 'intersect')).toEqual({ id: 1 })
+    })
+
+    it('combine always produces an $or, even for disjoint keys', () => {
+      expect(mergeQueryBodies({ a: 1 }, { b: 2 }, 'combine')).toEqual({
+        $or: [{ a: 1 }, { b: 2 }],
+      })
+    })
+
+    it('combine flattens and dedupes $or branches', () => {
+      expect(
+        mergeQueryBodies(
+          { $or: [{ id: 1 }, { id: 2 }] },
+          { $or: [{ id: 2 }, { id: 3 }] },
+          'combine',
+        ),
+      ).toEqual({ $or: [{ id: 1 }, { id: 2 }, { id: 3 }] })
+    })
+
+    it('combine collapses to a single body', () => {
+      expect(mergeQueryBodies({ id: 1 }, { id: 1 }, 'combine')).toEqual({
+        id: 1,
+      })
+    })
+
+    it('intersect merges disjoint keys flat', () => {
+      expect(mergeQueryBodies({ id: 1 }, { userId: 2 }, 'intersect')).toEqual({
+        id: 1,
+        userId: 2,
+      })
+    })
+
+    it('intersect wraps conflicts in $and', () => {
+      expect(mergeQueryBodies({ id: 1 }, { id: 2 }, 'intersect')).toEqual({
+        $and: [{ id: 1 }, { id: 2 }],
+      })
+    })
+
+    it('intersect flattens $and branches', () => {
+      expect(
+        mergeQueryBodies(
+          { $and: [{ id: 1 }, { id: 2 }] },
+          { $and: [{ id: 3 }] },
+          'intersect',
+        ),
+      ).toEqual({ $and: [{ id: 1 }, { id: 2 }, { id: 3 }] })
+    })
+  })
+}

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

@@ -0,0 +1,102 @@
+import type { Query } from '@feathersjs/feathers'
+import { extractQueryFilters } from './extract-query-filters.js'
+import { mergeQueryBodies } from './merge-query-bodies.js'
+import { mergeSelect } from './merge-select.js'
+
+export type MergeQueryMode = 'target' | 'source' | 'combine' | 'intersect'
+
+export interface MergeQueryOptions {
+  /**
+   * How to merge query properties that both queries constrain.
+   *
+   * - `combine` (default): broaden — the two queries always become branches of an `$or`.
+   * - `intersect`: narrow — non-conflicting properties merge flat, conflicts become an `$and`.
+   * - `target`: keep the target's value on conflict.
+   * - `source`: keep the source's value on conflict.
+   */
+  mode?: MergeQueryMode
+}
+
+/**
+ * Properties are combined with a logical operator rather than merged at the value
+ * level, so the result is always a valid query: `combine` always wraps the two
+ * queries in `$or` (broaden — OR has no flat form), while `intersect` merges
+ * non-conflicting properties flat and wraps conflicts in `$and` (narrow). The
+ * special filters `$select`, `$limit`, `$skip` and `$sort` are merged separately.
+ * Inputs are never mutated.
+ *
+ * This is well suited to merging a client-provided query with a server-side
+ * restriction inside a hook.
+ *
+ * @param target Query to be merged into
+ * @param source Query to be merged from
+ * @param options
+ * @returns the merged query
+ *
+ * @example
+ * ```ts
+ * import { mergeQuery } from 'feathers-utils/utils'
+ *
+ * // combine (default): the two queries always become an $or
+ * mergeQuery({ id: 1 }, { id: 2 })
+ * // => { $or: [{ id: 1 }, { id: 2 }] }
+ *
+ * mergeQuery({ status: 'active' }, { authorId: 5 })
+ * // => { $or: [{ status: 'active' }, { authorId: 5 }] }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // intersect: non-conflicting properties merge flat, conflicts become an $and
+ * mergeQuery({ status: 'active' }, { authorId: 5 }, { mode: 'intersect' })
+ * // => { status: 'active', authorId: 5 }
+ *
+ * mergeQuery({ id: 1 }, { id: 2 }, { mode: 'intersect' })
+ * // => { $and: [{ id: 1 }, { id: 2 }] }
+ * ```
+ *
+ * @see https://utils.feathersjs.com/utils/merge-query.html
+ */
+export function mergeQuery(
+  target: Query,
+  source: Query,
+  options?: MergeQueryOptions,
+): Query {
+  const mode = options?.mode ?? 'combine'
+
+  const targetFilters = extractQueryFilters(target)
+  const sourceFilters = extractQueryFilters(source)
+
+  const result: Query = mergeQueryBodies(
+    targetFilters.query,
+    sourceFilters.query,
+    mode,
+  )
+
+  const $select = mergeSelect(
+    targetFilters.$select,
+    sourceFilters.$select,
+    mode,
+  )
+  if ($select !== undefined) {
+    result.$select = $select
+  }
+
+  if ('$limit' in sourceFilters) {
+    result.$limit = sourceFilters.$limit
+  } else if ('$limit' in targetFilters) {
+    result.$limit = targetFilters.$limit
+  }
+
+  if ('$skip' in sourceFilters) {
+    result.$skip = sourceFilters.$skip
+  } else if ('$skip' in targetFilters) {
+    result.$skip = targetFilters.$skip
+  }
+
+  if ('$sort' in targetFilters || '$sort' in sourceFilters) {
+    result.$sort = { ...targetFilters.$sort, ...sourceFilters.$sort }
+  }
+
+  return result
+}

package/src/utils/merge-query/merge-select.ts

@@ -0,0 +1,64 @@
+import type { MergeQueryMode } from './merge-query.util.js'
+
+/**
+ * Merges two `$select` filters according to the mode: `combine` → union,
+ * `intersect` → intersection, `target`/`source` → that side. When only one side
+ * provides a `$select`, that one is used. Internal helper for {@link mergeQuery}.
+ */
+export function mergeSelect(
+  target: any,
+  source: any,
+  mode: MergeQueryMode,
+): any {
+  if (target === undefined) {
+    return source
+  }
+  if (source === undefined) {
+    return target
+  }
+  if (mode === 'target') {
+    return target
+  }
+  if (mode === 'source') {
+    return source
+  }
+  const targetArr = Array.isArray(target) ? target : [target]
+  const sourceArr = Array.isArray(source) ? source : [source]
+  if (mode === 'combine') {
+    return [...new Set([...targetArr, ...sourceArr])]
+  }
+  // intersect
+  return targetArr.filter((value) => sourceArr.includes(value))
+}
+
+if (import.meta.vitest) {
+  const { describe, it, expect } = import.meta.vitest
+
+  describe('mergeSelect', () => {
+    it('returns the defined side when one is missing', () => {
+      expect(mergeSelect(undefined, ['a'], 'combine')).toEqual(['a'])
+      expect(mergeSelect(['a'], undefined, 'combine')).toEqual(['a'])
+    })
+
+    it('unions on combine', () => {
+      expect(mergeSelect(['a', 'b'], ['b', 'c'], 'combine')).toEqual([
+        'a',
+        'b',
+        'c',
+      ])
+    })
+
+    it('intersects on intersect', () => {
+      expect(mergeSelect(['a', 'b'], ['b', 'c'], 'intersect')).toEqual(['b'])
+    })
+
+    it('can produce an empty intersection', () => {
+      expect(mergeSelect(['a'], ['b'], 'intersect')).toEqual([])
+    })
+
+    it('picks the requested side on target / source', () => {
+      expect(mergeSelect(['a'], ['b'], 'target')).toEqual(['a'])
+      expect(mergeSelect(['a'], ['b'], 'source')).toEqual(['b'])
+    })
+  })
+}

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

@@ -0,0 +1,39 @@
+import type { Query } from '@feathersjs/feathers'
+import { addToQuery } from '../add-to-query/add-to-query.util.js'
+import { queryHasProperty } from '../query-has-property/query-has-property.util.js'
+
+/**
+ * Adds default properties to a Feathers query — but only for fields the query does
+ * not already constrain. Presence is checked with {@link queryHasProperty}, so a field
+ * referenced anywhere (including nested in `$and`/`$or`/`$nor`) is left untouched and
+ * the caller keeps control over it. The query is treated as the `data` equivalent of
+ * the `defaults` transformer. Each default is applied independently (per-field).
+ *
+ * @example
+ * ```ts
+ * import { queryDefaults } from 'feathers-utils/utils'
+ *
+ * queryDefaults({ status: 'active' }, { isTemplate: false })
+ * // => { status: 'active', isTemplate: false }
+ *
+ * queryDefaults({ $or: [{ isTemplate: true }] }, { isTemplate: false })
+ * // => { $or: [{ isTemplate: true }] } (untouched — already referenced)
+ * ```
+ *
+ * @see https://utils.feathersjs.com/utils/query-defaults.html
+ */
+export const queryDefaults = (
+  query: Query | undefined,
+  defaults: Query,
+): Query => {
+  const source: Query = query ?? {}
+
+  const toAdd: Query = {}
+  for (const key in defaults) {
+    if (!queryHasProperty(source, key)) {
+      toAdd[key] = defaults[key]
+    }
+  }
+
+  return addToQuery(source, toAdd)
+}

package/src/utils/query-has-property/query-has-property.util.ts

@@ -0,0 +1,37 @@
+import type { Query } from '@feathersjs/feathers'
+import { toArray, type MaybeArray } from '../../internal.utils.js'
+import { walkQuery } from '../walk-query/walk-query.util.js'
+
+/**
+ * Checks whether a Feathers query contains one or more properties — including
+ * properties nested inside `$and`/`$or`/`$nor` arrays. Returns `true` as soon as
+ * any of the given property names is found. The query is not mutated.
+ *
+ * @example
+ * ```ts
+ * import { queryHasProperty } from 'feathers-utils/utils'
+ *
+ * queryHasProperty({ isTemplate: true }, 'isTemplate') // true
+ * queryHasProperty({ $or: [{ isTemplate: true }] }, 'isTemplate') // true
+ * queryHasProperty({ age: { $gt: 18 } }, ['isTemplate', 'status']) // false
+ * ```
+ *
+ * @see https://utils.feathersjs.com/utils/query-has-property.html
+ */
+export const queryHasProperty = (
+  query: Query,
+  property: MaybeArray<string>,
+): boolean => {
+  const properties = new Set(toArray(property))
+
+  let found = false
+  walkQuery(query, ({ property: key, stop }) => {
+    if (properties.has(key)) {
+      found = true
+      stop()
+    }
+    // returning undefined leaves the value untouched → no mutation
+  })
+
+  return found
+}

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

@@ -12,15 +12,27 @@ export type WalkQueryOptions = {
   operator: string | undefined
   value: any
   path: (string | number)[]
+  /**
+   * Stops the traversal. Any replacement value returned from the current walker
+   * call is still applied, but no further properties are visited.
+   */
+  stop: () => void
 }
 
 export type WalkQueryCallback = (options: WalkQueryOptions) => any
 
+type WalkQueryState = { stopped: boolean }
+
 const _walkQueryUtil = <Q extends Query>(
   query: Q,
   walker: WalkQueryCallback,
+  state: WalkQueryState,
   options?: WalkQueryOptionsInit | WalkQueryOptions,
 ): Q => {
+  const stop = () => {
+    state.stopped = true
+  }
+
   let cloned = false
   const clonedSecond: Record<string, boolean> = {}
   function set(key: string, value: any, secondKey?: string | number) {
@@ -42,6 +54,10 @@ const _walkQueryUtil = <Q extends Query>(
   }
 
   for (const key in query) {
+    if (state.stopped) {
+      break
+    }
+
     if (
       (key === '$or' || key === '$and' || key === '$nor') &&
       Array.isArray(query[key])
@@ -51,8 +67,12 @@ const _walkQueryUtil = <Q extends Query>(
       let copiedArray = false
 
       for (let i = 0, n = array.length; i < n; i++) {
+        if (state.stopped) {
+          break
+        }
+
         const nestedQuery = array[i]
-        const transformed = _walkQueryUtil(nestedQuery, walker, {
+        const transformed = _walkQueryUtil(nestedQuery, walker, state, {
           ...options,
           path: [...(options?.path || []), key, i],
         })
@@ -77,6 +97,10 @@ const _walkQueryUtil = <Q extends Query>(
     ) {
       let hasOperator = false
       for (const operator in query[key]) {
+        if (state.stopped) {
+          break
+        }
+
         if (operator.startsWith('$')) {
           hasOperator = true
           const value = walker({
@@ -84,6 +108,7 @@ const _walkQueryUtil = <Q extends Query>(
             path: [...(options?.path ?? []), key],
             property: key,
             value: query[key][operator],
+            stop,
           })
 
           if (value !== undefined && value !== query[key][operator]) {
@@ -98,6 +123,7 @@ const _walkQueryUtil = <Q extends Query>(
           path: [...(options?.path ?? []), key],
           property: key,
           value: query[key],
+          stop,
         })
 
         if (value !== undefined && value !== query[key]) {
@@ -110,6 +136,7 @@ const _walkQueryUtil = <Q extends Query>(
         path: [...(options?.path ?? []), key],
         property: key,
         value: query[key],
+        stop,
       })
 
       if (value !== undefined && value !== query[key]) {
@@ -124,7 +151,8 @@ const _walkQueryUtil = <Q extends Query>(
 /**
  * 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.
+ * value, path, and a `stop` function, and can return a replacement value. Calling `stop()` halts
+ * the traversal early. Returns a new query only if changes were made.
  *
  * @example
  * ```ts
@@ -136,11 +164,23 @@ const _walkQueryUtil = <Q extends Query>(
  * // => { age: { $gt: 18 } }
  * ```
  *
+ * @example
+ * ```ts
+ * // stop early once a property is found
+ * let found = false
+ * walkQuery(query, ({ property, stop }) => {
+ *   if (property === 'isTemplate') {
+ *     found = true
+ *     stop()
+ *   }
+ * })
+ * ```
+ *
  * @see https://utils.feathersjs.com/utils/walk-query.html
  */
 export const walkQuery = <Q extends Query>(
   query: Q,
   walker: WalkQueryCallback,
 ): Q => {
-  return _walkQueryUtil(query, walker)
+  return _walkQueryUtil(query, walker, { stopped: false })
 }