Add @defer directive to specified directives

src/index.d.ts

@@ -54,6 +54,7 @@ export {
   specifiedDirectives,
   GraphQLIncludeDirective,
   GraphQLSkipDirective,
+  GraphQLDeferDirective,
   GraphQLDeprecatedDirective,
   GraphQLSpecifiedByDirective,
   // "Enum" of Type Kinds

src/index.js

@@ -53,6 +53,7 @@ export {
   specifiedDirectives,
   GraphQLIncludeDirective,
   GraphQLSkipDirective,
+  GraphQLDeferDirective,
   GraphQLDeprecatedDirective,
   GraphQLSpecifiedByDirective,
   // "Enum" of Type Kinds

src/type/__tests__/introspection-test.js

@@ -936,6 +936,31 @@ describe('Introspection', () => {
                 },
               ],
             },
+            {
+              name: 'defer',
+              isRepeatable: false,
+              locations: ['FRAGMENT_SPREAD', 'INLINE_FRAGMENT'],
+              args: [
+                {
+                  defaultValue: null,
+                  name: 'if',
+                  type: {
+                    kind: 'SCALAR',
+                    name: 'Boolean',
+                    ofType: null,
+                  },
+                },
+                {
+                  defaultValue: null,
+                  name: 'label',
+                  type: {
+                    kind: 'SCALAR',
+                    name: 'String',
+                    ofType: null,
+                  },
+                },
+              ],
+            },
             {
               name: 'deprecated',
               isRepeatable: false,

src/type/directives.d.ts

@@ -73,6 +73,11 @@ export const GraphQLIncludeDirective: GraphQLDirective;
  */
 export const GraphQLSkipDirective: GraphQLDirective;
 
+/**
+ * Used to conditionally defer fragments.
+ */
+export const GraphQLDeferDirective: GraphQLDirective;
+
 /**
  * Used to provide a URL for specifying the behavior of custom scalar definitions.
  */

src/type/directives.js

@@ -170,6 +170,29 @@ export const GraphQLSkipDirective = new GraphQLDirective({
   },
 });
 
+/**
+ * Used to conditionally defer fragments.
+ */
+export const GraphQLDeferDirective = new GraphQLDirective({
+  name: 'defer',
+  description:
+    'Directs the executor to defer this fragment when the `if` argument is true or undefined.',
+  locations: [
+    DirectiveLocation.FRAGMENT_SPREAD,
+    DirectiveLocation.INLINE_FRAGMENT,
+  ],
+  args: {
+    if: {
+      type: GraphQLBoolean,
+      description: 'Deferred when true or undefined.',
+    },
+    label: {
+      type: GraphQLString,
+      description: 'Unique name',
+    },
+  },
+});
+
 /**
  * Constant string used for default reason for a deprecation.
  */
@@ -218,6 +241,7 @@ export const GraphQLSpecifiedByDirective = new GraphQLDirective({
 export const specifiedDirectives = Object.freeze([
   GraphQLIncludeDirective,
   GraphQLSkipDirective,
+  GraphQLDeferDirective,
   GraphQLDeprecatedDirective,
   GraphQLSpecifiedByDirective,
 ]);

src/type/index.d.ts

@@ -125,6 +125,7 @@ export {
   specifiedDirectives,
   GraphQLIncludeDirective,
   GraphQLSkipDirective,
+  GraphQLDeferDirective,
   GraphQLDeprecatedDirective,
   GraphQLSpecifiedByDirective,
   // Constant Deprecation Reason

src/type/index.js

@@ -76,6 +76,7 @@ export {
   specifiedDirectives,
   GraphQLIncludeDirective,
   GraphQLSkipDirective,
+  GraphQLDeferDirective,
   GraphQLDeprecatedDirective,
   GraphQLSpecifiedByDirective,
   // Constant Deprecation Reason

src/utilities/__tests__/buildASTSchema-test.js

@@ -20,6 +20,7 @@ import {
   GraphQLIncludeDirective,
   GraphQLDeprecatedDirective,
   GraphQLSpecifiedByDirective,
+  GraphQLDeferDirective,
 } from '../../type/directives';
 import {
   GraphQLID,
@@ -221,12 +222,13 @@ describe('Schema Builder', () => {
     expect(cycleSDL(sdl)).to.equal(sdl);
   });
 
-  it('Maintains @include, @skip & @specifiedBy', () => {
+  it('Maintains specified directives', () => {
     const schema = buildSchema('type Query');
 
-    expect(schema.getDirectives()).to.have.lengthOf(4);
+    expect(schema.getDirectives()).to.have.lengthOf(5);
     expect(schema.getDirective('skip')).to.equal(GraphQLSkipDirective);
     expect(schema.getDirective('include')).to.equal(GraphQLIncludeDirective);
+    expect(schema.getDirective('defer')).to.equal(GraphQLDeferDirective);
     expect(schema.getDirective('deprecated')).to.equal(
       GraphQLDeprecatedDirective,
     );
@@ -241,9 +243,10 @@ describe('Schema Builder', () => {
       directive @include on FIELD
       directive @deprecated on FIELD_DEFINITION
       directive @specifiedBy on FIELD_DEFINITION
+      directive @defer on FRAGMENT_SPREAD
     `);
 
-    expect(schema.getDirectives()).to.have.lengthOf(4);
+    expect(schema.getDirectives()).to.have.lengthOf(5);
     expect(schema.getDirective('skip')).to.not.equal(GraphQLSkipDirective);
     expect(schema.getDirective('include')).to.not.equal(
       GraphQLIncludeDirective,
@@ -254,16 +257,18 @@ describe('Schema Builder', () => {
     expect(schema.getDirective('specifiedBy')).to.not.equal(
       GraphQLSpecifiedByDirective,
     );
+    expect(schema.getDirective('defer')).to.not.equal(GraphQLDeferDirective);
   });
 
-  it('Adding directives maintains @include, @skip & @specifiedBy', () => {
+  it('Adding directives maintains specified directives', () => {
     const schema = buildSchema(`
       directive @foo(arg: Int) on FIELD
     `);
 
-    expect(schema.getDirectives()).to.have.lengthOf(5);
+    expect(schema.getDirectives()).to.have.lengthOf(6);
     expect(schema.getDirective('skip')).to.not.equal(undefined);
     expect(schema.getDirective('include')).to.not.equal(undefined);
+    expect(schema.getDirective('defer')).to.not.equal(undefined);
     expect(schema.getDirective('deprecated')).to.not.equal(undefined);
     expect(schema.getDirective('specifiedBy')).to.not.equal(undefined);
   });

src/utilities/__tests__/findBreakingChanges-test.js

@@ -4,6 +4,7 @@ import { describe, it } from 'mocha';
 import { GraphQLSchema } from '../../type/schema';
 import {
   GraphQLSkipDirective,
+  GraphQLDeferDirective,
   GraphQLIncludeDirective,
   GraphQLSpecifiedByDirective,
   GraphQLDeprecatedDirective,
@@ -802,6 +803,7 @@ describe('findBreakingChanges', () => {
         GraphQLSkipDirective,
         GraphQLIncludeDirective,
         GraphQLSpecifiedByDirective,
+        GraphQLDeferDirective,
       ],
     });
 

src/utilities/__tests__/printSchema-test.js

@@ -627,6 +627,17 @@ describe('Type System Printer', () => {
         if: Boolean!
       ) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT
 
+      """
+      Directs the executor to defer this fragment when the \`if\` argument is true or undefined.
+      """
+      directive @defer(
+        """Deferred when true or undefined."""
+        if: Boolean
+      
+        """Unique name"""
+        label: String
+      ) on FRAGMENT_SPREAD | INLINE_FRAGMENT
+
       """Marks an element of a GraphQL schema as no longer supported."""
       directive @deprecated(
         """