graphql 17.0.0-beta.2 → 17.0.0

package/README.md

@@ -1,11 +1,9 @@
-[![GraphQLConf 2025 Banner: September 08-10, Amsterdam. Hosted by the GraphQL Foundation](./assets/graphql-conf-2025.png)](https://graphql.org/conf/2025/?utm_source=github&utm_medium=graphql_js&utm_campaign=readme)
-
 # GraphQL.js
 
 The JavaScript reference implementation for GraphQL, a query language for APIs created by Facebook.
 
 [![npm version](https://badge.fury.io/js/graphql.svg)](https://badge.fury.io/js/graphql)
-[![Build Status](https://github.com/graphql/graphql-js/workflows/CI/badge.svg?branch=main)](https://github.com/graphql/graphql-js/actions?query=branch%3Amain)
+[![Build Status](https://github.com/graphql/graphql-js/actions/workflows/push.yml/badge.svg?branch=17.x.x)](https://github.com/graphql/graphql-js/actions/workflows/push.yml?query=branch%3A17.x.x)
 
 See more complete documentation at https://graphql.org/ and
 https://graphql.org/graphql-js/.
@@ -111,7 +109,7 @@ graphql({ schema, source }).then((result) => {
 ## Want to ride the bleeding edge?
 
 The `npm` branch in this repository is automatically maintained to be the last
-commit to `main` to pass all tests, in the same form found on npm. It is
+commit to `17.x.x` to pass all tests, in the same form found on npm. It is
 recommended to use builds deployed to npm for many reasons, but if you want to use
 the latest not-yet-released version of graphql-js, you can do so by depending
 directly on this branch:
@@ -139,7 +137,7 @@ in files with the `.js` extension and the ESModule build within `.mjs` files.
 
 We actively welcome pull requests. Learn how to [contribute](./.github/CONTRIBUTING.md).
 
-This repository is managed by EasyCLA. Project participants must sign the free ([GraphQL Specification Membership agreement](https://preview-spec-membership.graphql.org) before making a contribution. You only need to do this one time, and it can be signed by [individual contributors](http://individual-spec-membership.graphql.org/) or their [employers](http://corporate-spec-membership.graphql.org/).
+This repository is managed by EasyCLA. Project participants must sign the free [GraphQL Specification Membership agreement](https://preview-spec-membership.graphql.org) before making a contribution. You only need to do this one time, and it can be signed by [individual contributors](http://individual-spec-membership.graphql.org/) or their [employers](http://corporate-spec-membership.graphql.org/).
 
 To initiate the signature process please open a PR against this repo. The EasyCLA bot will block the merge if we still need a membership agreement from you.
 

package/__dev__/diagnostics.d.mts

@@ -0,0 +1 @@
+export * from '../diagnostics.mjs';

package/__dev__/diagnostics.d.ts

@@ -0,0 +1 @@
+export * from '../diagnostics.js';

package/__dev__/diagnostics.js

@@ -0,0 +1,3 @@
+const { enableDevMode } = require('../devMode.js');
+enableDevMode();
+module.exports = require('../diagnostics.js');

package/__dev__/diagnostics.mjs

@@ -0,0 +1,3 @@
+import { enableDevMode } from '../devMode.mjs';
+enableDevMode();
+export * from '../diagnostics.mjs';

package/diagnostics.d.mts

@@ -0,0 +1,307 @@
+/**
+ * TracingChannel integration.
+ *
+ * GraphQL.js publishes lifecycle events on a set of named tracing channels
+ * that application performance monitoring (APM) tools can subscribe to in
+ * order to observe parse, validate, execute, subscribe, and resolver behavior,
+ * plus selected executor internals. At module load time GraphQL.js resolves
+ * `node:diagnostics_channel` itself so APMs do not need to interact with the
+ * GraphQL API to enable tracing. On runtimes that do not expose
+ * `node:diagnostics_channel` (e.g., browsers) the load silently no-ops and
+ * emission sites short-circuit.
+ *
+ * Within the tracing context types, `error` means the traced JavaScript call
+ * threw or rejected; it does not mean every `GraphQLError` returned by
+ * GraphQL.js. Some channels complete normally and publish GraphQL errors on
+ * `result`. Resolver errors can appear both as `message.error` on
+ * `graphql:resolve` and as formatted errors in an enclosing execution or
+ * subscription result. `graphql:parse`, `graphql:validate`, and
+ * `graphql:execute:variableCoercion` are sync-only channels.
+ * @category Diagnostics
+ */
+import type { Maybe } from "./jsutils/Maybe.mjs";
+import type { ObjMap } from "./jsutils/ObjMap.mjs";
+import type { GraphQLError } from "./error/GraphQLError.mjs";
+import type { DocumentNode, OperationDefinitionNode, OperationTypeNode } from "./language/ast.mjs";
+import type { Source } from "./language/source.mjs";
+import type { GraphQLSchema } from "./type/schema.mjs";
+import type { ExecutionResult } from "./execution/Executor.mjs";
+import type { ExperimentalIncrementalExecutionResults } from "./execution/incremental/IncrementalExecutor.mjs";
+import type { VariableValues } from "./execution/values.mjs";
+/**
+ * Structural subset of `DiagnosticsChannel` sufficient for publishing and
+ * subscriber gating. The `node:diagnostics_channel` `Channel` satisfies this.
+ *
+ * @internal
+ */
+export interface MinimalChannel<TMessage = unknown> {
+    readonly hasSubscribers?: boolean;
+    publish: (message: TMessage) => void;
+    runStores: <T, ContextType extends object>(context: ContextType, fn: (this: ContextType, ...args: Array<unknown>) => T, thisArg?: unknown, ...args: Array<unknown>) => T;
+}
+/**
+ * Structural subset of the Node.js `TracingChannel` API. The
+ * `node:diagnostics_channel` `TracingChannel` satisfies this by duck typing,
+ * so GraphQL.js does not need a dependency on `@types/node` or on the runtime
+ * itself.
+ *
+ * @internal
+ */
+export interface MinimalTracingChannel<TContext = unknown> {
+    readonly hasSubscribers: boolean | undefined;
+    readonly start: MinimalChannel<TContext>;
+    readonly end: MinimalChannel<TContext>;
+    readonly asyncStart: MinimalChannel<TContext>;
+    readonly asyncEnd: MinimalChannel<TContext>;
+    readonly error: MinimalChannel<TContext>;
+    traceSync: <T>(fn: (...args: Array<unknown>) => T, context: TContext extends object ? TContext : object, thisArg?: unknown, ...args: Array<unknown>) => T;
+}
+/** Context published on the sync-only `graphql:parse` channel. */
+export interface GraphQLParseContext {
+    /** Source text or source object passed to the parser. */
+    source: string | Source;
+    /** Error thrown while parsing, when parsing fails. */
+    error?: unknown;
+    /** Parsed document, when parsing succeeds. */
+    result?: DocumentNode;
+}
+/** Context published on the sync-only `graphql:validate` channel. */
+export interface GraphQLValidateContext {
+    /** Schema used for validation. */
+    schema: GraphQLSchema;
+    /** Parsed document being validated. */
+    document: DocumentNode;
+    /** Error thrown while validating, when validation fails abruptly. */
+    error?: unknown;
+    /** Validation errors returned by validation. */
+    result?: ReadonlyArray<GraphQLError>;
+}
+/**
+ * Context published on `graphql:execute`.
+ *
+ * Returned results may contain GraphQL errors collected during execution.
+ */
+export interface GraphQLExecuteContext {
+    /** Schema used for execution. */
+    schema: GraphQLSchema;
+    /** Parsed document being executed. */
+    document: DocumentNode;
+    /** Raw variable values provided by the caller before coercion. */
+    rawVariableValues: Maybe<{
+        readonly [variable: string]: unknown;
+    }>;
+    /** Selected operation name, if one is available. */
+    operationName: string | undefined;
+    /** Selected operation type, if one is available. */
+    operationType: OperationTypeNode | undefined;
+    /** Error thrown or rejected while executing, when execution fails abruptly. */
+    error?: unknown;
+    /** Execution result returned by execution, including GraphQL errors. */
+    result?: ExecutionResult | ExperimentalIncrementalExecutionResults;
+}
+/**
+ * Context published on `graphql:execute:rootSelectionSet`.
+ *
+ * Returned results may contain GraphQL errors collected during execution.
+ */
+export interface GraphQLExecuteRootSelectionSetContext {
+    /** Schema used for execution. */
+    schema: GraphQLSchema;
+    /** Parsed document being executed. */
+    document: DocumentNode;
+    /** Operation definition selected for execution. */
+    operation: OperationDefinitionNode;
+    /** Raw variable values provided by the caller before coercion. */
+    rawVariableValues: Maybe<{
+        readonly [variable: string]: unknown;
+    }>;
+    /** Selected operation name, if one is available. */
+    operationName: string | undefined;
+    /** Selected operation type. */
+    operationType: OperationTypeNode;
+    /** Error thrown or rejected while executing the root selection set. */
+    error?: unknown;
+    /**
+     * Execution result returned from the root selection set, including GraphQL
+     * errors.
+     */
+    result?: ExecutionResult | ExperimentalIncrementalExecutionResults;
+}
+/**
+ * Context published on `graphql:execute:variableCoercion`.
+ *
+ * Coercion runs synchronously while execution arguments are validated, so only
+ * the `start`/`end` (and, on an abrupt throw, `error`) lifecycle fires.
+ * Ordinary variable coercion failures are returned on `result.errors`; when
+ * execution is invoked through APIs such as `execute()` or `subscribe()`, they
+ * surface as GraphQL result errors rather than as the tracing `error`
+ * lifecycle event.
+ */
+export interface GraphQLExecuteVariableCoercionContext {
+    /** Schema used for variable coercion. */
+    schema: GraphQLSchema;
+    /** Parsed document being executed. */
+    document: DocumentNode;
+    /** Operation definition whose variables are being coerced. */
+    operation: OperationDefinitionNode;
+    /** Raw variable values provided by the caller before coercion. */
+    rawVariableValues: Maybe<{
+        readonly [variable: string]: unknown;
+    }>;
+    /** Selected operation name, if one is available. */
+    operationName: string | undefined;
+    /** Selected operation type. */
+    operationType: OperationTypeNode;
+    /** Error thrown while coercing variables, when coercion fails abruptly. */
+    error?: unknown;
+    /** Coerced variable values or coercion errors returned by coercion. */
+    result?: {
+        variableValues: VariableValues;
+    } | {
+        errors: ReadonlyArray<GraphQLError>;
+    };
+}
+/**
+ * Context published on `graphql:subscribe`.
+ *
+ * Subscription source resolver errors and invalid source stream results are
+ * returned on `result` as ExecutionResult errors; they do not publish the
+ * `error` lifecycle event unless subscription setup fails abruptly before
+ * GraphQL can form a result.
+ */
+export interface GraphQLSubscribeContext {
+    /** Schema used for subscription execution. */
+    schema: GraphQLSchema;
+    /** Parsed subscription document. */
+    document: DocumentNode;
+    /** Raw variable values provided by the caller before coercion. */
+    rawVariableValues: Maybe<{
+        readonly [variable: string]: unknown;
+    }>;
+    /** Selected operation name, if one is available. */
+    operationName: string | undefined;
+    /** Selected operation type, if one is available. */
+    operationType: OperationTypeNode | undefined;
+    /** Error thrown or rejected while subscribing, when setup fails abruptly. */
+    error?: unknown;
+    /**
+     * Subscription response stream, or an ExecutionResult containing GraphQL
+     * errors.
+     */
+    result?: AsyncGenerator<ExecutionResult, void, void> | ExecutionResult;
+}
+/**
+ * Context published on `graphql:resolve`.
+ *
+ * Resolver throws and rejections publish the `error` lifecycle event here.
+ * The same failure may also be formatted into the enclosing execution or
+ * subscription result.
+ */
+export interface GraphQLResolveContext {
+    /** Field name being resolved. */
+    fieldName: string;
+    /** Response alias for the field being resolved. */
+    alias: string;
+    /** Parent type name for the field being resolved. */
+    parentType: string;
+    /** Return type string for the field being resolved. */
+    fieldType: string;
+    /** Argument values passed to the resolver. */
+    args: ObjMap<unknown>;
+    /** Whether the field is using the default resolver. */
+    isDefaultResolver: boolean;
+    /** Response path for the field being resolved. */
+    fieldPath: string;
+    /** Error thrown or rejected by the resolver, when resolution fails. */
+    error?: unknown;
+    /** Value returned by the resolver, when resolution succeeds. */
+    result?: unknown;
+}
+/** Mapping from tracing channel name to the context type published on it. */
+export interface GraphQLChannelContextByName {
+    /** Context published on `graphql:parse`. */
+    'graphql:parse': GraphQLParseContext;
+    /** Context published on `graphql:validate`. */
+    'graphql:validate': GraphQLValidateContext;
+    /** Context published on `graphql:execute`. */
+    'graphql:execute': GraphQLExecuteContext;
+    /** Context published on `graphql:execute:variableCoercion`. */
+    'graphql:execute:variableCoercion': GraphQLExecuteVariableCoercionContext;
+    /** Context published on `graphql:execute:rootSelectionSet`. */
+    'graphql:execute:rootSelectionSet': GraphQLExecuteRootSelectionSetContext;
+    /** Context published on `graphql:subscribe`. */
+    'graphql:subscribe': GraphQLSubscribeContext;
+    /** Context published on `graphql:resolve`. */
+    'graphql:resolve': GraphQLResolveContext;
+}
+/**
+ * The collection of tracing channels GraphQL.js emits on. Application
+ * performance monitoring (APM) tools subscribe to these by name on their own
+ * `node:diagnostics_channel` import; both paths land on the same channel
+ * instance because `tracingChannel(name)` is cached by name.
+ */
+export interface GraphQLChannels {
+    /** Tracing channel for `graphql:execute`. */
+    execute: MinimalTracingChannel<GraphQLExecuteContext>;
+    /** Tracing channel for `graphql:execute:variableCoercion`. */
+    executeVariableCoercion: MinimalTracingChannel<GraphQLExecuteVariableCoercionContext>;
+    /** Tracing channel for `graphql:execute:rootSelectionSet`. */
+    executeRootSelectionSet: MinimalTracingChannel<GraphQLExecuteRootSelectionSetContext>;
+    /** Tracing channel for `graphql:parse`. */
+    parse: MinimalTracingChannel<GraphQLParseContext>;
+    /** Tracing channel for `graphql:validate`. */
+    validate: MinimalTracingChannel<GraphQLValidateContext>;
+    /** Tracing channel for `graphql:resolve`. */
+    resolve: MinimalTracingChannel<GraphQLResolveContext>;
+    /** Tracing channel for `graphql:subscribe`. */
+    subscribe: MinimalTracingChannel<GraphQLSubscribeContext>;
+}
+/**
+ * Per-channel handles, resolved once at module load. `undefined` when
+ * `node:diagnostics_channel` isn't available. Emission sites read these
+ * directly to keep the no-subscriber fast path to a single property access
+ * plus a `hasSubscribers` check (no function calls, no closures).
+ *
+ * @internal
+ */
+export declare const parseChannel: MinimalTracingChannel<GraphQLParseContext> | undefined;
+/** @internal */
+export declare const validateChannel: MinimalTracingChannel<GraphQLValidateContext> | undefined;
+/** @internal */
+export declare const executeChannel: MinimalTracingChannel<GraphQLExecuteContext> | undefined;
+/** @internal */
+export declare const executeVariableCoercionChannel: MinimalTracingChannel<GraphQLExecuteVariableCoercionContext> | undefined;
+/** @internal */
+export declare const executeRootSelectionSetChannel: MinimalTracingChannel<GraphQLExecuteRootSelectionSetContext> | undefined;
+/** @internal */
+export declare const subscribeChannel: MinimalTracingChannel<GraphQLSubscribeContext> | undefined;
+/** @internal */
+export declare const resolveChannel: MinimalTracingChannel<GraphQLResolveContext> | undefined;
+/**
+ * Whether emission sites should publish to `channel`. Trusts the
+ * `TracingChannel.hasSubscribers` aggregate when the runtime exposes it; if
+ * the getter is missing (e.g. Bun's `node:diagnostics_channel`, where
+ * `tracingChannel.hasSubscribers` is `undefined`), falls back to checking
+ * each of the five underlying lifecycle channels so a subscriber attached
+ * via `tracingChannel.subscribe(handlers)` is still observed.
+ *
+ * @internal
+ */
+export declare function shouldTrace<TContext = unknown>(channel: MinimalTracingChannel<TContext> | undefined): channel is MinimalTracingChannel<TContext>;
+interface TraceLifecycleContext {
+    error?: unknown;
+    result?: unknown;
+}
+type TraceStartContext<TContext extends TraceLifecycleContext> = Omit<TContext, 'error' | 'result'>;
+/**
+ * Publish a traced call that may complete synchronously or with a promise.
+ * Caller has already verified that a subscriber is attached. On normal
+ * completion, `result` is attached before the terminal `end` or `asyncEnd`
+ * event. When the traced call throws or rejects, `error` is attached, the
+ * `error` sub-channel fires, and the terminal `end` or `asyncEnd` event is
+ * published before the original failure is propagated.
+ *
+ * @internal
+ */
+export declare function traceMixed<TResult, TContext extends TraceLifecycleContext>(channel: MinimalTracingChannel<TContext>, contextInput: TraceStartContext<TContext>, fn: () => TResult): TResult;
+export {};

package/diagnostics.d.ts

@@ -0,0 +1,307 @@
+/**
+ * TracingChannel integration.
+ *
+ * GraphQL.js publishes lifecycle events on a set of named tracing channels
+ * that application performance monitoring (APM) tools can subscribe to in
+ * order to observe parse, validate, execute, subscribe, and resolver behavior,
+ * plus selected executor internals. At module load time GraphQL.js resolves
+ * `node:diagnostics_channel` itself so APMs do not need to interact with the
+ * GraphQL API to enable tracing. On runtimes that do not expose
+ * `node:diagnostics_channel` (e.g., browsers) the load silently no-ops and
+ * emission sites short-circuit.
+ *
+ * Within the tracing context types, `error` means the traced JavaScript call
+ * threw or rejected; it does not mean every `GraphQLError` returned by
+ * GraphQL.js. Some channels complete normally and publish GraphQL errors on
+ * `result`. Resolver errors can appear both as `message.error` on
+ * `graphql:resolve` and as formatted errors in an enclosing execution or
+ * subscription result. `graphql:parse`, `graphql:validate`, and
+ * `graphql:execute:variableCoercion` are sync-only channels.
+ * @category Diagnostics
+ */
+import type { Maybe } from "./jsutils/Maybe.js";
+import type { ObjMap } from "./jsutils/ObjMap.js";
+import type { GraphQLError } from "./error/GraphQLError.js";
+import type { DocumentNode, OperationDefinitionNode, OperationTypeNode } from "./language/ast.js";
+import type { Source } from "./language/source.js";
+import type { GraphQLSchema } from "./type/schema.js";
+import type { ExecutionResult } from "./execution/Executor.js";
+import type { ExperimentalIncrementalExecutionResults } from "./execution/incremental/IncrementalExecutor.js";
+import type { VariableValues } from "./execution/values.js";
+/**
+ * Structural subset of `DiagnosticsChannel` sufficient for publishing and
+ * subscriber gating. The `node:diagnostics_channel` `Channel` satisfies this.
+ *
+ * @internal
+ */
+export interface MinimalChannel<TMessage = unknown> {
+    readonly hasSubscribers?: boolean;
+    publish: (message: TMessage) => void;
+    runStores: <T, ContextType extends object>(context: ContextType, fn: (this: ContextType, ...args: Array<unknown>) => T, thisArg?: unknown, ...args: Array<unknown>) => T;
+}
+/**
+ * Structural subset of the Node.js `TracingChannel` API. The
+ * `node:diagnostics_channel` `TracingChannel` satisfies this by duck typing,
+ * so GraphQL.js does not need a dependency on `@types/node` or on the runtime
+ * itself.
+ *
+ * @internal
+ */
+export interface MinimalTracingChannel<TContext = unknown> {
+    readonly hasSubscribers: boolean | undefined;
+    readonly start: MinimalChannel<TContext>;
+    readonly end: MinimalChannel<TContext>;
+    readonly asyncStart: MinimalChannel<TContext>;
+    readonly asyncEnd: MinimalChannel<TContext>;
+    readonly error: MinimalChannel<TContext>;
+    traceSync: <T>(fn: (...args: Array<unknown>) => T, context: TContext extends object ? TContext : object, thisArg?: unknown, ...args: Array<unknown>) => T;
+}
+/** Context published on the sync-only `graphql:parse` channel. */
+export interface GraphQLParseContext {
+    /** Source text or source object passed to the parser. */
+    source: string | Source;
+    /** Error thrown while parsing, when parsing fails. */
+    error?: unknown;
+    /** Parsed document, when parsing succeeds. */
+    result?: DocumentNode;
+}
+/** Context published on the sync-only `graphql:validate` channel. */
+export interface GraphQLValidateContext {
+    /** Schema used for validation. */
+    schema: GraphQLSchema;
+    /** Parsed document being validated. */
+    document: DocumentNode;
+    /** Error thrown while validating, when validation fails abruptly. */
+    error?: unknown;
+    /** Validation errors returned by validation. */
+    result?: ReadonlyArray<GraphQLError>;
+}
+/**
+ * Context published on `graphql:execute`.
+ *
+ * Returned results may contain GraphQL errors collected during execution.
+ */
+export interface GraphQLExecuteContext {
+    /** Schema used for execution. */
+    schema: GraphQLSchema;
+    /** Parsed document being executed. */
+    document: DocumentNode;
+    /** Raw variable values provided by the caller before coercion. */
+    rawVariableValues: Maybe<{
+        readonly [variable: string]: unknown;
+    }>;
+    /** Selected operation name, if one is available. */
+    operationName: string | undefined;
+    /** Selected operation type, if one is available. */
+    operationType: OperationTypeNode | undefined;
+    /** Error thrown or rejected while executing, when execution fails abruptly. */
+    error?: unknown;
+    /** Execution result returned by execution, including GraphQL errors. */
+    result?: ExecutionResult | ExperimentalIncrementalExecutionResults;
+}
+/**
+ * Context published on `graphql:execute:rootSelectionSet`.
+ *
+ * Returned results may contain GraphQL errors collected during execution.
+ */
+export interface GraphQLExecuteRootSelectionSetContext {
+    /** Schema used for execution. */
+    schema: GraphQLSchema;
+    /** Parsed document being executed. */
+    document: DocumentNode;
+    /** Operation definition selected for execution. */
+    operation: OperationDefinitionNode;
+    /** Raw variable values provided by the caller before coercion. */
+    rawVariableValues: Maybe<{
+        readonly [variable: string]: unknown;
+    }>;
+    /** Selected operation name, if one is available. */
+    operationName: string | undefined;
+    /** Selected operation type. */
+    operationType: OperationTypeNode;
+    /** Error thrown or rejected while executing the root selection set. */
+    error?: unknown;
+    /**
+     * Execution result returned from the root selection set, including GraphQL
+     * errors.
+     */
+    result?: ExecutionResult | ExperimentalIncrementalExecutionResults;
+}
+/**
+ * Context published on `graphql:execute:variableCoercion`.
+ *
+ * Coercion runs synchronously while execution arguments are validated, so only
+ * the `start`/`end` (and, on an abrupt throw, `error`) lifecycle fires.
+ * Ordinary variable coercion failures are returned on `result.errors`; when
+ * execution is invoked through APIs such as `execute()` or `subscribe()`, they
+ * surface as GraphQL result errors rather than as the tracing `error`
+ * lifecycle event.
+ */
+export interface GraphQLExecuteVariableCoercionContext {
+    /** Schema used for variable coercion. */
+    schema: GraphQLSchema;
+    /** Parsed document being executed. */
+    document: DocumentNode;
+    /** Operation definition whose variables are being coerced. */
+    operation: OperationDefinitionNode;
+    /** Raw variable values provided by the caller before coercion. */
+    rawVariableValues: Maybe<{
+        readonly [variable: string]: unknown;
+    }>;
+    /** Selected operation name, if one is available. */
+    operationName: string | undefined;
+    /** Selected operation type. */
+    operationType: OperationTypeNode;
+    /** Error thrown while coercing variables, when coercion fails abruptly. */
+    error?: unknown;
+    /** Coerced variable values or coercion errors returned by coercion. */
+    result?: {
+        variableValues: VariableValues;
+    } | {
+        errors: ReadonlyArray<GraphQLError>;
+    };
+}
+/**
+ * Context published on `graphql:subscribe`.
+ *
+ * Subscription source resolver errors and invalid source stream results are
+ * returned on `result` as ExecutionResult errors; they do not publish the
+ * `error` lifecycle event unless subscription setup fails abruptly before
+ * GraphQL can form a result.
+ */
+export interface GraphQLSubscribeContext {
+    /** Schema used for subscription execution. */
+    schema: GraphQLSchema;
+    /** Parsed subscription document. */
+    document: DocumentNode;
+    /** Raw variable values provided by the caller before coercion. */
+    rawVariableValues: Maybe<{
+        readonly [variable: string]: unknown;
+    }>;
+    /** Selected operation name, if one is available. */
+    operationName: string | undefined;
+    /** Selected operation type, if one is available. */
+    operationType: OperationTypeNode | undefined;
+    /** Error thrown or rejected while subscribing, when setup fails abruptly. */
+    error?: unknown;
+    /**
+     * Subscription response stream, or an ExecutionResult containing GraphQL
+     * errors.
+     */
+    result?: AsyncGenerator<ExecutionResult, void, void> | ExecutionResult;
+}
+/**
+ * Context published on `graphql:resolve`.
+ *
+ * Resolver throws and rejections publish the `error` lifecycle event here.
+ * The same failure may also be formatted into the enclosing execution or
+ * subscription result.
+ */
+export interface GraphQLResolveContext {
+    /** Field name being resolved. */
+    fieldName: string;
+    /** Response alias for the field being resolved. */
+    alias: string;
+    /** Parent type name for the field being resolved. */
+    parentType: string;
+    /** Return type string for the field being resolved. */
+    fieldType: string;
+    /** Argument values passed to the resolver. */
+    args: ObjMap<unknown>;
+    /** Whether the field is using the default resolver. */
+    isDefaultResolver: boolean;
+    /** Response path for the field being resolved. */
+    fieldPath: string;
+    /** Error thrown or rejected by the resolver, when resolution fails. */
+    error?: unknown;
+    /** Value returned by the resolver, when resolution succeeds. */
+    result?: unknown;
+}
+/** Mapping from tracing channel name to the context type published on it. */
+export interface GraphQLChannelContextByName {
+    /** Context published on `graphql:parse`. */
+    'graphql:parse': GraphQLParseContext;
+    /** Context published on `graphql:validate`. */
+    'graphql:validate': GraphQLValidateContext;
+    /** Context published on `graphql:execute`. */
+    'graphql:execute': GraphQLExecuteContext;
+    /** Context published on `graphql:execute:variableCoercion`. */
+    'graphql:execute:variableCoercion': GraphQLExecuteVariableCoercionContext;
+    /** Context published on `graphql:execute:rootSelectionSet`. */
+    'graphql:execute:rootSelectionSet': GraphQLExecuteRootSelectionSetContext;
+    /** Context published on `graphql:subscribe`. */
+    'graphql:subscribe': GraphQLSubscribeContext;
+    /** Context published on `graphql:resolve`. */
+    'graphql:resolve': GraphQLResolveContext;
+}
+/**
+ * The collection of tracing channels GraphQL.js emits on. Application
+ * performance monitoring (APM) tools subscribe to these by name on their own
+ * `node:diagnostics_channel` import; both paths land on the same channel
+ * instance because `tracingChannel(name)` is cached by name.
+ */
+export interface GraphQLChannels {
+    /** Tracing channel for `graphql:execute`. */
+    execute: MinimalTracingChannel<GraphQLExecuteContext>;
+    /** Tracing channel for `graphql:execute:variableCoercion`. */
+    executeVariableCoercion: MinimalTracingChannel<GraphQLExecuteVariableCoercionContext>;
+    /** Tracing channel for `graphql:execute:rootSelectionSet`. */
+    executeRootSelectionSet: MinimalTracingChannel<GraphQLExecuteRootSelectionSetContext>;
+    /** Tracing channel for `graphql:parse`. */
+    parse: MinimalTracingChannel<GraphQLParseContext>;
+    /** Tracing channel for `graphql:validate`. */
+    validate: MinimalTracingChannel<GraphQLValidateContext>;
+    /** Tracing channel for `graphql:resolve`. */
+    resolve: MinimalTracingChannel<GraphQLResolveContext>;
+    /** Tracing channel for `graphql:subscribe`. */
+    subscribe: MinimalTracingChannel<GraphQLSubscribeContext>;
+}
+/**
+ * Per-channel handles, resolved once at module load. `undefined` when
+ * `node:diagnostics_channel` isn't available. Emission sites read these
+ * directly to keep the no-subscriber fast path to a single property access
+ * plus a `hasSubscribers` check (no function calls, no closures).
+ *
+ * @internal
+ */
+export declare const parseChannel: MinimalTracingChannel<GraphQLParseContext> | undefined;
+/** @internal */
+export declare const validateChannel: MinimalTracingChannel<GraphQLValidateContext> | undefined;
+/** @internal */
+export declare const executeChannel: MinimalTracingChannel<GraphQLExecuteContext> | undefined;
+/** @internal */
+export declare const executeVariableCoercionChannel: MinimalTracingChannel<GraphQLExecuteVariableCoercionContext> | undefined;
+/** @internal */
+export declare const executeRootSelectionSetChannel: MinimalTracingChannel<GraphQLExecuteRootSelectionSetContext> | undefined;
+/** @internal */
+export declare const subscribeChannel: MinimalTracingChannel<GraphQLSubscribeContext> | undefined;
+/** @internal */
+export declare const resolveChannel: MinimalTracingChannel<GraphQLResolveContext> | undefined;
+/**
+ * Whether emission sites should publish to `channel`. Trusts the
+ * `TracingChannel.hasSubscribers` aggregate when the runtime exposes it; if
+ * the getter is missing (e.g. Bun's `node:diagnostics_channel`, where
+ * `tracingChannel.hasSubscribers` is `undefined`), falls back to checking
+ * each of the five underlying lifecycle channels so a subscriber attached
+ * via `tracingChannel.subscribe(handlers)` is still observed.
+ *
+ * @internal
+ */
+export declare function shouldTrace<TContext = unknown>(channel: MinimalTracingChannel<TContext> | undefined): channel is MinimalTracingChannel<TContext>;
+interface TraceLifecycleContext {
+    error?: unknown;
+    result?: unknown;
+}
+type TraceStartContext<TContext extends TraceLifecycleContext> = Omit<TContext, 'error' | 'result'>;
+/**
+ * Publish a traced call that may complete synchronously or with a promise.
+ * Caller has already verified that a subscriber is attached. On normal
+ * completion, `result` is attached before the terminal `end` or `asyncEnd`
+ * event. When the traced call throws or rejects, `error` is attached, the
+ * `error` sub-channel fires, and the terminal `end` or `asyncEnd` event is
+ * published before the original failure is propagated.
+ *
+ * @internal
+ */
+export declare function traceMixed<TResult, TContext extends TraceLifecycleContext>(channel: MinimalTracingChannel<TContext>, contextInput: TraceStartContext<TContext>, fn: () => TResult): TResult;
+export {};