feat(execution): expose async-work-finished execution hook

access finalization of all tracked 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

@@ -30,6 +30,14 @@ export class AsyncWorkTracker {
     }
   }
 
+  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>> {

src/execution/Executor.ts

@@ -61,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 { runAsyncWorkFinishedHook } from './hooks.js';
 import { returnIteratorCatchingErrors } from './returnIteratorCatchingErrors.js';
 import type { VariableValues } from './values.js';
 import { getArgumentValues } from './values.js';
@@ -116,6 +118,7 @@ export interface ValidatedExecutionArgs {
   errorPropagation: boolean;
   externalAbortSignal: AbortSignal | undefined;
   enableEarlyExecution: boolean;
+  hooks: ExecutionHooks | undefined;
 }
 
 /**
@@ -372,17 +375,31 @@ export class Executor<
     this.aborted = true;
   }
 
+  finishSharedExecution(): void {
+    this.resolverAbortController?.abort();
+    const asyncWorkFinishedHook =
+      this.validatedExecutionArgs.hooks?.asyncWorkFinished;
+    if (asyncWorkFinishedHook === undefined) {
+      return;
+    }
+    runAsyncWorkFinishedHook(
+      this.validatedExecutionArgs,
+      this.sharedExecutionContext,
+      asyncWorkFinishedHook,
+    );
+  }
+
   /**
    * Given a completed execution context and data, build the `{ errors, data }`
    * response defined by the "Response" section of the GraphQL specification.
    */
   buildResponse(
     data: ObjMap<unknown> | null,
   ): ExecutionResult | TAlternativeInitialResponse {
+    this.finishSharedExecution();
     this.finish();
     const errors = this.collectedErrors.errors;
     const result = errors.length ? { errors, data } : { data };
-    this.resolverAbortController?.abort();
     return result;
   }
 

src/execution/__tests__/AsyncWorkTracker-test.ts

@@ -144,4 +144,106 @@ describe('promiseCombinatorWithTracking', () => {
     await resolveOnNextTick();
     expect(tracker.pendingAsyncWork.size).to.equal(0);
   });
+
+  describe('wait', () => {
+    it('returns immediately with no pending promises', async () => {
+      const tracker = new AsyncWorkTracker();
+      await tracker.wait();
+    });
+
+    it('waits when tracked async work is present', async () => {
+      const tracker = new AsyncWorkTracker();
+
+      const delayed = promiseWithResolvers<undefined>();
+      tracker.add(delayed.promise);
+
+      let settled = false;
+      const wait = tracker.wait().then(() => {
+        settled = true;
+      });
+      await resolveOnNextTick();
+      expect(settled).to.equal(false);
+
+      delayed.resolve(undefined);
+      await wait;
+      expect(settled).to.equal(true);
+    });
+
+    it('keeps waiting when tracked async work is followed by more tracked async work', async () => {
+      const tracker = new AsyncWorkTracker();
+
+      const delayed = promiseWithResolvers<undefined>();
+      tracker.add(delayed.promise);
+
+      let settled = false;
+      const wait = tracker.wait().then(() => {
+        settled = true;
+      });
+      await resolveOnNextTick();
+      expect(settled).to.equal(false);
+
+      delayed.resolve(undefined);
+
+      const anotherDelayed = promiseWithResolvers<undefined>();
+      tracker.add(anotherDelayed.promise);
+      await resolveOnNextTick();
+      expect(settled).to.equal(false);
+
+      anotherDelayed.resolve(undefined);
+
+      await wait;
+      expect(settled).to.equal(true);
+    });
+  });
+});
+
+describe('wait', () => {
+  it('returns immediately with no pending promises', async () => {
+    const tracker = new AsyncWorkTracker();
+    await tracker.wait();
+  });
+
+  it('waits when tracked async work is present', async () => {
+    const tracker = new AsyncWorkTracker();
+
+    const delayed = promiseWithResolvers<undefined>();
+    tracker.add(delayed.promise);
+
+    let settled = false;
+    const wait = tracker.wait().then(() => {
+      settled = true;
+    });
+    await resolveOnNextTick();
+    expect(settled).to.equal(false);
+
+    delayed.resolve(undefined);
+    await wait;
+    expect(settled).to.equal(true);
+  });
+
+  it('keeps waiting when tracked async work is followed by more tracked async work', async () => {
+    const tracker = new AsyncWorkTracker();
+
+    const delayed = promiseWithResolvers<undefined>();
+    tracker.add(delayed.promise);
+
+    let settled = false;
+    const wait = tracker.wait().then(() => {
+      settled = true;
+    });
+    await resolveOnNextTick();
+    expect(settled).to.equal(false);
+
+    delayed.resolve(undefined);
+
+    const anotherDelayed = promiseWithResolvers<undefined>();
+    tracker.add(anotherDelayed.promise);
+    await resolveOnNextTick();
+    expect(settled).to.equal(false);
+
+    anotherDelayed.resolve(undefined);
+
+    await wait;
+    expect(settled).to.equal(true);
+  });
 });