@envelop/response-cache 8.2.0-alpha-20251013081815-d6f74fceb1a32fd336b2664f90f87872e1bbf2fe → 8.2.0-alpha-20251217212728-de569f3d7fe45e330eca177b69ee1c89fd5dc498

package/README.md

@@ -863,3 +863,67 @@ mutation SetNameMutation {
   }
 }
 ```
+
+#### Get scope of the query
+
+Useful for building a cache with more flexibility (e.g. generate a key that is shared across all
+sessions when `PUBLIC`).
+
+```ts
+import jsonStableStringify from 'fast-json-stable-stringify'
+import { execute, parse, subscribe, validate } from 'graphql'
+import { envelop } from '@envelop/core'
+import { hashSHA256, useResponseCache } from '@envelop/response-cache'
+
+const schema = buildSchema(/* GraphQL */ `
+  ${cacheControlDirective}
+  type PrivateProfile @cacheControl(scope: PRIVATE) {
+    # ...
+  }
+
+  type Profile {
+    privateData: String @cacheControl(scope: PRIVATE)
+  }
+`)
+
+const getEnveloped = envelop({
+  parse,
+  validate,
+  execute,
+  subscribe,
+  plugins: [
+    // ... other plugins ...
+    useResponseCache({
+      ttl: 2000,
+      session: request => getSessionId(request),
+      buildResponseCacheKey: ({
+        sessionId,
+        documentString,
+        operationName,
+        variableValues,
+        extras
+      }) =>
+        hashSHA256(
+          [
+            // Use it to put a unique key for every session when `PUBLIC`
+            extras(schema).scope === 'PUBLIC' ? 'PUBLIC' : sessionId,
+            documentString,
+            operationName ?? '',
+            jsonStableStringify(variableValues ?? {})
+          ].join('|')
+        ),
+      scopePerSchemaCoordinate: {
+        // Set scope for an entire query
+        'Query.getProfile': 'PRIVATE',
+        // Set scope for an entire type
+        PrivateProfile: 'PRIVATE',
+        // Set scope for a single field
+        'Profile.privateData': 'PRIVATE'
+      }
+    })
+  ]
+})
+```
+
+> Note: The use of this callback will increase the ram usage since it memoizes the scope for each
+> query in a weak map.

package/cjs/plugin.js

@@ -7,6 +7,7 @@ exports.resultWithMetadata = resultWithMetadata;
 const tslib_1 = require("tslib");
 const fast_json_stable_stringify_1 = tslib_1.__importDefault(require("fast-json-stable-stringify"));
 const graphql_1 = require("graphql");
+const lru_cache_1 = require("lru-cache");
 const core_1 = require("@envelop/core");
 const utils_1 = require("@graphql-tools/utils");
 const promise_helpers_1 = require("@whatwg-node/promise-helpers");
@@ -96,41 +97,62 @@ const getDocumentWithMetadataAndTTL = (0, utils_1.memoize4)(function addTypeName
     };
     return [(0, graphql_1.visit)(document, (0, graphql_1.visitWithTypeInfo)(typeInfo, visitor)), ttl];
 });
-function useResponseCache({ cache = (0, in_memory_cache_js_1.createInMemoryCache)(), ttl: globalTtl = Infinity, session, enabled, ignoredTypes = [], ttlPerType, ttlPerSchemaCoordinate = {}, scopePerSchemaCoordinate = {}, idFields = ['id'], invalidateViaMutation = true, buildResponseCacheKey = exports.defaultBuildResponseCacheKey, getDocumentString = defaultGetDocumentString, shouldCacheResult = exports.defaultShouldCacheResult, onTtl, includeExtensionMetadata = typeof process !== 'undefined'
+const DOCUMENTS_SCOPE_MAX = 1000;
+const DOCUMENTS_SCOPE_TTL = 3600000;
+function useResponseCache({ cache = (0, in_memory_cache_js_1.createInMemoryCache)(), ttl: globalTtl = Infinity, session, enabled, ignoredTypes = [], ttlPerType, idFields = ['id'], invalidateViaMutation = true, ignoreSessionIdForPublicScope = false, buildResponseCacheKey = exports.defaultBuildResponseCacheKey, getDocumentString = defaultGetDocumentString, shouldCacheResult = exports.defaultShouldCacheResult, onTtl, includeExtensionMetadata = typeof process !== 'undefined'
     ? // eslint-disable-next-line dot-notation
         process.env['NODE_ENV'] === 'development' || !!process.env['DEBUG']
-    : false, }) {
+    : false, ...options }) {
     const cacheFactory = typeof cache === 'function' ? (0, utils_1.memoize1)(cache) : () => cache;
     const ignoredTypesMap = new Set(ignoredTypes);
-    const typePerSchemaCoordinateMap = new Map();
     enabled = enabled ? (0, utils_1.memoize1)(enabled) : enabled;
-    // never cache Introspections
-    ttlPerSchemaCoordinate = { 'Query.__schema': 0, ...ttlPerSchemaCoordinate };
+    const configPerSchemaCoordinate = {
+        // never cache Introspections
+        ttl: { 'Query.__schema': 0, ...options.ttlPerSchemaCoordinate },
+        scope: { ...options.scopePerSchemaCoordinate },
+    };
     if (ttlPerType) {
         // eslint-disable-next-line no-console
         console.warn('[useResponseCache] `ttlForType` is deprecated. To migrate, merge it with `ttlForSchemaCoordinate` option');
         for (const [typeName, ttl] of Object.entries(ttlPerType)) {
-            ttlPerSchemaCoordinate[typeName] = ttl;
+            configPerSchemaCoordinate.ttl[typeName] = ttl;
         }
     }
-    const documentMetadataOptions = {
-        queries: { invalidateViaMutation, ttlPerSchemaCoordinate },
-        mutations: { invalidateViaMutation }, // remove ttlPerSchemaCoordinate for mutations to skip TTL calculation
+    const makeSchemaConfig = function makeSchemaConfig(schema) {
+        const ttl = { ...configPerSchemaCoordinate.ttl };
+        const scope = { ...configPerSchemaCoordinate.scope };
+        return {
+            schema,
+            perSchemaCoordinate: { ttl, scope, type: new Map() },
+            idFieldByTypeName: new Map(),
+            publicDocuments: new lru_cache_1.LRUCache({
+                max: DOCUMENTS_SCOPE_MAX,
+                ttl: DOCUMENTS_SCOPE_TTL,
+            }),
+            documentMetadataOptions: {
+                // Do not override mutations metadata to keep a stable reference for memoization
+                mutations: { invalidateViaMutation },
+                queries: { invalidateViaMutation, ttlPerSchemaCoordinate: ttl },
+            },
+            isPrivate(typeName, data) {
+                if (scope[typeName] === 'PRIVATE') {
+                    return true;
+                }
+                return data
+                    ? Object.keys(data).some(fieldName => scope[`${typeName}.${fieldName}`] === 'PRIVATE')
+                    : false;
+            },
+        };
     };
-    const idFieldByTypeName = new Map();
-    let schema;
-    function isPrivate(typeName, data) {
-        if (scopePerSchemaCoordinate[typeName] === 'PRIVATE') {
-            return true;
-        }
-        return Object.keys(data).some(fieldName => scopePerSchemaCoordinate[`${typeName}.${fieldName}`] === 'PRIVATE');
-    }
+    const schemaConfigs = new WeakMap();
     return {
-        onSchemaChange({ schema: newSchema }) {
-            if (schema === newSchema) {
+        onSchemaChange({ schema }) {
+            if (schemaConfigs.has(schema)) {
                 return;
             }
-            schema = newSchema;
+            const config = makeSchemaConfig(schema);
+            schemaConfigs.set(schema, config);
+            // Reset all configs, to avoid keeping stale field configuration
             const directive = schema.getDirective('cacheControl');
             (0, utils_1.mapSchema)(schema, {
                 ...(directive && {
@@ -138,10 +160,10 @@ function useResponseCache({ cache = (0, in_memory_cache_js_1.createInMemoryCache
                         const cacheControlAnnotations = (0, utils_1.getDirective)(schema, type, 'cacheControl');
                         cacheControlAnnotations?.forEach(cacheControl => {
                             if (cacheControl.maxAge != null) {
-                                ttlPerSchemaCoordinate[type.name] = cacheControl.maxAge * 1000;
+                                config.perSchemaCoordinate.ttl[type.name] = cacheControl.maxAge * 1000;
                             }
                             if (cacheControl.scope) {
-                                scopePerSchemaCoordinate[type.name] = cacheControl.scope;
+                                config.perSchemaCoordinate.scope[type.name] = cacheControl.scope;
                             }
                         });
                         return type;
@@ -150,18 +172,18 @@ function useResponseCache({ cache = (0, in_memory_cache_js_1.createInMemoryCache
                 [utils_1.MapperKind.FIELD]: (fieldConfig, fieldName, typeName) => {
                     const schemaCoordinates = `${typeName}.${fieldName}`;
                     const resultTypeNames = unwrapTypenames(fieldConfig.type);
-                    typePerSchemaCoordinateMap.set(schemaCoordinates, resultTypeNames);
-                    if (idFields.includes(fieldName) && !idFieldByTypeName.has(typeName)) {
-                        idFieldByTypeName.set(typeName, fieldName);
+                    config.perSchemaCoordinate.type.set(schemaCoordinates, resultTypeNames);
+                    if (idFields.includes(fieldName) && !config.idFieldByTypeName.has(typeName)) {
+                        config.idFieldByTypeName.set(typeName, fieldName);
                     }
                     if (directive) {
                         const cacheControlAnnotations = (0, utils_1.getDirective)(schema, fieldConfig, 'cacheControl');
                         cacheControlAnnotations?.forEach(cacheControl => {
                             if (cacheControl.maxAge != null) {
-                                ttlPerSchemaCoordinate[schemaCoordinates] = cacheControl.maxAge * 1000;
+                                config.perSchemaCoordinate.ttl[schemaCoordinates] = cacheControl.maxAge * 1000;
                             }
                             if (cacheControl.scope) {
-                                scopePerSchemaCoordinate[schemaCoordinates] = cacheControl.scope;
+                                config.perSchemaCoordinate.scope[schemaCoordinates] = cacheControl.scope;
                             }
                         });
                     }
@@ -173,11 +195,25 @@ function useResponseCache({ cache = (0, in_memory_cache_js_1.createInMemoryCache
             if (enabled && !enabled(onExecuteParams.args.contextValue)) {
                 return;
             }
+            const { schema } = onExecuteParams.args;
+            if (!schemaConfigs.has(schema)) {
+                // eslint-disable-next-line no-console
+                console.error('[response-cache] Unknown schema, operation ignored');
+                return;
+            }
+            const config = schemaConfigs.get(schema);
             const identifier = new Map();
             const types = new Set();
             let currentTtl;
+            let isPrivate = false;
             let skip = false;
-            const sessionId = session(onExecuteParams.args.contextValue);
+            const documentString = getDocumentString(onExecuteParams.args);
+            // Verify if we already know this document is public or not. If it is public, we should not
+            // take the session ID into account. If not, we keep the default behavior of letting user
+            // decide if a session id should be used to build the key
+            const sessionId = ignoreSessionIdForPublicScope && config.publicDocuments.get(documentString)
+                ? undefined
+                : session(onExecuteParams.args.contextValue);
             function setExecutor({ execute, onExecuteDone, }) {
                 let executed = false;
                 onExecuteParams.setExecuteFn(args => {
@@ -198,21 +234,21 @@ function useResponseCache({ cache = (0, in_memory_cache_js_1.createInMemoryCache
                 if (skip) {
                     return;
                 }
-                if (ignoredTypesMap.has(entity.typename) ||
-                    (!sessionId && isPrivate(entity.typename, data))) {
+                isPrivate ||= config.isPrivate(entity.typename, data);
+                if (ignoredTypesMap.has(entity.typename) || (!sessionId && isPrivate)) {
                     skip = true;
                     return;
                 }
                 // in case the entity has no id, we attempt to extract it from the data
                 if (!entity.id) {
-                    const idField = idFieldByTypeName.get(entity.typename);
+                    const idField = config.idFieldByTypeName.get(entity.typename);
                     if (idField) {
                         entity.id = data[idField];
                     }
                 }
                 types.add(entity.typename);
-                if (entity.typename in ttlPerSchemaCoordinate) {
-                    const maybeTtl = ttlPerSchemaCoordinate[entity.typename];
+                if (entity.typename in config.perSchemaCoordinate.ttl) {
+                    const maybeTtl = config.perSchemaCoordinate.ttl[entity.typename];
                     currentTtl = calculateTtl(maybeTtl, currentTtl);
                 }
                 if (entity.id != null) {
@@ -221,10 +257,10 @@ function useResponseCache({ cache = (0, in_memory_cache_js_1.createInMemoryCache
                 for (const fieldName in data) {
                     const fieldData = data[fieldName];
                     if (fieldData == null || (Array.isArray(fieldData) && fieldData.length === 0)) {
-                        const inferredTypes = typePerSchemaCoordinateMap.get(`${entity.typename}.${fieldName}`);
+                        const inferredTypes = config.perSchemaCoordinate.type.get(`${entity.typename}.${fieldName}`);
                         inferredTypes?.forEach(inferredType => {
-                            if (inferredType in ttlPerSchemaCoordinate) {
-                                const maybeTtl = ttlPerSchemaCoordinate[inferredType];
+                            if (inferredType in config.perSchemaCoordinate.ttl) {
+                                const maybeTtl = config.perSchemaCoordinate.ttl[inferredType];
                                 currentTtl = calculateTtl(maybeTtl, currentTtl);
                             }
                             identifier.set(inferredType, { typename: inferredType });
@@ -233,9 +269,11 @@ function useResponseCache({ cache = (0, in_memory_cache_js_1.createInMemoryCache
                 }
             }
             function invalidateCache(result, setResult) {
+                let changed = false;
                 if (result.data) {
-                    collectEntities(result.data, onEntity);
-                    setStringifyWithoutMetadata(result);
+                    result = { ...result };
+                    result.data = removeMetadataFieldsFromResult(result.data, onEntity);
+                    changed = true;
                 }
                 const cacheInstance = cacheFactory(onExecuteParams.args.contextValue);
                 if (cacheInstance == null) {
@@ -251,13 +289,16 @@ function useResponseCache({ cache = (0, in_memory_cache_js_1.createInMemoryCache
                         }));
                     }
                 }
+                if (changed) {
+                    setResult(result);
+                }
             }
             if (invalidateViaMutation !== false) {
                 const operationAST = (0, graphql_1.getOperationAST)(onExecuteParams.args.document, onExecuteParams.args.operationName);
                 if (operationAST?.operation === 'mutation') {
                     return setExecutor({
                         execute(args) {
-                            const [document] = getDocumentWithMetadataAndTTL(args.document, documentMetadataOptions.mutations, args.schema, idFieldByTypeName);
+                            const [document] = getDocumentWithMetadataAndTTL(args.document, config.documentMetadataOptions.mutations, args.schema, config.idFieldByTypeName);
                             return onExecuteParams.executeFn({ ...args, document });
                         },
                         onExecuteDone({ result, setResult }) {
@@ -270,30 +311,36 @@ function useResponseCache({ cache = (0, in_memory_cache_js_1.createInMemoryCache
                 }
             }
             return (0, promise_helpers_1.handleMaybePromise)(() => buildResponseCacheKey({
-                documentString: getDocumentString(onExecuteParams.args),
+                sessionId,
+                documentString,
                 variableValues: onExecuteParams.args.variableValues,
                 operationName: onExecuteParams.args.operationName,
-                sessionId,
                 context: onExecuteParams.args.contextValue,
             }), cacheKey => {
                 const cacheInstance = cacheFactory(onExecuteParams.args.contextValue);
                 if (cacheInstance == null) {
                     // eslint-disable-next-line no-console
                     console.warn('[useResponseCache] Cache instance is not available for the context. Skipping cache lookup.');
+                    return;
                 }
-                return (0, promise_helpers_1.handleMaybePromise)(() => cacheInstance.get(cacheKey), cachedResponse => {
-                    if (cachedResponse != null) {
-                        return setExecutor({
-                            execute: () => includeExtensionMetadata
-                                ? resultWithMetadata(cachedResponse, { hit: true })
-                                : cachedResponse,
-                        });
+                function maybeCacheResult(result, setResult) {
+                    if (result.data) {
+                        result.data = removeMetadataFieldsFromResult(result.data, onEntity);
                     }
-                    function maybeCacheResult(result, setResult) {
-                        if (result.data) {
-                            collectEntities(result.data, onEntity);
-                            setStringifyWithoutMetadata(result);
+                    return (0, promise_helpers_1.handleMaybePromise)(() => {
+                        if (!skip && ignoreSessionIdForPublicScope && !isPrivate && sessionId) {
+                            config.publicDocuments.set(documentString, true);
+                            return buildResponseCacheKey({
+                                // Build a public key for this document
+                                sessionId: undefined,
+                                documentString,
+                                variableValues: onExecuteParams.args.variableValues,
+                                operationName: onExecuteParams.args.operationName,
+                                context: onExecuteParams.args.contextValue,
+                            });
                         }
+                        return cacheKey;
+                    }, cacheKey => {
                         // we only use the global ttl if no currentTtl has been determined.
                         let finalTtl = currentTtl ?? globalTtl;
                         if (onTtl) {
@@ -312,10 +359,19 @@ function useResponseCache({ cache = (0, in_memory_cache_js_1.createInMemoryCache
                         if (includeExtensionMetadata) {
                             setResult(resultWithMetadata(result, { hit: false, didCache: true, ttl: finalTtl }));
                         }
+                    });
+                }
+                return (0, promise_helpers_1.handleMaybePromise)(() => cacheInstance.get(cacheKey), cachedResponse => {
+                    if (cachedResponse != null) {
+                        return setExecutor({
+                            execute: () => includeExtensionMetadata
+                                ? resultWithMetadata(cachedResponse, { hit: true })
+                                : cachedResponse,
+                        });
                     }
                     return setExecutor({
                         execute(args) {
-                            const [document, ttl] = getDocumentWithMetadataAndTTL(args.document, documentMetadataOptions.queries, schema, idFieldByTypeName);
+                            const [document, ttl] = getDocumentWithMetadataAndTTL(args.document, config.documentMetadataOptions.queries, schema, config.idFieldByTypeName);
                             currentTtl = ttl;
                             return onExecuteParams.executeFn({ ...args, document });
                         },
@@ -340,7 +396,7 @@ function handleAsyncIterableResult(handler) {
         onNext(payload) {
             // This is the first result with the initial data payload sent to the client. We use it as the base result
             if (payload.result.data) {
-                result.data = structuredClone(payload.result.data);
+                result.data = payload.result.data;
             }
             if (payload.result.errors) {
                 result.errors = payload.result.errors;
@@ -352,10 +408,7 @@ function handleAsyncIterableResult(handler) {
                 const { incremental, hasNext } = payload.result;
                 if (incremental) {
                     for (const patch of incremental) {
-                        (0, utils_1.mergeIncrementalResult)({
-                            executionResult: result,
-                            incrementalResult: structuredClone(patch),
-                        });
+                        (0, utils_1.mergeIncrementalResult)({ executionResult: result, incrementalResult: patch });
                     }
                 }
                 if (!hasNext) {
@@ -363,22 +416,30 @@ function handleAsyncIterableResult(handler) {
                     handler(result, payload.setResult);
                 }
             }
-            if (payload.result.data) {
-                collectEntities(payload.result.data);
+            const newResult = { ...payload.result };
+            // Handle initial/single result
+            if (newResult.data) {
+                newResult.data = removeMetadataFieldsFromResult(newResult.data);
             }
             // Handle Incremental results
-            if ('hasNext' in payload.result && payload.result.incremental) {
-                payload.result.incremental = payload.result.incremental.map(value => {
+            if ('hasNext' in newResult && newResult.incremental) {
+                newResult.incremental = newResult.incremental.map(value => {
                     if ('items' in value && value.items) {
-                        collectEntities(value.items);
+                        return {
+                            ...value,
+                            items: removeMetadataFieldsFromResult(value.items),
+                        };
                     }
                     if ('data' in value && value.data) {
-                        collectEntities(value.data);
+                        return {
+                            ...value,
+                            data: removeMetadataFieldsFromResult(value.data),
+                        };
                     }
                     return value;
                 });
             }
-            setStringifyWithoutMetadata(payload.result);
+            payload.setResult(newResult);
         },
     };
 }
@@ -423,45 +484,38 @@ exports.cacheControlDirective = `
 
   directive @cacheControl(maxAge: Int, scope: CacheControlScope) on FIELD_DEFINITION | OBJECT
 `;
-function collectEntities(data, onEntity) {
+function removeMetadataFieldsFromResult(data, onEntity) {
     if (Array.isArray(data)) {
-        for (const record of data) {
-            collectEntities(record, onEntity);
-        }
-        return;
+        return data.map(record => removeMetadataFieldsFromResult(record, onEntity));
     }
     if (typeof data !== 'object' || data == null) {
-        return;
+        return data;
     }
     const dataPrototype = Object.getPrototypeOf(data);
-    // TODO: For some reason, when running in Jest, `structuredClone` result have a weird prototype
-    //       that doesn't equal Object.prototype as it should.
-    //       As a workaround, we can just check that there is no parent prototype, which should be
-    //       the case only when it's the Object prototype
-    //       Rollback once migrated to Bun or vitest
-    //
-    // if (dataPrototype != null && dataPrototype !== Object.prototype) {
-    if (dataPrototype != null && Object.getPrototypeOf(dataPrototype) !== null) {
-        // It is not a plain object, like a Date, don't inspect further
-        return;
+    if (dataPrototype != null && dataPrototype !== Object.prototype) {
+        return data;
     }
+    // clone the data to avoid mutation
+    data = { ...data };
     const typename = data.__responseCacheTypeName ?? data.__typename;
     if (typeof typename === 'string') {
         const entity = { typename };
+        delete data.__responseCacheTypeName;
         if (data.__responseCacheId &&
             (typeof data.__responseCacheId === 'string' || typeof data.__responseCacheId === 'number')) {
             entity.id = data.__responseCacheId;
+            delete data.__responseCacheId;
         }
         onEntity?.(entity, data);
     }
     for (const key in data) {
-        collectEntities(data[key], onEntity);
+        const value = data[key];
+        if (Array.isArray(value)) {
+            data[key] = removeMetadataFieldsFromResult(value, onEntity);
+        }
+        if (value !== null && typeof value === 'object') {
+            data[key] = removeMetadataFieldsFromResult(value, onEntity);
+        }
     }
+    return data;
 }
-function setStringifyWithoutMetadata(result) {
-    result.stringify = stringifyWithoutMetadata;
-    return result;
-}
-const stringifyWithoutMetadata = result => {
-    return JSON.stringify(result, (key, value) => key === '__responseCacheId' || key === '__responseCacheTypeName' ? undefined : value);
-};

package/esm/plugin.js

@@ -1,5 +1,6 @@
-import jsonStableStringify from 'fast-json-stable-stringify';
+import stringify from 'fast-json-stable-stringify';
 import { getOperationAST, isListType, isNonNullType, isUnionType, Kind, print, TypeInfo, visit, visitWithTypeInfo, } from 'graphql';
+import { LRUCache } from 'lru-cache';
 import { getDocumentString, isAsyncIterable, } from '@envelop/core';
 import { getDirective, MapperKind, mapSchema, memoize1, memoize4, mergeIncrementalResult, } from '@graphql-tools/utils';
 import { handleMaybePromise } from '@whatwg-node/promise-helpers';
@@ -12,7 +13,7 @@ import { createInMemoryCache } from './in-memory-cache.js';
 export const defaultBuildResponseCacheKey = (params) => hashSHA256([
     params.documentString,
     params.operationName ?? '',
-    jsonStableStringify(params.variableValues ?? {}),
+    stringify(params.variableValues ?? {}),
     params.sessionId ?? '',
 ].join('|'));
 /**
@@ -87,41 +88,62 @@ const getDocumentWithMetadataAndTTL = memoize4(function addTypeNameToDocument(do
     };
     return [visit(document, visitWithTypeInfo(typeInfo, visitor)), ttl];
 });
-export function useResponseCache({ cache = createInMemoryCache(), ttl: globalTtl = Infinity, session, enabled, ignoredTypes = [], ttlPerType, ttlPerSchemaCoordinate = {}, scopePerSchemaCoordinate = {}, idFields = ['id'], invalidateViaMutation = true, buildResponseCacheKey = defaultBuildResponseCacheKey, getDocumentString = defaultGetDocumentString, shouldCacheResult = defaultShouldCacheResult, onTtl, includeExtensionMetadata = typeof process !== 'undefined'
+const DOCUMENTS_SCOPE_MAX = 1000;
+const DOCUMENTS_SCOPE_TTL = 3600000;
+export function useResponseCache({ cache = createInMemoryCache(), ttl: globalTtl = Infinity, session, enabled, ignoredTypes = [], ttlPerType, idFields = ['id'], invalidateViaMutation = true, ignoreSessionIdForPublicScope = false, buildResponseCacheKey = defaultBuildResponseCacheKey, getDocumentString = defaultGetDocumentString, shouldCacheResult = defaultShouldCacheResult, onTtl, includeExtensionMetadata = typeof process !== 'undefined'
     ? // eslint-disable-next-line dot-notation
         process.env['NODE_ENV'] === 'development' || !!process.env['DEBUG']
-    : false, }) {
+    : false, ...options }) {
     const cacheFactory = typeof cache === 'function' ? memoize1(cache) : () => cache;
     const ignoredTypesMap = new Set(ignoredTypes);
-    const typePerSchemaCoordinateMap = new Map();
     enabled = enabled ? memoize1(enabled) : enabled;
-    // never cache Introspections
-    ttlPerSchemaCoordinate = { 'Query.__schema': 0, ...ttlPerSchemaCoordinate };
+    const configPerSchemaCoordinate = {
+        // never cache Introspections
+        ttl: { 'Query.__schema': 0, ...options.ttlPerSchemaCoordinate },
+        scope: { ...options.scopePerSchemaCoordinate },
+    };
     if (ttlPerType) {
         // eslint-disable-next-line no-console
         console.warn('[useResponseCache] `ttlForType` is deprecated. To migrate, merge it with `ttlForSchemaCoordinate` option');
         for (const [typeName, ttl] of Object.entries(ttlPerType)) {
-            ttlPerSchemaCoordinate[typeName] = ttl;
+            configPerSchemaCoordinate.ttl[typeName] = ttl;
         }
     }
-    const documentMetadataOptions = {
-        queries: { invalidateViaMutation, ttlPerSchemaCoordinate },
-        mutations: { invalidateViaMutation }, // remove ttlPerSchemaCoordinate for mutations to skip TTL calculation
+    const makeSchemaConfig = function makeSchemaConfig(schema) {
+        const ttl = { ...configPerSchemaCoordinate.ttl };
+        const scope = { ...configPerSchemaCoordinate.scope };
+        return {
+            schema,
+            perSchemaCoordinate: { ttl, scope, type: new Map() },
+            idFieldByTypeName: new Map(),
+            publicDocuments: new LRUCache({
+                max: DOCUMENTS_SCOPE_MAX,
+                ttl: DOCUMENTS_SCOPE_TTL,
+            }),
+            documentMetadataOptions: {
+                // Do not override mutations metadata to keep a stable reference for memoization
+                mutations: { invalidateViaMutation },
+                queries: { invalidateViaMutation, ttlPerSchemaCoordinate: ttl },
+            },
+            isPrivate(typeName, data) {
+                if (scope[typeName] === 'PRIVATE') {
+                    return true;
+                }
+                return data
+                    ? Object.keys(data).some(fieldName => scope[`${typeName}.${fieldName}`] === 'PRIVATE')
+                    : false;
+            },
+        };
     };
-    const idFieldByTypeName = new Map();
-    let schema;
-    function isPrivate(typeName, data) {
-        if (scopePerSchemaCoordinate[typeName] === 'PRIVATE') {
-            return true;
-        }
-        return Object.keys(data).some(fieldName => scopePerSchemaCoordinate[`${typeName}.${fieldName}`] === 'PRIVATE');
-    }
+    const schemaConfigs = new WeakMap();
     return {
-        onSchemaChange({ schema: newSchema }) {
-            if (schema === newSchema) {
+        onSchemaChange({ schema }) {
+            if (schemaConfigs.has(schema)) {
                 return;
             }
-            schema = newSchema;
+            const config = makeSchemaConfig(schema);
+            schemaConfigs.set(schema, config);
+            // Reset all configs, to avoid keeping stale field configuration
             const directive = schema.getDirective('cacheControl');
             mapSchema(schema, {
                 ...(directive && {
@@ -129,10 +151,10 @@ export function useResponseCache({ cache = createInMemoryCache(), ttl: globalTtl
                         const cacheControlAnnotations = getDirective(schema, type, 'cacheControl');
                         cacheControlAnnotations?.forEach(cacheControl => {
                             if (cacheControl.maxAge != null) {
-                                ttlPerSchemaCoordinate[type.name] = cacheControl.maxAge * 1000;
+                                config.perSchemaCoordinate.ttl[type.name] = cacheControl.maxAge * 1000;
                             }
                             if (cacheControl.scope) {
-                                scopePerSchemaCoordinate[type.name] = cacheControl.scope;
+                                config.perSchemaCoordinate.scope[type.name] = cacheControl.scope;
                             }
                         });
                         return type;
@@ -141,18 +163,18 @@ export function useResponseCache({ cache = createInMemoryCache(), ttl: globalTtl
                 [MapperKind.FIELD]: (fieldConfig, fieldName, typeName) => {
                     const schemaCoordinates = `${typeName}.${fieldName}`;
                     const resultTypeNames = unwrapTypenames(fieldConfig.type);
-                    typePerSchemaCoordinateMap.set(schemaCoordinates, resultTypeNames);
-                    if (idFields.includes(fieldName) && !idFieldByTypeName.has(typeName)) {
-                        idFieldByTypeName.set(typeName, fieldName);
+                    config.perSchemaCoordinate.type.set(schemaCoordinates, resultTypeNames);
+                    if (idFields.includes(fieldName) && !config.idFieldByTypeName.has(typeName)) {
+                        config.idFieldByTypeName.set(typeName, fieldName);
                     }
                     if (directive) {
                         const cacheControlAnnotations = getDirective(schema, fieldConfig, 'cacheControl');
                         cacheControlAnnotations?.forEach(cacheControl => {
                             if (cacheControl.maxAge != null) {
-                                ttlPerSchemaCoordinate[schemaCoordinates] = cacheControl.maxAge * 1000;
+                                config.perSchemaCoordinate.ttl[schemaCoordinates] = cacheControl.maxAge * 1000;
                             }
                             if (cacheControl.scope) {
-                                scopePerSchemaCoordinate[schemaCoordinates] = cacheControl.scope;
+                                config.perSchemaCoordinate.scope[schemaCoordinates] = cacheControl.scope;
                             }
                         });
                     }
@@ -164,11 +186,25 @@ export function useResponseCache({ cache = createInMemoryCache(), ttl: globalTtl
             if (enabled && !enabled(onExecuteParams.args.contextValue)) {
                 return;
             }
+            const { schema } = onExecuteParams.args;
+            if (!schemaConfigs.has(schema)) {
+                // eslint-disable-next-line no-console
+                console.error('[response-cache] Unknown schema, operation ignored');
+                return;
+            }
+            const config = schemaConfigs.get(schema);
             const identifier = new Map();
             const types = new Set();
             let currentTtl;
+            let isPrivate = false;
             let skip = false;
-            const sessionId = session(onExecuteParams.args.contextValue);
+            const documentString = getDocumentString(onExecuteParams.args);
+            // Verify if we already know this document is public or not. If it is public, we should not
+            // take the session ID into account. If not, we keep the default behavior of letting user
+            // decide if a session id should be used to build the key
+            const sessionId = ignoreSessionIdForPublicScope && config.publicDocuments.get(documentString)
+                ? undefined
+                : session(onExecuteParams.args.contextValue);
             function setExecutor({ execute, onExecuteDone, }) {
                 let executed = false;
                 onExecuteParams.setExecuteFn(args => {
@@ -189,21 +225,21 @@ export function useResponseCache({ cache = createInMemoryCache(), ttl: globalTtl
                 if (skip) {
                     return;
                 }
-                if (ignoredTypesMap.has(entity.typename) ||
-                    (!sessionId && isPrivate(entity.typename, data))) {
+                isPrivate ||= config.isPrivate(entity.typename, data);
+                if (ignoredTypesMap.has(entity.typename) || (!sessionId && isPrivate)) {
                     skip = true;
                     return;
                 }
                 // in case the entity has no id, we attempt to extract it from the data
                 if (!entity.id) {
-                    const idField = idFieldByTypeName.get(entity.typename);
+                    const idField = config.idFieldByTypeName.get(entity.typename);
                     if (idField) {
                         entity.id = data[idField];
                     }
                 }
                 types.add(entity.typename);
-                if (entity.typename in ttlPerSchemaCoordinate) {
-                    const maybeTtl = ttlPerSchemaCoordinate[entity.typename];
+                if (entity.typename in config.perSchemaCoordinate.ttl) {
+                    const maybeTtl = config.perSchemaCoordinate.ttl[entity.typename];
                     currentTtl = calculateTtl(maybeTtl, currentTtl);
                 }
                 if (entity.id != null) {
@@ -212,10 +248,10 @@ export function useResponseCache({ cache = createInMemoryCache(), ttl: globalTtl
                 for (const fieldName in data) {
                     const fieldData = data[fieldName];
                     if (fieldData == null || (Array.isArray(fieldData) && fieldData.length === 0)) {
-                        const inferredTypes = typePerSchemaCoordinateMap.get(`${entity.typename}.${fieldName}`);
+                        const inferredTypes = config.perSchemaCoordinate.type.get(`${entity.typename}.${fieldName}`);
                         inferredTypes?.forEach(inferredType => {
-                            if (inferredType in ttlPerSchemaCoordinate) {
-                                const maybeTtl = ttlPerSchemaCoordinate[inferredType];
+                            if (inferredType in config.perSchemaCoordinate.ttl) {
+                                const maybeTtl = config.perSchemaCoordinate.ttl[inferredType];
                                 currentTtl = calculateTtl(maybeTtl, currentTtl);
                             }
                             identifier.set(inferredType, { typename: inferredType });
@@ -224,9 +260,11 @@ export function useResponseCache({ cache = createInMemoryCache(), ttl: globalTtl
                 }
             }
             function invalidateCache(result, setResult) {
+                let changed = false;
                 if (result.data) {
-                    collectEntities(result.data, onEntity);
-                    setStringifyWithoutMetadata(result);
+                    result = { ...result };
+                    result.data = removeMetadataFieldsFromResult(result.data, onEntity);
+                    changed = true;
                 }
                 const cacheInstance = cacheFactory(onExecuteParams.args.contextValue);
                 if (cacheInstance == null) {
@@ -242,13 +280,16 @@ export function useResponseCache({ cache = createInMemoryCache(), ttl: globalTtl
                         }));
                     }
                 }
+                if (changed) {
+                    setResult(result);
+                }
             }
             if (invalidateViaMutation !== false) {
                 const operationAST = getOperationAST(onExecuteParams.args.document, onExecuteParams.args.operationName);
                 if (operationAST?.operation === 'mutation') {
                     return setExecutor({
                         execute(args) {
-                            const [document] = getDocumentWithMetadataAndTTL(args.document, documentMetadataOptions.mutations, args.schema, idFieldByTypeName);
+                            const [document] = getDocumentWithMetadataAndTTL(args.document, config.documentMetadataOptions.mutations, args.schema, config.idFieldByTypeName);
                             return onExecuteParams.executeFn({ ...args, document });
                         },
                         onExecuteDone({ result, setResult }) {
@@ -261,30 +302,36 @@ export function useResponseCache({ cache = createInMemoryCache(), ttl: globalTtl
                 }
             }
             return handleMaybePromise(() => buildResponseCacheKey({
-                documentString: getDocumentString(onExecuteParams.args),
+                sessionId,
+                documentString,
                 variableValues: onExecuteParams.args.variableValues,
                 operationName: onExecuteParams.args.operationName,
-                sessionId,
                 context: onExecuteParams.args.contextValue,
             }), cacheKey => {
                 const cacheInstance = cacheFactory(onExecuteParams.args.contextValue);
                 if (cacheInstance == null) {
                     // eslint-disable-next-line no-console
                     console.warn('[useResponseCache] Cache instance is not available for the context. Skipping cache lookup.');
+                    return;
                 }
-                return handleMaybePromise(() => cacheInstance.get(cacheKey), cachedResponse => {
-                    if (cachedResponse != null) {
-                        return setExecutor({
-                            execute: () => includeExtensionMetadata
-                                ? resultWithMetadata(cachedResponse, { hit: true })
-                                : cachedResponse,
-                        });
+                function maybeCacheResult(result, setResult) {
+                    if (result.data) {
+                        result.data = removeMetadataFieldsFromResult(result.data, onEntity);
                     }
-                    function maybeCacheResult(result, setResult) {
-                        if (result.data) {
-                            collectEntities(result.data, onEntity);
-                            setStringifyWithoutMetadata(result);
+                    return handleMaybePromise(() => {
+                        if (!skip && ignoreSessionIdForPublicScope && !isPrivate && sessionId) {
+                            config.publicDocuments.set(documentString, true);
+                            return buildResponseCacheKey({
+                                // Build a public key for this document
+                                sessionId: undefined,
+                                documentString,
+                                variableValues: onExecuteParams.args.variableValues,
+                                operationName: onExecuteParams.args.operationName,
+                                context: onExecuteParams.args.contextValue,
+                            });
                         }
+                        return cacheKey;
+                    }, cacheKey => {
                         // we only use the global ttl if no currentTtl has been determined.
                         let finalTtl = currentTtl ?? globalTtl;
                         if (onTtl) {
@@ -303,10 +350,19 @@ export function useResponseCache({ cache = createInMemoryCache(), ttl: globalTtl
                         if (includeExtensionMetadata) {
                             setResult(resultWithMetadata(result, { hit: false, didCache: true, ttl: finalTtl }));
                         }
+                    });
+                }
+                return handleMaybePromise(() => cacheInstance.get(cacheKey), cachedResponse => {
+                    if (cachedResponse != null) {
+                        return setExecutor({
+                            execute: () => includeExtensionMetadata
+                                ? resultWithMetadata(cachedResponse, { hit: true })
+                                : cachedResponse,
+                        });
                     }
                     return setExecutor({
                         execute(args) {
-                            const [document, ttl] = getDocumentWithMetadataAndTTL(args.document, documentMetadataOptions.queries, schema, idFieldByTypeName);
+                            const [document, ttl] = getDocumentWithMetadataAndTTL(args.document, config.documentMetadataOptions.queries, schema, config.idFieldByTypeName);
                             currentTtl = ttl;
                             return onExecuteParams.executeFn({ ...args, document });
                         },
@@ -331,7 +387,7 @@ function handleAsyncIterableResult(handler) {
         onNext(payload) {
             // This is the first result with the initial data payload sent to the client. We use it as the base result
             if (payload.result.data) {
-                result.data = structuredClone(payload.result.data);
+                result.data = payload.result.data;
             }
             if (payload.result.errors) {
                 result.errors = payload.result.errors;
@@ -343,10 +399,7 @@ function handleAsyncIterableResult(handler) {
                 const { incremental, hasNext } = payload.result;
                 if (incremental) {
                     for (const patch of incremental) {
-                        mergeIncrementalResult({
-                            executionResult: result,
-                            incrementalResult: structuredClone(patch),
-                        });
+                        mergeIncrementalResult({ executionResult: result, incrementalResult: patch });
                     }
                 }
                 if (!hasNext) {
@@ -354,22 +407,30 @@ function handleAsyncIterableResult(handler) {
                     handler(result, payload.setResult);
                 }
             }
-            if (payload.result.data) {
-                collectEntities(payload.result.data);
+            const newResult = { ...payload.result };
+            // Handle initial/single result
+            if (newResult.data) {
+                newResult.data = removeMetadataFieldsFromResult(newResult.data);
             }
             // Handle Incremental results
-            if ('hasNext' in payload.result && payload.result.incremental) {
-                payload.result.incremental = payload.result.incremental.map(value => {
+            if ('hasNext' in newResult && newResult.incremental) {
+                newResult.incremental = newResult.incremental.map(value => {
                     if ('items' in value && value.items) {
-                        collectEntities(value.items);
+                        return {
+                            ...value,
+                            items: removeMetadataFieldsFromResult(value.items),
+                        };
                     }
                     if ('data' in value && value.data) {
-                        collectEntities(value.data);
+                        return {
+                            ...value,
+                            data: removeMetadataFieldsFromResult(value.data),
+                        };
                     }
                     return value;
                 });
             }
-            setStringifyWithoutMetadata(payload.result);
+            payload.setResult(newResult);
         },
     };
 }
@@ -414,45 +475,38 @@ export const cacheControlDirective = /* GraphQL */ `
 
   directive @cacheControl(maxAge: Int, scope: CacheControlScope) on FIELD_DEFINITION | OBJECT
 `;
-function collectEntities(data, onEntity) {
+function removeMetadataFieldsFromResult(data, onEntity) {
     if (Array.isArray(data)) {
-        for (const record of data) {
-            collectEntities(record, onEntity);
-        }
-        return;
+        return data.map(record => removeMetadataFieldsFromResult(record, onEntity));
     }
     if (typeof data !== 'object' || data == null) {
-        return;
+        return data;
     }
     const dataPrototype = Object.getPrototypeOf(data);
-    // TODO: For some reason, when running in Jest, `structuredClone` result have a weird prototype
-    //       that doesn't equal Object.prototype as it should.
-    //       As a workaround, we can just check that there is no parent prototype, which should be
-    //       the case only when it's the Object prototype
-    //       Rollback once migrated to Bun or vitest
-    //
-    // if (dataPrototype != null && dataPrototype !== Object.prototype) {
-    if (dataPrototype != null && Object.getPrototypeOf(dataPrototype) !== null) {
-        // It is not a plain object, like a Date, don't inspect further
-        return;
+    if (dataPrototype != null && dataPrototype !== Object.prototype) {
+        return data;
     }
+    // clone the data to avoid mutation
+    data = { ...data };
     const typename = data.__responseCacheTypeName ?? data.__typename;
     if (typeof typename === 'string') {
         const entity = { typename };
+        delete data.__responseCacheTypeName;
         if (data.__responseCacheId &&
             (typeof data.__responseCacheId === 'string' || typeof data.__responseCacheId === 'number')) {
             entity.id = data.__responseCacheId;
+            delete data.__responseCacheId;
         }
         onEntity?.(entity, data);
     }
     for (const key in data) {
-        collectEntities(data[key], onEntity);
+        const value = data[key];
+        if (Array.isArray(value)) {
+            data[key] = removeMetadataFieldsFromResult(value, onEntity);
+        }
+        if (value !== null && typeof value === 'object') {
+            data[key] = removeMetadataFieldsFromResult(value, onEntity);
+        }
     }
+    return data;
 }
-function setStringifyWithoutMetadata(result) {
-    result.stringify = stringifyWithoutMetadata;
-    return result;
-}
-const stringifyWithoutMetadata = result => {
-    return JSON.stringify(result, (key, value) => key === '__responseCacheId' || key === '__responseCacheTypeName' ? undefined : value);
-};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@envelop/response-cache",
-  "version": "8.2.0-alpha-20251013081815-d6f74fceb1a32fd336b2664f90f87872e1bbf2fe",
+  "version": "8.2.0-alpha-20251217212728-de569f3d7fe45e330eca177b69ee1c89fd5dc498",
   "sideEffects": false,
   "peerDependencies": {
     "graphql": "^14.0.0 || ^15.0.0 || ^16.0.0",

package/typings/plugin.d.cts

@@ -22,6 +22,8 @@ export type ShouldCacheResultFunction = (params: {
     cacheKey: string;
     result: ExecutionResult;
 }) => boolean;
+export type TTLPerSchemaCoordinate = Record<string, number | undefined>;
+export type ScopePerSchemaCoordinate = Record<string, 'PRIVATE' | 'PUBLIC' | undefined>;
 export type UseResponseCacheParameter<PluginContext extends Record<string, any> = {}> = {
     cache?: Cache | ((ctx: Record<string, any>) => Cache);
     /**
@@ -40,8 +42,25 @@ export type UseResponseCacheParameter<PluginContext extends Record<string, any>
      * In the unusual case where you actually want to cache introspection query operations,
      * you need to provide the value `{ 'Query.__schema': undefined }`.
      */
-    ttlPerSchemaCoordinate?: Record<string, number | undefined>;
-    scopePerSchemaCoordinate?: Record<string, 'PRIVATE' | 'PUBLIC' | undefined>;
+    ttlPerSchemaCoordinate?: TTLPerSchemaCoordinate;
+    /**
+     * Define the scope (PUBLIC or PRIVATE) by schema coordinate.
+     * The default scope for all types and fields is PUBLIC
+     *
+     * If an operation contains a PRIVATE type or field, the result will be cached only if a session
+     * id is found for this request.
+     *
+     * Note: To share cache of responses with a PUBLIC scope between all users, enable `ignoreSessionIdForPublicScope`
+     */
+    scopePerSchemaCoordinate?: ScopePerSchemaCoordinate;
+    /**
+     * If enabled, a response with a PUBLIC scope will be cached with an operation key ignoring the
+     * session ID. This allows to improve cache hit further, but scope should be carefully defined
+     * to avoid any private data.
+     *
+     * @default false.
+     */
+    ignoreSessionIdForPublicScope?: boolean;
     /**
      * Allows to cache responses based on the resolved session id.
      * Return a unique value for each session.
@@ -151,6 +170,10 @@ export type ResponseCacheExtensions = {
 export type ResponseCacheExecutionResult = ExecutionResult<ObjMap<unknown>, {
     responseCache?: ResponseCacheExtensions;
 }>;
-export declare function useResponseCache<PluginContext extends Record<string, any> = {}>({ cache, ttl: globalTtl, session, enabled, ignoredTypes, ttlPerType, ttlPerSchemaCoordinate, scopePerSchemaCoordinate, idFields, invalidateViaMutation, buildResponseCacheKey, getDocumentString, shouldCacheResult, onTtl, includeExtensionMetadata, }: UseResponseCacheParameter<PluginContext>): Plugin<PluginContext>;
+export type CacheControlDirective = {
+    maxAge?: number;
+    scope?: 'PUBLIC' | 'PRIVATE';
+};
+export declare function useResponseCache<PluginContext extends Record<string, any> = {}>({ cache, ttl: globalTtl, session, enabled, ignoredTypes, ttlPerType, idFields, invalidateViaMutation, ignoreSessionIdForPublicScope, buildResponseCacheKey, getDocumentString, shouldCacheResult, onTtl, includeExtensionMetadata, ...options }: UseResponseCacheParameter<PluginContext>): Plugin<PluginContext>;
 export declare function resultWithMetadata(result: ExecutionResult, metadata: ResponseCacheExtensions): ResponseCacheExecutionResult;
 export declare const cacheControlDirective = "\n  enum CacheControlScope {\n    PUBLIC\n    PRIVATE\n  }\n\n  directive @cacheControl(maxAge: Int, scope: CacheControlScope) on FIELD_DEFINITION | OBJECT\n";

package/typings/plugin.d.ts

@@ -22,6 +22,8 @@ export type ShouldCacheResultFunction = (params: {
     cacheKey: string;
     result: ExecutionResult;
 }) => boolean;
+export type TTLPerSchemaCoordinate = Record<string, number | undefined>;
+export type ScopePerSchemaCoordinate = Record<string, 'PRIVATE' | 'PUBLIC' | undefined>;
 export type UseResponseCacheParameter<PluginContext extends Record<string, any> = {}> = {
     cache?: Cache | ((ctx: Record<string, any>) => Cache);
     /**
@@ -40,8 +42,25 @@ export type UseResponseCacheParameter<PluginContext extends Record<string, any>
      * In the unusual case where you actually want to cache introspection query operations,
      * you need to provide the value `{ 'Query.__schema': undefined }`.
      */
-    ttlPerSchemaCoordinate?: Record<string, number | undefined>;
-    scopePerSchemaCoordinate?: Record<string, 'PRIVATE' | 'PUBLIC' | undefined>;
+    ttlPerSchemaCoordinate?: TTLPerSchemaCoordinate;
+    /**
+     * Define the scope (PUBLIC or PRIVATE) by schema coordinate.
+     * The default scope for all types and fields is PUBLIC
+     *
+     * If an operation contains a PRIVATE type or field, the result will be cached only if a session
+     * id is found for this request.
+     *
+     * Note: To share cache of responses with a PUBLIC scope between all users, enable `ignoreSessionIdForPublicScope`
+     */
+    scopePerSchemaCoordinate?: ScopePerSchemaCoordinate;
+    /**
+     * If enabled, a response with a PUBLIC scope will be cached with an operation key ignoring the
+     * session ID. This allows to improve cache hit further, but scope should be carefully defined
+     * to avoid any private data.
+     *
+     * @default false.
+     */
+    ignoreSessionIdForPublicScope?: boolean;
     /**
      * Allows to cache responses based on the resolved session id.
      * Return a unique value for each session.
@@ -151,6 +170,10 @@ export type ResponseCacheExtensions = {
 export type ResponseCacheExecutionResult = ExecutionResult<ObjMap<unknown>, {
     responseCache?: ResponseCacheExtensions;
 }>;
-export declare function useResponseCache<PluginContext extends Record<string, any> = {}>({ cache, ttl: globalTtl, session, enabled, ignoredTypes, ttlPerType, ttlPerSchemaCoordinate, scopePerSchemaCoordinate, idFields, invalidateViaMutation, buildResponseCacheKey, getDocumentString, shouldCacheResult, onTtl, includeExtensionMetadata, }: UseResponseCacheParameter<PluginContext>): Plugin<PluginContext>;
+export type CacheControlDirective = {
+    maxAge?: number;
+    scope?: 'PUBLIC' | 'PRIVATE';
+};
+export declare function useResponseCache<PluginContext extends Record<string, any> = {}>({ cache, ttl: globalTtl, session, enabled, ignoredTypes, ttlPerType, idFields, invalidateViaMutation, ignoreSessionIdForPublicScope, buildResponseCacheKey, getDocumentString, shouldCacheResult, onTtl, includeExtensionMetadata, ...options }: UseResponseCacheParameter<PluginContext>): Plugin<PluginContext>;
 export declare function resultWithMetadata(result: ExecutionResult, metadata: ResponseCacheExtensions): ResponseCacheExecutionResult;
 export declare const cacheControlDirective = "\n  enum CacheControlScope {\n    PUBLIC\n    PRIVATE\n  }\n\n  directive @cacheControl(maxAge: Int, scope: CacheControlScope) on FIELD_DEFINITION | OBJECT\n";