Add support for a human-readable string whenever passing a maxAge via schema hint or dynamic hints in code

.changeset/warm-ties-add.md

@@ -0,0 +1,7 @@
+---
+'@apollo/server-plugin-response-cache': minor
+'@apollo/cache-control-types': minor
+'@apollo/server': minor
+---
+
+Add support for a human-readable string whenever passing a maxAge via schema hint or dynamic hints in code

docs/source/performance/caching.md

@@ -9,7 +9,7 @@ description: Configure caching behavior on a per-field basis
 type Post {
   id: ID!
   title: String
-  author: Author
+  author: Author @cacheControl(maxAge: "1d")
   votes: Int @cacheControl(maxAge: 30)
   comments: [Comment]
   readByCurrentUser: Boolean! @cacheControl(maxAge: 10, scope: PRIVATE)
@@ -55,7 +55,7 @@ The `@cacheControl` directive accepts the following arguments:
 
 | Name | Description |
 |------|-------------|
-| `maxAge` | The maximum amount of time the field's cached value is valid, in seconds. The default value is `0`, but you can [set a different default](#setting-a-different-default-maxage). |
+| `maxAge` | The maximum amount of time the field's cached value is valid in seconds or [human-readable string](https://www.npmjs.com/package/ms). The default value is `0`, but you can [set a different default](#setting-a-different-default-maxage). |
 | `scope` | If `PRIVATE`, the field's value is specific to a single user. The default value is `PUBLIC`. See also [Identifying users for `PRIVATE` responses](#identifying-users-for-private-responses). |
 | `inheritMaxAge` | If `true`, this field inherits the `maxAge` of its parent field instead of using the [default `maxAge`](#setting-a-different-default-maxage). Do not provide `maxAge` if you provide this argument. |
 

packages/cache-control-types/src/index.ts

@@ -16,7 +16,7 @@ export type CacheScope = 'PUBLIC' | 'PRIVATE';
  * specify a maxAge and/or a scope.
  */
 export interface CacheHint {
-  maxAge?: number;
+  maxAge?: number | string;
   scope?: CacheScope;
 }
 

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

@@ -347,7 +347,9 @@ export default function plugin<TContext extends BaseContext>(
             // still calls `cache.set` synchronously (ie, that it writes to
             // InMemoryLRUCache synchronously).
             cache
-              .set(key, serializedValue, { ttl: policyIfCacheable.maxAge })
+              .set(key, serializedValue, {
+                ttl: policyIfCacheable.maxAge as number, // This will always be a number but user can pass in string to the cache hint which gets parsed into a number
+              })
               .catch(logger.warn);
           };
 

packages/server/package.json

@@ -138,12 +138,14 @@
     "@graphql-tools/schema": "^9.0.0",
     "@types/express": "^4.17.13",
     "@types/express-serve-static-core": "^4.17.30",
+    "@types/ms": "^0.7.34",
     "@types/node-fetch": "^2.6.1",
     "async-retry": "^1.2.1",
     "cors": "^2.8.5",
     "express": "^4.17.1",
     "loglevel": "^1.6.8",
     "lru-cache": "^7.10.1",
+    "ms": "^2.1.3",
     "negotiator": "^0.6.3",
     "node-abort-controller": "^3.1.1",
     "node-fetch": "^2.6.7",

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

@@ -109,6 +109,60 @@ describe('@cacheControl directives', () => {
     expect(hints).toStrictEqual(new Map([['droid', { maxAge: 60 }]]));
   });
 
+  it('should set the specified maxAge from a human-readable cache hint on the field when a string is passed', async () => {
+    const schema = buildSchemaWithCacheControlSupport(`
+      type Query {
+        droid(id: ID!): Droid @cacheControl(maxAge: "1d")
+      }
+
+      type Droid {
+        id: ID!
+        name: String!
+      }
+    `);
+
+    const hints = await collectCacheControlHints(
+      schema,
+      `
+        query {
+          droid(id: 2001) {
+            name
+          }
+        }
+      `,
+      { defaultMaxAge: 10 },
+    );
+
+    expect(hints).toStrictEqual(new Map([['droid', { maxAge: 86400 }]]));
+  });
+
+  it('should set the default maxAge cache hint on the field when an invalid string is passed', async () => {
+    const schema = buildSchemaWithCacheControlSupport(`
+      type Query {
+        droid(id: ID!): Droid @cacheControl(maxAge: "1ddddd")
+      }
+
+      type Droid {
+        id: ID!
+        name: String!
+      }
+    `);
+
+    const hints = await collectCacheControlHints(
+      schema,
+      `
+        query {
+          droid(id: 2001) {
+            name
+          }
+        }
+      `,
+      { defaultMaxAge: 10 },
+    );
+
+    expect(hints).toStrictEqual(new Map([['droid', { maxAge: 10 }]]));
+  });
+
   it('should set the specified maxAge for a field from a cache hint on the target type', async () => {
     const schema = buildSchemaWithCacheControlSupport(`
       type Query {

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

@@ -81,6 +81,42 @@ describe('plugin', () => {
         );
       });
 
+      // start
+      it('should set cache-control headers to default max age when provided a defaultMaxAge', async () => {
+        const response = await makePluginWithOptions({
+          pluginInitializationOptions: {
+            calculateHttpHeaders: true,
+            defaultMaxAge: 100,
+          },
+        });
+        expect(response.headers.get('cache-control')).toBe(
+          'max-age=100, public',
+        );
+      });
+
+      it('should set cache-control headers to default max age when provided a defaultMaxAge in a human readable format', async () => {
+        const response = await makePluginWithOptions({
+          pluginInitializationOptions: {
+            calculateHttpHeaders: true,
+            defaultMaxAge: '1d',
+          },
+        });
+        expect(response.headers.get('cache-control')).toBe(
+          'max-age=86400, public',
+        );
+      });
+
+      it('should not set cache-control headers when provided a defaultMaxAge in a invalid human readable format', async () => {
+        const response = await makePluginWithOptions({
+          pluginInitializationOptions: {
+            calculateHttpHeaders: true,
+            defaultMaxAge: '1ddddd',
+          },
+        });
+        expect(response.headers.get('cache-control')).toBe('no-store');
+      });
+      // end
+
       const shouldNotSetCacheControlHeader = (
         response: HTTPGraphQLResponse,
       ) => {