AbortController support (#4250)

This adds support for aborting execution from the outside or resolvers,
this adds a few tests and tries to make the support as easy as possible.

Do we want to support having abort support on subscriptions, I guess it
makes sense for server-sent events.

I've chosen 2 places to place these interrupts

- `executeFieldsSerially` - every time we start a new mutation we check
whether the runtime has interrupted
- `executeFields` - every time we start executing a new field we check
whether the runtime has interrupted
- inside of the catch block as well so we return a singular error, all
though this doesn't really matter as the consumer would not receive
anything
  - this here should also take care of deferred fields

When comparing this to `graphql-tools/execute` I am not sure whether we
want to match this behavior, this throws a DomException which would be a
whole new exception that gets thrown while normally during execution we
wrap everything with GraphQLErrors.

Supersedes #3791
Resolves #3764

Co-authored-by: yaacovCR <yaacovCR@gmail.com>

Author: JoviDeCroock

integrationTests/ts/tsconfig.json

@@ -1,7 +1,13 @@
 {
   "compilerOptions": {
     "module": "commonjs",
-    "lib": ["es2019", "es2020.promise", "es2020.bigint", "es2020.string"],
+    "lib": [
+      "es2019",
+      "es2020.promise",
+      "es2020.bigint",
+      "es2020.string",
+      "DOM"
+    ],
     "noEmit": true,
     "types": [],
     "strict": true,

package-lock.json

@@ -55,7 +55,7 @@
   "devDependencies": {
     "@types/chai": "4.3.19",
     "@types/mocha": "10.0.7",
-    "@types/node": "22.5.4",
+    "@types/node": "22.7.7",
     "@typescript-eslint/eslint-plugin": "8.4.0",
     "@typescript-eslint/parser": "8.4.0",
     "c8": "10.1.2",

package.json

@@ -0,0 +1,200 @@
+import { expect } from 'chai';
+import { describe, it } from 'mocha';
+
+import { expectJSON } from '../../__testUtils__/expectJSON.js';
+
+import { parse } from '../../language/parser.js';
+
+import { buildSchema } from '../../utilities/buildASTSchema.js';
+
+import { execute } from '../execute.js';
+
+const schema = buildSchema(`
+  type Todo {
+    id: ID
+    text: String
+    author: User
+  }
+
+  type User {
+    id: ID
+    name: String
+  }
+
+  type Query {
+    todo: Todo
+  }
+
+  type Mutation {
+    foo: String
+    bar: String
+  }
+`);
+
+describe('Execute: Cancellation', () => {
+  it('should stop the execution when aborted during object field completion', async () => {
+    const abortController = new AbortController();
+    const document = parse(`
+      query {
+        todo {
+          id
+          author {
+            id
+          }
+        }
+      }
+    `);
+
+    const resultPromise = execute({
+      document,
+      schema,
+      abortSignal: abortController.signal,
+      rootValue: {
+        todo: async () =>
+          Promise.resolve({
+            id: '1',
+            text: 'Hello, World!',
+            /* c8 ignore next */
+            author: () => expect.fail('Should not be called'),
+          }),
+      },
+    });
+
+    abortController.abort('Aborted');
+
+    const result = await resultPromise;
+
+    expectJSON(result).toDeepEqual({
+      data: {
+        todo: null,
+      },
+      errors: [
+        {
+          message: 'Aborted',
+          path: ['todo', 'id'],
+          locations: [{ line: 4, column: 11 }],
+        },
+      ],
+    });
+  });
+
+  it('should stop the execution when aborted during nested object field completion', async () => {
+    const abortController = new AbortController();
+    const document = parse(`
+      query {
+        todo {
+          id
+          author {
+            id
+          }
+        }
+      }
+    `);
+
+    const resultPromise = execute({
+      document,
+      schema,
+      abortSignal: abortController.signal,
+      rootValue: {
+        todo: {
+          id: '1',
+          text: 'Hello, World!',
+          /* c8 ignore next 3 */
+          author: async () =>
+            Promise.resolve(() => expect.fail('Should not be called')),
+        },
+      },
+    });
+
+    abortController.abort('Aborted');
+
+    const result = await resultPromise;
+
+    expectJSON(result).toDeepEqual({
+      data: {
+        todo: {
+          id: '1',
+          author: null,
+        },
+      },
+      errors: [
+        {
+          message: 'Aborted',
+          path: ['todo', 'author', 'id'],
+          locations: [{ line: 6, column: 13 }],
+        },
+      ],
+    });
+  });
+
+  it('should stop the execution when aborted mid-mutation', async () => {
+    const abortController = new AbortController();
+    const document = parse(`
+      mutation {
+        foo
+        bar
+      }
+    `);
+
+    const resultPromise = execute({
+      document,
+      schema,
+      abortSignal: abortController.signal,
+      rootValue: {
+        foo: async () => Promise.resolve('baz'),
+        /* c8 ignore next */
+        bar: () => expect.fail('Should not be called'),
+      },
+    });
+
+    abortController.abort('Aborted');
+
+    const result = await resultPromise;
+
+    expectJSON(result).toDeepEqual({
+      data: {
+        foo: 'baz',
+        bar: null,
+      },
+      errors: [
+        {
+          message: 'Aborted',
+          path: ['bar'],
+          locations: [{ line: 4, column: 9 }],
+        },
+      ],
+    });
+  });
+
+  it('should stop the execution when aborted pre-execute', async () => {
+    const abortController = new AbortController();
+    const document = parse(`
+      query {
+        todo {
+          id
+          author {
+            id
+          }
+        }
+      }
+    `);
+    abortController.abort('Aborted');
+    const result = await execute({
+      document,
+      schema,
+      abortSignal: abortController.signal,
+      rootValue: {
+        /* c8 ignore next */
+        todo: () => expect.fail('Should not be called'),
+      },
+    });
+
+    expectJSON(result).toDeepEqual({
+      errors: [
+        {
+          message: 'Aborted',
+        },
+      ],
+    });
+  });
+});

src/execution/__tests__/abort-signal-test.ts

@@ -137,6 +137,7 @@ export interface ValidatedExecutionArgs {
     validatedExecutionArgs: ValidatedExecutionArgs,
   ) => PromiseOrValue<ExecutionResult>;
   hideSuggestions: boolean;
+  abortSignal: AbortSignal | undefined;
 }
 
 /**
@@ -224,6 +225,7 @@ export interface ExecutionArgs {
     ) => PromiseOrValue<ExecutionResult>
   >;
   hideSuggestions?: Maybe<boolean>;
+  abortSignal?: Maybe<AbortSignal>;
   /** Additional execution options. */
   options?: {
     /** Set the maximum number of errors allowed for coercing (defaults to 50). */
@@ -376,9 +378,14 @@ export function validateExecutionArgs(
     typeResolver,
     subscribeFieldResolver,
     perEventExecutor,
+    abortSignal,
     options,
   } = args;
 
+  if (abortSignal?.aborted) {
+    return [locatedError(new Error(abortSignal.reason), undefined)];
+  }
+
   // If the schema used for execution is invalid, throw an error.
   assertValidSchema(schema);
 
@@ -457,6 +464,7 @@ export function validateExecutionArgs(
     subscribeFieldResolver: subscribeFieldResolver ?? defaultFieldResolver,
     perEventExecutor: perEventExecutor ?? executeSubscriptionEvent,
     hideSuggestions,
+    abortSignal: args.abortSignal ?? undefined,
   };
 }
 
@@ -512,6 +520,19 @@ function executeFieldsSerially(
     groupedFieldSet,
     (results, [responseName, fieldDetailsList]) => {
       const fieldPath = addPath(path, responseName, parentType.name);
+      const abortSignal = exeContext.validatedExecutionArgs.abortSignal;
+      if (abortSignal?.aborted) {
+        handleFieldError(
+          new Error(abortSignal.reason),
+          exeContext,
+          parentType,
+          fieldDetailsList,
+          fieldPath,
+        );
+        results[responseName] = null;
+        return results;
+      }
+
       const result = executeField(
         exeContext,
         parentType,
@@ -552,6 +573,15 @@ function executeFields(
   try {
     for (const [responseName, fieldDetailsList] of groupedFieldSet) {
       const fieldPath = addPath(path, responseName, parentType.name);
+      const abortSignal = exeContext.validatedExecutionArgs.abortSignal;
+      if (abortSignal?.aborted) {
+        throw locatedError(
+          new Error(abortSignal.reason),
+          toNodes(fieldDetailsList),
+          pathToArray(fieldPath),
+        );
+      }
+
       const result = executeField(
         exeContext,
         parentType,
@@ -1152,8 +1182,9 @@ function completeLeafValue(
   const coerced = returnType.coerceOutputValue(result);
   if (coerced == null) {
     throw new Error(
-      `Expected \`${inspect(returnType)}.coerceOutputValue(${inspect(result)})\` to ` +
-        `return non-nullable value, returned: ${inspect(coerced)}`,
+      `Expected \`${inspect(returnType)}.coerceOutputValue(${inspect(
+        result,
+      )})\` to return non-nullable value, returned: ${inspect(coerced)}`,
     );
   }
   return coerced;

src/execution/execute.ts

@@ -66,6 +66,7 @@ export interface GraphQLArgs {
   operationName?: Maybe<string>;
   fieldResolver?: Maybe<GraphQLFieldResolver<any, any>>;
   typeResolver?: Maybe<GraphQLTypeResolver<any, any>>;
+  abortSignal?: Maybe<AbortSignal>;
 }
 
 export function graphql(args: GraphQLArgs): Promise<ExecutionResult> {