@pantheon-systems/nextjs-cache-handler 0.1.0 → 0.2.0

package/dist/use-cache/gcs-handler.js

@@ -0,0 +1,406 @@
+import { Storage } from '@google-cloud/storage';
+import { serializeUseCacheEntry, deserializeUseCacheEntry, } from './stream-serialization.js';
+import { createLogger } from '../utils/logger.js';
+import { createEdgeCacheClearer } from '../edge/edge-cache-clear.js';
+const log = createLogger('UseCacheGcsHandler');
+/**
+ * Next.js internal prefix for path-based cache tags.
+ * When revalidatePath('/api/foo') is called, Next.js internally calls
+ * revalidateTag('_N_T_/api/foo'). This prefix identifies path tags.
+ */
+const NEXTJS_PATH_TAG_PREFIX = '_N_T_';
+/**
+ * Symbol used to access CacheTagContext from globalThis.
+ * This matches the Symbol.for pattern used by Next.js for @next/request-context.
+ */
+const CACHE_TAG_CONTEXT_SYMBOL = Symbol.for('@nextjs-cache-handler/tag-context');
+/**
+ * Symbol used to expose registerPathTags on globalThis.
+ * This allows withSurrogateKey (which knows the request path and captured tags)
+ * to register path→surrogate-key mappings without a direct module import.
+ */
+const PATH_TAGS_REGISTRY_SYMBOL = Symbol.for('@nextjs-cache-handler/path-tags-registry');
+/**
+ * Access the CacheTagContext via globalThis using Symbol.for.
+ * This allows cross-context access without direct module imports.
+ */
+function getCacheTagContext() {
+    const accessor = globalThis[CACHE_TAG_CONTEXT_SYMBOL];
+    return accessor?.get();
+}
+/**
+ * Add tags to the CacheTagContext if available.
+ * Falls back to global store if CacheTagContext is not active.
+ */
+function captureTags(tags) {
+    if (tags.length === 0) {
+        return { captured: false, source: 'none' };
+    }
+    // Primary: Try CacheTagContext (Symbol.for pattern)
+    const context = getCacheTagContext();
+    if (context) {
+        context.tags.push(...tags);
+        log.debug(`Captured ${tags.length} tags via CacheTagContext: ${tags.join(', ')}`);
+        return { captured: true, source: 'CacheTagContext' };
+    }
+    // Fallback: Use global store (for environments where Symbol.for doesn't propagate)
+    let globalTags = globalThis.__pantheonSurrogateKeyTags;
+    if (!globalTags) {
+        globalTags = [];
+        globalThis.__pantheonSurrogateKeyTags = globalTags;
+    }
+    globalTags.push(...tags);
+    log.debug(`Captured ${tags.length} tags via globalStore fallback: ${tags.join(', ')}`);
+    return { captured: true, source: 'globalStore' };
+}
+/**
+ * Google Cloud Storage cache handler for Next.js 16 'use cache' directive.
+ * Implements the cacheHandlers (plural) interface.
+ *
+ * Suitable for:
+ * - Production/Pantheon environments
+ * - Multi-instance deployments requiring shared cache
+ */
+export class UseCacheGcsHandler {
+    constructor() {
+        this.tagTimestamps = new Map();
+        this.pathToSurrogateKeys = new Map();
+        this.initialized = false;
+        this.initPromise = null;
+        const bucketName = process.env.CACHE_BUCKET;
+        if (!bucketName) {
+            throw new Error('CACHE_BUCKET environment variable is required for GCS cache handler');
+        }
+        const storage = new Storage();
+        this.bucket = storage.bucket(bucketName);
+        this.cachePrefix = 'use-cache/';
+        this.tagsKey = `${this.cachePrefix}_tags.json`;
+        this.edgeCacheClearer = createEdgeCacheClearer();
+        // Expose registerPathTags on globalThis so withSurrogateKey can register
+        // path→surrogate-key mappings without direct module coupling
+        globalThis[PATH_TAGS_REGISTRY_SYMBOL] =
+            (path, tags) => this.registerPathTags(path, tags);
+        // Initialize asynchronously but track the promise
+        this.initPromise = this.initialize().catch(() => { });
+        log.info('Initialized GCS use-cache handler');
+    }
+    async initialize() {
+        if (this.initialized)
+            return;
+        await this.loadTagTimestamps();
+        this.initialized = true;
+    }
+    async ensureInitialized() {
+        if (this.initPromise) {
+            await this.initPromise;
+            this.initPromise = null;
+        }
+    }
+    async loadTagTimestamps() {
+        try {
+            const file = this.bucket.file(this.tagsKey);
+            const [exists] = await file.exists();
+            if (!exists) {
+                // Only reset if not already populated by local operations
+                if (this.tagTimestamps.size === 0) {
+                    this.tagTimestamps = new Map();
+                }
+                return;
+            }
+            const [data] = await file.download();
+            const parsed = JSON.parse(data.toString());
+            // Merge with existing in-memory state (local updates take precedence)
+            const loadedTimestamps = new Map(Object.entries(parsed));
+            for (const [tag, timestamp] of loadedTimestamps) {
+                const existing = this.tagTimestamps.get(tag);
+                if (!existing || timestamp > existing) {
+                    this.tagTimestamps.set(tag, timestamp);
+                }
+            }
+        }
+        catch (error) {
+            log.warn('Error loading tag timestamps:', error);
+            // Don't reset - keep existing in-memory state
+        }
+    }
+    async saveTagTimestamps() {
+        try {
+            const obj = Object.fromEntries(this.tagTimestamps);
+            const file = this.bucket.file(this.tagsKey);
+            await file.save(JSON.stringify(obj, null, 2), {
+                metadata: { contentType: 'application/json' },
+            });
+        }
+        catch (error) {
+            log.error('Error saving tag timestamps:', error);
+        }
+    }
+    getCacheKey(cacheKey) {
+        // Sanitize cache key for GCS object naming
+        const safeKey = cacheKey.replace(/[^a-zA-Z0-9-]/g, '_');
+        return `${this.cachePrefix}${safeKey}.json`;
+    }
+    /**
+     * Check if an entry is expired based on revalidate time.
+     */
+    isExpired(entry) {
+        const now = Date.now();
+        const age = now - entry.timestamp;
+        const revalidateMs = entry.revalidate * 1000;
+        // Entry is expired if it's older than revalidate time
+        if (age > revalidateMs) {
+            return true;
+        }
+        // Also check if any of the entry's tags have been invalidated
+        for (const tag of entry.tags) {
+            const tagTimestamp = this.tagTimestamps.get(tag);
+            if (tagTimestamp && tagTimestamp > entry.timestamp) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Retrieve a cache entry.
+     */
+    async get(cacheKey, softTags) {
+        log.debug(`GET: ${cacheKey}`);
+        try {
+            const gcsKey = this.getCacheKey(cacheKey);
+            const file = this.bucket.file(gcsKey);
+            const [exists] = await file.exists();
+            if (!exists) {
+                log.debug(`MISS: ${cacheKey} (not found)`);
+                return undefined;
+            }
+            const [data] = await file.download();
+            const stored = JSON.parse(data.toString());
+            const entry = deserializeUseCacheEntry(stored);
+            // Check expiration
+            if (this.isExpired(entry)) {
+                log.debug(`MISS: ${cacheKey} (expired)`);
+                // Optionally delete expired entry
+                try {
+                    await file.delete();
+                }
+                catch {
+                    // Ignore deletion errors
+                }
+                return undefined;
+            }
+            log.debug(`HIT: ${cacheKey}`);
+            // Capture tags for Surrogate-Key header propagation
+            // Uses Symbol.for pattern to access PantheonContext across async boundaries
+            const storedTags = entry.tags ?? [];
+            const { captured, source } = captureTags(storedTags);
+            if (captured) {
+                log.debug(`HIT ${cacheKey}: Captured ${storedTags.length} tags via ${source}`);
+            }
+            else if (storedTags.length === 0) {
+                // TODO: Remove this diagnostic logging once Next.js fixes the empty tags bug
+                // See: https://github.com/vercel/next.js/issues/78864
+                log.info(`HIT ${cacheKey}: No tags to capture (Next.js empty tags bug)`);
+            }
+            return entry;
+        }
+        catch (error) {
+            log.error(`Error reading cache for key ${cacheKey}:`, error);
+            return undefined;
+        }
+    }
+    /**
+     * Store a cache entry.
+     * CRITICAL: Must await pendingEntry before storing.
+     */
+    async set(cacheKey, pendingEntry) {
+        log.debug(`SET: ${cacheKey}`);
+        try {
+            // CRITICAL: Await the pending entry
+            const entry = await pendingEntry;
+            // TODO: Remove this diagnostic logging once Next.js fixes the empty tags bug
+            // Diagnostic logging for empty tags issue
+            // See: https://github.com/vercel/next.js/issues/78864
+            // See: docs/known-issues-nextjs16.md
+            const tagsLength = entry.tags?.length ?? 0;
+            if (tagsLength === 0) {
+                // Use info level so this is gated behind CACHE_DEBUG
+                log.info(`[EMPTY_TAGS_BUG] SET ${cacheKey}: Next.js passed empty tags array. ` +
+                    `This is a known Next.js bug - cacheTag() values are not propagated to cacheHandlers.set(). ` +
+                    `See: https://github.com/vercel/next.js/issues/78864`);
+            }
+            log.info(`SET entry structure for ${cacheKey}:`, {
+                hasTags: !!entry.tags,
+                tags: entry.tags,
+                tagsLength,
+                stale: entry.stale,
+                revalidate: entry.revalidate,
+                expire: entry.expire,
+                timestamp: entry.timestamp,
+                hasValue: !!entry.value,
+                entryKeys: Object.keys(entry),
+            });
+            const serialized = await serializeUseCacheEntry(entry);
+            const gcsKey = this.getCacheKey(cacheKey);
+            const file = this.bucket.file(gcsKey);
+            await file.save(JSON.stringify(serialized, null, 2), {
+                metadata: { contentType: 'application/json' },
+            });
+            log.debug(`Cached ${cacheKey}`);
+        }
+        catch (error) {
+            log.error(`Error setting cache for key ${cacheKey}:`, error);
+        }
+    }
+    /**
+     * Synchronize tag state from external source.
+     * Reloads tag timestamps from GCS.
+     */
+    async refreshTags() {
+        log.debug('REFRESH TAGS');
+        await this.loadTagTimestamps();
+    }
+    /**
+     * Return maximum revalidation timestamp for given tags.
+     */
+    async getExpiration(tags) {
+        let maxTimestamp = 0;
+        for (const tag of tags) {
+            const timestamp = this.tagTimestamps.get(tag) ?? 0;
+            if (timestamp > maxTimestamp) {
+                maxTimestamp = timestamp;
+            }
+        }
+        log.debug(`GET EXPIRATION for [${tags.join(', ')}]: ${maxTimestamp}`);
+        return maxTimestamp;
+    }
+    /**
+     * Register the surrogate keys (explicit cacheTag values) associated with a path.
+     * Called by withSurrogateKey when tags are captured during a cache HIT,
+     * enabling revalidatePath to resolve the correct CDN surrogate keys.
+     */
+    registerPathTags(path, surrogateKeys) {
+        this.pathToSurrogateKeys.set(path, surrogateKeys);
+        log.debug(`Registered path tags: ${path} → [${surrogateKeys.join(', ')}]`);
+    }
+    /**
+     * Invalidate cache entries with matching tags.
+     */
+    async updateTags(tags, durations) {
+        log.debug(`UPDATE TAGS: [${tags.join(', ')}]`);
+        if (tags.length === 0) {
+            return;
+        }
+        const now = Date.now();
+        for (const tag of tags) {
+            this.tagTimestamps.set(tag, now);
+        }
+        await this.saveTagTimestamps();
+        // Clear edge cache if configured
+        if (this.edgeCacheClearer) {
+            // Separate explicit tags from _N_T_ path tags
+            const explicitTags = [];
+            const pathTags = [];
+            for (const tag of tags) {
+                if (tag.startsWith(NEXTJS_PATH_TAG_PREFIX)) {
+                    pathTags.push(tag);
+                }
+                else {
+                    explicitTags.push(tag);
+                }
+            }
+            // Purge explicit tags as surrogate keys (these match CDN Surrogate-Key headers directly)
+            if (explicitTags.length > 0) {
+                this.edgeCacheClearer.clearKeysInBackground(explicitTags, `use-cache tag invalidation: ${explicitTags.join(', ')}`);
+            }
+            // Resolve _N_T_ path tags to surrogate keys via the registered mapping
+            if (pathTags.length > 0) {
+                const resolvedKeys = [];
+                const unresolvedPaths = [];
+                for (const pathTag of pathTags) {
+                    const path = pathTag.substring(NEXTJS_PATH_TAG_PREFIX.length);
+                    const surrogateKeys = this.pathToSurrogateKeys.get(path);
+                    if (surrogateKeys && surrogateKeys.length > 0) {
+                        resolvedKeys.push(...surrogateKeys);
+                        log.debug(`Resolved path tag ${pathTag} → surrogate keys: [${surrogateKeys.join(', ')}]`);
+                    }
+                    else {
+                        unresolvedPaths.push(path);
+                        log.debug(`No surrogate key mapping for path tag ${pathTag}, falling back to path purge`);
+                    }
+                }
+                // Purge resolved surrogate keys
+                if (resolvedKeys.length > 0) {
+                    this.edgeCacheClearer.clearKeysInBackground(resolvedKeys, `path revalidation (resolved): ${resolvedKeys.join(', ')}`);
+                }
+                // Fallback: attempt path-based purge for unmapped paths
+                if (unresolvedPaths.length > 0) {
+                    this.edgeCacheClearer.clearPathsInBackground(unresolvedPaths, `path revalidation (fallback): ${unresolvedPaths.join(', ')}`);
+                }
+            }
+        }
+    }
+    /**
+     * Get cache statistics for the use-cache entries in GCS.
+     * Returns information about all valid (non-expired) cache entries.
+     */
+    async getStats() {
+        log.debug('GET STATS');
+        const entries = [];
+        const keys = [];
+        try {
+            await this.ensureInitialized();
+            // List all files in the use-cache prefix
+            const [files] = await this.bucket.getFiles({ prefix: this.cachePrefix });
+            for (const file of files) {
+                // Skip tags file
+                if (file.name === this.tagsKey) {
+                    continue;
+                }
+                // Only process .json files
+                if (!file.name.endsWith('.json')) {
+                    continue;
+                }
+                try {
+                    const [data] = await file.download();
+                    const stored = JSON.parse(data.toString());
+                    // Extract key from filename (remove prefix and .json suffix)
+                    const key = file.name.replace(this.cachePrefix, '').replace('.json', '');
+                    // Deserialize to check expiration
+                    const entry = deserializeUseCacheEntry(stored);
+                    // Skip expired entries
+                    if (this.isExpired(entry)) {
+                        continue;
+                    }
+                    // Get file metadata for size
+                    const [metadata] = await file.getMetadata();
+                    const entryInfo = {
+                        key,
+                        tags: stored.tags || [],
+                        type: 'use-cache',
+                        lastModified: new Date(entry.timestamp).toISOString(),
+                        size: Number(metadata.size) || 0,
+                        revalidate: entry.revalidate,
+                        stale: entry.stale,
+                        expire: entry.expire,
+                    };
+                    entries.push(entryInfo);
+                    keys.push(key);
+                }
+                catch (error) {
+                    log.warn(`Error reading cache file ${file.name}:`, error);
+                }
+            }
+        }
+        catch (error) {
+            log.error('Error getting cache stats:', error);
+        }
+        log.debug(`Found ${entries.length} valid cache entries`);
+        return {
+            size: entries.length,
+            entries,
+            keys,
+        };
+    }
+}
+export default UseCacheGcsHandler;
+//# sourceMappingURL=gcs-handler.js.map

package/dist/use-cache/gcs-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcs-handler.js","sourceRoot":"","sources":["../../src/use-cache/gcs-handler.ts"],"names":[],"mappings":"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"}

package/dist/use-cache/index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Next.js 16 'use cache' Handler Module
+ *
+ * This module provides cache handlers for the new `cacheHandlers` (plural)
+ * configuration in Next.js 16, which supports the `'use cache'` directive.
+ *
+ * @example
+ * ```javascript
+ * // next.config.mjs
+ * import { createUseCacheHandler } from '@pantheon-systems/nextjs-cache-handler/use-cache';
+ *
+ * const nextConfig = {
+ *   // Existing handler for ISR, routes, fetch cache
+ *   cacheHandler: require.resolve('./cache-handler.mjs'),
+ *
+ *   // NEW handler for 'use cache' directive
+ *   cacheHandlers: {
+ *     default: require.resolve('./use-cache-handler.mjs'),
+ *   },
+ *
+ *   cacheComponents: true,
+ * };
+ *
+ * export default nextConfig;
+ * ```
+ */
+import type { UseCacheHandlerConfig } from './types.js';
+import { UseCacheFileHandler } from './file-handler.js';
+import { UseCacheGcsHandler } from './gcs-handler.js';
+/**
+ * Factory function to create a use cache handler based on configuration.
+ *
+ * @param config - Configuration options for the cache handler
+ * @returns A cache handler class that implements the cacheHandlers interface
+ *
+ * @example
+ * ```typescript
+ * // In your use-cache-handler.ts file:
+ * import { createUseCacheHandler } from '@pantheon-systems/nextjs-cache-handler/use-cache';
+ *
+ * const UseCacheHandler = createUseCacheHandler({
+ *   type: 'auto', // Auto-detect: GCS if CACHE_BUCKET exists, else file-based
+ * });
+ *
+ * export default UseCacheHandler;
+ * ```
+ */
+export declare function createUseCacheHandler(config?: UseCacheHandlerConfig): typeof UseCacheFileHandler | typeof UseCacheGcsHandler;
+export { UseCacheFileHandler } from './file-handler.js';
+export { UseCacheGcsHandler } from './gcs-handler.js';
+export type { UseCacheEntry, UseCacheHandler, UseCacheHandlerConfig, SerializedUseCacheEntry, UseCacheStats, UseCacheEntryInfo, } from './types.js';
+/**
+ * Get cache statistics for use-cache entries.
+ * Automatically detects whether to use file-based or GCS cache stats.
+ */
+export declare function getUseCacheStats(): Promise<import('./types.js').UseCacheStats>;
+export { streamToBytes, bytesToStream, serializeUseCacheEntry, deserializeUseCacheEntry, } from './stream-serialization.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/use-cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/use-cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEtD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,CAAC,EAAE,qBAAqB,GAC7B,OAAO,mBAAmB,GAAG,OAAO,kBAAkB,CAQxD;AAkBD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAMtD,YAAY,EACV,aAAa,EACb,eAAe,EACf,qBAAqB,EACrB,uBAAuB,EACvB,aAAa,EACb,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAMpB;;;GAGG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,OAAO,YAAY,EAAE,aAAa,CAAC,CAOpF;AAMD,OAAO,EACL,aAAa,EACb,aAAa,EACb,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,2BAA2B,CAAC"}

package/dist/use-cache/index.js

@@ -0,0 +1,87 @@
+/**
+ * Next.js 16 'use cache' Handler Module
+ *
+ * This module provides cache handlers for the new `cacheHandlers` (plural)
+ * configuration in Next.js 16, which supports the `'use cache'` directive.
+ *
+ * @example
+ * ```javascript
+ * // next.config.mjs
+ * import { createUseCacheHandler } from '@pantheon-systems/nextjs-cache-handler/use-cache';
+ *
+ * const nextConfig = {
+ *   // Existing handler for ISR, routes, fetch cache
+ *   cacheHandler: require.resolve('./cache-handler.mjs'),
+ *
+ *   // NEW handler for 'use cache' directive
+ *   cacheHandlers: {
+ *     default: require.resolve('./use-cache-handler.mjs'),
+ *   },
+ *
+ *   cacheComponents: true,
+ * };
+ *
+ * export default nextConfig;
+ * ```
+ */
+import { UseCacheFileHandler } from './file-handler.js';
+import { UseCacheGcsHandler } from './gcs-handler.js';
+/**
+ * Factory function to create a use cache handler based on configuration.
+ *
+ * @param config - Configuration options for the cache handler
+ * @returns A cache handler class that implements the cacheHandlers interface
+ *
+ * @example
+ * ```typescript
+ * // In your use-cache-handler.ts file:
+ * import { createUseCacheHandler } from '@pantheon-systems/nextjs-cache-handler/use-cache';
+ *
+ * const UseCacheHandler = createUseCacheHandler({
+ *   type: 'auto', // Auto-detect: GCS if CACHE_BUCKET exists, else file-based
+ * });
+ *
+ * export default UseCacheHandler;
+ * ```
+ */
+export function createUseCacheHandler(config) {
+    const type = config?.type ?? 'auto';
+    if (shouldUseGcs(type)) {
+        return UseCacheGcsHandler;
+    }
+    return UseCacheFileHandler;
+}
+function shouldUseGcs(type) {
+    if (type === 'gcs') {
+        return true;
+    }
+    if (type === 'auto') {
+        return !!process.env.CACHE_BUCKET;
+    }
+    return false;
+}
+// ============================================================================
+// Handler exports
+// ============================================================================
+export { UseCacheFileHandler } from './file-handler.js';
+export { UseCacheGcsHandler } from './gcs-handler.js';
+// ============================================================================
+// Stats function
+// ============================================================================
+/**
+ * Get cache statistics for use-cache entries.
+ * Automatically detects whether to use file-based or GCS cache stats.
+ */
+export async function getUseCacheStats() {
+    if (process.env.CACHE_BUCKET) {
+        const handler = new UseCacheGcsHandler();
+        return handler.getStats();
+    }
+    const handler = new UseCacheFileHandler();
+    return handler.getStats();
+}
+// ============================================================================
+// Utility exports
+// ============================================================================
+export { streamToBytes, bytesToStream, serializeUseCacheEntry, deserializeUseCacheEntry, } from './stream-serialization.js';
+//# sourceMappingURL=index.js.map

package/dist/use-cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/use-cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEtD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAA8B;IAE9B,MAAM,IAAI,GAAG,MAAM,EAAE,IAAI,IAAI,MAAM,CAAC;IAEpC,IAAI,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;QACvB,OAAO,kBAAkB,CAAC;IAC5B,CAAC;IAED,OAAO,mBAAmB,CAAC;AAC7B,CAAC;AAED,SAAS,YAAY,CAAC,IAA6B;IACjD,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,OAAO,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;IACpC,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,+EAA+E;AAC/E,kBAAkB;AAClB,+EAA+E;AAE/E,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAetD,+EAA+E;AAC/E,iBAAiB;AACjB,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB;IACpC,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,IAAI,kBAAkB,EAAE,CAAC;QACzC,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAC;IAC5B,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,mBAAmB,EAAE,CAAC;IAC1C,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAC;AAC5B,CAAC;AAED,+EAA+E;AAC/E,kBAAkB;AAClB,+EAA+E;AAE/E,OAAO,EACL,aAAa,EACb,aAAa,EACb,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,2BAA2B,CAAC"}

package/dist/use-cache/stream-serialization.d.ts

@@ -0,0 +1,34 @@
+import type { UseCacheEntry, SerializedUseCacheEntry } from './types.js';
+/**
+ * Convert a ReadableStream<Uint8Array> to a Uint8Array.
+ * Consumes the entire stream and concatenates all chunks.
+ *
+ * @param stream - The stream to consume
+ * @returns A single Uint8Array containing all the stream data
+ */
+export declare function streamToBytes(stream: ReadableStream<Uint8Array>): Promise<Uint8Array>;
+/**
+ * Convert a Uint8Array to a ReadableStream<Uint8Array>.
+ * Creates a stream that emits the entire array as a single chunk.
+ *
+ * @param bytes - The bytes to convert to a stream
+ * @returns A ReadableStream that emits the bytes
+ */
+export declare function bytesToStream(bytes: Uint8Array): ReadableStream<Uint8Array>;
+/**
+ * Serialize a UseCacheEntry for persistent storage.
+ * Converts the ReadableStream value to a base64-encoded string.
+ *
+ * @param entry - The cache entry to serialize
+ * @returns A serialized entry suitable for JSON storage
+ */
+export declare function serializeUseCacheEntry(entry: UseCacheEntry): Promise<SerializedUseCacheEntry>;
+/**
+ * Deserialize a stored cache entry back to UseCacheEntry.
+ * Converts the base64-encoded value back to a ReadableStream.
+ *
+ * @param stored - The serialized entry from storage
+ * @returns A UseCacheEntry with a ReadableStream value
+ */
+export declare function deserializeUseCacheEntry(stored: SerializedUseCacheEntry): UseCacheEntry;
+//# sourceMappingURL=stream-serialization.d.ts.map

package/dist/use-cache/stream-serialization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-serialization.d.ts","sourceRoot":"","sources":["../../src/use-cache/stream-serialization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAEzE;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAgC3F;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,cAAc,CAAC,UAAU,CAAC,CAO3E;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAenG;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,uBAAuB,GAAG,aAAa,CAkBvF"}