@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.