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

package/dist/use-cache/stream-serialization.js

@@ -0,0 +1,96 @@
+/**
+ * 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 async function streamToBytes(stream) {
+    const reader = stream.getReader();
+    const chunks = [];
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (value) {
+            chunks.push(value);
+        }
+    }
+    // Handle empty stream
+    if (chunks.length === 0) {
+        return new Uint8Array(0);
+    }
+    // Single chunk optimization
+    if (chunks.length === 1) {
+        return chunks[0];
+    }
+    // Concatenate all chunks
+    const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+        result.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return result;
+}
+/**
+ * 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 function bytesToStream(bytes) {
+    return new ReadableStream({
+        start(controller) {
+            controller.enqueue(bytes);
+            controller.close();
+        },
+    });
+}
+/**
+ * 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 async function serializeUseCacheEntry(entry) {
+    // Convert stream to bytes
+    const bytes = await streamToBytes(entry.value);
+    // Convert bytes to base64 for JSON-safe storage
+    const base64Value = Buffer.from(bytes).toString('base64');
+    return {
+        value: base64Value,
+        tags: entry.tags,
+        stale: entry.stale,
+        timestamp: entry.timestamp,
+        expire: entry.expire,
+        revalidate: entry.revalidate,
+    };
+}
+/**
+ * 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 function deserializeUseCacheEntry(stored) {
+    // Convert base64 back to bytes
+    const bytes = stored.value ? Buffer.from(stored.value, 'base64') : new Uint8Array(0);
+    // Convert bytes to Uint8Array (Buffer is a subclass, but be explicit)
+    const uint8Array = new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    // Create stream from bytes
+    const stream = bytesToStream(uint8Array);
+    return {
+        value: stream,
+        tags: stored.tags,
+        stale: stored.stale,
+        timestamp: stored.timestamp,
+        expire: stored.expire,
+        revalidate: stored.revalidate,
+    };
+}
+//# sourceMappingURL=stream-serialization.js.map

package/dist/use-cache/stream-serialization.js.map

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

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

@@ -0,0 +1,202 @@
+/**
+ * Cache entry structure for 'use cache' directive.
+ *
+ * Key differences from the legacy cacheHandler interface:
+ * - value is a ReadableStream<Uint8Array> instead of a serializable object
+ * - Includes timing metadata: stale, expire, revalidate
+ * - timestamp is in milliseconds (creation time)
+ */
+export interface UseCacheEntry {
+    /**
+     * The cached value as a stream.
+     * Must be consumed or tee()'d if needed for multiple reads.
+     */
+    value: ReadableStream<Uint8Array>;
+    /**
+     * Cache tags for on-demand revalidation.
+     * Used with cacheTag() and revalidateTag().
+     */
+    tags: string[];
+    /**
+     * Duration in seconds for client-side staleness.
+     * Controls how long the entry can be served as stale while revalidating.
+     */
+    stale: number;
+    /**
+     * Creation timestamp in milliseconds.
+     * Used to determine cache age.
+     */
+    timestamp: number;
+    /**
+     * How long (in seconds) the entry is allowed to be used.
+     * After this time, the entry should not be served.
+     */
+    expire: number;
+    /**
+     * How long (in seconds) until the entry should be revalidated.
+     * After this time, the entry is considered stale but may still be served.
+     */
+    revalidate: number;
+}
+/**
+ * Serialized format for storing UseCacheEntry to persistent storage.
+ * The ReadableStream is converted to a base64 string.
+ */
+export interface SerializedUseCacheEntry {
+    /**
+     * Base64-encoded bytes from the stream.
+     */
+    value: string;
+    /**
+     * Cache tags for on-demand revalidation.
+     */
+    tags: string[];
+    /**
+     * Duration in seconds for client-side staleness.
+     */
+    stale: number;
+    /**
+     * Creation timestamp in milliseconds.
+     */
+    timestamp: number;
+    /**
+     * How long (in seconds) the entry is allowed to be used.
+     */
+    expire: number;
+    /**
+     * How long (in seconds) until the entry should be revalidated.
+     */
+    revalidate: number;
+}
+/**
+ * Cache handler interface for 'use cache' directive (cacheHandlers plural).
+ *
+ * Key differences from the legacy CacheHandler interface:
+ * - get() receives softTags parameter
+ * - set() receives a Promise that must be awaited
+ * - Includes refreshTags(), getExpiration(), and updateTags() methods
+ */
+export interface UseCacheHandler {
+    /**
+     * Retrieve a cache entry.
+     *
+     * @param cacheKey - The cache key to look up
+     * @param softTags - Framework-provided tags for additional filtering
+     * @returns The cache entry if found and valid, undefined otherwise
+     *
+     * Implementation notes:
+     * - Check expiration based on entry.revalidate and entry.timestamp
+     * - Return undefined if missing or expired
+     */
+    get(cacheKey: string, softTags: string[]): Promise<UseCacheEntry | undefined>;
+    /**
+     * Store a cache entry.
+     *
+     * @param cacheKey - The cache key to store under
+     * @param pendingEntry - A Promise that MUST be awaited before storage
+     *
+     * Implementation notes:
+     * - CRITICAL: Must await pendingEntry before storing
+     * - entry.value is a ReadableStream that may need .tee() if reading
+     * - For persistent storage, convert stream to bytes before storing
+     */
+    set(cacheKey: string, pendingEntry: Promise<UseCacheEntry>): Promise<void>;
+    /**
+     * Synchronize tag state from external source.
+     *
+     * Implementation notes:
+     * - Can be no-op for in-memory caches
+     * - For distributed caches, sync tag invalidation state from shared storage
+     */
+    refreshTags(): Promise<void>;
+    /**
+     * Return maximum revalidation timestamp for given tags.
+     *
+     * @param tags - Array of tag names to check
+     * @returns The most recent invalidation timestamp, or 0 if no cached info
+     *
+     * Implementation notes:
+     * - Used to determine if cached entries are still valid
+     * - Return 0 if no tags have been invalidated
+     */
+    getExpiration(tags: string[]): Promise<number>;
+    /**
+     * Invalidate cache entries with matching tags.
+     *
+     * @param tags - Array of tag names to invalidate
+     * @param durations - Corresponding invalidation durations (currently unused by Next.js)
+     *
+     * Implementation notes:
+     * - Store invalidation timestamps for each tag
+     * - Entries with matching tags should be considered invalid
+     */
+    updateTags(tags: string[], durations: number[]): Promise<void>;
+}
+/**
+ * Configuration options for creating a use cache handler instance.
+ */
+export interface UseCacheHandlerConfig {
+    /**
+     * Handler type selection:
+     * - 'auto': Automatically detect based on environment (GCS if CACHE_BUCKET is set, otherwise file)
+     * - 'file': Use file-based caching (local development)
+     * - 'gcs': Use Google Cloud Storage (production/Pantheon)
+     */
+    type?: 'auto' | 'file' | 'gcs';
+}
+/**
+ * Information about a single use-cache entry for stats reporting.
+ */
+export interface UseCacheEntryInfo {
+    /**
+     * The cache key.
+     */
+    key: string;
+    /**
+     * Cache tags associated with this entry.
+     */
+    tags: string[];
+    /**
+     * Type identifier for stats reporting.
+     * Always 'use-cache' for entries from cacheHandlers (plural).
+     */
+    type: 'use-cache';
+    /**
+     * When the entry was created (ISO timestamp).
+     */
+    lastModified?: string;
+    /**
+     * Approximate size in bytes (if available).
+     */
+    size?: number;
+    /**
+     * Revalidation time in seconds.
+     */
+    revalidate?: number;
+    /**
+     * Stale time in seconds.
+     */
+    stale?: number;
+    /**
+     * Expire time in seconds.
+     */
+    expire?: number;
+}
+/**
+ * Cache statistics for use-cache entries.
+ */
+export interface UseCacheStats {
+    /**
+     * Number of cache entries.
+     */
+    size: number;
+    /**
+     * Detailed information about each entry.
+     */
+    entries: UseCacheEntryInfo[];
+    /**
+     * List of cache keys.
+     */
+    keys: string[];
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/use-cache/types.ts"],"names":[],"mappings":"AAQA;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,KAAK,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IAElC;;;OAGG;IACH,IAAI,EAAE,MAAM,EAAE,CAAC;IAEf;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,IAAI,EAAE,MAAM,EAAE,CAAC;IAEf;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;;OAUG;IACH,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAAC;IAE9E;;;;;;;;;;OAUG;IACH,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3E;;;;;;OAMG;IACH,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7B;;;;;;;;;OASG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE/C;;;;;;;;;OASG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChE;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;CAChC;AAMD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;OAEG;IACH,IAAI,EAAE,MAAM,EAAE,CAAC;IAEf;;;OAGG;IACH,IAAI,EAAE,WAAW,CAAC;IAElB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAE7B;;OAEG;IACH,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB"}

package/dist/use-cache/types.js

@@ -0,0 +1,9 @@
+// ============================================================================
+// Next.js 16 'use cache' Handler Types
+// ============================================================================
+// These types implement the cacheHandlers (plural) interface for the
+// 'use cache' directive introduced in Next.js 16.
+// See: https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheHandlers
+// ============================================================================
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/use-cache/types.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,uCAAuC;AACvC,+EAA+E;AAC/E,qEAAqE;AACrE,kDAAkD;AAClD,qFAAqF;AACrF,+EAA+E"}

package/dist/utils/cache-tag-context.d.ts

@@ -0,0 +1,66 @@
+interface CacheTagContextData {
+    tags: string[];
+    requestId: string;
+    startTime: number;
+}
+/**
+ * Request-scoped context for tracking cache tags using the Symbol.for pattern.
+ *
+ * This approach mirrors Next.js's @next/request-context pattern, which is known
+ * to propagate through Next.js's internal mechanisms (used by `after()`).
+ *
+ * The key difference from direct AsyncLocalStorage usage is that cache handlers
+ * can access this context via `globalThis[Symbol.for('@nextjs-cache-handler/tag-context')]`
+ * rather than importing a module directly.
+ */
+export declare class CacheTagContext {
+    /**
+     * Add tags to the current request context.
+     * Called by cache handler during cache hits.
+     */
+    static addTags(tags: string[]): void;
+    /**
+     * Get all unique tags accumulated during the current request.
+     * Called by middleware before sending response.
+     */
+    static getTags(): string[];
+    /**
+     * Get the current request ID.
+     */
+    static getRequestId(): string | undefined;
+    /**
+     * Run a callback within a cache tag context.
+     * Must be called by withSurrogateKey to initialize tracking.
+     */
+    static run<T>(callback: () => T): T;
+    /**
+     * Check if running within a cache tag context.
+     */
+    static isActive(): boolean;
+    /**
+     * Get the well-known symbol for accessing this context from cache handlers.
+     * Cache handlers should use: globalThis[CacheTagContext.symbol]?.get()
+     */
+    static get symbol(): symbol;
+}
+/**
+ * Helper function for cache handlers to access the cache tag context.
+ * This can be called from any module without importing CacheTagContext directly.
+ *
+ * @example
+ * ```typescript
+ * // In cache handler (use-cache-handler.mjs)
+ * const context = globalThis[Symbol.for('@nextjs-cache-handler/tag-context')]?.get();
+ * if (context) {
+ *   context.tags.push(...entry.tags);
+ * }
+ * ```
+ */
+export declare function getCacheTagContextFromGlobal(): CacheTagContextData | undefined;
+/**
+ * Helper function for cache handlers to add tags to the cache tag context.
+ * This can be called from any module without importing CacheTagContext directly.
+ */
+export declare function addTagsToCacheTagContext(tags: string[]): boolean;
+export {};
+//# sourceMappingURL=cache-tag-context.d.ts.map

package/dist/utils/cache-tag-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-tag-context.d.ts","sourceRoot":"","sources":["../../src/utils/cache-tag-context.ts"],"names":[],"mappings":"AAYA,UAAU,mBAAmB;IAC3B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AA0BD;;;;;;;;;GASG;AACH,qBAAa,eAAe;IAC1B;;;OAGG;IACH,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;IAUpC;;;OAGG;IACH,MAAM,CAAC,OAAO,IAAI,MAAM,EAAE;IAQ1B;;OAEG;IACH,MAAM,CAAC,YAAY,IAAI,MAAM,GAAG,SAAS;IAIzC;;;OAGG;IACH,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC;IAcnC;;OAEG;IACH,MAAM,CAAC,QAAQ,IAAI,OAAO;IAI1B;;;OAGG;IACH,MAAM,KAAK,MAAM,IAAI,MAAM,CAE1B;CACF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,IAAI,mBAAmB,GAAG,SAAS,CAK9E;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAQhE"}

package/dist/utils/cache-tag-context.js

@@ -0,0 +1,126 @@
+import { AsyncLocalStorage } from 'async_hooks';
+import { createLogger } from './logger.js';
+const log = createLogger('CacheTagContext');
+/**
+ * Symbol used to store the cache tag context accessor on globalThis.
+ * Uses Symbol.for() to ensure the same symbol is used across module boundaries,
+ * similar to Next.js's @next/request-context pattern.
+ */
+const CACHE_TAG_CONTEXT_SYMBOL = Symbol.for('@nextjs-cache-handler/tag-context');
+/**
+ * AsyncLocalStorage instance for request-scoped context.
+ * This is created once and registered globally via Symbol.for().
+ */
+const cacheTagContextStorage = new AsyncLocalStorage();
+/**
+ * The accessor object that will be stored on globalThis.
+ * Cache handlers can retrieve this via globalThis[Symbol.for('@nextjs-cache-handler/tag-context')].
+ */
+const cacheTagContextAccessor = {
+    get() {
+        return cacheTagContextStorage.getStore();
+    },
+};
+// Register the accessor on globalThis using the well-known symbol
+// This allows cache handlers (which run in a different module context) to access it
+globalThis[CACHE_TAG_CONTEXT_SYMBOL] = cacheTagContextAccessor;
+/**
+ * Request-scoped context for tracking cache tags using the Symbol.for pattern.
+ *
+ * This approach mirrors Next.js's @next/request-context pattern, which is known
+ * to propagate through Next.js's internal mechanisms (used by `after()`).
+ *
+ * The key difference from direct AsyncLocalStorage usage is that cache handlers
+ * can access this context via `globalThis[Symbol.for('@nextjs-cache-handler/tag-context')]`
+ * rather than importing a module directly.
+ */
+export class CacheTagContext {
+    /**
+     * Add tags to the current request context.
+     * Called by cache handler during cache hits.
+     */
+    static addTags(tags) {
+        const context = cacheTagContextStorage.getStore();
+        if (context) {
+            context.tags.push(...tags);
+            log.debug(`Added ${tags.length} tags to CacheTagContext: ${tags.join(', ')}`);
+        }
+        else {
+            log.debug('No CacheTagContext available - tags will not be captured via Symbol.for');
+        }
+    }
+    /**
+     * Get all unique tags accumulated during the current request.
+     * Called by middleware before sending response.
+     */
+    static getTags() {
+        const context = cacheTagContextStorage.getStore();
+        if (!context) {
+            return [];
+        }
+        return [...new Set(context.tags)];
+    }
+    /**
+     * Get the current request ID.
+     */
+    static getRequestId() {
+        return cacheTagContextStorage.getStore()?.requestId;
+    }
+    /**
+     * Run a callback within a cache tag context.
+     * Must be called by withSurrogateKey to initialize tracking.
+     */
+    static run(callback) {
+        const requestId = crypto.randomUUID();
+        log.debug(`Starting CacheTagContext with requestId: ${requestId}`);
+        return cacheTagContextStorage.run({
+            tags: [],
+            requestId,
+            startTime: Date.now(),
+        }, callback);
+    }
+    /**
+     * Check if running within a cache tag context.
+     */
+    static isActive() {
+        return cacheTagContextStorage.getStore() !== undefined;
+    }
+    /**
+     * Get the well-known symbol for accessing this context from cache handlers.
+     * Cache handlers should use: globalThis[CacheTagContext.symbol]?.get()
+     */
+    static get symbol() {
+        return CACHE_TAG_CONTEXT_SYMBOL;
+    }
+}
+/**
+ * Helper function for cache handlers to access the cache tag context.
+ * This can be called from any module without importing CacheTagContext directly.
+ *
+ * @example
+ * ```typescript
+ * // In cache handler (use-cache-handler.mjs)
+ * const context = globalThis[Symbol.for('@nextjs-cache-handler/tag-context')]?.get();
+ * if (context) {
+ *   context.tags.push(...entry.tags);
+ * }
+ * ```
+ */
+export function getCacheTagContextFromGlobal() {
+    const accessor = globalThis[CACHE_TAG_CONTEXT_SYMBOL];
+    return accessor?.get();
+}
+/**
+ * Helper function for cache handlers to add tags to the cache tag context.
+ * This can be called from any module without importing CacheTagContext directly.
+ */
+export function addTagsToCacheTagContext(tags) {
+    const context = getCacheTagContextFromGlobal();
+    if (context && tags.length > 0) {
+        context.tags.push(...tags);
+        log.debug(`Added ${tags.length} tags via global accessor: ${tags.join(', ')}`);
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=cache-tag-context.js.map

package/dist/utils/cache-tag-context.js.map

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

package/dist/utils/index.d.ts

@@ -2,4 +2,7 @@ export { serializeForStorage, deserializeFromStorage } from './serialization.js'
 export { getBuildId, isBuildPhase } from './build-detection.js';
 export { getStaticRoutes } from './static-routes.js';
 export { createLogger, type Logger } from './logger.js';
+export { RequestContext } from './request-context.js';
+export { CacheTagContext, getCacheTagContextFromGlobal, addTagsToCacheTagContext, } from './cache-tag-context.js';
+export { withSurrogateKey, type SurrogateKeyOptions } from './with-surrogate-key.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EACL,eAAe,EACf,4BAA4B,EAC5B,wBAAwB,GACzB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,gBAAgB,EAAE,KAAK,mBAAmB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/utils/index.js

@@ -2,4 +2,7 @@ export { serializeForStorage, deserializeFromStorage } from './serialization.js'
 export { getBuildId, isBuildPhase } from './build-detection.js';
 export { getStaticRoutes } from './static-routes.js';
 export { createLogger } from './logger.js';
+export { RequestContext } from './request-context.js';
+export { CacheTagContext, getCacheTagContextFromGlobal, addTagsToCacheTagContext, } from './cache-tag-context.js';
+export { withSurrogateKey } from './with-surrogate-key.js';
 //# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAe,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAe,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EACL,eAAe,EACf,4BAA4B,EAC5B,wBAAwB,GACzB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,gBAAgB,EAA4B,MAAM,yBAAyB,CAAC"}

package/dist/utils/request-context.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Request-scoped context for tracking cache tags during SSR.
+ * Uses AsyncLocalStorage to maintain isolation between concurrent requests.
+ */
+export declare class RequestContext {
+    private static storage;
+    /**
+     * Add tags to the current request context.
+     * Called by cache handler during cache hits.
+     */
+    static addTags(tags: string[]): void;
+    /**
+     * Get all unique tags accumulated during the current request.
+     * Called by middleware before sending response.
+     */
+    static getTags(): string[];
+    /**
+     * Run a callback within a request context.
+     * Must be called by middleware to initialize tracking.
+     */
+    static run<T>(callback: () => T): T;
+    /**
+     * Check if running within a request context.
+     * Useful for debugging and conditional logic.
+     */
+    static isActive(): boolean;
+}
+//# sourceMappingURL=request-context.d.ts.map

package/dist/utils/request-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-context.d.ts","sourceRoot":"","sources":["../../src/utils/request-context.ts"],"names":[],"mappings":"AAUA;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAC,OAAO,CAA+C;IAErE;;;OAGG;IACH,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;IAUpC;;;OAGG;IACH,MAAM,CAAC,OAAO,IAAI,MAAM,EAAE;IAS1B;;;OAGG;IACH,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC;IAUnC;;;OAGG;IACH,MAAM,CAAC,QAAQ,IAAI,OAAO;CAG3B"}

package/dist/utils/request-context.js

@@ -0,0 +1,54 @@
+import { AsyncLocalStorage } from 'async_hooks';
+import { createLogger } from './logger.js';
+const log = createLogger('RequestContext');
+/**
+ * Request-scoped context for tracking cache tags during SSR.
+ * Uses AsyncLocalStorage to maintain isolation between concurrent requests.
+ */
+export class RequestContext {
+    /**
+     * Add tags to the current request context.
+     * Called by cache handler during cache hits.
+     */
+    static addTags(tags) {
+        const context = this.storage.getStore();
+        if (context) {
+            context.tags.push(...tags);
+            log.debug(`Added ${tags.length} tags to request context: ${tags.join(', ')}`);
+        }
+        else {
+            log.warn('No request context available - tags will not be captured');
+        }
+    }
+    /**
+     * Get all unique tags accumulated during the current request.
+     * Called by middleware before sending response.
+     */
+    static getTags() {
+        const context = this.storage.getStore();
+        if (!context) {
+            return [];
+        }
+        // Remove duplicates using Set
+        return [...new Set(context.tags)];
+    }
+    /**
+     * Run a callback within a request context.
+     * Must be called by middleware to initialize tracking.
+     */
+    static run(callback) {
+        return this.storage.run({
+            tags: [],
+            startTime: Date.now(),
+        }, callback);
+    }
+    /**
+     * Check if running within a request context.
+     * Useful for debugging and conditional logic.
+     */
+    static isActive() {
+        return this.storage.getStore() !== undefined;
+    }
+}
+RequestContext.storage = new AsyncLocalStorage();
+//# sourceMappingURL=request-context.js.map

package/dist/utils/request-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-context.js","sourceRoot":"","sources":["../../src/utils/request-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,GAAG,GAAG,YAAY,CAAC,gBAAgB,CAAC,CAAC;AAO3C;;;GAGG;AACH,MAAM,OAAO,cAAc;IAGzB;;;OAGG;IACH,MAAM,CAAC,OAAO,CAAC,IAAc;QAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;QACxC,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;YAC3B,GAAG,CAAC,KAAK,CAAC,SAAS,IAAI,CAAC,MAAM,6BAA6B,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAChF,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,IAAI,CAAC,0DAA0D,CAAC,CAAC;QACvE,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,OAAO;QACZ,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;QACxC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,8BAA8B;QAC9B,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACpC,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,GAAG,CAAI,QAAiB;QAC7B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CACrB;YACE,IAAI,EAAE,EAAE;YACR,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACtB,EACD,QAAQ,CACT,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,QAAQ;QACb,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,KAAK,SAAS,CAAC;IAC/C,CAAC;;AAjDc,sBAAO,GAAG,IAAI,iBAAiB,EAAsB,CAAC"}

package/dist/utils/request-context.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=request-context.test.d.ts.map

package/dist/utils/request-context.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-context.test.d.ts","sourceRoot":"","sources":["../../src/utils/request-context.test.ts"],"names":[],"mappings":""}