@graphql-hive/core 0.19.0-rc-20251222110102-ca00d2ee12be6920f3247ac812aa83bf9f8e9581 → 0.19.0-rc-20260105125447-29b7291593ce66ef5f929776a3df44fc05ac0886

package/cjs/client/persisted-documents.js

@@ -6,6 +6,7 @@ const tiny_lru_1 = tslib_1.__importDefault(require("tiny-lru"));
 const circuit_js_1 = tslib_1.__importDefault(require("../circuit-breaker/circuit.js"));
 const circuit_breaker_js_1 = require("./circuit-breaker.js");
 const http_client_js_1 = require("./http-client.js");
+const types_js_1 = require("./types.js");
 function isRequestOk(response) {
     return response.status === 200 || response.status === 404;
 }
@@ -66,8 +67,14 @@ function createValidationError(documentId, error) {
     return new PersistedDocumentValidationError(documentId, error);
 }
 function createPersistedDocuments(config) {
-    var _a;
+    var _a, _b, _c, _d, _e, _f;
+    // L1
     const persistedDocumentsCache = (0, tiny_lru_1.default)((_a = config.cache) !== null && _a !== void 0 ? _a : 10000);
+    // L2
+    const layer2Cache = (_b = config.layer2Cache) === null || _b === void 0 ? void 0 : _b.cache;
+    const layer2TtlSeconds = (_c = config.layer2Cache) === null || _c === void 0 ? void 0 : _c.ttlSeconds;
+    const layer2NotFoundTtlSeconds = (_e = (_d = config.layer2Cache) === null || _d === void 0 ? void 0 : _d.notFoundTtlSeconds) !== null && _e !== void 0 ? _e : 60;
+    const layer2WaitUntil = (_f = config.layer2Cache) === null || _f === void 0 ? void 0 : _f.waitUntil;
     let allowArbitraryDocuments;
     if (typeof config.allowArbitraryDocuments === 'boolean') {
         let value = config.allowArbitraryDocuments;
@@ -109,28 +116,101 @@ function createPersistedDocuments(config) {
         }, Object.assign(Object.assign({}, ((_a = config.circuitBreaker) !== null && _a !== void 0 ? _a : circuit_breaker_js_1.defaultCircuitBreakerConfiguration)), { timeout: false, autoRenewAbortController: true }));
         return circuitBreaker;
     });
-    /** Batch load a persisted documents */
-    function loadPersistedDocument(documentId) {
+    // Attempt to get document from L2 cache, returns: { hit: true, value: string | null } or { hit: false }
+    async function getFromLayer2Cache(documentId) {
+        if (!layer2Cache) {
+            return { hit: false };
+        }
+        let cached;
+        try {
+            cached = await layer2Cache.get(documentId);
+        }
+        catch (error) {
+            // L2 cache failure should not break the request
+            config.logger.warn('L2 cache get failed for document %s: %O', documentId, error);
+            return { hit: false };
+        }
+        if (cached === null) {
+            // Cache miss
+            return { hit: false };
+        }
+        if (cached === types_js_1.PERSISTED_DOCUMENT_NOT_FOUND) {
+            // Negative cache hit, document was previously not found
+            config.logger.debug('L2 cache negative hit for document %s', documentId);
+            return { hit: true, value: null };
+        }
+        // Cache hit with document
+        config.logger.debug('L2 cache hit for document %s', documentId);
+        return { hit: true, value: cached };
+    }
+    // store document in L2 cache (fire-and-forget, non-blocking)
+    function setInLayer2Cache(documentId, value, waitUntil) {
+        if (!(layer2Cache === null || layer2Cache === void 0 ? void 0 : layer2Cache.set)) {
+            return;
+        }
+        // Skip negative caching if TTL is 0
+        if (value === null && layer2NotFoundTtlSeconds === 0) {
+            return;
+        }
+        const cacheValue = value === null ? types_js_1.PERSISTED_DOCUMENT_NOT_FOUND : value;
+        const ttl = value === null ? layer2NotFoundTtlSeconds : layer2TtlSeconds;
+        // Fire-and-forget. don't await, don't block
+        const setPromise = layer2Cache.set(documentId, cacheValue, ttl ? { ttl } : undefined);
+        if (setPromise) {
+            const handledPromise = Promise.resolve(setPromise).then(() => {
+                config.logger.debug('L2 cache set succeeded for document %s', documentId);
+            }, error => {
+                config.logger.warn('L2 cache set failed for document %s: %O', documentId, error);
+            });
+            // Register with waitUntil for serverless environments
+            // Config waitUntil takes precedence over context waitUntil
+            const effectiveWaitUntil = layer2WaitUntil !== null && layer2WaitUntil !== void 0 ? layer2WaitUntil : waitUntil;
+            if (effectiveWaitUntil) {
+                try {
+                    effectiveWaitUntil(handledPromise);
+                }
+                catch (error) {
+                    config.logger.warn('Failed to register L2 cache write with waitUntil: %O', error);
+                }
+            }
+        }
+    }
+    /** Load a persisted document with validation and L1 -> L2 -> CDN fallback */
+    function loadPersistedDocument(documentId, context) {
+        // Validate document ID format first
         const validationError = validateDocumentId(documentId);
         if (validationError) {
             // Return a promise that will be rejected with a proper error
             return Promise.reject(createValidationError(documentId, validationError.error));
         }
-        const document = persistedDocumentsCache.get(documentId);
-        if (document) {
-            return document;
+        // L1 cache check (in-memory)
+        // Note: We need to distinguish between "not in cache" (undefined) and "cached as not found" (null)
+        const cachedDocument = persistedDocumentsCache.get(documentId);
+        if (cachedDocument !== undefined) {
+            // Cache hit, return the value
+            return cachedDocument;
         }
+        // Check in-flight requests
         let promise = fetchCache.get(documentId);
         if (promise) {
             return promise;
         }
         promise = Promise.resolve()
             .then(async () => {
+            // L2 cache check
+            const l2Result = await getFromLayer2Cache(documentId);
+            if (l2Result.hit) {
+                // L2 cache hit, store in L1 for faster subsequent access
+                persistedDocumentsCache.set(documentId, l2Result.value);
+                return { value: l2Result.value, fromL2: true };
+            }
+            // CDN fetch
             const cdnDocumentId = documentId.replaceAll('~', '/');
             let lastError = null;
             for (const breaker of circuitBreakers) {
                 try {
-                    return await breaker.fire(cdnDocumentId);
+                    const result = await breaker.fire(cdnDocumentId);
+                    return { value: result, fromL2: false };
                 }
                 catch (error) {
                     config.logger.debug({ error });
@@ -142,9 +222,14 @@ function createPersistedDocuments(config) {
             }
             throw new Error('Failed to look up persisted operation.');
         })
-            .then(result => {
-            persistedDocumentsCache.set(documentId, result);
-            return result;
+            .then(({ value, fromL2 }) => {
+            // Store in L1 cache (in-memory), only if not already stored from L2 hit
+            if (!fromL2) {
+                persistedDocumentsCache.set(documentId, value);
+                // Store in L2 cache (async, non-blocking), only for CDN fetched data
+                setInLayer2Cache(documentId, value, context === null || context === void 0 ? void 0 : context.waitUntil);
+            }
+            return value;
         })
             .finally(() => {
             fetchCache.delete(documentId);

package/cjs/client/types.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PERSISTED_DOCUMENT_NOT_FOUND = void 0;
+/**
+ * A sentinel value used to indicate a document was looked up but not found.
+ * This enables negative caching - caching the absence of a document to avoid
+ * repeated CDN lookups for documents that don't exist.
+ */
+exports.PERSISTED_DOCUMENT_NOT_FOUND = '__HIVE_PERSISTED_DOCUMENT_NOT_FOUND__';

package/cjs/version.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.version = void 0;
-exports.version = '0.19.0-rc-20251222110102-ca00d2ee12be6920f3247ac812aa83bf9f8e9581';
+exports.version = '0.19.0-rc-20260105125447-29b7291593ce66ef5f929776a3df44fc05ac0886';

package/esm/client/persisted-documents.js

@@ -2,6 +2,7 @@ import LRU from 'tiny-lru';
 import CircuitBreaker from '../circuit-breaker/circuit.js';
 import { defaultCircuitBreakerConfiguration } from './circuit-breaker.js';
 import { http } from './http-client.js';
+import { PERSISTED_DOCUMENT_NOT_FOUND, } from './types.js';
 function isRequestOk(response) {
     return response.status === 200 || response.status === 404;
 }
@@ -62,8 +63,14 @@ function createValidationError(documentId, error) {
     return new PersistedDocumentValidationError(documentId, error);
 }
 export function createPersistedDocuments(config) {
-    var _a;
+    var _a, _b, _c, _d, _e, _f;
+    // L1
     const persistedDocumentsCache = LRU((_a = config.cache) !== null && _a !== void 0 ? _a : 10000);
+    // L2
+    const layer2Cache = (_b = config.layer2Cache) === null || _b === void 0 ? void 0 : _b.cache;
+    const layer2TtlSeconds = (_c = config.layer2Cache) === null || _c === void 0 ? void 0 : _c.ttlSeconds;
+    const layer2NotFoundTtlSeconds = (_e = (_d = config.layer2Cache) === null || _d === void 0 ? void 0 : _d.notFoundTtlSeconds) !== null && _e !== void 0 ? _e : 60;
+    const layer2WaitUntil = (_f = config.layer2Cache) === null || _f === void 0 ? void 0 : _f.waitUntil;
     let allowArbitraryDocuments;
     if (typeof config.allowArbitraryDocuments === 'boolean') {
         let value = config.allowArbitraryDocuments;
@@ -105,28 +112,101 @@ export function createPersistedDocuments(config) {
         }, Object.assign(Object.assign({}, ((_a = config.circuitBreaker) !== null && _a !== void 0 ? _a : defaultCircuitBreakerConfiguration)), { timeout: false, autoRenewAbortController: true }));
         return circuitBreaker;
     });
-    /** Batch load a persisted documents */
-    function loadPersistedDocument(documentId) {
+    // Attempt to get document from L2 cache, returns: { hit: true, value: string | null } or { hit: false }
+    async function getFromLayer2Cache(documentId) {
+        if (!layer2Cache) {
+            return { hit: false };
+        }
+        let cached;
+        try {
+            cached = await layer2Cache.get(documentId);
+        }
+        catch (error) {
+            // L2 cache failure should not break the request
+            config.logger.warn('L2 cache get failed for document %s: %O', documentId, error);
+            return { hit: false };
+        }
+        if (cached === null) {
+            // Cache miss
+            return { hit: false };
+        }
+        if (cached === PERSISTED_DOCUMENT_NOT_FOUND) {
+            // Negative cache hit, document was previously not found
+            config.logger.debug('L2 cache negative hit for document %s', documentId);
+            return { hit: true, value: null };
+        }
+        // Cache hit with document
+        config.logger.debug('L2 cache hit for document %s', documentId);
+        return { hit: true, value: cached };
+    }
+    // store document in L2 cache (fire-and-forget, non-blocking)
+    function setInLayer2Cache(documentId, value, waitUntil) {
+        if (!(layer2Cache === null || layer2Cache === void 0 ? void 0 : layer2Cache.set)) {
+            return;
+        }
+        // Skip negative caching if TTL is 0
+        if (value === null && layer2NotFoundTtlSeconds === 0) {
+            return;
+        }
+        const cacheValue = value === null ? PERSISTED_DOCUMENT_NOT_FOUND : value;
+        const ttl = value === null ? layer2NotFoundTtlSeconds : layer2TtlSeconds;
+        // Fire-and-forget. don't await, don't block
+        const setPromise = layer2Cache.set(documentId, cacheValue, ttl ? { ttl } : undefined);
+        if (setPromise) {
+            const handledPromise = Promise.resolve(setPromise).then(() => {
+                config.logger.debug('L2 cache set succeeded for document %s', documentId);
+            }, error => {
+                config.logger.warn('L2 cache set failed for document %s: %O', documentId, error);
+            });
+            // Register with waitUntil for serverless environments
+            // Config waitUntil takes precedence over context waitUntil
+            const effectiveWaitUntil = layer2WaitUntil !== null && layer2WaitUntil !== void 0 ? layer2WaitUntil : waitUntil;
+            if (effectiveWaitUntil) {
+                try {
+                    effectiveWaitUntil(handledPromise);
+                }
+                catch (error) {
+                    config.logger.warn('Failed to register L2 cache write with waitUntil: %O', error);
+                }
+            }
+        }
+    }
+    /** Load a persisted document with validation and L1 -> L2 -> CDN fallback */
+    function loadPersistedDocument(documentId, context) {
+        // Validate document ID format first
         const validationError = validateDocumentId(documentId);
         if (validationError) {
             // Return a promise that will be rejected with a proper error
             return Promise.reject(createValidationError(documentId, validationError.error));
         }
-        const document = persistedDocumentsCache.get(documentId);
-        if (document) {
-            return document;
+        // L1 cache check (in-memory)
+        // Note: We need to distinguish between "not in cache" (undefined) and "cached as not found" (null)
+        const cachedDocument = persistedDocumentsCache.get(documentId);
+        if (cachedDocument !== undefined) {
+            // Cache hit, return the value
+            return cachedDocument;
         }
+        // Check in-flight requests
         let promise = fetchCache.get(documentId);
         if (promise) {
             return promise;
         }
         promise = Promise.resolve()
             .then(async () => {
+            // L2 cache check
+            const l2Result = await getFromLayer2Cache(documentId);
+            if (l2Result.hit) {
+                // L2 cache hit, store in L1 for faster subsequent access
+                persistedDocumentsCache.set(documentId, l2Result.value);
+                return { value: l2Result.value, fromL2: true };
+            }
+            // CDN fetch
             const cdnDocumentId = documentId.replaceAll('~', '/');
             let lastError = null;
             for (const breaker of circuitBreakers) {
                 try {
-                    return await breaker.fire(cdnDocumentId);
+                    const result = await breaker.fire(cdnDocumentId);
+                    return { value: result, fromL2: false };
                 }
                 catch (error) {
                     config.logger.debug({ error });
@@ -138,9 +218,14 @@ export function createPersistedDocuments(config) {
             }
             throw new Error('Failed to look up persisted operation.');
         })
-            .then(result => {
-            persistedDocumentsCache.set(documentId, result);
-            return result;
+            .then(({ value, fromL2 }) => {
+            // Store in L1 cache (in-memory), only if not already stored from L2 hit
+            if (!fromL2) {
+                persistedDocumentsCache.set(documentId, value);
+                // Store in L2 cache (async, non-blocking), only for CDN fetched data
+                setInLayer2Cache(documentId, value, context === null || context === void 0 ? void 0 : context.waitUntil);
+            }
+            return value;
         })
             .finally(() => {
             fetchCache.delete(documentId);

package/esm/client/types.js

@@ -0,0 +1,6 @@
+/**
+ * A sentinel value used to indicate a document was looked up but not found.
+ * This enables negative caching - caching the absence of a document to avoid
+ * repeated CDN lookups for documents that don't exist.
+ */
+export const PERSISTED_DOCUMENT_NOT_FOUND = '__HIVE_PERSISTED_DOCUMENT_NOT_FOUND__';

package/esm/version.js

@@ -1 +1 @@
-export const version = '0.19.0-rc-20251222110102-ca00d2ee12be6920f3247ac812aa83bf9f8e9581';
+export const version = '0.19.0-rc-20260105125447-29b7291593ce66ef5f929776a3df44fc05ac0886';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphql-hive/core",
-  "version": "0.19.0-rc-20251222110102-ca00d2ee12be6920f3247ac812aa83bf9f8e9581",
+  "version": "0.19.0-rc-20260105125447-29b7291593ce66ef5f929776a3df44fc05ac0886",
   "sideEffects": false,
   "peerDependencies": {
     "graphql": "^0.13.0 || ^14.0.0 || ^15.0.0 || ^16.0.0"

package/typings/client/persisted-documents.d.cts

@@ -1,12 +1,14 @@
 import type { PromiseOrValue } from 'graphql/jsutils/PromiseOrValue.cjs';
 import { Logger } from '@graphql-hive/logger';
 import { HttpCallConfig } from './http-client.cjs';
-import type { PersistedDocumentsConfiguration } from './types';
+import { type PersistedDocumentsConfiguration } from './types.cjs';
 type HeadersObject = {
     get(name: string): string | null;
 };
 type PersistedDocuments = {
-    resolve(documentId: string): PromiseOrValue<string | null>;
+    resolve(documentId: string, context?: {
+        waitUntil?: (promise: Promise<void> | void) => void;
+    }): PromiseOrValue<string | null>;
     allowArbitraryDocuments(context: {
         headers?: HeadersObject;
     }): PromiseOrValue<boolean>;

package/typings/client/persisted-documents.d.ts

@@ -1,12 +1,14 @@
 import type { PromiseOrValue } from 'graphql/jsutils/PromiseOrValue.js';
 import { Logger } from '@graphql-hive/logger';
 import { HttpCallConfig } from './http-client.js';
-import type { PersistedDocumentsConfiguration } from './types';
+import { type PersistedDocumentsConfiguration } from './types.js';
 type HeadersObject = {
     get(name: string): string | null;
 };
 type PersistedDocuments = {
-    resolve(documentId: string): PromiseOrValue<string | null>;
+    resolve(documentId: string, context?: {
+        waitUntil?: (promise: Promise<void> | void) => void;
+    }): PromiseOrValue<string | null>;
     allowArbitraryDocuments(context: {
         headers?: HeadersObject;
     }): PromiseOrValue<boolean>;

package/typings/client/types.d.cts

@@ -1,6 +1,7 @@
 import type { ExecutionArgs } from 'graphql';
 import type { PromiseOrValue } from 'graphql/jsutils/PromiseOrValue.cjs';
 import { LogLevel as HiveLoggerLevel, Logger } from '@graphql-hive/logger';
+import { MaybePromise } from '@graphql-tools/utils';
 import type { AgentOptions } from './agent.cjs';
 import { CircuitBreakerConfiguration } from './circuit-breaker.cjs';
 import type { autoDisposeSymbol, hiveClientSymbol } from './client.cjs';
@@ -39,7 +40,9 @@ export interface HiveClient {
     createInstrumentedSubscribe(executeImpl: any): any;
     dispose(): Promise<void>;
     experimental__persistedDocuments: null | {
-        resolve(documentId: string): PromiseOrValue<string | null>;
+        resolve(documentId: string, context?: {
+            waitUntil?: (promise: Promise<void> | void) => void;
+        }): PromiseOrValue<string | null>;
         allowArbitraryDocuments(context: {
             headers?: HeadersObject;
         }): PromiseOrValue<boolean>;
@@ -272,6 +275,81 @@ export interface ServicesFetcherOptions {
     endpoint: string;
     key: string;
 }
+/**
+ * A sentinel value used to indicate a document was looked up but not found.
+ * This enables negative caching - caching the absence of a document to avoid
+ * repeated CDN lookups for documents that don't exist.
+ */
+export declare const PERSISTED_DOCUMENT_NOT_FOUND: "__HIVE_PERSISTED_DOCUMENT_NOT_FOUND__";
+export type PersistedDocumentNotFound = typeof PERSISTED_DOCUMENT_NOT_FOUND;
+/**
+ * Layer 2 cache interface for persisted documents.
+ * Implementers can use Redis, Memcached, or any other distributed cache.
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from 'redis';
+ * import { createHive} from '@graphql-hive/core';
+ *
+ * const redis = createClient({ url: 'redis://localhost:6379' });
+ * await redis.connect();
+ *
+ * const cache: PersistedDocumentsCache = {
+ *   async get(key) {
+ *     return redis.get(`hive:pd:${key}`);
+ *   },
+ *   async set(key, value, options) {
+ *     if (options?.ttl) {
+ *       await redis.set(`hive:pd:${key}`, value, { EX: options.ttl });
+ *     } else {
+ *       await redis.set(`hive:pd:${key}`, value);
+ *     }
+ *   },
+ * };
+ * ```
+ */
+export type PersistedDocumentsCache = {
+    /**
+     * Get a document from the cache.
+     * @param key - The document ID (e.g., "myapp~v1.0.0~abc123")
+     * @returns The document body, PERSISTED_DOCUMENT_NOT_FOUND for negative cache hit, or null for cache miss
+     */
+    get(key: string): Promise<string | PersistedDocumentNotFound | null>;
+    /**
+     * Store a document in the cache.
+     * Optional - if not provided, the cache is read-only.
+     * @param key - The document ID
+     * @param value - The document body or PERSISTED_DOCUMENT_NOT_FOUND for negative caching
+     * @param options - Optional TTL configuration (ttl is in seconds)
+     */
+    set?(key: string, value: string | PersistedDocumentNotFound, options?: {
+        ttl?: number;
+    }): MaybePromise<unknown>;
+};
+/**
+ * Configuration for the layer 2 cache.
+ */
+export type Layer2CacheConfiguration = {
+    /**
+     * The cache implementation (e.g., Redis client wrapper)
+     */
+    cache: PersistedDocumentsCache;
+    /**
+     * TTL in seconds for successfully found documents.
+     * @default undefined (no expiration, or cache implementation default)
+     */
+    ttlSeconds?: number;
+    /**
+     * TTL in seconds for negative cache entries (document not found).
+     * Set to 0 to disable negative caching.
+     * @default 60 (1 minute)
+     */
+    notFoundTtlSeconds?: number;
+    /**
+     * Optional function to register background work in serverless environments if not available in context.
+     */
+    waitUntil?: (promise: Promise<void> | void) => void;
+};
 export type PersistedDocumentsConfiguration = {
     /**
      * CDN configuration for loading persisted documents.
@@ -316,6 +394,42 @@ export type PersistedDocumentsConfiguration = {
     fetch?: typeof fetch;
     /** Configuration for the circuit breaker. */
     circuitBreaker?: CircuitBreakerConfiguration;
+    /**
+     * Optional layer 2 cache configuration.
+     * When configured, the SDK will check this cache after the in-memory cache miss
+     * and before making a CDN request.
+     *
+     * This is useful for distributed caching (e.g., Redis) in multi-instance deployments,
+     * providing:
+     * - Shared cache between gateway instances
+     * - Additional resilience layer for CDN outages
+     * - Faster response times after gateway restarts
+     *
+     * @example
+     * ```typescript
+     * import { createClient } from 'redis';
+     * import { createHive} from '@graphql-hive/core';
+     *
+     * const redis = createClient({ url: 'redis://localhost:6379' });
+     * await redis.connect();
+     *
+     * const hive = createHive({
+     *   experimental__persistedDocuments: {
+     *     cdn: { endpoint: '...', accessToken: '...' },
+     *     layer2Cache: {
+     *       cache: {
+     *         get: (key) => redis.get(`hive:pd:${key}`),
+     *         set: (key, value, opts) =>
+     *           redis.set(`hive:pd:${key}`, value, opts?.ttl ? { EX: opts.ttl } : {}),
+     *       },
+     *       ttlSeconds: 3600,        // 1 hour for found documents
+     *       notFoundTtlSeconds: 60,  // 1 minute for notfound entries
+     *     },
+     *   },
+     * });
+     * ```
+     */
+    layer2Cache?: Layer2CacheConfiguration;
 };
 export type AllowArbitraryDocumentsFunction = (context: {
     /** an object for accessing the request headers. */

package/typings/client/types.d.ts

@@ -1,6 +1,7 @@
 import type { ExecutionArgs } from 'graphql';
 import type { PromiseOrValue } from 'graphql/jsutils/PromiseOrValue.js';
 import { LogLevel as HiveLoggerLevel, Logger } from '@graphql-hive/logger';
+import { MaybePromise } from '@graphql-tools/utils';
 import type { AgentOptions } from './agent.js';
 import { CircuitBreakerConfiguration } from './circuit-breaker.js';
 import type { autoDisposeSymbol, hiveClientSymbol } from './client.js';
@@ -39,7 +40,9 @@ export interface HiveClient {
     createInstrumentedSubscribe(executeImpl: any): any;
     dispose(): Promise<void>;
     experimental__persistedDocuments: null | {
-        resolve(documentId: string): PromiseOrValue<string | null>;
+        resolve(documentId: string, context?: {
+            waitUntil?: (promise: Promise<void> | void) => void;
+        }): PromiseOrValue<string | null>;
         allowArbitraryDocuments(context: {
             headers?: HeadersObject;
         }): PromiseOrValue<boolean>;
@@ -272,6 +275,81 @@ export interface ServicesFetcherOptions {
     endpoint: string;
     key: string;
 }
+/**
+ * A sentinel value used to indicate a document was looked up but not found.
+ * This enables negative caching - caching the absence of a document to avoid
+ * repeated CDN lookups for documents that don't exist.
+ */
+export declare const PERSISTED_DOCUMENT_NOT_FOUND: "__HIVE_PERSISTED_DOCUMENT_NOT_FOUND__";
+export type PersistedDocumentNotFound = typeof PERSISTED_DOCUMENT_NOT_FOUND;
+/**
+ * Layer 2 cache interface for persisted documents.
+ * Implementers can use Redis, Memcached, or any other distributed cache.
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from 'redis';
+ * import { createHive} from '@graphql-hive/core';
+ *
+ * const redis = createClient({ url: 'redis://localhost:6379' });
+ * await redis.connect();
+ *
+ * const cache: PersistedDocumentsCache = {
+ *   async get(key) {
+ *     return redis.get(`hive:pd:${key}`);
+ *   },
+ *   async set(key, value, options) {
+ *     if (options?.ttl) {
+ *       await redis.set(`hive:pd:${key}`, value, { EX: options.ttl });
+ *     } else {
+ *       await redis.set(`hive:pd:${key}`, value);
+ *     }
+ *   },
+ * };
+ * ```
+ */
+export type PersistedDocumentsCache = {
+    /**
+     * Get a document from the cache.
+     * @param key - The document ID (e.g., "myapp~v1.0.0~abc123")
+     * @returns The document body, PERSISTED_DOCUMENT_NOT_FOUND for negative cache hit, or null for cache miss
+     */
+    get(key: string): Promise<string | PersistedDocumentNotFound | null>;
+    /**
+     * Store a document in the cache.
+     * Optional - if not provided, the cache is read-only.
+     * @param key - The document ID
+     * @param value - The document body or PERSISTED_DOCUMENT_NOT_FOUND for negative caching
+     * @param options - Optional TTL configuration (ttl is in seconds)
+     */
+    set?(key: string, value: string | PersistedDocumentNotFound, options?: {
+        ttl?: number;
+    }): MaybePromise<unknown>;
+};
+/**
+ * Configuration for the layer 2 cache.
+ */
+export type Layer2CacheConfiguration = {
+    /**
+     * The cache implementation (e.g., Redis client wrapper)
+     */
+    cache: PersistedDocumentsCache;
+    /**
+     * TTL in seconds for successfully found documents.
+     * @default undefined (no expiration, or cache implementation default)
+     */
+    ttlSeconds?: number;
+    /**
+     * TTL in seconds for negative cache entries (document not found).
+     * Set to 0 to disable negative caching.
+     * @default 60 (1 minute)
+     */
+    notFoundTtlSeconds?: number;
+    /**
+     * Optional function to register background work in serverless environments if not available in context.
+     */
+    waitUntil?: (promise: Promise<void> | void) => void;
+};
 export type PersistedDocumentsConfiguration = {
     /**
      * CDN configuration for loading persisted documents.
@@ -316,6 +394,42 @@ export type PersistedDocumentsConfiguration = {
     fetch?: typeof fetch;
     /** Configuration for the circuit breaker. */
     circuitBreaker?: CircuitBreakerConfiguration;
+    /**
+     * Optional layer 2 cache configuration.
+     * When configured, the SDK will check this cache after the in-memory cache miss
+     * and before making a CDN request.
+     *
+     * This is useful for distributed caching (e.g., Redis) in multi-instance deployments,
+     * providing:
+     * - Shared cache between gateway instances
+     * - Additional resilience layer for CDN outages
+     * - Faster response times after gateway restarts
+     *
+     * @example
+     * ```typescript
+     * import { createClient } from 'redis';
+     * import { createHive} from '@graphql-hive/core';
+     *
+     * const redis = createClient({ url: 'redis://localhost:6379' });
+     * await redis.connect();
+     *
+     * const hive = createHive({
+     *   experimental__persistedDocuments: {
+     *     cdn: { endpoint: '...', accessToken: '...' },
+     *     layer2Cache: {
+     *       cache: {
+     *         get: (key) => redis.get(`hive:pd:${key}`),
+     *         set: (key, value, opts) =>
+     *           redis.set(`hive:pd:${key}`, value, opts?.ttl ? { EX: opts.ttl } : {}),
+     *       },
+     *       ttlSeconds: 3600,        // 1 hour for found documents
+     *       notFoundTtlSeconds: 60,  // 1 minute for notfound entries
+     *     },
+     *   },
+     * });
+     * ```
+     */
+    layer2Cache?: Layer2CacheConfiguration;
 };
 export type AllowArbitraryDocumentsFunction = (context: {
     /** an object for accessing the request headers. */

package/typings/index.d.cts

@@ -1,6 +1,6 @@
 export * from './normalize/operation.cjs';
 export { collectSchemaCoordinates } from './client/collect-schema-coordinates.cjs';
-export type { HivePluginOptions, HiveClient, CollectUsageCallback, LegacyLogger as Logger, } from './client/types.cjs';
+export type { HivePluginOptions, HiveClient, CollectUsageCallback, LegacyLogger as Logger, PersistedDocumentsCache, Layer2CacheConfiguration, } from './client/types.cjs';
 export { createSchemaFetcher, createServicesFetcher } from './client/gateways.cjs';
 export { createHive, autoDisposeSymbol } from './client/client.cjs';
 export { atLeastOnceSampler } from './client/samplers.cjs';

package/typings/index.d.ts

@@ -1,6 +1,6 @@
 export * from './normalize/operation.js';
 export { collectSchemaCoordinates } from './client/collect-schema-coordinates.js';
-export type { HivePluginOptions, HiveClient, CollectUsageCallback, LegacyLogger as Logger, } from './client/types.js';
+export type { HivePluginOptions, HiveClient, CollectUsageCallback, LegacyLogger as Logger, PersistedDocumentsCache, Layer2CacheConfiguration, } from './client/types.js';
 export { createSchemaFetcher, createServicesFetcher } from './client/gateways.js';
 export { createHive, autoDisposeSymbol } from './client/client.js';
 export { atLeastOnceSampler } from './client/samplers.js';

package/typings/version.d.cts

@@ -1,2 +1,2 @@
-export declare const version = "0.19.0-rc-20251222110102-ca00d2ee12be6920f3247ac812aa83bf9f8e9581";
+export declare const version = "0.19.0-rc-20260105125447-29b7291593ce66ef5f929776a3df44fc05ac0886";
 //# sourceMappingURL=version.d.ts.map

package/typings/version.d.ts

@@ -1,2 +1,2 @@
-export declare const version = "0.19.0-rc-20251222110102-ca00d2ee12be6920f3247ac812aa83bf9f8e9581";
+export declare const version = "0.19.0-rc-20260105125447-29b7291593ce66ef5f929776a3df44fc05ac0886";
 //# sourceMappingURL=version.d.ts.map