feathers-utils 10.2.0 → 10.4.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,152 @@
+import type { MergeQueryMode } from './merge-query.util.js'
+import { isEmptyObject } from '../../common/is-empty-object.js'
+import { dedupeBranches } from '../../common/dedupe-branches.js'
+import { flattenAndBranches } from '../../common/flatten-and-branches.js'
+import { logicalBranches } from './logical-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 collected = [
+    ...(targetBranches ?? [target]),
+    ...(sourceBranches ?? [source]),
+  ]
+
+  // under `$and`, hoist any nested `$and` so the result never nests `$and` in `$and`
+  const branches = dedupeBranches(
+    op === '$and' ? flattenAndBranches(collected) : collected,
+  )
+
+  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 }] })
+    })
+
+    it('intersect hoists a nested $and instead of nesting it', () => {
+      expect(
+        mergeQueryBodies(
+          { $or: ['u'] },
+          { $or: ['c'], $and: [{ $nor: ['n'] }] },
+          'intersect',
+        ),
+      ).toEqual({ $and: [{ $or: ['u'] }, { $or: ['c'] }, { $nor: ['n'] }] })
+    })
+  })
+}

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

@@ -0,0 +1,105 @@
+import type { Query } from '@feathersjs/feathers'
+import { simplifyQuery } from '../simplify-query/simplify-query.util.js'
+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'
+
+  // normalize inputs first: drop empty/duplicate/redundant logical wrappers and
+  // hoist nested operators, so the merge works on clean, canonical queries
+  const targetFilters = extractQueryFilters(simplifyQuery(target))
+  const sourceFilters = extractQueryFilters(simplifyQuery(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/replace-data/replace-data.util.ts

@@ -1,5 +1,5 @@
-import type { HookContext } from "@feathersjs/feathers";
-import type { DataSingleHookContext } from "../../utility-types/hook-context.js";
+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
@@ -21,6 +21,6 @@ export function replaceData<H extends HookContext = HookContext>(
   context: H,
   data: DataSingleHookContext<H>[],
 ): H {
-  context.data = Array.isArray(context.data) ? data : data[0];
-  return context;
+  context.data = Array.isArray(context.data) ? data : data[0]
+  return context
 }

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

@@ -1,8 +1,8 @@
-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";
+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 = {
   /**
@@ -10,8 +10,8 @@ export type ReplaceResultOptions = {
    * writes both `result` and `dispatch`. When dispatch is requested and not yet
    * present, it is seeded from a clone of `context.result`.
    */
-  dispatch?: DispatchOption;
-};
+  dispatch?: DispatchOption
+}
 
 /**
  * Replaces `context.result` (and/or `context.dispatch`) wholesale with the given
@@ -34,27 +34,27 @@ export function replaceResult<H extends HookContext = HookContext>(
   options?: ReplaceResultOptions,
 ): H {
   if (!!options?.dispatch && !context.dispatch) {
-    context.dispatch = copy(context.result);
+    context.dispatch = copy(context.result)
   }
 
   const write = (dispatch: boolean) => {
-    const { isArray, key } = getResultIsArray(context, { dispatch });
+    const { isArray, key } = getResultIsArray(context, { dispatch })
 
     if (!isArray) {
-      context[key] = result[0];
+      context[key] = result[0]
     } else if (!Array.isArray(context[key]) && context[key]?.data) {
-      context[key].data = result;
+      context[key].data = result
     } else {
-      context[key] = result;
+      context[key] = result
     }
-  };
+  }
 
-  if (options?.dispatch === "both") {
-    write(true);
-    write(false);
+  if (options?.dispatch === 'both') {
+    write(true)
+    write(false)
   } else {
-    write(!!options?.dispatch);
+    write(!!options?.dispatch)
   }
 
-  return context;
+  return context
 }

package/src/utils/simplify-query/merge-and-branches-up.ts

@@ -0,0 +1,86 @@
+import { dequal as deepEqual } from 'dequal'
+
+type QueryRecord = Record<string, any>
+
+/**
+ * `$and` is an implicit AND with the rest of the query, so ALL of its branches can
+ * be merged up into the parent at once — as long as no key would be set to two
+ * different values (across the branches or the existing keys). On any such collision
+ * the `$and` is kept intact. Internal helper for {@link simplifyQuery}.
+ */
+export function mergeAndBranchesUp(
+  result: QueryRecord,
+  enabled: boolean,
+): QueryRecord {
+  if (!enabled || !Array.isArray(result.$and) || result.$and.length === 0) {
+    return result
+  }
+  const rest = { ...result }
+  delete rest.$and
+  const seen = new Map<string, any>(Object.entries(rest))
+  for (const branch of result.$and) {
+    for (const [key, value] of Object.entries(branch)) {
+      if (seen.has(key) && !deepEqual(seen.get(key), value)) {
+        return result
+      }
+      seen.set(key, value)
+    }
+  }
+  return Object.assign(rest, ...result.$and)
+}
+
+if (import.meta.vitest) {
+  const { describe, it, expect } = import.meta.vitest
+
+  describe('mergeAndBranchesUp', () => {
+    it('merges all branches up when keys do not collide', () => {
+      expect(mergeAndBranchesUp({ $and: [{ a: 1 }, { b: 2 }] }, true)).toEqual({
+        a: 1,
+        b: 2,
+      })
+    })
+
+    it('merges branches up alongside existing root keys', () => {
+      expect(
+        mergeAndBranchesUp({ c: 3, $and: [{ a: 1 }, { b: 2 }] }, true),
+      ).toEqual({ a: 1, b: 2, c: 3 })
+    })
+
+    it('keeps the $and on a value collision between branches', () => {
+      expect(mergeAndBranchesUp({ $and: [{ a: 1 }, { a: 2 }] }, true)).toEqual({
+        $and: [{ a: 1 }, { a: 2 }],
+      })
+    })
+
+    it('keeps the $and on a collision with a root key', () => {
+      expect(mergeAndBranchesUp({ a: 1, $and: [{ a: 2 }] }, true)).toEqual({
+        a: 1,
+        $and: [{ a: 2 }],
+      })
+    })
+
+    it('allows a branch key equal to an existing root value', () => {
+      expect(
+        mergeAndBranchesUp({ a: 1, $and: [{ a: 1 }, { b: 2 }] }, true),
+      ).toEqual({ a: 1, b: 2 })
+    })
+
+    it('does nothing when disabled', () => {
+      expect(mergeAndBranchesUp({ $and: [{ a: 1 }] }, false)).toEqual({
+        $and: [{ a: 1 }],
+      })
+    })
+
+    it('ignores a missing or empty $and', () => {
+      expect(mergeAndBranchesUp({ a: 1 }, true)).toEqual({ a: 1 })
+      expect(mergeAndBranchesUp({ $and: [] }, true)).toEqual({ $and: [] })
+    })
+
+    it('does not mutate the input', () => {
+      const query = { c: 3, $and: [{ a: 1 }, { b: 2 }] }
+      const snapshot = structuredClone(query)
+      mergeAndBranchesUp(query, true)
+      expect(query).toEqual(snapshot)
+    })
+  })
+}

package/src/utils/simplify-query/merge-or-branch-up.ts

@@ -0,0 +1,74 @@
+import { dequal as deepEqual } from 'dequal'
+
+type QueryRecord = Record<string, any>
+
+/**
+ * `$or` is a disjunction, so only a *single* branch can be merged up (an `$or` of
+ * one is just that branch) — and only when no key would collide. This is the key
+ * asymmetry with `$and` ({@link mergeAndBranchesUp}). Internal helper for
+ * {@link simplifyQuery}.
+ */
+export function mergeOrBranchUp(
+  result: QueryRecord,
+  enabled: boolean,
+): QueryRecord {
+  if (!enabled || !Array.isArray(result.$or) || result.$or.length !== 1) {
+    return result
+  }
+  const branch = result.$or[0]
+  const rest = { ...result }
+  delete rest.$or
+  for (const key of Object.keys(branch)) {
+    if (key in rest && !deepEqual(rest[key], branch[key])) {
+      return result
+    }
+  }
+  return { ...rest, ...branch }
+}
+
+if (import.meta.vitest) {
+  const { describe, it, expect } = import.meta.vitest
+
+  describe('mergeOrBranchUp', () => {
+    it('merges a single branch up when keys do not collide', () => {
+      expect(mergeOrBranchUp({ a: 1, $or: [{ b: 2 }] }, true)).toEqual({
+        a: 1,
+        b: 2,
+      })
+    })
+
+    it('collapses a sole single-branch $or to that branch', () => {
+      expect(mergeOrBranchUp({ $or: [{ a: 1 }] }, true)).toEqual({ a: 1 })
+    })
+
+    it('keeps the $or on a collision with a root key', () => {
+      expect(mergeOrBranchUp({ a: 1, $or: [{ a: 2 }] }, true)).toEqual({
+        a: 1,
+        $or: [{ a: 2 }],
+      })
+    })
+
+    it('does NOT merge a multi-branch $or', () => {
+      expect(mergeOrBranchUp({ $or: [{ a: 1 }, { b: 2 }] }, true)).toEqual({
+        $or: [{ a: 1 }, { b: 2 }],
+      })
+    })
+
+    it('does nothing when disabled', () => {
+      expect(mergeOrBranchUp({ $or: [{ a: 1 }] }, false)).toEqual({
+        $or: [{ a: 1 }],
+      })
+    })
+
+    it('ignores a missing $or', () => {
+      expect(mergeOrBranchUp({ a: 1 }, true)).toEqual({ a: 1 })
+    })
+
+    it('does not mutate the input', () => {
+      const query = { a: 1, $or: [{ b: 2 }] }
+      const snapshot = structuredClone(query)
+      mergeOrBranchUp(query, true)
+      expect(query).toEqual(snapshot)
+    })
+  })
+}