feat(execution): expose asyncWorkFinished execution hook

[yaacovCR]

Cancelled async work may still be running even after the result returns. This hook allows interested execution harnesses to track when this async work completes.

Depends on:

• refactor(execution): track pending work #4657

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

An execute wrapper that waits for all tracked async work can be written as:

function executeAndWaitForAsyncWorkFinished(
  args: ExecutionArgs,
): PromiseOrValue<ExecutionResult> {
  let hookHasFired = false;
  const { promise: hookFinished, resolve: resolveHookFinished } =
    Promise.withResolvers<void>();

  const userAsyncWorkFinishedHook = args.hooks?.asyncWorkFinished;
  const result = execute({
    ...args,
    hooks: {
      ...args.hooks,
      asyncWorkFinished(info) {
        try {
          userAsyncWorkFinishedHook?.(info);
        } finally {
          hookHasFired = true;
          resolveHookFinished();
        }
      },
    },
  });

  return hookHasFired ? result : hookFinished.then(() => result);
}

To ensure resolver-side async work is also tracked and awaited, use info.getAsyncHelpers().track(...) or info.getAsyncHelpers().promiseAll(...).

promiseAll(...) is optimized for the common case where the returned promise is awaited (or returned) from the resolver. It only starts tracking on rejection, and does so as a side-effect. Un-awaited async side effects are an anti-pattern:

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

In that anti-pattern, tracking starts only after rejection (on a later microtask), so this work is not guaranteed to delay hooks.asyncWorkFinished.

Use track(...) for un-awaited async side effects:

resolve(_source, _args, _context, info) {
  const { track } = info.getAsyncHelpers();
  track([doCleanupAsync().catch(() => undefined)]);
  return 'ok';
}

[vercel]

@yaacovCR is attempting to deploy a commit to the The GraphQL Foundation Team on Vercel.

A member of the Team first needs to authorize it.