Add support for willResolveField and corresponding end handler.

[abernix]

This adds two of the life-cycle hooks which were available in the graphql-extensions API but missing from the new request pipeline plugin API (documentation found here!): willResolveField and a corresponding didResolveField. These are introduced in a similar way to how they were in the graphql-extensions API (where the didResolveField callback is returned from willResolveField). A notable difference is that the technique used to reach the "plugin stack" is through a non-enumerable property, keyed with a Symbol, on the context received by the resolver, rather than the technique employed by the graphql-extensions approach.

These omissions from the new plugin API have stood in the way of our own ability to migrate our Apollo-related extensions (e.g. apollo-cache-control, apollo-engine-reporting in federated and non-federated forms, apollo-tracing) to the new plugin API and our intention to deprecate that API (which was never officially intended to be public and never was documented).

That's not to say that any of the effort to do those migrations is easy (it will absolutely not be), however, this unblocks those efforts and can be reviewed (and changed) separately.

If there are questions about the implementation chosen here, everything is strongly modeled after the graphql-extensions approach for these same life-cycle hooks. That doesn't meant this is the perfect approach though! We can presumably iterate on this without affecting the plugins which implement this, or at least with somewhat minimal changes to their approach in their integration with Apollo Server itself.

Example

The object received by the new willResolveField hook is an object representation of what will be received by the resolver itself's positional parameters and is declared in the types for the new hook, as seen here, as GraphQLFieldResolverParams:

apollo-server/packages/apollo-server-types/src/index.ts

Lines 161 to 170 in 52418a4

	export type GraphQLFieldResolverParams<
	TSource,
	TContext,
	TArgs = { [argName: string]: any }
	> = {
	source: TSource;
	args: TArgs;
	context: TContext;
	info: GraphQLResolveInfo;
	};

To get further clarity on that, the type for GraphQLFieldResolverParams:

apollo-server/packages/apollo-server-types/src/index.ts

Lines 161 to 170 in 52418a4

	export type GraphQLFieldResolverParams<
	TSource,
	TContext,
	TArgs = { [argName: string]: any }
	> = {
	source: TSource;
	args: TArgs;
	context: TContext;
	info: GraphQLResolveInfo;
	};

Put another way, rather than receiving the positional parameters (source, args, context, info), it receives ({ source, args, context, info }) which allows easier destructuring and discarding of undesired properties, as would be normal with, e.g., (_source, _args, _context, info), just to get to info).

A note about the pattern: The addition of the willResolveField hook in this PR continues with the nested approach (e.g. willResolveField is within executionDidStart is within requestDidStart) that the plugin API previous introduced and is one of its strengths. Seen in the example below, this provides a natural way to scope variables within related spans of the request life-cycle and provides narrowed TypeScript typing via the requestContext which is received along the way.

The TypeScript definitions demonstrate the precision of that narrowing and can be best seen within the apollo-server-plugin-base module:

apollo-server/packages/apollo-server-plugin-base/src/index.ts

Lines 56 to 116 in 52418a4

	export interface ApolloServerPlugin<
	TContext extends BaseContext = BaseContext
	> {
	serverWillStart?(service: GraphQLServiceContext): ValueOrPromise<void>;
	requestDidStart?(
	requestContext: GraphQLRequestContext<TContext>,
	): GraphQLRequestListener<TContext> | void;
	}
	export type GraphQLRequestListenerParsingDidEnd = (err?: Error) => void;
	export type GraphQLRequestListenerValidationDidEnd =
	((err?: ReadonlyArray<Error>) => void);
	export type GraphQLRequestListenerExecutionDidEnd = ((err?: Error) => void);
	export type GraphQLRequestListenerDidResolveField =
	((error: Error | null, result?: any) => void);
	export interface GraphQLRequestListener<
	TContext extends BaseContext = BaseContext
	> extends AnyFunctionMap {
	didResolveSource?(
	requestContext: GraphQLRequestContextDidResolveSource<TContext>,
	): ValueOrPromise<void>;
	parsingDidStart?(
	requestContext: GraphQLRequestContextParsingDidStart<TContext>,
	): GraphQLRequestListenerParsingDidEnd | void;
	validationDidStart?(
	requestContext: GraphQLRequestContextValidationDidStart<TContext>,
	): GraphQLRequestListenerValidationDidEnd | void;
	didResolveOperation?(
	requestContext: GraphQLRequestContextDidResolveOperation<TContext>,
	): ValueOrPromise<void>;
	didEncounterErrors?(
	requestContext: GraphQLRequestContextDidEncounterErrors<TContext>,
	): ValueOrPromise<void>;
	// If this hook is defined, it is invoked immediately before GraphQL execution
	// would take place. If its return value resolves to a non-null
	// GraphQLResponse, that result is used instead of executing the query.
	// Hooks from different plugins are invoked in series and the first non-null
	// response is used.
	responseForOperation?(
	requestContext: GraphQLRequestContextResponseForOperation<TContext>,
	): ValueOrPromise<GraphQLResponse | null>;
	executionDidStart?(
	requestContext: GraphQLRequestContextExecutionDidStart<TContext>,
	):
	| GraphQLRequestExecutionListener
	| GraphQLRequestListenerExecutionDidEnd
	| void;
	willSendResponse?(
	requestContext: GraphQLRequestContextWillSendResponse<TContext>,
	): ValueOrPromise<void>;
	}
	export interface GraphQLRequestExecutionListener<
	TContext extends BaseContext = BaseContext
	> extends AnyFunctionMap {
	executionDidEnd?: GraphQLRequestListenerExecutionDidEnd;
	willResolveField?(
	fieldResolverParams: GraphQLFieldResolverParams<any, TContext>
	): GraphQLRequestListenerDidResolveField | void;
	}

And finally, the example:

const server = new ApolloServer({
  typeDefs: gql`
    type Query {
      # Omitted intentionally.
    }
  `,
  resolvers: () => ({ /* Omitted intentionally */ }),
  plugins: [
    {
      requestDidStart: () => ({
        executionDidStart: () => ({
          willResolveField({ source, args, context, info }) {
            console.log("Field is about to resolve.");
            return () => {
              console.log("Field did resolve!");
            };
          }
        }),
      }),
    },
  ],
});

TODO

- [ ] Documentation See #4104

[trevor-scheer]

This looks great! One question and one caveat within.

[glasser]

I will probably want to review this as part of reviewing #3998. (Probably won't get to either today.)

[glasser]

Looking good, only one substantive concern.

[abernix]

Thanks very much for the review, @glasser. I've made some preliminary adjustments based on your feedback, but will circle back to put some additional thought on some bits tomorrow.