add graphql "harness" abstraction along with async parse/validate support (#4562)

This PR extends the functionality of the graphql function by allowing users to pass in a custom harness with user-supplied parse/validate/execute/subscribe functions. This allows users to pass custom versions of those functions, enabling a simple API for adding pre/post hooks, a very simplified version of the pattern introduced by [Envelop](https://the-guild.dev/graphql/envelop).

Although this extends what is possible with the graphql function, which is neat, the underlying purpose is not to compete with Envelop and other frameworks, but rather to facilitate them, background at #3421.

The introduction of the `GraphQLParseFn`, `GraphQLValidateFn`, `GraphQLExecuteFn` and `GraphQLSubscribeFn` types for the functions which make up the harness include purposeful maybe-async return types, even though our internal
`parse` and `validate` functions are always sync, to encourage servers and other tooling to expect that user-supplied versions of these functions may have async pre/post hooks.

This is a softened response to the request by Envelop maintainers in #3421 to wrap the `parse` result in a promise. This PR nudges servers and other tooling in that direction by exposing types that return maybe-async results, but is a non-breaking change.

Co-authored-by: Laurin Quast <laurinquast@googlemail.com>

Author: yaacovCR

src/__tests__/graphql-test.ts

@@ -11,7 +11,10 @@ import { GraphQLSchema } from '../type/schema.js';
 
 import type { ValidationRule } from '../validation/ValidationContext.js';
 
+import { execute } from '../execution/execute.js';
+
 import { graphql, graphqlSync } from '../graphql.js';
+import { defaultHarness } from '../harness.js';
 
 const schema = new GraphQLSchema({
   query: new GraphQLObjectType({
@@ -139,6 +142,109 @@ describe('graphql', () => {
       'Query root type must be provided.',
     );
   });
+
+  it('works when a custom harness is provided', async () => {
+    const result = await graphql({
+      schema,
+      source: '{ syncField }',
+      rootValue: 'rootValue',
+      harness: {
+        ...defaultHarness,
+        execute: (args) =>
+          execute({ ...args, rootValue: `**${args.rootValue}**` }),
+      },
+    });
+
+    expect(result).to.deep.equal({ data: { syncField: '**rootValue**' } });
+  });
+
+  it('returns parse errors thrown synchronously by a custom harness', async () => {
+    const parseError = new GraphQLError('sync parse error');
+    const result = await graphql({
+      schema,
+      source: '{ syncField }',
+      harness: {
+        ...defaultHarness,
+        parse: () => {
+          throw parseError;
+        },
+      },
+    });
+
+    expect(result).to.deep.equal({ errors: [parseError] });
+  });
+
+  it('works with asynchronous parse from a custom harness', async () => {
+    const result = await graphql({
+      schema,
+      source: '{ syncField }',
+      rootValue: 'rootValue',
+      harness: {
+        ...defaultHarness,
+        parse: (source, options) =>
+          Promise.resolve(defaultHarness.parse(source, options)),
+      },
+    });
+
+    expect(result).to.deep.equal({ data: { syncField: 'rootValue' } });
+  });
+
+  it('handles errors from an asynchronous parse from a custom harness', async () => {
+    const parseError = new GraphQLError('async parse error');
+    const result = await graphql({
+      schema,
+      source: '{ syncField }',
+      harness: {
+        ...defaultHarness,
+        parse: () => Promise.reject(parseError),
+      },
+    });
+
+    expect(result).to.deep.equal({ errors: [parseError] });
+  });
+
+  it('works with asynchronous validation from a custom harness', async () => {
+    const result = await graphql({
+      schema,
+      source: '{ syncField }',
+      rootValue: 'rootValue',
+      harness: {
+        ...defaultHarness,
+        validate: (s, document) =>
+          Promise.resolve(defaultHarness.validate(s, document)),
+      },
+    });
+
+    expect(result).to.deep.equal({ data: { syncField: 'rootValue' } });
+  });
+
+  it('returns validation errors from synchronous validation from a custom harness', async () => {
+    const validationError = new GraphQLError('async validation error');
+    const result = await graphql({
+      schema,
+      source: '{ syncField }',
+      harness: {
+        ...defaultHarness,
+        validate: () => [validationError],
+      },
+    });
+
+    expect(result).to.deep.equal({ errors: [validationError] });
+  });
+
+  it('returns validation errors from asynchronous validation from a custom harness', async () => {
+    const validationError = new GraphQLError('async validation error');
+    const result = await graphql({
+      schema,
+      source: '{ syncField }',
+      harness: {
+        ...defaultHarness,
+        validate: () => Promise.resolve([validationError]),
+      },
+    });
+
+    expect(result).to.deep.equal({ errors: [validationError] });
+  });
 });
 
 describe('graphqlSync', () => {

src/graphql.ts

@@ -1,20 +1,24 @@
 import { isPromise } from './jsutils/isPromise.js';
 import type { PromiseOrValue } from './jsutils/PromiseOrValue.js';
 
+import type { GraphQLError } from './error/GraphQLError.js';
+
+import type { DocumentNode } from './language/ast.js';
 import type { ParseOptions } from './language/parser.js';
-import { parse } from './language/parser.js';
 import type { Source } from './language/source.js';
 
+import type { GraphQLSchema } from './type/schema.js';
 import { validateSchema } from './type/validate.js';
 
 import type { ValidationOptions } from './validation/validate.js';
-import { validate } from './validation/validate.js';
 import type { ValidationRule } from './validation/ValidationContext.js';
 
 import type { ExecutionArgs } from './execution/execute.js';
-import { execute } from './execution/execute.js';
 import type { ExecutionResult } from './execution/Executor.js';
 
+import type { GraphQLHarness } from './harness.js';
+import { defaultHarness } from './harness.js';
+
 /**
  * This is the primary entry point function for fulfilling GraphQL operations
  * by parsing, validating, and executing a GraphQL document along side a
@@ -58,6 +62,7 @@ export interface GraphQLArgs
   extends ParseOptions,
     ValidationOptions,
     Omit<ExecutionArgs, 'document'> {
+  harness?: GraphQLHarness | undefined;
   source: string | Source;
   rules?: ReadonlyArray<ValidationRule> | undefined;
 }
@@ -85,6 +90,7 @@ export function graphqlSync(args: GraphQLArgs): ExecutionResult {
 }
 
 function graphqlImpl(args: GraphQLArgs): PromiseOrValue<ExecutionResult> {
+  const harness = args.harness ?? defaultHarness;
   const { schema, source } = args;
 
   // Validate Schema
@@ -96,17 +102,55 @@ function graphqlImpl(args: GraphQLArgs): PromiseOrValue<ExecutionResult> {
   // Parse
   let document;
   try {
-    document = parse(source, args);
+    document = harness.parse(source, args);
   } catch (syntaxError) {
     return { errors: [syntaxError] };
   }
 
+  if (isPromise(document)) {
+    return document.then(
+      (resolvedDocument) =>
+        validateAndExecute(harness, args, schema, resolvedDocument),
+      (syntaxError: unknown) => ({ errors: [syntaxError as GraphQLError] }),
+    );
+  }
+
+  return validateAndExecute(harness, args, schema, document);
+}
+
+function validateAndExecute(
+  harness: GraphQLHarness,
+  args: GraphQLArgs,
+  schema: GraphQLSchema,
+  document: DocumentNode,
+): PromiseOrValue<ExecutionResult> {
   // Validate
-  const validationErrors = validate(schema, document, args.rules, args);
-  if (validationErrors.length > 0) {
-    return { errors: validationErrors };
+  const validationResult = harness.validate(schema, document, args.rules, args);
+
+  if (isPromise(validationResult)) {
+    return validationResult.then((resolvedValidationResult) =>
+      checkValidationAndExecute(
+        harness,
+        args,
+        resolvedValidationResult,
+        document,
+      ),
+    );
+  }
+
+  return checkValidationAndExecute(harness, args, validationResult, document);
+}
+
+function checkValidationAndExecute(
+  harness: GraphQLHarness,
+  args: GraphQLArgs,
+  validationResult: ReadonlyArray<GraphQLError>,
+  document: DocumentNode,
+): PromiseOrValue<ExecutionResult> {
+  if (validationResult.length > 0) {
+    return { errors: validationResult };
   }
 
   // Execute
-  return execute({ ...args, document });
+  return harness.execute({ ...args, document });
 }

src/harness.ts

@@ -0,0 +1,37 @@
+import type { PromiseOrValue } from './jsutils/PromiseOrValue.js';
+
+import { parse } from './language/parser.js';
+
+import { validate } from './validation/validate.js';
+
+import { execute, subscribe } from './execution/execute.js';
+
+export type GraphQLParseFn = (
+  ...args: Parameters<typeof parse>
+) => PromiseOrValue<ReturnType<typeof parse>>;
+
+export type GraphQLValidateFn = (
+  ...args: Parameters<typeof validate>
+) => PromiseOrValue<ReturnType<typeof validate>>;
+
+export type GraphQLExecuteFn = (
+  ...args: Parameters<typeof execute>
+) => ReturnType<typeof execute>;
+
+export type GraphQLSubscribeFn = (
+  ...args: Parameters<typeof subscribe>
+) => ReturnType<typeof subscribe>;
+
+export interface GraphQLHarness {
+  parse: GraphQLParseFn;
+  validate: GraphQLValidateFn;
+  execute: GraphQLExecuteFn;
+  subscribe: GraphQLSubscribeFn;
+}
+
+export const defaultHarness: GraphQLHarness = {
+  parse,
+  validate,
+  execute,
+  subscribe,
+};

src/index.ts

@@ -36,6 +36,16 @@ export { enableDevMode, isDevModeEnabled } from './devMode.js';
 export type { GraphQLArgs } from './graphql.js';
 export { graphql, graphqlSync } from './graphql.js';
 
+// The default versions of the parse/validate/execute/subscribe harness used by `graphql` and `graphqlSync`.
+export { defaultHarness } from './harness.js';
+export type {
+  GraphQLHarness,
+  GraphQLParseFn,
+  GraphQLValidateFn,
+  GraphQLExecuteFn,
+  GraphQLSubscribeFn,
+} from './harness.js';
+
 // Create and operate on GraphQL type definitions and schema.
 export type {
   GraphQLField,