feat(response-cache): support @cacheControl(maxAge: Int) (#1603)

Co-authored-by: Valentin Cocaud <[email protected]>

Author: ardatan

.changeset/nasty-beers-lie.md

@@ -0,0 +1,5 @@
+---
+'@envelop/response-cache': minor
+---
+
+Support for `directive @cacheControl(maxAge: Int) on FIELD_DEFINITION | OBJECT | INTERFACE | UNION`

packages/plugins/response-cache/README.md

@@ -205,6 +205,36 @@ const getEnveloped = envelop({
 })
 ```
 
+It is also possible to define the TTL by using the `@cacheControl` directive in your schema.
+
+```ts
+import { execute, parse, subscribe, validate, buildSchema } from 'graphql'
+import { envelop } from '@envelop/core'
+import { useResponseCache, cacheControlDirective } from '@envelop/response-cache'
+
+const schema = buildSchema(/* GraphQL */ `
+  ${cacheControlDirective}
+
+  type Stock @cacheControl(maxAge: 500) {
+    # ... stock fields ...
+  }
+
+  # ... rest of the schema ...
+`)
+
+const getEnveloped = envelop({
+  parse,
+  validate,
+  execute,
+  subscribe,
+  plugins: [
+    useSchema(schema)
+    // ... other plugins ...
+    useResponseCache({ ttl: 2000 })
+  ]
+})
+```
+
 ### Cache with custom TTL per schema coordinate
 
 ```ts
@@ -230,6 +260,36 @@ const getEnveloped = envelop({
 })
 ```
 
+It is also possible to define the TTL by using the `@cacheControl` directive in your schema.
+
+```ts
+import { buildSchema, execute, parse, subscribe, validate } from 'graphql'
+import { envelop } from '@envelop/core'
+import { cacheControlDirective, useResponseCache } from '@envelop/response-cache'
+
+const schema = buildSchema(/* GraphQL */ `
+  ${cacheControlDirective}
+
+  type Query {
+    rocketCoordinates: Coordinates @cacheControl(maxAge: 100)
+  }
+
+  # ... rest of the schema ...
+`)
+
+const getEnveloped = envelop({
+  parse,
+  validate,
+  execute,
+  subscribe,
+  plugins: [
+    useSchema(schema)
+    // ... other plugins ...
+    useResponseCache({ ttl: 2000 })
+  ]
+})
+```
+
 ### Disable cache based on session/user
 
 ```ts

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

@@ -18,7 +18,7 @@ import {
   ObjMap,
   Plugin,
 } from '@envelop/core';
-import { memoize1, visitResult } from '@graphql-tools/utils';
+import { getDirective, MapperKind, mapSchema, memoize1, visitResult } from '@graphql-tools/utils';
 import type { Cache, CacheEntityRecord } from './cache.js';
 import { hashSHA256 } from './hash-sha256.js';
 import { createInMemoryCache } from './in-memory-cache.js';
@@ -245,6 +245,7 @@ export function useResponseCache<PluginContext extends Record<string, any> = {}>
     : false,
 }: UseResponseCacheParameter<PluginContext>): Plugin<PluginContext> {
   const ignoredTypesMap = new Set<string>(ignoredTypes);
+  const processedSchemas = new WeakSet();
 
   // never cache Introspections
   ttlPerSchemaCoordinate = { 'Query.__schema': 0, ...ttlPerSchemaCoordinate };
@@ -257,6 +258,38 @@ export function useResponseCache<PluginContext extends Record<string, any> = {}>
         }
       };
     },
+    onSchemaChange({ schema }) {
+      if (processedSchemas.has(schema)) {
+        return;
+      }
+      // Check if the schema has @cacheControl directive
+      const cacheControlDirective = schema.getDirective('cacheControl');
+      if (cacheControlDirective) {
+        mapSchema(schema, {
+          [MapperKind.COMPOSITE_TYPE]: type => {
+            const cacheControlAnnotations = getDirective(schema, type, 'cacheControl');
+            cacheControlAnnotations?.forEach(cacheControl => {
+              const ttl = cacheControl.maxAge * 1000;
+              if (ttl != null) {
+                ttlPerType[type.name] = ttl;
+              }
+            });
+            return type;
+          },
+          [MapperKind.FIELD]: (fieldConfig, fieldName, typeName) => {
+            const cacheControlAnnotations = getDirective(schema, fieldConfig, 'cacheControl');
+            cacheControlAnnotations?.forEach(cacheControl => {
+              const ttl = cacheControl.maxAge * 1000;
+              if (ttl != null) {
+                ttlPerSchemaCoordinate[`${typeName}.${fieldName}`] = ttl;
+              }
+            });
+            return fieldConfig;
+          },
+        });
+      }
+      processedSchemas.add(schema);
+    },
     async onExecute(onExecuteParams) {
       const identifier = new Map<string, CacheEntityRecord>();
       const types = new Set<string>();
@@ -487,3 +520,7 @@ function calculateTtl(typeTtl: number, currentTtl: number | undefined): number {
   }
   return typeTtl;
 }
+
+export const cacheControlDirective = /* GraphQL */ `
+  directive @cacheControl(maxAge: Int) on FIELD_DEFINITION | OBJECT
+`;

packages/plugins/response-cache/test/response-cache.spec.ts

@@ -2099,6 +2099,84 @@ describe('useResponseCache', () => {
       });
     });
   });
+  it('supports @cacheControl directive with maxAge on a field', async () => {
+    const schema = makeExecutableSchema({
+      typeDefs: /* GraphQL */ `
+        directive @cacheControl(maxAge: Int) on FIELD_DEFINITION
+        type Query {
+          foo: String @cacheControl(maxAge: 10)
+        }
+      `,
+      resolvers: {
+        Query: {
+          foo: () => 'bar',
+        },
+      },
+    });
+    const testkit = createTestkit(
+      [
+        useResponseCache({
+          session: () => null,
+          includeExtensionMetadata: true,
+        }),
+      ],
+      schema,
+    );
+    const operation = /* GraphQL */ `
+      {
+        foo
+      }
+    `;
+    const result = await testkit.execute(operation);
+    assertSingleExecutionValue(result);
+    expect(result.extensions?.['responseCache']).toEqual({
+      didCache: true,
+      hit: false,
+      ttl: 10000,
+    });
+  });
+
+  it('supports @cacheControl directive with maxAge on a type', async () => {
+    const schema = makeExecutableSchema({
+      typeDefs: /* GraphQL */ `
+        directive @cacheControl(maxAge: Int) on OBJECT
+        type Query {
+          foo: Foo
+        }
+        type Foo @cacheControl(maxAge: 10) {
+          id: String
+        }
+      `,
+      resolvers: {
+        Query: {
+          foo: () => ({ id: 'baz' }),
+        },
+      },
+    });
+    const testkit = createTestkit(
+      [
+        useResponseCache({
+          session: () => null,
+          includeExtensionMetadata: true,
+        }),
+      ],
+      schema,
+    );
+    const operation = /* GraphQL */ `
+      {
+        foo {
+          id
+        }
+      }
+    `;
+    const result = await testkit.execute(operation);
+    assertSingleExecutionValue(result);
+    expect(result.extensions?.['responseCache']).toEqual({
+      didCache: true,
+      hit: false,
+      ttl: 10000,
+    });
+  });
 
   describe('ignoring and ttl per type for types without id field', () => {
     let spyWithId: jest.Mock<{ id: Number; field: String }, []>;