incremental delivery without branching

At a glance

• Identifier: #1023
• Stage: RFC X / Superseded
• Champion: @yaacovCR
• Latest activity: Marked as Superseded on 2025-06-12
• Spec PR: https://github.com/graphql/graphql-spec/pull/1023
• Related:
  • #742

Spec PR description

These spec edits should correspond to the working implementation at https://github.com/graphql/graphql-js/pull/3862 demonstrating incremental delivery without branching.

[The diff to main might be helpful, but this is built on top of the amazing https://github.com/graphql/graphql-spec/pull/742 and so the diff from that branch could be more useful.]

Other efforts are in the works to avoid branching, specifically #1018 and #1020. As far as I can tell, the main distinction of the approach taken by this PR is that the implementation and spec changes show how one can start executing deferred fragments semi-immediately (i.e. after deferring in an implementation-specific way), rather than waiting for the entire initial result to be emitted. This is not required -- one could still be compliant with the spec by deferring all the way until the initial result completes! In fact, how one defers is not per se observable and so the spec cannot mandate much about it with great normative force. But -- and I think this is important -- this PR and the implementation PR provide an algorithm/implementation/spec changes that give servers the flexibility to do what they think is right in that regard, and that might be desirable.

As of this moment, I am fairly confident in the implementation PR over at graphql-js, and the spec PR should generally correspond, demonstrating:

• the Field Group, Defer Usage, and Stream Usage record types that contain the complex information derived from the operation during field collection
• the new Publisher construct, which keeps track of when to release payloads
• the change from a single parent Async Payload record to potentially multiple parents
• the deferMap, which maps Defer Usage records to individual Deferred Fragment Async Payload records
• the tracking mechanism by which Deferred Fragment records are notified as complete, namely the AddPendingDeferredField and ReportDeferredValue algorithms

Deduplication and Payload Format

The implementation and these spec edits do not currently included deduplication, and the payload format is the same as the deferred fragment, but that can be easily changed as per below.

TLDR: it can be easily changed.

Adding deduplication

The algorithm includes events and handlers corresponding to:

1. the unique completion of each fields
2. the successful completion of each overall deferred fragment at a given path.

On events of type 1, fields are forwarded to each deferred fragment, and on events of type 2, the fragment including potentially duplicate values is published. We can easily change the algorithm to do something different in response to each event, without the use of WeakMap or any sort of long-lived cache.

For example:

• On events of type 1, we could immediately publish the field values
• On events of type 2, we could publish a completion notice for the fragment

Or, potentially:

• On events of type 1, we could add the field to a list of values ready to be sent -- once the first payload completes.
• On events of type 2, we could send a completion notice for the fragment and release any pending field values associated with the fragment.

Or, we could do something more complicated:

We could modify the field group collection algorithm to defined "building blocks" or subset of the deferred fragments that will combine in a predictable way no matter the order of deferred fragment completion.

• On events of type 1A, field completion, we could notify the "building block" that a field is ready.
• On events of type 1B, "building block" completion, we could notify the deferred fragment that a building block is ready
• On events of type 2, all "building blocks" for a field are ready, we could send a completion notice for the fragment and release any pending "building blocks" associated with the fragment.

** huge thanks to @urigo and @dotansimha of the guild for sponsoring my open-source work on this. **