Require legacy incremental execute as an ApolloServer option instead of a dynamic import (#8161)

Fixes #8159

Dynamically importing `@yaacovcr/transform` if available has proven to
be a difficult solution because some bundlers fail to build when the
package isn't installed.

This PR addresses this issue by making the legacy execute function an
option that can be provided to the `ApolloServer` constructor. This
means no direct dependency on `@yaacovcr/transform` and makes it
possible to use other legacy execution functions if available.

To migrate, import the `legacyExecuteIncrementally` and provide it as
the `legacyExperimentalExecuteIncrementally` option to the
`ApolloServer` constructor.


```ts
import { legacyExecuteIncrementally } from '@yaacovcr/transform';

const server = new ApolloServer({
  // ...
  legacyExperimentalExecuteIncrementally: legacyExecuteIncrementally
})

```

Author: jerelmiller

.changeset/chatty-states-write.md

@@ -0,0 +1,16 @@
+---
+'@apollo/server': minor
+---
+
+Fix an issue where some bundlers would fail to build because of the dynamic import for the optional peer dependency on `@yaacovcr/transform` introduced in `@apollo/server` 5.1.0. To provide support for the legacy incremental format, you must now provide the `legacyExperimentalExecuteIncrementally` option to the `ApolloServer` constructor.
+
+```ts
+import { legacyExecuteIncrementally } from '@yaacovcr/transform';
+
+const server = new ApolloServer({
+  // ...
+  legacyExperimentalExecuteIncrementally: legacyExecuteIncrementally
+})
+```
+
+If the `legacyExperimentalExecuteIncrementally` option is not provided and the client sends an `Accept` header with a value of `multipart/mixed; deferSpec=20220824`, an error is returned by the server.

docs/source/workflow/requests.md

@@ -131,7 +131,7 @@ Apollo Server 5.1 changed the required pre-release `graphql` version from `17.0.
 
 </Note>
 
-<MinVersion version="5.1.0">
+<MinVersion version="5.2.0">
 
 ### Add support for the legacy incremental delivery protocol
 
@@ -145,4 +145,13 @@ You may choose to support the legacy incremental delivery protocol by installing
 npm install @yaacovcr/transform
 ```
 
-There is nothing else to configure. Apollo Server will load the necessary utility if this package is installed.
+You will then need to configure Apollo Server with the `legacyExperimentalExecuteIncrementally` option in order to provide support for the legacy incremental format.
+
+```ts
+import { legacyExecuteIncrementally } from '@yaacovcr/transform';
+
+const server = new ApolloServer({
+  // ...
+  legacyExperimentalExecuteIncrementally: legacyExecuteIncrementally
+})
+```

packages/integration-testsuite/src/apolloServerTests.ts

@@ -1181,7 +1181,19 @@ export function defineIntegrationTestSuiteApolloServerTests(
           (process.env.INCREMENTAL_DELIVERY_TESTS_ENABLED ? it : it.skip)(
             'includes all fields with defer legacy',
             async () => {
-              await setupApolloServerAndFetchPair({}, {}, [], true);
+              const { legacyExecuteIncrementally } = await import(
+                // @ts-ignore might not be installed
+                '@yaacovcr/transform'
+              );
+              await setupApolloServerAndFetchPair(
+                {},
+                {
+                  legacyExperimentalExecuteIncrementally:
+                    legacyExecuteIncrementally,
+                },
+                [],
+                true,
+              );
               const response = await fetch(uri, {
                 method: 'POST',
                 headers: {

packages/integration-testsuite/src/httpServerTests.ts

@@ -2466,7 +2466,16 @@ export function defineIntegrationTestSuiteHttpServerTests(
               ['multipart/mixed; deferSpec=20220824, application/json'],
               ['application/json, multipart/mixed; deferSpec=20220824'],
             ])('basic @defer working with accept: %s', async (accept) => {
-              const app = await createApp({ typeDefs, resolvers });
+              const { legacyExecuteIncrementally } = await import(
+                // @ts-ignore might not be installed
+                '@yaacovcr/transform'
+              );
+              const app = await createApp({
+                typeDefs,
+                resolvers,
+                legacyExperimentalExecuteIncrementally:
+                  legacyExecuteIncrementally,
+              });
               const res = await request(app)
                 .post('/')
                 .set('accept', accept)
@@ -2497,6 +2506,10 @@ content-type: application/json; charset=utf-8\r
               ['multipart/mixed; deferSpec=20220824, application/json'],
               ['application/json, multipart/mixed; deferSpec=20220824'],
             ])('basic @stream working with accept: %s', async (accept) => {
+              const { legacyExecuteIncrementally } = await import(
+                // @ts-ignore might not be installed
+                '@yaacovcr/transform'
+              );
               const app = await createApp({
                 typeDefs: `#graphql
                     directive @stream(if: Boolean! = true, label: String, initialCount: Int! = 0) on FIELD
@@ -2518,6 +2531,8 @@ content-type: application/json; charset=utf-8\r
                     },
                   },
                 },
+                legacyExperimentalExecuteIncrementally:
+                  legacyExecuteIncrementally,
               });
               const res = await request(app)
                 .post('/')
@@ -2557,7 +2572,16 @@ content-type: application/json; charset=utf-8\r
             });
 
             it('first payload sent while deferred field is blocking', async () => {
-              const app = await createApp({ typeDefs, resolvers });
+              const { legacyExecuteIncrementally } = await import(
+                // @ts-ignore might not be installed
+                '@yaacovcr/transform'
+              );
+              const app = await createApp({
+                typeDefs,
+                resolvers,
+                legacyExperimentalExecuteIncrementally:
+                  legacyExecuteIncrementally,
+              });
               const gotFirstChunkBarrier = resolvable();
               const resPromise = request(app)
                 .post('/')

packages/server/src/ApolloServer.ts

@@ -36,6 +36,7 @@ import { ApolloServerErrorCode } from './errors/index.js';
 import type { ApolloServerOptionsWithStaticSchema } from './externalTypes/constructor.js';
 import type {
   ExecuteOperationOptions,
+  LegacyExperimentalExecuteIncrementally,
   VariableValues,
 } from './externalTypes/graphql.js';
 import type {
@@ -171,6 +172,7 @@ export interface ApolloServerInternals<TContext extends BaseContext> {
   stringifyResult: (
     value: FormattedExecutionResult,
   ) => string | Promise<string>;
+  legacyExperimentalExecuteIncrementally?: LegacyExperimentalExecuteIncrementally;
 }
 
 function defaultLogger(): Logger {
@@ -350,6 +352,8 @@ export class ApolloServer<in out TContext extends BaseContext = BaseContext> {
       __testing_incrementalExecutionResults:
         config.__testing_incrementalExecutionResults,
       stringifyResult: config.stringifyResult ?? prettyJSONStringify,
+      legacyExperimentalExecuteIncrementally:
+        config.legacyExperimentalExecuteIncrementally,
     };
 
     this.warnAgainstDeprecatedConfigOptions(config);

packages/server/src/externalTypes/constructor.ts

@@ -18,7 +18,10 @@ import type {
 import type { KeyValueCache } from '@apollo/utils.keyvaluecache';
 import type { GatewayInterface } from '@apollo/server-gateway-interface';
 import type { ApolloServerPlugin } from './plugins.js';
-import type { BaseContext } from './index.js';
+import type {
+  BaseContext,
+  LegacyExperimentalExecuteIncrementally,
+} from './index.js';
 import type {
   GraphQLExperimentalIncrementalExecutionResultsAlpha2,
   GraphQLExperimentalIncrementalExecutionResultsAlpha9,
@@ -121,6 +124,8 @@ interface ApolloServerOptionsBase<TContext extends BaseContext> {
    */
   status400ForVariableCoercionErrors?: boolean;
 
+  legacyExperimentalExecuteIncrementally?: LegacyExperimentalExecuteIncrementally;
+
   // For testing only.
   __testing_incrementalExecutionResults?:
     | GraphQLExperimentalIncrementalExecutionResultsAlpha2

packages/server/src/externalTypes/graphql.ts

@@ -4,7 +4,11 @@
  * `executeHTTPGraphQLRequest` and `executeOperation`. The
  * `responseForOperation` plugin hook also returns a `GraphQLResponse`.
  */
-import type { FormattedExecutionResult } from 'graphql';
+import type {
+  ExecutionArgs,
+  ExecutionResult,
+  FormattedExecutionResult,
+} from 'graphql';
 import type { BaseContext } from './context.js';
 import type { HTTPGraphQLHead, HTTPGraphQLRequest } from './http.js';
 import type { WithRequired } from '@apollo/utils.withrequired';
@@ -16,6 +20,7 @@ import type {
   GraphQLExperimentalFormattedInitialIncrementalExecutionResultAlpha9,
   GraphQLExperimentalFormattedSubsequentIncrementalExecutionResultAlpha9,
 } from './incrementalDeliveryPolyfillAlpha9.js';
+import { type GraphQLExperimentalIncrementalExecutionResultsAlpha2 } from '../incrementalDeliveryPolyfill.js';
 
 export interface GraphQLRequest<
   TVariables extends VariableValues = VariableValues,
@@ -62,3 +67,15 @@ export type GraphQLResponse<TData = Record<string, unknown>> = WithRequired<
 export interface ExecuteOperationOptions<TContext extends BaseContext> {
   contextValue?: TContext;
 }
+
+type PromiseOrValue<T> = Promise<T> | T;
+
+export type LegacyExperimentalExecuteIncrementally<
+  TData = Record<string, unknown>,
+  TExtensions = Record<string, unknown>,
+> = (
+  args: ExecutionArgs,
+) => PromiseOrValue<
+  | ExecutionResult<TData, TExtensions>
+  | GraphQLExperimentalIncrementalExecutionResultsAlpha2<TData, TExtensions>
+>;

packages/server/src/externalTypes/index.ts

@@ -5,7 +5,11 @@
  * intention (it's public API).
  */
 export type { BaseContext, ContextFunction, ContextThunk } from './context.js';
-export type { GraphQLRequest, GraphQLResponse } from './graphql.js';
+export type {
+  GraphQLRequest,
+  GraphQLResponse,
+  LegacyExperimentalExecuteIncrementally,
+} from './graphql.js';
 export type {
   HTTPGraphQLRequest,
   HTTPGraphQLResponse,

packages/server/src/incrementalDeliveryPolyfill.ts

@@ -6,6 +6,7 @@ import {
 } from 'graphql';
 import { BadRequestError } from './internalErrorClasses.js';
 import { MEDIA_TYPES } from './ApolloServer.js';
+import { type LegacyExperimentalExecuteIncrementally } from './externalTypes/graphql.js';
 
 // This file "polyfills" graphql@17's experimentalExecuteIncrementally (by
 // returning a function that does not understand incremental directives if
@@ -191,30 +192,8 @@ let graphqlExperimentalExecuteIncrementally:
   | null
   | undefined = undefined;
 
-let legacyExecuteIncrementally:
-  | ((
-      args: ExecutionArgs,
-    ) => PromiseOrValue<
-      ExecutionResult | GraphQLExperimentalIncrementalExecutionResultsAlpha2
-    >)
-  | null
-  | undefined;
-
-async function tryToLoadLegacyExecuteIncrementally() {
-  try {
-    // @ts-ignore `@yaacovcr/transform` is an optional peer dependency
-    const transform = await import('@yaacovcr/transform');
-    legacyExecuteIncrementally = transform.legacyExecuteIncrementally;
-  } catch {
-    legacyExecuteIncrementally = null;
-  }
-}
-
 async function tryToLoadGraphQL17() {
-  if (
-    graphqlExperimentalExecuteIncrementally !== undefined &&
-    legacyExecuteIncrementally !== undefined
-  ) {
+  if (graphqlExperimentalExecuteIncrementally !== undefined) {
     return;
   }
 
@@ -223,8 +202,6 @@ async function tryToLoadGraphQL17() {
     graphql.version === '17.0.0-alpha.9' &&
     'experimentalExecuteIncrementally' in graphql
   ) {
-    await tryToLoadLegacyExecuteIncrementally();
-
     graphqlExperimentalExecuteIncrementally = (graphql as any)
       .experimentalExecuteIncrementally;
   } else {
@@ -234,17 +211,23 @@ async function tryToLoadGraphQL17() {
 
 export async function executeIncrementally({
   useLegacyIncremental,
+  legacyExperimentalExecuteIncrementally,
   ...args
-}: ExecutionArgs & { useLegacyIncremental?: boolean }): Promise<
+}: ExecutionArgs & {
+  useLegacyIncremental?: boolean;
+  legacyExperimentalExecuteIncrementally:
+    | LegacyExperimentalExecuteIncrementally
+    | undefined;
+}): Promise<
   | ExecutionResult
   | GraphQLExperimentalIncrementalExecutionResultsAlpha2
   | GraphQLExperimentalIncrementalExecutionResultsAlpha9
 > {
   await tryToLoadGraphQL17();
 
   if (useLegacyIncremental) {
-    if (legacyExecuteIncrementally) {
-      return legacyExecuteIncrementally(args);
+    if (legacyExperimentalExecuteIncrementally) {
+      return legacyExperimentalExecuteIncrementally(args);
     }
 
     // Only throw if the server supports incremental delivery with the new

packages/server/src/requestPipeline.ts

@@ -584,6 +584,8 @@ export async function processGraphQLRequest<TContext extends BaseContext>(
         operationName: request.operationName,
         fieldResolver: internals.fieldResolver,
         useLegacyIncremental,
+        legacyExperimentalExecuteIncrementally:
+          internals.legacyExperimentalExecuteIncrementally,
       });
       if ('initialResult' in resultOrResults) {
         return {