@mrjasonroy/cache-components-cache-handler 16.0.0-alpha.0

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

@@ -0,0 +1,85 @@
+/**
+ * Next.js Data Cache Handler Types
+ * For "use cache" directive support
+ * Source: next.js/packages/next/src/server/lib/cache-handlers/types.ts
+ */
+/**
+ * A timestamp in milliseconds elapsed since the epoch
+ */
+export type Timestamp = number;
+/**
+ * Cache entry for data cache (used by "use cache" directive)
+ * Uses ReadableStream for streaming responses
+ */
+export interface DataCacheEntry {
+    /**
+     * The ReadableStream can error and only have partial data so any cache
+     * handlers need to handle this case and decide to keep the partial cache
+     * around or not.
+     */
+    value: ReadableStream<Uint8Array>;
+    /**
+     * The tags configured for the entry excluding soft tags
+     */
+    tags: string[];
+    /**
+     * This is for the client, not used to calculate cache entry expiration
+     * [duration in seconds]
+     */
+    stale: number;
+    /**
+     * When the cache entry was created [timestamp in milliseconds]
+     */
+    timestamp: Timestamp;
+    /**
+     * How long the entry is allowed to be used (should be longer than revalidate)
+     * [duration in seconds]
+     */
+    expire: number;
+    /**
+     * How long until the entry should be revalidated [duration in seconds]
+     */
+    revalidate: number;
+}
+/**
+ * Data cache handler interface that must be implemented
+ * This is for "use cache" directive support
+ */
+export interface DataCacheHandler {
+    /**
+     * Retrieve a cache entry for the given cache key, if available. Will return
+     * undefined if there's no valid entry, or if the given soft tags are stale.
+     */
+    get(cacheKey: string, softTags: string[]): Promise<undefined | DataCacheEntry>;
+    /**
+     * Store a cache entry for the given cache key. When this is called, the entry
+     * may still be pending, i.e. its value stream may still be written to. So it
+     * needs to be awaited first. If a `get` for the same cache key is called,
+     * before the pending entry is complete, the cache handler must wait for the
+     * `set` operation to finish, before returning the entry, instead of returning
+     * undefined.
+     */
+    set(cacheKey: string, pendingEntry: Promise<DataCacheEntry>): Promise<void>;
+    /**
+     * This function may be called periodically, but always before starting a new
+     * request. If applicable, it should communicate with the tags service to
+     * refresh the local tags manifest accordingly.
+     */
+    refreshTags(): Promise<void>;
+    /**
+     * This function is called for each set of soft tags that are relevant at the
+     * start of a request. The result is the maximum timestamp of a revalidate
+     * event for the tags. Returns `0` if none of the tags were ever revalidated.
+     * Returns `Infinity` if the soft tags are supposed to be passed into the
+     * `get` method instead to be checked for expiration.
+     */
+    getExpiration(tags: string[]): Promise<Timestamp>;
+    /**
+     * This function is called when tags are revalidated/expired. If applicable,
+     * it should update the tags manifest accordingly.
+     */
+    updateTags(tags: string[], durations?: {
+        expire?: number;
+    }): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/data-cache/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAE/B;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,KAAK,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IAElC;;OAEG;IACH,IAAI,EAAE,MAAM,EAAE,CAAC;IAEf;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,SAAS,EAAE,SAAS,CAAC;IAErB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,GAAG,cAAc,CAAC,CAAC;IAE/E;;;;;;;OAOG;IACH,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5E;;;;OAIG;IACH,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7B;;;;;;OAMG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAElD;;;OAGG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5E"}

package/dist/data-cache/types.js

@@ -0,0 +1,7 @@
+/**
+ * Next.js Data Cache Handler Types
+ * For "use cache" directive support
+ * Source: next.js/packages/next/src/server/lib/cache-handlers/types.ts
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/data-cache/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/handlers/composite.d.ts

@@ -0,0 +1,70 @@
+import type { CacheHandler, CacheHandlerContext, CacheHandlerGetMeta, CacheHandlerOptions, CacheHandlerValue, CacheValue } from "../types.js";
+export interface CompositeHandlerOptions extends CacheHandlerOptions {
+    /**
+     * Array of cache handlers to use (ordered by priority)
+     * First handler is checked first for reads
+     */
+    handlers: CacheHandler[];
+    /**
+     * Strategy function to determine which handler to use for set operations
+     * Returns the index of the handler to use
+     *
+     * @default - Write to all handlers
+     */
+    setStrategy?: (data: CacheHandlerValue) => number;
+}
+/**
+ * Composite cache handler that orchestrates multiple cache handlers
+ * Enables multi-tier caching strategies (e.g., memory -> Redis)
+ *
+ * Features:
+ * - First-match read strategy (fast fallback)
+ * - Configurable write strategy
+ * - Fault tolerance with Promise.allSettled()
+ * - Parallel revalidation across all handlers
+ *
+ * @example
+ * ```typescript
+ * // Memory + Redis two-tier cache
+ * const handler = createCompositeHandler({
+ *   handlers: [memoryHandler, redisHandler],
+ *   // Only cache small items in memory, everything in Redis
+ *   setStrategy: (data) => {
+ *     const size = JSON.stringify(data).length;
+ *     return size < 10000 ? 0 : 1; // 0 = memory, 1 = redis
+ *   }
+ * });
+ * ```
+ */
+export declare class CompositeHandler implements CacheHandler {
+    readonly name = "composite";
+    private readonly handlers;
+    private readonly setStrategy?;
+    constructor(options: CompositeHandlerOptions);
+    get(key: string, meta?: CacheHandlerGetMeta): Promise<CacheValue | null>;
+    set(key: string, value: CacheValue, context?: CacheHandlerContext): Promise<void>;
+    revalidateTag(tag: string, profile?: string | {
+        expire?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * Create a composite cache handler instance
+ *
+ * @example
+ * ```typescript
+ * // Route based on tags
+ * const handler = createCompositeHandler({
+ *   handlers: [memoryHandler, redisHandler],
+ *   setStrategy: (data) => {
+ *     // Use memory for items tagged with "memory-cache"
+ *     if (data.tags.includes("memory-cache")) {
+ *       return 0; // memory handler
+ *     }
+ *     return 1; // redis handler
+ *   }
+ * });
+ * ```
+ */
+export declare function createCompositeHandler(options: CompositeHandlerOptions): CompositeHandler;
+//# sourceMappingURL=composite.d.ts.map

package/dist/handlers/composite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../../src/handlers/composite.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,UAAU,EACX,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,uBAAwB,SAAQ,mBAAmB;IAClE;;;OAGG;IACH,QAAQ,EAAE,YAAY,EAAE,CAAC;IAEzB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,iBAAiB,KAAK,MAAM,CAAC;CACnD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,gBAAiB,YAAW,YAAY;IACnD,SAAgB,IAAI,eAAe;IAEnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAC1C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAsC;gBAEvD,OAAO,EAAE,uBAAuB;IAStC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAiBxE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BjF,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAcjF,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAezC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,gBAAgB,CAEzF"}

package/dist/handlers/composite.js

@@ -0,0 +1,123 @@
+/**
+ * Composite cache handler that orchestrates multiple cache handlers
+ * Enables multi-tier caching strategies (e.g., memory -> Redis)
+ *
+ * Features:
+ * - First-match read strategy (fast fallback)
+ * - Configurable write strategy
+ * - Fault tolerance with Promise.allSettled()
+ * - Parallel revalidation across all handlers
+ *
+ * @example
+ * ```typescript
+ * // Memory + Redis two-tier cache
+ * const handler = createCompositeHandler({
+ *   handlers: [memoryHandler, redisHandler],
+ *   // Only cache small items in memory, everything in Redis
+ *   setStrategy: (data) => {
+ *     const size = JSON.stringify(data).length;
+ *     return size < 10000 ? 0 : 1; // 0 = memory, 1 = redis
+ *   }
+ * });
+ * ```
+ */
+export class CompositeHandler {
+    name = "composite";
+    handlers;
+    setStrategy;
+    constructor(options) {
+        if (!options.handlers || options.handlers.length === 0) {
+            throw new Error("CompositeHandler requires at least one handler");
+        }
+        this.handlers = options.handlers;
+        this.setStrategy = options.setStrategy;
+    }
+    async get(key, meta) {
+        // Try handlers in order, return first hit
+        for (const handler of this.handlers) {
+            try {
+                const value = await handler.get(key, meta);
+                if (value !== null) {
+                    return value;
+                }
+            }
+            catch (error) {
+                // Log error but continue to next handler
+                console.error(`Handler ${handler.name} failed:`, error);
+            }
+        }
+        return null;
+    }
+    async set(key, value, context) {
+        // Build the full cache handler value for strategy function
+        const now = Date.now();
+        const cacheHandlerValue = {
+            lastModified: now,
+            lifespan: null, // Simplified - handlers will calculate their own
+            tags: context?.tags ?? [],
+            value,
+        };
+        // Determine which handler(s) to write to
+        if (this.setStrategy) {
+            const handlerIndex = this.setStrategy(cacheHandlerValue);
+            if (handlerIndex >= 0 && handlerIndex < this.handlers.length) {
+                await this.handlers[handlerIndex].set(key, value, context);
+            }
+        }
+        else {
+            // Default: write to all handlers with fault tolerance
+            const results = await Promise.allSettled(this.handlers.map((handler) => handler.set(key, value, context)));
+            // Log failures but don't throw (fault tolerance)
+            results.forEach((result, index) => {
+                if (result.status === "rejected") {
+                    console.error(`Handler ${this.handlers[index].name} set failed:`, result.reason);
+                }
+            });
+        }
+    }
+    async revalidateTag(tag, profile) {
+        // Revalidate on all handlers in parallel with fault tolerance
+        const results = await Promise.allSettled(this.handlers.map((handler) => handler.revalidateTag(tag, profile)));
+        // Log failures but don't throw
+        results.forEach((result, index) => {
+            if (result.status === "rejected") {
+                console.error(`Handler ${this.handlers[index].name} revalidateTag failed:`, result.reason);
+            }
+        });
+    }
+    async delete(key) {
+        // Delete from all handlers that support it
+        const deletePromises = this.handlers
+            .filter((handler) => typeof handler.delete === "function")
+            .map((handler) => handler.delete?.(key));
+        const results = await Promise.allSettled(deletePromises);
+        // Log failures but don't throw
+        results.forEach((result, index) => {
+            if (result.status === "rejected") {
+                console.error(`Handler ${this.handlers[index].name} delete failed:`, result.reason);
+            }
+        });
+    }
+}
+/**
+ * Create a composite cache handler instance
+ *
+ * @example
+ * ```typescript
+ * // Route based on tags
+ * const handler = createCompositeHandler({
+ *   handlers: [memoryHandler, redisHandler],
+ *   setStrategy: (data) => {
+ *     // Use memory for items tagged with "memory-cache"
+ *     if (data.tags.includes("memory-cache")) {
+ *       return 0; // memory handler
+ *     }
+ *     return 1; // redis handler
+ *   }
+ * });
+ * ```
+ */
+export function createCompositeHandler(options) {
+    return new CompositeHandler(options);
+}
+//# sourceMappingURL=composite.js.map

package/dist/handlers/composite.js.map

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

package/dist/handlers/memory.d.ts

@@ -0,0 +1,77 @@
+import type { CacheHandler, CacheHandlerContext, CacheHandlerGetMeta, CacheHandlerOptions, CacheValue } from "../types.js";
+export interface MemoryCacheHandlerOptions extends CacheHandlerOptions {
+    /**
+     * Maximum number of items to store (LRU eviction when exceeded)
+     * @default 1000
+     */
+    maxItemsNumber?: number;
+    /**
+     * Maximum size in bytes for a single item
+     * @default 104857600 (100MB)
+     */
+    maxItemSizeBytes?: number;
+    /**
+     * Default TTL in seconds for entries without explicit revalidate
+     * @default undefined (no expiration)
+     */
+    defaultTTL?: number;
+}
+/**
+ * In-memory LRU cache handler for Next.js 16+
+ * Suitable for development and single-instance deployments
+ *
+ * Features:
+ * - LRU eviction based on item count and size
+ * - Implicit tag tracking for ISR
+ * - Proper expiration handling
+ * - Tag-based revalidation
+ *
+ * @example
+ * ```typescript
+ * const handler = createMemoryCacheHandler({
+ *   maxItemsNumber: 1000,
+ *   maxItemSizeBytes: 100 * 1024 * 1024, // 100MB
+ *   defaultTTL: 3600 // 1 hour
+ * });
+ * ```
+ */
+export declare class MemoryCacheHandler implements CacheHandler {
+    readonly name = "local-lru";
+    private cache;
+    private revalidatedTags;
+    private readonly maxItemsNumber;
+    private readonly maxItemSizeBytes;
+    private readonly defaultTTL?;
+    constructor(options?: MemoryCacheHandlerOptions);
+    get(key: string, meta?: CacheHandlerGetMeta): Promise<CacheValue | null>;
+    set(key: string, value: CacheValue, context?: CacheHandlerContext): Promise<void>;
+    revalidateTag(tag: string, _profile?: string | {
+        expire?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+    /**
+     * Clear all cache entries (useful for testing)
+     */
+    clear(): Promise<void>;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        size: number;
+        maxSize: number;
+        revalidatedTags: number;
+    };
+}
+/**
+ * Create a memory cache handler instance
+ *
+ * @example
+ * ```typescript
+ * const handler = createMemoryCacheHandler({
+ *   maxItemsNumber: 500,
+ *   defaultTTL: 3600
+ * });
+ * ```
+ */
+export declare function createMemoryCacheHandler(options?: MemoryCacheHandlerOptions): MemoryCacheHandler;
+//# sourceMappingURL=memory.d.ts.map

package/dist/handlers/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/handlers/memory.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,YAAY,EACZ,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EAEnB,UAAU,EACX,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,yBAA0B,SAAQ,mBAAmB;IACpE;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,kBAAmB,YAAW,YAAY;IACrD,SAAgB,IAAI,eAAe;IAEnC,OAAO,CAAC,KAAK,CAAiC;IAC9C,OAAO,CAAC,eAAe,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAS;gBAEzB,OAAO,GAAE,yBAA8B;IAQ7C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAiCxE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAmCjF,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BlF,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B;;OAEG;IACH,QAAQ;;;;;CAOT;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,CAAC,EAAE,yBAAyB,GAAG,kBAAkB,CAEhG"}

package/dist/handlers/memory.js

@@ -0,0 +1,145 @@
+import { isImplicitTag } from "../helpers/is-implicit-tag.js";
+import { calculateLifespan, isExpired } from "../helpers/lifespan.js";
+/**
+ * In-memory LRU cache handler for Next.js 16+
+ * Suitable for development and single-instance deployments
+ *
+ * Features:
+ * - LRU eviction based on item count and size
+ * - Implicit tag tracking for ISR
+ * - Proper expiration handling
+ * - Tag-based revalidation
+ *
+ * @example
+ * ```typescript
+ * const handler = createMemoryCacheHandler({
+ *   maxItemsNumber: 1000,
+ *   maxItemSizeBytes: 100 * 1024 * 1024, // 100MB
+ *   defaultTTL: 3600 // 1 hour
+ * });
+ * ```
+ */
+export class MemoryCacheHandler {
+    name = "local-lru";
+    cache;
+    revalidatedTags; // tag -> timestamp (milliseconds)
+    maxItemsNumber;
+    maxItemSizeBytes;
+    defaultTTL;
+    constructor(options = {}) {
+        this.cache = new Map();
+        this.revalidatedTags = new Map();
+        this.maxItemsNumber = options.maxItemsNumber ?? 1000;
+        this.maxItemSizeBytes = options.maxItemSizeBytes ?? 104857600; // 100MB
+        this.defaultTTL = options.defaultTTL;
+    }
+    async get(key, meta) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return null;
+        }
+        // Check if expired based on lifespan
+        if (entry.lifespan && isExpired(entry.lifespan)) {
+            await this.delete(key);
+            return null;
+        }
+        // Check if any tag (explicit or implicit) has been revalidated
+        const allTags = [...entry.tags, ...(meta?.implicitTags ?? [])];
+        for (const tag of allTags) {
+            const revalidatedAt = this.revalidatedTags.get(tag);
+            // If tag was revalidated after entry was last modified, entry is stale
+            if (revalidatedAt && revalidatedAt > entry.lastModified) {
+                await this.delete(key);
+                return null;
+            }
+        }
+        // Move to end for LRU (delete and re-add)
+        this.cache.delete(key);
+        this.cache.set(key, entry);
+        return entry.value;
+    }
+    async set(key, value, context) {
+        // Calculate size of the entry
+        const size = JSON.stringify(value).length;
+        // Check if entry exceeds max size
+        if (size > this.maxItemSizeBytes) {
+            // Skip storing oversized entries
+            return;
+        }
+        // Enforce max items (LRU eviction)
+        if (this.cache.size >= this.maxItemsNumber) {
+            // Delete the oldest entry (first in Map)
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey) {
+                await this.delete(firstKey);
+            }
+        }
+        // Calculate lifespan
+        const lifespan = calculateLifespan(context?.revalidate, this.defaultTTL);
+        // Combine tags (explicit user tags only - implicit tags are passed in get())
+        const tags = context?.tags ?? [];
+        const entry = {
+            lastModified: Date.now(),
+            lifespan,
+            tags,
+            value,
+        };
+        this.cache.set(key, entry);
+    }
+    async revalidateTag(tag, _profile) {
+        // Store revalidation timestamp
+        // Note: profile parameter is used by Next.js for cache-life configuration
+        // but for memory handler we just invalidate immediately
+        this.revalidatedTags.set(tag, Date.now());
+        // For explicit tags (non-implicit), we can directly delete entries
+        if (!isImplicitTag(tag)) {
+            const keysToDelete = [];
+            for (const [key, entry] of this.cache.entries()) {
+                if (entry.tags.includes(tag)) {
+                    keysToDelete.push(key);
+                }
+            }
+            // Delete all entries with this tag
+            for (const key of keysToDelete) {
+                await this.delete(key);
+            }
+        }
+        // For implicit tags, we rely on the get() method to check revalidation
+        // This is because implicit tags are passed dynamically in meta.implicitTags
+    }
+    async delete(key) {
+        this.cache.delete(key);
+    }
+    /**
+     * Clear all cache entries (useful for testing)
+     */
+    async clear() {
+        this.cache.clear();
+        this.revalidatedTags.clear();
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        return {
+            size: this.cache.size,
+            maxSize: this.maxItemsNumber,
+            revalidatedTags: this.revalidatedTags.size,
+        };
+    }
+}
+/**
+ * Create a memory cache handler instance
+ *
+ * @example
+ * ```typescript
+ * const handler = createMemoryCacheHandler({
+ *   maxItemsNumber: 500,
+ *   defaultTTL: 3600
+ * });
+ * ```
+ */
+export function createMemoryCacheHandler(options) {
+    return new MemoryCacheHandler(options);
+}
+//# sourceMappingURL=memory.js.map

package/dist/handlers/memory.js.map

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

package/dist/handlers/redis.d.ts

@@ -0,0 +1,80 @@
+import { type RedisOptions } from "ioredis";
+import type { CacheHandler, CacheHandlerContext, CacheHandlerGetMeta, CacheHandlerOptions, CacheValue } from "../types.js";
+export interface RedisCacheHandlerOptions extends CacheHandlerOptions {
+    /**
+     * Redis connection options (ioredis)
+     * Can be a URL string or RedisOptions object
+     */
+    redis?: string | RedisOptions;
+    /**
+     * Key prefix for all cache entries
+     * @default "nextjs:cache:"
+     */
+    keyPrefix?: string;
+    /**
+     * Key prefix for tag tracking
+     * @default "nextjs:tags:"
+     */
+    tagPrefix?: string;
+    /**
+     * Default TTL in seconds for entries without explicit revalidate
+     * @default undefined (no expiration)
+     */
+    defaultTTL?: number;
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Redis cache handler for Next.js 16+ with Cache Components support
+ *
+ * Features:
+ * - Persistent caching across server restarts
+ * - Tag-based revalidation with Redis Sets
+ * - TTL support with automatic expiration
+ * - Compatible with Redis, ElastiCache, and Valkey
+ * - Connection pooling via ioredis
+ *
+ * @example
+ * ```typescript
+ * // In cache-handler.mjs or data-cache-handler.mjs
+ * import { RedisCacheHandler } from "@mrjasonroy/cache-components-cache-handler/handlers/redis";
+ *
+ * export default class NextCacheHandler extends RedisCacheHandler {
+ *   constructor(options) {
+ *     super({
+ *       ...options,
+ *       redis: process.env.REDIS_URL || "redis://localhost:6379",
+ *       keyPrefix: "nextjs:cache:",
+ *       defaultTTL: 3600
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export declare class RedisCacheHandler implements CacheHandler {
+    readonly name = "redis";
+    private redis;
+    private readonly keyPrefix;
+    private readonly tagPrefix;
+    private readonly defaultTTL?;
+    private readonly debug;
+    constructor(options?: RedisCacheHandlerOptions);
+    private log;
+    private getCacheKey;
+    private getTagKey;
+    get(key: string, meta?: CacheHandlerGetMeta): Promise<CacheValue | null>;
+    set(key: string, value: CacheValue, context?: CacheHandlerContext): Promise<void>;
+    revalidateTag(tag: string, _profile?: string | {
+        expire?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+    /**
+     * Close the Redis connection
+     * Call this when shutting down your application
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=redis.d.ts.map

package/dist/handlers/redis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.d.ts","sourceRoot":"","sources":["../../src/handlers/redis.ts"],"names":[],"mappings":"AAAA,OAAc,EAAE,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAEnD,OAAO,KAAK,EACV,YAAY,EACZ,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EAEnB,UAAU,EACX,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,wBAAyB,SAAQ,mBAAmB;IACnE;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;IAE9B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,iBAAkB,YAAW,YAAY;IACpD,SAAgB,IAAI,WAAW;IAE/B,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;gBAEpB,OAAO,GAAE,wBAA6B;IA2BlD,OAAO,CAAC,GAAG;IAMX,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,SAAS;IAIX,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IA8CxE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IA2DjF,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA8BlF,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUxC;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAQ7B"}