feat: add supplemental SDL config

src/execution/execute.ts

@@ -94,18 +94,28 @@ export type RootSelectionSetExecutor = (
  * import { buildSchema } from 'graphql/utilities';
  * import { execute } from 'graphql/execution';
  *
- * const schema = buildSchema(`
- *   type Query {
- *     greeting(name: String!): String
- *   }
- * `);
+ * const schema = buildSchema(
+ *   `
+ *     type Query {
+ *       greeting(name: String!): String
+ *     }
+ *   `,
+ *   {
+ *     supplementalConfig: {
+ *       objectTypes: {
+ *         Query: {
+ *           fields: {
+ *             greeting: (_source, { name }) => `Hello, ${name}!`,
+ *           },
+ *         },
+ *       },
+ *     },
+ *   },
+ * );
  *
  * const result = await execute({
  *   schema,
  *   document: parse('query ($name: String!) { greeting(name: $name) }'),
- *   rootValue: {
- *     greeting: ({ name }) => `Hello, ${name}!`,
- *   },
  *   variableValues: { name: 'Ada' },
  * });
  *
@@ -185,16 +195,28 @@ function executeImpl(args: ExecutionArgs): PromiseOrValue<ExecutionResult> {
  * import { buildSchema } from 'graphql/utilities';
  * import { experimentalExecuteIncrementally } from 'graphql/execution';
  *
- * const schema = buildSchema(`
- *   type Query {
- *     greeting: String
- *   }
- * `);
+ * const schema = buildSchema(
+ *   `
+ *     type Query {
+ *       greeting: String
+ *     }
+ *   `,
+ *   {
+ *     supplementalConfig: {
+ *       objectTypes: {
+ *         Query: {
+ *           fields: {
+ *             greeting: () => 'Hello',
+ *           },
+ *         },
+ *       },
+ *     },
+ *   },
+ * );
  *
  * const result = await experimentalExecuteIncrementally({
  *   schema,
  *   document: parse('{ greeting }'),
- *   rootValue: { greeting: 'Hello' },
  * });
  *
  * result; // => { data: { greeting: 'Hello' } }
@@ -455,7 +477,6 @@ export function executeSubscriptionEvent(
  * @returns A response stream for a valid subscription, or an execution result containing errors.
  * @example
  * ```ts
- * // Use a same-named rootValue function to provide the source event stream.
  * import assert from 'node:assert';
  * import { parse } from 'graphql/language';
  * import { buildSchema } from 'graphql/utilities';
@@ -466,20 +487,34 @@ export function executeSubscriptionEvent(
  *   yield { greeting: 'Bonjour' };
  * }
  *
- * const schema = buildSchema(`
- *   type Query {
- *     noop: String
- *   }
- *
- *   type Subscription {
- *     greeting: String
- *   }
- * `);
+ * const schema = buildSchema(
+ *   `
+ *     type Query {
+ *       noop: String
+ *     }
+ *
+ *     type Subscription {
+ *       greeting: String
+ *     }
+ *   `,
+ *   {
+ *     supplementalConfig: {
+ *       objectTypes: {
+ *         Subscription: {
+ *           fields: {
+ *             greeting: {
+ *               subscribe: () => greetings(),
+ *             },
+ *           },
+ *         },
+ *       },
+ *     },
+ *   },
+ * );
  *
  * const result = await subscribe({
  *   schema,
  *   document: parse('subscription { greeting }'),
- *   rootValue: { greeting: () => greetings() },
  * });
  *
  * assert('next' in result);
@@ -627,19 +662,33 @@ function subscribeImpl(
  *   yield { greeting: 'Hello' };
  * }
  *
- * const schema = buildSchema(`
- *   type Query {
- *     noop: String
- *   }
- *
- *   type Subscription {
- *     greeting: String
- *   }
- * `);
+ * const schema = buildSchema(
+ *   `
+ *     type Query {
+ *       noop: String
+ *     }
+ *
+ *     type Subscription {
+ *       greeting: String
+ *     }
+ *   `,
+ *   {
+ *     supplementalConfig: {
+ *       objectTypes: {
+ *         Subscription: {
+ *           fields: {
+ *             greeting: {
+ *               subscribe: () => greetings(),
+ *             },
+ *           },
+ *         },
+ *       },
+ *     },
+ *   },
+ * );
  * const validatedArgs = validateSubscriptionArgs({
  *   schema,
  *   document: parse('subscription { greeting }'),
- *   rootValue: { greeting: () => greetings() },
  * });
  *
  * assert('schema' in validatedArgs);

src/graphql.ts

@@ -66,18 +66,28 @@ export interface GraphQLArgs
  * // Execute a complete asynchronous request with variables.
  * import { graphql, buildSchema } from 'graphql';
  *
- * const schema = buildSchema(`
- *   type Query {
- *     greeting(name: String!): String
- *   }
- * `);
+ * const schema = buildSchema(
+ *   `
+ *     type Query {
+ *       greeting(name: String!): String
+ *     }
+ *   `,
+ *   {
+ *     supplementalConfig: {
+ *       objectTypes: {
+ *         Query: {
+ *           fields: {
+ *             greeting: (_source, { name }) => `Hello, ${name}!`,
+ *           },
+ *         },
+ *       },
+ *     },
+ *   },
+ * );
  *
  * const result = await graphql({
  *   schema,
  *   source: 'query SayHello($name: String!) { greeting(name: $name) }',
- *   rootValue: {
- *     greeting: ({ name }) => `Hello, ${name}!`,
- *   },
  *   variableValues: { name: 'Ada' },
  *   operationName: 'SayHello',
  * });
@@ -124,11 +134,24 @@ export interface GraphQLArgs
  * // This variant customizes the request pipeline with a harness.
  * import { buildSchema, defaultHarness, graphql } from 'graphql';
  *
- * const schema = buildSchema(`
- *   type Query {
- *     greeting: String
- *   }
- * `);
+ * const schema = buildSchema(
+ *   `
+ *     type Query {
+ *       greeting: String
+ *     }
+ *   `,
+ *   {
+ *     supplementalConfig: {
+ *       objectTypes: {
+ *         Query: {
+ *           fields: {
+ *             greeting: () => 'Hello',
+ *           },
+ *         },
+ *       },
+ *     },
+ *   },
+ * );
  * const stages = [];
  * const abortController = new AbortController();
  * const harness = {
@@ -153,7 +176,6 @@ export interface GraphQLArgs
  * const result = await graphql({
  *   schema,
  *   source: '{ greeting }',
- *   rootValue: { greeting: 'Hello' },
  *   rules: [],
  *   maxErrors: 25,
  *   hideSuggestions: true,
@@ -186,18 +208,28 @@ export function graphql(args: GraphQLArgs): Promise<ExecutionResult> {
  * // Execute a complete synchronous request with variables.
  * import { graphqlSync, buildSchema } from 'graphql';
  *
- * const schema = buildSchema(`
- *   type Query {
- *     greeting(name: String!): String
- *   }
- * `);
+ * const schema = buildSchema(
+ *   `
+ *     type Query {
+ *       greeting(name: String!): String
+ *     }
+ *   `,
+ *   {
+ *     supplementalConfig: {
+ *       objectTypes: {
+ *         Query: {
+ *           fields: {
+ *             greeting: (_source, { name }) => `Hello, ${name}!`,
+ *           },
+ *         },
+ *       },
+ *     },
+ *   },
+ * );
  *
  * const result = graphqlSync({
  *   schema,
  *   source: 'query SayHello($name: String!) { greeting(name: $name) }',
- *   rootValue: {
- *     greeting: ({ name }) => `Hello, ${name}!`,
- *   },
  *   variableValues: { name: 'Ada' },
  *   operationName: 'SayHello',
  * });

src/index.ts

@@ -598,6 +598,20 @@ export type {
   IntrospectionEnumValue,
   IntrospectionDirective,
   BuildSchemaOptions,
+  ExtendSchemaOptions,
+  GraphQLSchemaSupplementalConfig,
+  GraphQLScalarTypeSupplementalConfig,
+  GraphQLObjectTypeSupplementalConfig,
+  GraphQLFieldSupplementalConfig,
+  GraphQLFieldSupplementalConfigMap,
+  GraphQLArgumentSupplementalConfig,
+  GraphQLInterfaceTypeSupplementalConfig,
+  GraphQLUnionTypeSupplementalConfig,
+  GraphQLEnumTypeSupplementalConfig,
+  GraphQLEnumValueSupplementalConfig,
+  GraphQLInputObjectTypeSupplementalConfig,
+  GraphQLInputFieldSupplementalConfig,
+  GraphQLDirectiveSupplementalConfig,
   BreakingChange,
   SafeChange,
   DangerousChange,

src/type/scalars.ts

@@ -335,14 +335,20 @@ export const specifiedScalarTypes: ReadonlyArray<GraphQLScalarType> =
  * @example
  * ```ts
  * import {
- *   GraphQLScalarType,
+ *   assertScalarType,
  *   GraphQLString,
  *   isSpecifiedScalarType,
  * } from 'graphql/type';
+ * import { buildSchema } from 'graphql/utilities';
  *
- * const DateTime = new GraphQLScalarType({
- *   name: 'DateTime',
- * });
+ * const schema = buildSchema(`
+ *   scalar DateTime
+ *
+ *   type Query {
+ *     now: DateTime
+ *   }
+ * `);
+ * const DateTime = assertScalarType(schema.getType('DateTime'));
  *
  * isSpecifiedScalarType(GraphQLString); // => true
  * isSpecifiedScalarType(DateTime); // => false

src/utilities/__tests__/buildASTSchema-test.ts

@@ -1089,6 +1089,33 @@ describe('Schema Builder', () => {
     buildSchema(sdl, { assumeValidSDL: true });
   });
 
+  it('Rejects invalid supplemental config by default', () => {
+    const supplementalConfig = {
+      objectTypes: {
+        Missing: {},
+      },
+    };
+
+    expect(() => buildSchema('type Query', { supplementalConfig })).to.throw(
+      'Type supplemental config "Missing" does not match a type declared by the document.',
+    );
+  });
+
+  it('Allows to disable supplemental config validation', () => {
+    const supplementalConfig = {
+      objectTypes: {
+        Missing: {},
+      },
+    };
+
+    expect(() =>
+      buildSchema('type Query', {
+        assumeValidSupplementalConfig: true,
+        supplementalConfig,
+      }),
+    ).to.not.throw();
+  });
+
   it('buildSchema parses directives on directive definitions', () => {
     const schema = buildSchema(
       dedent`