@graphql-tools/merge

Major Changes

• breaking

  Drop GraphQL v14/v15 support and require Node.js >= 22.18.

  • graphql peer range is now ^16.0.0 || ^17.0.0.

  • engines.node is now >=22.18.0 (Node fs.glob + Babel 8).

  • Dev tooling and @graphql-tools/graphql-tag-pluck move to Babel 8 (@babel/core / parser / traverse / types).

  • The standalone cross-inspect package is discontinued. Use inspect from @graphql-tools/utils instead (Node util.inspect via process.getBuiltinModule, with a small JSON.stringify / String fallback).

Removed @graphql-tools/utils exports

inspect and the WeakMap memoize1…memoize2of5 helpers remain on @graphql-tools/utils (inspect is no longer re-exported from cross-inspect).

File matching (globby → fs.glob)

Loaders and @graphql-tools/load-files now use Node’s fs.glob through:

import { matchFiles, matchFilesSync } from '@graphql-tools/load-files';

Directory symlinks are followed for recursive (**) patterns:

• On Node.js ≥26.1 (and ≥24.16 where backported), fs.glob followSymlinks is used.

• On older engines, symlink directories are discovered only under each pattern’s literal prefix (not the whole cwd) and patterns are re-rooted.

• Non-recursive / literal patterns skip the symlink walk entirely.

@graphql-tools/executor hot-path caches (collectSubfields, argument coercion, @stream detection) use memoize2 / memoize3 from utils. collectSubFields in utils stays unmemoized so the executor can own a single memoize3 layer.

Errors and other cleanup

• Prefer new GraphQLError(message, options) from graphql. Experimental schema coordinate support remains on locatedError / relocatedError / getSchemaCoordinate.

• Removed GraphQL versions older than 16 compatibility branches (error construction, validation rule name suffixes, URL.canParse fallback).

• Promise helpers should be imported from @whatwg-node/promise-helpers (handleMaybePromise, isPromise, fakePromise, mapAsyncIterator, MaybePromise) rather than re-exported from utils.

Patch Changes

• dependencies updates:

  • Updated dependency graphql@^16.0.0 || ^17.0.0 ↗︎ (from ^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0, in peerDependencies)

Patch Changes

• dependencies updates:

  • Updated dependency @graphql-tools/utils@^12.0.4 ↗︎ (from ^12.0.3, in dependencies)

• Fix: Preserve symbol-keyed GraphQL extensions when building, merging, or extracting schemas.

  GraphQL.js v17 allows string | symbol keys on schema/type/field extensions (via toObjMapWithSymbols). @graphql-tools was dropping those symbol keys in two places:

  1. mergeDeep only walked enumerable string keys (for...in), so symbol extensions were lost when applying schemaExtensions.

  2. extractExtensionsFromSchema did not copy non-enumerable own symbol keys (enumerable symbols already survive object rest/spread; the explicit loop covers the non-enumerable case).

Example (bug)

import { makeExecutableSchema } from '@graphql-tools/schema'

const META = Symbol('META')

const schema = makeExecutableSchema({
  typeDefs: /* GraphQL */ `
    type Query {
      hello: String
    }
  `,
  schemaExtensions: {
    schemaExtensions: {
      [META]: { source: 'app' },
      tagged: true,
    },
    types: {},
  },
})

// Before: only string keys survived
// schema.extensions === { tagged: true }

// After: symbol keys are preserved
// schema.extensions[META] === { source: 'app' }
// schema.extensions.tagged === true

Schema extension merge/extract and resolver merging always enable { enumerable: true, nonEnumerable: true } so symbol keys survive in tools' own merge/extract paths on every supported GraphQL.js major. (GraphQL.js itself may still drop symbol keys from field configs below v17 when rebuilding types.)

mergeDeep API

mergeDeep now accepts an options object. The old positional boolean arguments still work but are deprecated.

import { mergeDeep } from '@graphql-tools/utils'

// Deprecated (still supported)
mergeDeep([a, b], false, true, false, true)
//                ^proto ^arrays ^len  ^non-enumerable symbols only

// Preferred
mergeDeep([a, b], {
  respectPrototype: false,
  respectArrays: true,
  respectArrayLength: false,
  respectSymbols: {
    enumerable: true, // merge `obj[sym] = value` keys
    nonEnumerable: true, // copy defineProperty(..., { enumerable: false }) symbols
  },
})

respectSymbols defaults to { enumerable: false, nonEnumerable: false } (symbols dropped), matching the historical default. The legacy 5th positional flag still maps to { nonEnumerable: true } only.

Resolver map types (IResolvers / field resolver extensions and type __extensions) now use ExtensionsObject (Record<string | symbol, any>), so symbol-keyed resolver extensions type-check under GraphQL.js v17+.

Patch Changes

• security

  Fix prototype pollution in mergeIncrementalResult

  Path segments are now rejected unless they are primitive strings or numbers, and keys named __proto__, constructor or prototype are still blocked. Previously a non-primitive segment such as ["__proto__"] bypassed the string equality guard and was coerced into a write on Object.prototype.

  Also exports shared isSafeObjectKey / isDangerousObjectKey helpers used by this path walker and other package call sites. @graphql-tools/merge and @graphql-tools/mock are patched so they ship with the new imports; updateInternalDependencies raises their utils floor when 12.0.2 is versioned.

Patch Changes

• Preserve multiple applications of the same directive when extending a type even if the repeatable directive definition is not present in the merge inputs.

• Write the synthesized default operation types back onto the schema definition node, so merging a schema extension that has no operation block (federation SDL, for example) still produces a query root on graphql@17.

Patch Changes

• #8349 7fe0319 Thanks @aarne! - Pass the collected directive definitions to mergeSchemaDefs so repeatable directives on schema definitions and extend schema extensions (e.g. a repeatable @link) are kept as separate instances instead of being collapsed and having their arguments merged.