Experimental Specification Features

GraphQL.js v17 release candidate supports several GraphQL specification proposals. This page lists experimental features available in the v17 release-candidate line; not every feature listed here is new to v17. These features are intentionally explicit: syntax usually requires a parser option or schema directive, and execution behavior usually requires a specific executor.

GraphQL.js-specific runtime APIs, such as abort signals, execution hooks, and the harness API, are documented separately because they are not GraphQL language features.

Incremental delivery

Incremental delivery adds @defer, @stream, and execution results with initial and subsequent payloads.

The relevant GraphQL.js APIs are GraphQLDeferDirective, GraphQLStreamDirective, and experimentalExecuteIncrementally(). GraphQL.js does not include the directives in specifiedDirectives; a schema that uses them should add them explicitly and execute matching operations with experimentalExecuteIncrementally(). If you add them programmatically with the GraphQLSchema directives config property, include specifiedDirectives as well. Providing directives replaces the default directive list, whose default value is specifiedDirectives.

See Defer and Stream.

Disabling error propagation

Disabling error propagation lets an execution error resolve the errored response position to null without nulling out non-null parent fields. GraphQL.js exposes this through the experimental operation directive @experimental_disableErrorPropagation.

The motivations are:

• Preserve useful partial data. A failed field should not necessarily remove sibling response data that resolved successfully.
• Keep normalized caches safe. A bubbled ancestor null can look like a real object update when only one descendant field failed.
• Separate execution errors from true semantic nullability. Schema nullability should be able to express whether null is a normal domain value, not whether a resolver might fail.

This feature is part of a longer nullability and error-handling proposal thread. The latest proposals to follow are Error Behavior, which defines client-selected onError modes, and Service Capabilities, which pulls the capabilities work out into the introspection mechanism clients use to discover support, accepted modes, and default behavior.

See Disabling Error Propagation.

Fragment arguments

Fragment arguments let named fragments declare local variables and let named fragment spreads pass values for them. GraphQL.js exposes the syntax through the experimentalFragmentArguments parser option. The AST surface includes FragmentArgumentNode, and execution supports the resulting values.

See Fragment Arguments.