feat(execution): expose partial result on abort errors (#4674)

When execution is aborted while work is still resolving, the executor previously rejected with only the abort reason. That loses access to any response data and errors that execution can still produce while unwinding the in-flight operation.

This PR wraps pre-result aborts in `AbortedGraphQLExecutionError` and attach the partial result as `abortedResult`. If the response has already been produced, `abortedResult` is that response value. If root execution is still pending, `abortedResult` is the original execution promise so callers can await the eventual partial response separately
from the abort rejection.

For example, if a query aborts while a field resolver is pending, `execute()` rejects with the original abort reason as the error message and cause, while `error.abortedResult` later resolves to a response such as `{ data: { blocker: null }, errors: [{ message: 'Aborted!', path: ['blocker'] }] }`.

[Incremental execution follows the same pattern for the pending initial result, but aborts after the initial incremental payload continue to surface as rejection of `next` calls on the `subsequentResults` iterator (without this new wrapper).

`abortedResult` is usually a a `Promise` rather than a value because since the `execute` promise rejects immediately, execution has not finished.]

It may sometimes be a value, i.e. if the executor aborted internally during synchronous execution, which currently can happen if a resolver triggers the external abort signal or if there is a developer error, such as using a schema or query with defer/stream directives when using `execute` (instead of using `experimentalExecuteIncrementally`).

Author: yaacovCR

src/__testUtils__/expectPromise.ts

@@ -5,7 +5,7 @@ import { isPromise } from '../jsutils/isPromise.js';
 
 interface PromiseExpectation {
   toResolve: () => Promise<unknown>;
-  toRejectWith: (message: string) => Promise<void>;
+  toRejectWith: (message: string) => Promise<Error>;
 }
 
 export function expectPromise(maybePromise: unknown): PromiseExpectation {
@@ -18,7 +18,7 @@ export function expectPromise(maybePromise: unknown): PromiseExpectation {
     toResolve(): Promise<unknown> {
       return maybePromise;
     },
-    async toRejectWith(message: string): Promise<void> {
+    async toRejectWith(message: string): Promise<Error> {
       let caughtError: unknown;
       let resolved;
       let rejected = false;
@@ -38,6 +38,7 @@ export function expectPromise(maybePromise: unknown): PromiseExpectation {
 
       expect(caughtError).to.be.an.instanceOf(Error);
       expect(caughtError).to.have.property('message', message);
+      return caughtError as Error;
     },
   };
 }

src/execution/AbortedGraphQLExecutionError.ts

@@ -0,0 +1,30 @@
+import type { PromiseOrValue } from '../jsutils/PromiseOrValue.js';
+
+export class AbortedGraphQLExecutionError<TResult> extends Error {
+  readonly abortedResult: PromiseOrValue<TResult>;
+
+  constructor(reason: unknown, result: PromiseOrValue<TResult>) {
+    super(getAbortReasonMessage(reason), { cause: reason });
+    this.name = 'AbortedGraphQLExecutionError';
+    this.abortedResult = result;
+  }
+
+  get [Symbol.toStringTag](): string {
+    return 'AbortedGraphQLExecutionError';
+  }
+}
+
+function getAbortReasonMessage(reason: unknown): string {
+  if (reason instanceof Error) {
+    return reason.message;
+  }
+  if (
+    typeof reason === 'object' &&
+    reason !== null &&
+    'message' in reason &&
+    typeof reason.message === 'string'
+  ) {
+    return reason.message;
+  }
+  return String(reason);
+}

src/execution/Executor.ts

@@ -44,6 +44,7 @@ import {
 } from '../type/definition.js';
 import type { GraphQLSchema } from '../type/schema.js';
 
+import { AbortedGraphQLExecutionError } from './AbortedGraphQLExecutionError.js';
 import { withCancellation } from './cancellablePromise.js';
 import type {
   DeferUsage,
@@ -339,7 +340,7 @@ export class Executor<
         const { promise: cancellablePromise, abort: abortResultPromise } =
           withCancellation(promise.then((resolved) => this.finish(resolved)));
         this.abortResultPromise = () => {
-          abortResultPromise(this.abortReason);
+          abortResultPromise(this.createAbortedExecutionError(promise));
         };
         if (this.aborted) {
           this.abortResultPromise();
@@ -369,12 +370,18 @@ export class Executor<
 
   finish<T>(result: T): T {
     if (this.aborted) {
-      throw this.abortReason;
+      throw this.createAbortedExecutionError(result);
     }
     this.aborted = true;
     return result;
   }
 
+  createAbortedExecutionError<T>(
+    result: PromiseOrValue<T>,
+  ): AbortedGraphQLExecutionError<T> {
+    return new AbortedGraphQLExecutionError(this.abortReason, result);
+  }
+
   getFinishSharedExecution(): () => void {
     const resolverAbortController = this.resolverAbortController;
     const asyncWorkFinishedHook =
@@ -649,10 +656,6 @@ export class Executor<
     fieldDetailsList: FieldDetailsList,
     path: Path,
   ): void {
-    if (this.aborted) {
-      throw new Error('Aborted!');
-    }
-
     const error = locatedError(
       rawError,
       toNodes(fieldDetailsList),

src/execution/__tests__/AbortedGraphQLExecutionError-test.ts

@@ -0,0 +1,58 @@
+import { expect } from 'chai';
+import { describe, it } from 'mocha';
+
+import { AbortedGraphQLExecutionError } from '../AbortedGraphQLExecutionError.js';
+
+describe('AbortedGraphQLExecutionError', () => {
+  it('uses the original Error reason message and cause', () => {
+    const reason = new Error('Original reason');
+    const result = { data: { ok: true } };
+
+    const error = new AbortedGraphQLExecutionError(reason, result);
+
+    expect(error).to.be.instanceof(Error);
+    expect(error).to.be.instanceof(AbortedGraphQLExecutionError);
+    expect(error).to.include({
+      name: 'AbortedGraphQLExecutionError',
+      message: 'Original reason',
+      cause: reason,
+      abortedResult: result,
+    });
+    expect(Object.prototype.toString.call(error)).to.equal(
+      '[object AbortedGraphQLExecutionError]',
+    );
+  });
+
+  it('uses the message property from non-Error reasons', () => {
+    const reason = { message: 'Object reason' };
+    const result = Promise.resolve({ data: null });
+
+    const error = new AbortedGraphQLExecutionError(reason, result);
+
+    expect(error).to.include({
+      message: 'Object reason',
+      cause: reason,
+      abortedResult: result,
+    });
+  });
+
+  it('stringifies reasons without a message', () => {
+    const error = new AbortedGraphQLExecutionError('String reason', {
+      data: null,
+    });
+
+    expect(error).to.include({
+      message: 'String reason',
+      cause: 'String reason',
+    });
+  });
+
+  it('stringifies null reasons', () => {
+    const error = new AbortedGraphQLExecutionError(null, { data: null });
+
+    expect(error).to.include({
+      message: 'null',
+      cause: null,
+    });
+  });
+});