add graphql "harness" abstraction along with async parse/validate support

see graphql#3421

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
@@ -60,6 +64,7 @@ export interface GraphQLArgs
   extends ParseOptions,
     ValidationOptions,
     Omit<ExecutionArgs, 'document'> {
+  harness?: GraphQLHarness | undefined;
   source: string | Source;
   rules?: ReadonlyArray<ValidationRule> | undefined;
 }
@@ -87,6 +92,7 @@ export function graphqlSync(args: GraphQLArgs): ExecutionResult {
 }
 
 function graphqlImpl(args: GraphQLArgs): PromiseOrValue<ExecutionResult> {
+  const harness = args.harness ?? defaultHarness;
   const { schema, source } = args;
 
   // Validate Schema
@@ -98,17 +104,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,