@graphql-tools/utils

mapSchema now remaps directive argument defaults the same way it already remaps field argument defaults.

Use case: UserRole is remapped to internal ids, and @auth defaults to USER.

const schema = mapSchema(originalSchema, {
  [MapperKind.ENUM_VALUE]: (valueConfig, typeName, _schema, externalValue) => {
    if (typeName === 'UserRole' && externalValue === 'USER') {
      return { ...valueConfig, value: '3user' };
    }
    return valueConfig;
  },
});

// directive @auth(role: UserRole = USER)
schema.getDirective('auth').args.find(arg => arg.name === 'role').defaultValue;
// before: "USER"
// after:  "3user"

mapSchema serializes the stored default with the source type before parsing with the remapped type, so an internal value that matches another enum name (USER -> "ADMIN") stays "ADMIN" instead of being parsed as that name.

forEachDefaultValue walks directive arguments too, so makeExecutableSchema enum resolvers get the same result.

Published Executor types include /// <reference lib="esnext.disposable" preserve="true" /> so consumers do not need skipLibCheck or a full esnext lib just to import this package.

Use case: an app with "lib": ["es2022"] or ["es2024"] and skipLibCheck: false that imports @graphql-tools/utils:

import type { Executor } from '@graphql-tools/utils';

export const executor: Executor = async request => {
  // ...
};

Executor can return a Disposable / AsyncIterable result. Those names live in TypeScript's esnext.disposable lib, which is not part of es2022/es2024. Without the preserved reference, tsc reports Cannot find name 'Disposable'. With it, the published .d.ts pulls in that lib for the consumer automatically.

printSchemaWithDirectives no longer turns unquoted directive argument literals into strings.

In GraphQL SDL, an unquoted identifier in value position is an EnumValue AST node. A quoted value is a StringValue. Those are different kinds even when the argument type is a custom scalar rather than an enum type. parseLiteral on that scalar receives the original kind, so a custom scalar can treat argument_value and "argument_value" as different inputs.

The printer was reconstructing directive arguments from JS values. valueFromASTUntyped maps both kinds to the same string, and astFromValue then emits a StringValue. The printed SDL became @directive(arg: "argument_value") even though the schema AST still had @directive(arg: argument_value).

That is a round-trip / fidelity bug: loaders, schema diffs, snapshots, and subgraph publishes see different SDL, and a scalar that distinguishes the two kinds changes meaning. Default scalars coerce both to the same JS string, so many runtime paths do not notice.

When the original AST is still the source of truth, printSchemaWithDirectives now keeps those directive argument nodes, including nested list and input-object values. If directive values are supplied only through extensions (code-first), JS strings are still printed as strings because the original kind is not available.

Fixes #8557

INCREMENTAL_DELIVERY_SPECS is the shared HTTP contract for incrementalSpec. Each row maps an Accept / Content-Type parameter (deferSpec=20220824, incrementalSpec=v0.2, ...) to the executor payload id ('v0.1' | 'v0.2').

GraphQL Yoga, Hive Gateway, HTTP executors, and other servers should look up this table instead of hardcoding spec strings. When a later incremental spec ships, the work stays in graphql-tools: add a row here and an executor publisher. Consumers bump @graphql-tools/utils / @graphql-tools/executor. Accept negotiation, Content-Type echo, and 406 for unknown spec params keep working without a Yoga / Gateway / executor-http patch for the new identifier.

Unknown values for a registered parameter name stay unsupported (HTTP 406). Helpers: lookupIncrementalDeliverySpec, getMultipartContentType, getDefaultIncrementalDeliverySpec, getIncrementalSpecParameterNames.

@graphql-tools/executor can publish both incremental delivery payload formats from one execution kernel. Pass incrementalSpec: 'v0.1' | 'v0.2' on execute / subscribe / normalizedExecutor (also on ExecutionRequest for executorFromSchema). 'v0.1' remains the default and keeps the existing path / label patches used with multipart/mixed;deferSpec=20220824. 'v0.2' emits Apollo incremental v0.2 payloads (pending with id and path, incremental with id and optional subPath, completed) used with multipart/mixed;incrementalSpec=v0.2.

Field execution, @defer / @stream scheduling, and AbortSignal cancellation are shared. Spec-specific JSON is built by a publisher: v0.1 still yields { incremental, hasNext }; v0.2 assigns ids when a pending group is first announced, groups streamed items under one pending path, and reports completion separately. Nested @defer patches are collected as children of the parent patch so v0.2 can announce the inner fragment only after the parent is pending, without making the nested fragment wait on the parent's promise (v0.1 sibling completion is unchanged aside from incremental array order).

Publisher state (Map / Set of ids) is allocated only for 'v0.2'. StreamGroup is created only for v0.2 and only when items are actually streamed. v0.2 stream completion uses an open-count on the group instead of scanning subsequentPayloads.

mergeIncrementalResult still merges v0.1 path / items patches. For v0.2 it records pending ids on the execution result, writes deferred data at pending.path + subPath, appends streamed items onto the list at pending.path, and folds completed.errors into errors. visitResult flattens nested deferred patches so result visiting still sees fields that live under a child @defer.

Add asGetArgumentValuesVariables and coerceGetVariableValuesResult helpers for GraphQL 16/17 VariableValues compatibility when calling getArgumentValues / normalizing getVariableValues results for helpers like shouldIncludeNode.

Align memoize4 third-level cache initialization with the let + reassignment pattern used by memoize3 / memoize5.

Previously a nested const cache4 inside if (!cache4) shadowed the outer binding. Runtime behavior was already safe (that branch stores the map and returns), but the declaration was easy to misread and fragile if the early return were removed. The helper now assigns to the outer let cache4 instead, with regression tests for the third-level cache path.

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

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.

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:

utils: coerce GraphQL 17 argument defaults in getArgumentValues via local input coercion (defaults, missing variables, nested sources)

Keep argument types of defined directives when pruning so that unused directives such as @key(fields: _FieldSet!) retain their full definitions instead of losing the argument together with its type.

Skip empty and whitespace-only description values in getDescriptionNode / printSchemaWithDirectives, so loaders that set description: "" no longer emit """""" in printed SDL.

Compare incremental path keys to __proto__ at the property access in setObjectKeyPath, in addition to the existing isSafeObjectKey check.

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.

dependencies updates:

Fix prototype pollution in mergeDeep

Source keys named __proto__, constructor or prototype are now skipped at every recursion level, and the check for an existing key uses hasOwnProperty instead of in, so inherited properties are never used as merge targets.

Previously, merging untrusted data such as JSON.parse('{"constructor":{"__proto__":{"call":"x"}}}') could reach and overwrite properties on Object.prototype or Function.prototype.

Omit mutation/subscription from printSchemaWithDirectives when those root types are no longer present on the schema (e.g. after pruneSchema).

Allow % in paths checked by isValidPath (e.g. directories from URL-encoded repo names).

#8346 2273c21 Thanks @ardatan! - This release adds GraphQL v17 support and aligns the existing executor implementation with the latest GraphQL v17 API changes. The following changes are included: