Move cache declarations to @apollo/cache-control-types (#6764)

(This package temporarily resides in the apollo-utils repo so that we
can publish it as non-alpha during the AS4 alpha process, eg for use in
`@apollo/subgraph`.)

Notably, this removes the `declare module` declaration. This does mean
that TypeScript users will have to work a tad harder (as shown in the
migration guide) to access dynamic cacheControl, but it also means that
we no longer have to worry about multiple copies of `declare module` in
a TypeScript build conflicting with each other, which has been a serious
source of pain in this past.

Co-authored-by: Rose M Koron <32436232+rkoron007@users.noreply.github.com>

.changeset/pink-eggs-draw.md

@@ -0,0 +1,7 @@
+---
+"@apollo/server-integration-testsuite": patch
+"@apollo/server-plugin-response-cache": patch
+"@apollo/server": patch
+---
+
+Get cache-control types from @apollo/cache-control-types; no more `declare module` for info.cacheControl

docs/source/migration.mdx

@@ -1090,6 +1090,7 @@ In Apollo Server 4, if your server _hasn't_ set up draining and it receives an o
 If you are using the `startStandaloneServer` function, your server drains automatically. If you are using `expressMiddleware` or another `http.Server`-based web server, you can add draining using the  [`ApolloServerPluginDrainHttpServer` plugin](/apollo-server/api/plugin/drain-http-server/#using-the-plugin).
 
 ### `CacheScope` type
+
 In Apollo Server 4,  `CacheScope` is now a union of strings (`PUBLIC` or `PRIVATE`) rather than an enum:
 
 ```ts
@@ -1098,7 +1099,7 @@ export type CacheScope = 'PUBLIC' | 'PRIVATE';
 
 You can no longer type `CacheScope.Public` or `CacheScope.Private`. Instead, just use the string `'PUBLIC'` or `'PRIVATE'`. Values defined as `CacheScope` will only accept those two values, so any typos are still caught at compile time.
 
-
+You can now import `CacheScope` from the new `@apollo/cache-control-types` package (instead of importing it from an Apollo Server package). This enables libraries that work with multiple GraphQL servers (such as `@apollo/subgraph`) to refer to `CacheScope` without depending on `@apollo/server`.
 
 ## Plugin API changes
 
@@ -1322,6 +1323,39 @@ In Apollo Server 3, the `apollo-server-env` package primarily provides TypeScrip
 Apollo Server 4 introduces `@apollo/utils.fetcher`, which defines a minimal fetch API (`Fetcher`) that provides Fetch API TypeScript typings. It is similar to `apollo-server-env` but has a clearer name and only supports argument structures that are likely to be compatible across many implementations of the Fetch API. (Specifically, it does not allow you to pass `Request` or `Headers` objects to `fetch`, because libraries often only know how to recognize their own implementations of these interfaces.)
 
 
+### `@apollo/cache-control-types`
+
+In Apollo Server 3, you could import the `CacheScope`, `CacheHint`, `CacheAnnotation`, `CachePolicy`, and `ResolveInfoCacheControl` types from your chosen Apollo Server package. 
+
+In Apollo Server 4,  the new `@apollo/cache-control-types` package exports the [`CacheScope`](#cachescope-type), `CacheHint`, `CacheAnnotation`, `CachePolicy`, and `ResolveInfoCacheControl` types. This enables libraries that work with multiple GraphQL servers (such as `@apollo/subgraph`) to refer to these types without depending on `@apollo/server`.
+
+Apollo Server 4 no longer uses the `declare module` TypeScript feature to declare that all `GraphQLResolveInfo` objects (i.e., the `info` argument to resolvers) have a `cacheControl` field. Instead, `@apollo/cache-control-types` provides a `GraphQLResolveInfoWithCacheControl` interface that you can cast `info` to (if you don't want run-time validation), or if you do want runtime validation, you can use the `maybeCacheControlFromInfo` and `cacheControlFromInfo` functions.
+
+For example, if you had this resolver in Apollo Server 3:
+
+```ts
+  someField(parent, args, context, { cacheControl }) {
+    cacheControl.setCacheHint({ maxAge: 100 });
+  }
+```
+
+you can write this in Apollo Server 4:
+
+```ts
+import { cacheControlFromInfo } from '@apollo/cache-control-types';
+
+// ...
+  someField(parent, args, context, info) {
+    cacheControlFromInfo(info).setCacheHint({ maxAge: 100 });
+  }
+```
+
+Alternatively, you can declare `info` to be of type `GraphQLResolveInfoWithCacheControl`. For example, if using `graphql-code-generator` with `typescript-resolvers`, you can use the `customResolveInfo` option.
+
+Note: this is a TypeScript-specific change. The runtime representation hasn't changed, and JavaScript code can continue to access `info.cacheControl` directly.
+
+The `CacheAnnotation` type is no longer exported from any package.
+
 ### Renamed types
 
 This section lists the TypeScript-only types (i.e.,  interfaces, not classes) whose names changed in Apollo Server 4 (not including those mentioned elsewhere in this guide).

package.json

@@ -40,6 +40,7 @@
     "npm": "^8.5.0"
   },
   "devDependencies": {
+    "@apollo/cache-control-types": "1.0.2",
     "@apollo/client": "3.6.9",
     "@apollo/utils.createhash": "1.1.0",
     "@changesets/changelog-github": "0.4.6",

packages/integration-testsuite/package.json

@@ -27,6 +27,7 @@
     "node": ">=14.0"
   },
   "dependencies": {
+    "@apollo/cache-control-types": "^1.0.2",
     "@apollo/client": "^3.6.9",
     "@apollo/utils.keyvaluecache": "^1.0.1",
     "@apollo/utils.createhash": "^1.1.0",

packages/integration-testsuite/src/httpServerTests.ts

@@ -46,6 +46,7 @@ import {
   afterEach,
 } from '@jest/globals';
 import type { Mock, SpyInstance } from 'jest-mock';
+import { cacheControlFromInfo } from '@apollo/cache-control-types';
 
 const QueryRootType = new GraphQLObjectType({
   name: 'QueryRoot',
@@ -132,7 +133,7 @@ const queryType = new GraphQLObjectType({
     testPersonWithCacheControl: {
       type: personType,
       resolve(_source, _args, _context, info) {
-        info.cacheControl.setCacheHint({ maxAge: 11 });
+        cacheControlFromInfo(info).setCacheHint({ maxAge: 11 });
         return { firstName: 'Jane', lastName: 'Doe' };
       },
     },

packages/plugin-response-cache/src/ApolloServerPluginResponseCache.ts

@@ -1,7 +1,7 @@
+import type { CacheHint } from '@apollo/cache-control-types';
 import type {
   ApolloServerPlugin,
   BaseContext,
-  CacheHint,
   GraphQLRequestContext,
   GraphQLRequestListener,
   GraphQLResponse,

packages/server/package.json

@@ -89,6 +89,7 @@
     "node": ">=12.0"
   },
   "dependencies": {
+    "@apollo/cache-control-types": "^1.0.2",
     "@apollo/usage-reporting-protobuf": "^4.0.0-alpha.1",
     "@apollo/utils.createhash": "^1.1.0",
     "@apollo/utils.fetcher": "^1.0.0",

packages/server/src/__tests__/cachePolicy.test.ts

@@ -1,4 +1,4 @@
-import type { CachePolicy } from '..';
+import type { CachePolicy } from '@apollo/cache-control-types';
 import { newCachePolicy } from '../cachePolicy.js';
 
 describe('newCachePolicy', () => {

packages/server/src/__tests__/plugin/cacheControl/cacheControlPlugin.test.ts

@@ -3,7 +3,8 @@ import {
   ApolloServerPluginCacheControl,
   ApolloServerPluginCacheControlOptions,
 } from '../../../plugin/cacheControl';
-import { ApolloServer, CacheHint, HTTPGraphQLResponse } from '../../..';
+import { ApolloServer, HTTPGraphQLResponse } from '../../..';
+import type { CacheHint } from '@apollo/cache-control-types';
 
 describe('plugin', () => {
   describe('willSendResponse', () => {

packages/server/src/__tests__/plugin/cacheControl/collectCacheControlHints.ts

@@ -1,5 +1,6 @@
+import type { CacheHint } from '@apollo/cache-control-types';
 import type { GraphQLSchema } from 'graphql';
-import { ApolloServer, CacheHint } from '../../..';
+import { ApolloServer } from '../../..';
 import {
   ApolloServerPluginCacheControl,
   ApolloServerPluginCacheControlOptions,

packages/server/src/__tests__/plugin/cacheControl/dynamicCacheControl.test.ts

@@ -1,3 +1,4 @@
+import { cacheControlFromInfo } from '@apollo/cache-control-types';
 import type {
   GraphQLScalarType,
   GraphQLFieldResolver,
@@ -38,8 +39,8 @@ describe('dynamic cache control', () => {
 
     const resolvers: GraphQLResolvers = {
       Query: {
-        droid: (_source, _args, _context, { cacheControl }) => {
-          cacheControl.setCacheHint({ maxAge: 60 });
+        droid: (_source, _args, _context, info) => {
+          cacheControlFromInfo(info).setCacheHint({ maxAge: 60 });
           return {
             id: 2001,
             name: 'R2-D2',
@@ -82,8 +83,8 @@ describe('dynamic cache control', () => {
 
     const resolvers: GraphQLResolvers = {
       Query: {
-        droid: (_source, _args, _context, { cacheControl }) => {
-          cacheControl.cacheHint.restrict({ maxAge: 60 });
+        droid: (_source, _args, _context, info) => {
+          cacheControlFromInfo(info).cacheHint.restrict({ maxAge: 60 });
           return {
             id: 2001,
             name: 'R2-D2',
@@ -126,8 +127,8 @@ describe('dynamic cache control', () => {
 
     const resolvers: GraphQLResolvers = {
       Query: {
-        droid: (_source, _args, _context, { cacheControl }) => {
-          cacheControl.setCacheHint({ scope: 'PRIVATE' });
+        droid: (_source, _args, _context, info) => {
+          cacheControlFromInfo(info).setCacheHint({ scope: 'PRIVATE' });
           return {
             id: 2001,
             name: 'R2-D2',
@@ -172,8 +173,8 @@ describe('dynamic cache control', () => {
 
     const resolvers: GraphQLResolvers = {
       Query: {
-        droid: (_source, _args, _context, { cacheControl }) => {
-          cacheControl.setCacheHint({ maxAge: 120 });
+        droid: (_source, _args, _context, info) => {
+          cacheControlFromInfo(info).setCacheHint({ maxAge: 120 });
           return {
             id: 2001,
             name: 'R2-D2',

packages/server/src/cachePolicy.ts

@@ -1,4 +1,4 @@
-import type { CacheHint, CachePolicy } from './externalTypes';
+import type { CacheHint, CachePolicy } from '@apollo/cache-control-types';
 
 export function newCachePolicy(): CachePolicy {
   return {

packages/server/src/externalTypes/graphql.ts

@@ -6,7 +6,7 @@ import type {
   GraphQLSchema,
   OperationDefinitionNode,
 } from 'graphql';
-import type { CachePolicy } from './cacheControl';
+import type { CachePolicy } from '@apollo/cache-control-types';
 import type { BaseContext } from './context';
 import type { HTTPGraphQLHead, HTTPGraphQLRequest } from './http';
 import type { ApolloServer } from '../ApolloServer';

packages/server/src/externalTypes/index.ts

@@ -4,12 +4,6 @@
  * is re-exported by the root (via * export), so add exports to this file with
  * intention (it's public API).
  */
-export type {
-  CacheAnnotation,
-  CacheHint,
-  CachePolicy,
-  CacheScope,
-} from './cacheControl.js';
 export type { BaseContext, ContextFunction, ContextThunk } from './context.js';
 export type {
   GraphQLRequest,