feat(execution): track pending async work

access finalization of all async work beyond that included in the result via experimental hook

Access the asyncWorkFinished hook via `experimentalHooks` on execution args:

```ts
const result = execute({
  schema,
  document: parse('{ test }'),
  experimentalHooks: {
    queryOrMutationOrSubscriptionEventAsyncWorkFinished({
      validatedExecutionArgs,
    }) {
      const operationName =
        validatedExecutionArgs.operationName ?? '<anonymous>';
      console.log(`async work finished for operation: ${operationName}`);
    },
  },
});
```

`execute(...)` can return synchronously (for example after a synchronous bubbled
error) while tracked async work is still pending. To always get a Promise that
resolves only after this hook is called:

```ts
const args: ExecutionArgs = {
  schema,
  document: parse('{ test }'),
};

let hookCalled = false;
let resolveAsyncWorkFinished: (() => void) | undefined;
const asyncWorkFinished = new Promise<void>((resolve) => {
  resolveAsyncWorkFinished = resolve;
});

const existingHook =
  args.experimentalHooks
    ?.queryOrMutationOrSubscriptionEventAsyncWorkFinished;

const result = execute({
  ...args,
  experimentalHooks: {
    ...(args.experimentalHooks ?? {}),
    queryOrMutationOrSubscriptionEventAsyncWorkFinished(info) {
      try {
        existingHook?.(info);
      } finally {
        hookCalled = true;
        resolveAsyncWorkFinished?.();
      }
    },
  },
});

const resultAfterAsyncWorkFinished: Promise<ExecutionResult> =
  Promise.resolve(result).then((executionResult) =>
    hookCalled
      ? executionResult
      : asyncWorkFinished.then(() => executionResult),
  );
```

This is safe whether `result` is sync or async, and whether the hook callback is
reached immediately or later.

Async work started inside resolvers is not automatically guaranteed to be tracked.
For example, `Promise.all([...])` rejects on the first rejection, so sibling promises
may still be pending after `execute(...)` has already produced a result.

Use `info.getAsyncHelpers()` to include that work in async tracking:

```ts
resolve(_source, _args, _context, info) {
  const { promiseAll } = info.getAsyncHelpers();
  return promiseAll([
    fetchFromA(),
    fetchFromB(),
    fetchFromC(),
  ]);
}
```

`promiseAny` and `promiseRace` similarly track non-winning/non-settled promises,
and `trackPromise` can be used for any additional Promise you want included:

```ts
resolve(_source, _args, _context, info) {
  const { trackPromise } = info.getAsyncHelpers();
  trackPromise(cleanupAfterResponse());
  return 'ok';
}
```

Author: yaacovCR

src/execution/AsyncWorkTracker.ts

@@ -0,0 +1,60 @@
+import { isPromise } from '../jsutils/isPromise.js';
+import type { PromiseOrValue } from '../jsutils/PromiseOrValue.js';
+
+/** @internal */
+export class AsyncWorkTracker {
+  pendingAsyncWork: Set<Promise<void>>;
+
+  constructor() {
+    this.pendingAsyncWork = new Set<Promise<void>>();
+  }
+
+  add(promise: Promise<unknown>): void {
+    const pendingAsyncWork = this.pendingAsyncWork;
+    const promiseToSettle = promise.then(
+      () => {
+        pendingAsyncWork.delete(promiseToSettle);
+      },
+      () => {
+        pendingAsyncWork.delete(promiseToSettle);
+      },
+    );
+    pendingAsyncWork.add(promiseToSettle);
+  }
+
+  addValues(values: ReadonlyArray<PromiseOrValue<unknown>>): void {
+    for (const value of values) {
+      if (isPromise(value)) {
+        this.add(value);
+      }
+    }
+  }
+
+  async wait(): Promise<void> {
+    await Promise.resolve();
+    while (this.pendingAsyncWork.size > 0) {
+      // eslint-disable-next-line no-await-in-loop
+      await Promise.allSettled(Array.from(this.pendingAsyncWork));
+    }
+  }
+
+  promiseAllTrackOnReject<T>(
+    values: ReadonlyArray<PromiseOrValue<T>>,
+  ): Promise<Array<T>> {
+    const promise = Promise.all(values);
+    promise.then(undefined, () => {
+      this.addValues(values);
+    });
+    return promise;
+  }
+
+  promiseCombinatorWithTracking<T, TResult>(
+    values: ReadonlyArray<PromiseOrValue<T>>,
+    combinator: (
+      promises: ReadonlyArray<PromiseOrValue<T>>,
+    ) => Promise<TResult>,
+  ): Promise<TResult> {
+    this.add(Promise.allSettled(values));
+    return combinator(values);
+  }
+}

src/execution/Executor.ts

@@ -32,6 +32,7 @@ import type {
   GraphQLObjectType,
   GraphQLOutputType,
   GraphQLResolveInfo,
+  GraphQLResolveInfoHelpers,
   GraphQLTypeResolver,
 } from '../type/definition.js';
 import {
@@ -60,6 +61,8 @@ import { createSharedExecutionContext } from './createSharedExecutionContext.js'
 import { buildResolveInfo } from './execute.js';
 import type { StreamUsage } from './getStreamUsage.js';
 import { getStreamUsage as _getStreamUsage } from './getStreamUsage.js';
+import type { ExecutionHooks } from './hooks.js';
+import { runPostExecutionHooks } from './hooks.js';
 import { returnIteratorCatchingErrors } from './returnIteratorCatchingErrors.js';
 import type { VariableValues } from './values.js';
 import { getArgumentValues } from './values.js';
@@ -115,6 +118,7 @@ export interface ValidatedExecutionArgs {
   errorPropagation: boolean;
   externalAbortSignal: AbortSignal | undefined;
   enableEarlyExecution: boolean;
+  experimentalHooks: ExecutionHooks | undefined;
 }
 
 /**
@@ -231,6 +235,11 @@ export class Executor<
   abortResultPromise: ((reason?: unknown) => void) | undefined;
   resolverAbortController: AbortController | undefined;
   getAbortSignal: () => AbortSignal | undefined;
+  getAsyncHelpers: () => GraphQLResolveInfoHelpers;
+  trackPromise: (cleanup: Promise<unknown>) => void;
+  promiseAll: <T>(
+    values: ReadonlyArray<PromiseOrValue<T>>,
+  ) => Promise<Array<T>>;
 
   constructor(
     validatedExecutionArgs: ValidatedExecutionArgs,
@@ -249,8 +258,12 @@ export class Executor<
     } else {
       this.sharedExecutionContext = sharedExecutionContext;
     }
-    const { getAbortSignal } = this.sharedExecutionContext;
+    const { getAbortSignal, getAsyncHelpers, getTrackPromise, promiseAll } =
+      this.sharedExecutionContext;
     this.getAbortSignal = getAbortSignal;
+    this.getAsyncHelpers = getAsyncHelpers;
+    this.trackPromise = getTrackPromise();
+    this.promiseAll = promiseAll;
   }
 
   executeQueryOrMutationOrSubscriptionEvent(): PromiseOrValue<
@@ -261,10 +274,7 @@ export class Executor<
     if (externalAbortSignal) {
       externalAbortSignal.throwIfAborted();
       const onExternalAbort = () => {
-        const aborted = this.abort(externalAbortSignal.reason);
-        if (isPromise(aborted)) {
-          aborted.catch(() => undefined);
-        }
+        this.abort(externalAbortSignal.reason);
       };
       removeExternalAbortListener = () =>
         externalAbortSignal.removeEventListener('abort', onExternalAbort);
@@ -326,6 +336,7 @@ export class Executor<
             return this.buildResponse(null);
           },
         );
+        this.sharedExecutionContext.asyncWorkTracker.add(promise);
         const { promise: cancellablePromise, abort: abortResultPromise } =
           withCancellation(promise);
         this.abortResultPromise = abortResultPromise;
@@ -349,7 +360,7 @@ export class Executor<
     }
   }
 
-  abort(reason?: unknown): PromiseOrValue<void> {
+  abort(reason?: unknown): void {
     if (this.aborted) {
       return;
     }
@@ -359,9 +370,23 @@ export class Executor<
     }
     this.abortResultPromise?.(this.abortReason);
     this.resolverAbortController?.abort(this.abortReason);
+    const hooks = this.validatedExecutionArgs.experimentalHooks;
+    if (hooks !== undefined) {
+      runPostExecutionHooks(
+        this.validatedExecutionArgs,
+        this.sharedExecutionContext,
+      );
+    }
   }
 
   finish(): void {
+    const hooks = this.validatedExecutionArgs.experimentalHooks;
+    if (hooks !== undefined) {
+      runPostExecutionHooks(
+        this.validatedExecutionArgs,
+        this.sharedExecutionContext,
+      );
+    }
     this.throwIfAborted();
     this.aborted = true;
   }
@@ -508,8 +533,9 @@ export class Executor<
       }
     } catch (error) {
       if (containsPromise) {
-        // Ensure that any promises returned by other fields are handled, as they may also reject.
-        promiseForObject(results).catch(() => undefined);
+        this.sharedExecutionContext.asyncWorkTracker.addValues(
+          Object.values(results),
+        );
       }
       throw error;
     }
@@ -522,7 +548,7 @@ export class Executor<
     // Otherwise, results is a map from field name to the result of resolving that
     // field, which is possibly a promise. Return a promise that will return this
     // same map, but with any promises replaced with the values they resolved to.
-    return promiseForObject(results);
+    return promiseForObject(results, this.promiseAll);
   }
 
   /**
@@ -559,6 +585,7 @@ export class Executor<
       parentType,
       path,
       this.getAbortSignal,
+      this.getAsyncHelpers,
     );
 
     // Get the resolve function, regardless of if its result is normal or abrupt (error).
@@ -855,24 +882,26 @@ export class Executor<
         index++;
       }
     } catch (error) {
-      // eslint-disable-next-line @typescript-eslint/no-floating-promises
-      returnIteratorCatchingErrors(asyncIterator);
+      this.trackPromise(returnIteratorCatchingErrors(asyncIterator));
       if (containsPromise) {
-        Promise.all(completedResults).catch(() => undefined);
+        this.sharedExecutionContext.asyncWorkTracker.addValues(
+          completedResults,
+        );
       }
       throw error;
     }
 
     // Throwing on completion outside of the loop may allow engines to better optimize
     if (this.aborted) {
       if (!iteration?.done) {
-        // eslint-disable-next-line @typescript-eslint/no-floating-promises
-        returnIteratorCatchingErrors(asyncIterator);
+        this.trackPromise(returnIteratorCatchingErrors(asyncIterator));
       }
       throw new Error('Aborted!');
     }
 
-    return containsPromise ? Promise.all(completedResults) : completedResults;
+    return containsPromise
+      ? this.promiseAll(completedResults)
+      : completedResults;
   }
 
   /* c8 ignore next 12 */
@@ -993,15 +1022,17 @@ export class Executor<
         index++;
       }
     } catch (error) {
-      const maybePromises = containsPromise ? completedResults : [];
-      maybePromises.push(...collectIteratorPromises(iterator));
-      if (maybePromises.length) {
-        Promise.all(maybePromises).catch(() => undefined);
+      const asyncWorkTracker = this.sharedExecutionContext.asyncWorkTracker;
+      if (containsPromise) {
+        asyncWorkTracker.addValues(completedResults);
       }
+      asyncWorkTracker.addValues(collectIteratorPromises(iterator));
       throw error;
     }
 
-    return containsPromise ? Promise.all(completedResults) : completedResults;
+    return containsPromise
+      ? this.promiseAll(completedResults)
+      : completedResults;
   }
 
   completeMaybePromisedListItemValue(