Cache Expiration Management

/**
 * Allows you define an expiration and/or limit on the number of responses stored in a Cache
 */
class CacheExpiration {
  /**
   * Constructs a new CacheExpiration instance. At least one of maxEntries or maxAgeSeconds must be provided.
   * @param cacheName - Name of the cache to apply restrictions to
   * @param config - Configuration options for cache expiration
   */
  constructor(cacheName: string, config: CacheExpirationConfig = {});

  /**
   * Expires entries for the given cache based on the configured criteria.
   * Removes entries that exceed maxEntries (LRU) or are older than maxAgeSeconds.
   */
  expireEntries(): Promise<void>;

  /**
   * Updates the timestamp for the given URL to ensure accurate LRU tracking
   * and expiration calculations. Call this when a cached response is used.
   * @param url - The URL to update the timestamp for
   */
  updateTimestamp(url: string): Promise<void>;

  /**
   * Checks if a URL has expired based on maxAgeSeconds configuration.
   * Performs IndexedDB lookup so can be slow.
   * Note: This method will not remove the cached entry.
   * @param url - The URL to check for expiration
   * @returns true if the URL has expired, false otherwise
   */
  isURLExpired(url: string): Promise<boolean>;

  /**
   * Removes the IndexedDB object store used to keep track of cache expiration metadata.
   * Call this when you no longer need expiration tracking for this cache.
   */
  delete(): Promise<void>;
}

interface CacheExpirationConfig {
  /** Maximum number of entries to cache. Entries used least recently will be removed first. */
  maxEntries?: number;
  /** Maximum age of an entry in seconds before it's treated as stale and removed. */
  maxAgeSeconds?: number;
  /** CacheQueryOptions that will be used when calling delete() on the cache. */
  matchOptions?: CacheQueryOptions;
}

import { CacheExpiration } from "workbox-expiration";

// Create cache expiration with entry limit
const cacheExpiration = new CacheExpiration("api-responses", {
  maxEntries: 50,
});

// Create cache expiration with age limit
const timeLimitedCache = new CacheExpiration("temp-data", {
  maxAgeSeconds: 60 * 60, // 1 hour
});

// Combined limits
const restrictedCache = new CacheExpiration("restricted-cache", {
  maxEntries: 100,
  maxAgeSeconds: 60 * 60 * 24, // 24 hours
  matchOptions: { ignoreSearch: true },
});

// Manual expiration
await cacheExpiration.expireEntries();

// Update timestamp when using a cached response
await cacheExpiration.updateTimestamp("https://api.example.com/data");

// Check if URL is expired before using
const expired = await cacheExpiration.isURLExpired("https://api.example.com/data");
if (!expired) {
  // Use cached response
}

// Clean up when done
await cacheExpiration.delete();