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

expose an execution hook that runs once tracked async work has finished,
including work that can outlive a returned execution result

The hook is available through `hooks.asyncWorkFinished` on execution args.

`AsyncWorkTracker.wait()` now has a synchronous fast-path:
- returns `void` when no async work is currently tracked
- returns `Promise<void>` only while tracked work is pending

This keeps synchronous execution paths synchronous when hooks are enabled.

`GraphQLResolveInfoHelpers.promiseAll` is documented as a tracked helper that is
intended to be returned/awaited as part of resolver work.

Example (synchronous execution stays synchronous):

```ts
const calls: Array<string> = [];

const result = execute({
  schema,
  document: parse('{ test }'),
  hooks: {
    asyncWorkFinished() {
      calls.push('asyncWorkFinished');
    },
  },
});

// result is sync and the hook has already run.
console.log(result);
console.log(calls);
```

Anti-pattern example (fire-and-forget `promiseAll` side effect):

```ts
resolve(_source, _args, _context, info) {
  info
    .getAsyncHelpers()
    .promiseAll([Promise.reject(new Error('bad')), pendingCleanup])
    .catch(() => undefined);
  return 'ok';
}
```

This pattern is discouraged. Tracking for this call starts on a later
microtask, so `hooks.asyncWorkFinished` is not guaranteed to wait for it.
A regression test now asserts this behavior.

Recommended fire-and-forget pattern:

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

Author: yaacovCR

src/execution/AsyncWorkTracker.ts

@@ -30,6 +30,15 @@ export class AsyncWorkTracker {
     }
   }
 
+  wait(): Promise<void> | void {
+    // wait can complete synchronously when there is no tracked async work,
+    // which allows synchronous execution paths to remain synchronous.
+    if (this.pendingAsyncWork.size === 0) {
+      return;
+    }
+    return this.waitForPendingAsyncWork();
+  }
+
   promiseAllTrackOnReject<T>(
     values: ReadonlyArray<PromiseOrValue<T>>,
   ): Promise<Array<T>> {
@@ -39,4 +48,21 @@ export class AsyncWorkTracker {
     });
     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);
+  }
+
+  private async waitForPendingAsyncWork(): Promise<void> {
+    while (this.pendingAsyncWork.size > 0) {
+      // eslint-disable-next-line no-await-in-loop
+      await Promise.allSettled(Array.from(this.pendingAsyncWork));
+    }
+  }
 }

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

@@ -58,7 +58,7 @@ describe('promiseAllTrackOnReject', () => {
     expect(settled).to.equal(true);
   });
 
-  it('tracks all promises only after rejection', async () => {
+  it('tracks sibling promises only after rejection', async () => {
     const delayed = promiseWithResolvers<undefined>();
     const tracker = new AsyncWorkTracker();
     const result = tracker.promiseAllTrackOnReject([
@@ -103,3 +103,125 @@ describe('promiseAllTrackOnReject', () => {
     expect(unhandledRejection).to.equal(null);
   });
 });
+
+describe('promiseCombinatorWithTracking', () => {
+  it('tracks pending promises after Promise.any resolves', async () => {
+    const tracker = new AsyncWorkTracker();
+
+    const delayed = promiseWithResolvers<number>();
+    const result = await tracker.promiseCombinatorWithTracking(
+      [1, delayed.promise],
+      // eslint-disable-next-line @typescript-eslint/await-thenable
+      (promises) => Promise.any(promises),
+    );
+    expect(result).to.equal(1);
+
+    await resolveOnNextTick();
+    expect(tracker.pendingAsyncWork.size).to.equal(1);
+
+    delayed.resolve(2);
+    await Promise.allSettled(Array.from(tracker.pendingAsyncWork));
+    await resolveOnNextTick();
+    expect(tracker.pendingAsyncWork.size).to.equal(0);
+  });
+
+  it('tracks pending promises after Promise.race rejects', async () => {
+    const tracker = new AsyncWorkTracker();
+
+    const delayed = promiseWithResolvers<number>();
+    const result = tracker.promiseCombinatorWithTracking(
+      [Promise.reject(new Error('bad')), delayed.promise],
+      // eslint-disable-next-line @typescript-eslint/await-thenable
+      (promises) => Promise.race(promises),
+    );
+
+    await result.catch(() => undefined);
+    await resolveOnNextTick();
+    expect(tracker.pendingAsyncWork.size).to.equal(1);
+
+    delayed.resolve(1);
+    await Promise.allSettled(Array.from(tracker.pendingAsyncWork));
+    await resolveOnNextTick();
+    expect(tracker.pendingAsyncWork.size).to.equal(0);
+  });
+});
+
+describe('wait', () => {
+  it('returns synchronously when there is no pending async work', () => {
+    const tracker = new AsyncWorkTracker();
+    expect(tracker.wait()).to.equal(undefined);
+  });
+
+  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 maybeWait = tracker.wait();
+    expect(maybeWait).to.be.instanceOf(Promise);
+    const wait = Promise.resolve(maybeWait).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 maybeWait = tracker.wait();
+    expect(maybeWait).to.be.instanceOf(Promise);
+    const wait = Promise.resolve(maybeWait).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);
+  });
+
+  it('does not wait for side-effect promiseAll tracking added on next microtask', async () => {
+    const tracker = new AsyncWorkTracker();
+    const delayed = promiseWithResolvers<undefined>();
+
+    tracker
+      .promiseAllTrackOnReject([
+        Promise.reject(new Error('bad')),
+        delayed.promise,
+      ])
+      .catch(() => undefined);
+
+    const maybeWait = tracker.wait();
+    expect(maybeWait).to.equal(undefined);
+
+    await resolveOnNextTick();
+    expect(tracker.pendingAsyncWork.size).to.equal(0);
+    await resolveOnNextTick();
+    expect(tracker.pendingAsyncWork.size).to.be.greaterThan(0);
+
+    delayed.resolve(undefined);
+    await Promise.allSettled(Array.from(tracker.pendingAsyncWork));
+    await resolveOnNextTick();
+    expect(tracker.pendingAsyncWork.size).to.equal(0);
+  });
+});

src/execution/__tests__/executor-test.ts

@@ -261,7 +261,12 @@ describe('Execute: Handles basic execution tasks', () => {
       'getAsyncHelpers',
     );
     const asyncHelpers = resolvedInfo?.getAsyncHelpers();
-    expect(asyncHelpers).to.have.all.keys('trackPromise');
+    expect(asyncHelpers).to.have.all.keys(
+      'promiseAll',
+      'promiseAny',
+      'promiseRace',
+      'trackPromise',
+    );
 
     const operation = document.definitions[0];
     assert(operation.kind === Kind.OPERATION_DEFINITION);
@@ -300,6 +305,18 @@ describe('Execute: Handles basic execution tasks', () => {
 
     expect(resolvedInfo?.getAsyncHelpers()).to.equal(asyncHelpers);
 
+    const promiseAll = asyncHelpers?.promiseAll;
+    expect(promiseAll).to.be.a('function');
+    expect(resolvedInfo?.getAsyncHelpers().promiseAll).to.equal(promiseAll);
+
+    const promiseAny = asyncHelpers?.promiseAny;
+    expect(promiseAny).to.be.a('function');
+    expect(resolvedInfo?.getAsyncHelpers().promiseAny).to.equal(promiseAny);
+
+    const promiseRace = asyncHelpers?.promiseRace;
+    expect(promiseRace).to.be.a('function');
+    expect(resolvedInfo?.getAsyncHelpers().promiseRace).to.equal(promiseRace);
+
     const trackPromise = asyncHelpers?.trackPromise;
     expect(trackPromise).to.be.a('function');
     expect(resolvedInfo?.getAsyncHelpers().trackPromise).to.equal(trackPromise);