swimple 0.6.0 → 0.8.0

package/helpers.js

@@ -5,8 +5,7 @@
 /// <reference no-default-lib="true"/>
 /// <reference lib="esnext" />
 /// <reference lib="webworker" />
-
-/** @import { CacheStrategy, HandleRequestConfig, LoggingLevel } from "./types" */
+/// <reference path="./types.js" />
 
 import {
   CACHE_TIMESTAMP_HEADER,

package/index.d.ts

@@ -1,13 +1,242 @@
 /// <reference no-default-lib="true"/>
 /**
- * Creates a request handler function for service worker fetch events.
- * The handler implements HTTP caching with configurable strategies (cache-first, network-first, stale-while-revalidate),
- * automatic cache invalidation for mutations, and periodic cache cleanup. Only handles same-origin GET requests
- * that match the configured scope.
- *
- * @param {HandleRequestConfig} config - Configuration options including cache name, scope, default strategy, and TTL settings
- * @returns {(event: FetchEvent) => Promise<Response> | null} Request handler function that can be used in service worker fetch event listeners
+ * Caching strategy for handling requests.
+ * - `cache-first`: Return from cache if fresh (within TTL), otherwise fetch from network immediately. Stale cache is only used when offline (network request fails). No background updates.
+ * - `network-first`: Try network first, fall back to stale cache if offline (within stale TTL). Cache updated when network succeeds.
+ * - `stale-while-revalidate`: Return from cache immediately (fresh = no update, stale = update in background). Fetch from network if too stale or missing.
  */
-export function createHandleRequest(config: HandleRequestConfig): (event: FetchEvent) => Promise<Response> | null;
-export { cleanupOldCacheEntries } from "./helpers.js";
-import type { HandleRequestConfig } from "./types";
+type CacheStrategy = "cache-first" | "network-first" | "stale-while-revalidate";
+/**
+ * Logging level for cache operations.
+ * - `none`: No logging
+ * - `minimal`: Logs cache hits and cache invalidation only
+ * - `verbose`: Logs all events including cache misses, cleanup, and header usage
+ */
+type LoggingLevel = "none" | "minimal" | "verbose";
+type HandleRequestConfig = {
+    /**
+     * - Name of the cache, used when calling `Cache.open(cacheName)` internally. Changing this name effectively clears the previous cache entries.
+     */
+    cacheName: string;
+    /**
+     * - URL prefixes to cache by default (e.g., `['/api/']`). If not set and `defaultTTLSeconds` is set, all same-origin GET requests are cached automatically. If not set and `defaultTTLSeconds` is not set (or 0), no requests are cached by default. Individual requests outside the scope can still enable caching with `X-SW-Cache-TTL-Seconds` header. Note: Cross-origin requests are never cached, regardless of scope or TTL headers.
+     */
+    scope?: string[];
+    /**
+     * - Default caching strategy: `'cache-first'`, `'network-first'`, or `'stale-while-revalidate'`.
+     */
+    defaultStrategy?: CacheStrategy;
+    /**
+     * - Maximum age for fresh content. Fresh content will be returned from cache for cache-first and stale-while-revalidate strategies, and also from network-first when offline. Fresh content does not get updated from the network. Since this defaults to `300`, caching is automatic by default for GET requests matching the scope. Set to `0` or `undefined` to disable automatic caching (individual requests can still enable caching with `X-SW-Cache-TTL-Seconds` header).
+     */
+    defaultTTLSeconds?: number;
+    /**
+     * - Maximum age for stale content. Stale content will be returned from cache for cache-first (when offline), network-first (when offline), and stale-while-revalidate strategies. That means responses past the fresh TTL but within stale TTL can still be returned from cache. Stale content does get updated from the network.
+     */
+    defaultStaleTTLSeconds?: number;
+    /**
+     * - Automatically invalidate cache on POST/PATCH/PUT/DELETE requests.
+     */
+    inferInvalidation?: boolean;
+    /**
+     * - Custom fetch function to use for network requests. Receives a `Request` object and must return a `Promise<Response>`. Useful for handling authentication errors (401/403) or adding custom headers to all requests.
+     */
+    customFetch?: typeof fetch;
+    /**
+     * - Maximum age (in seconds) before cache entries are automatically cleaned up. Entries older than this age are deleted. Defaults to 7200 seconds (2 hours, which is 2x the default stale TTL). Cache entries are cleaned up reactively (when accessed) and periodically (every 100 fetches).
+     */
+    maxCacheAgeSeconds?: number;
+    /**
+     * - Logging level: "none" (no logging), "minimal" (cache hits and invalidation only), or "verbose" (all logging including misses, cleanup, and headers). Defaults to "none".
+     */
+    loggingLevel?: LoggingLevel;
+};
+declare module "headers" {
+    /**
+     * Header constants used by swimple for cache control.
+     * These constants can be imported in non-service-worker code to set headers on requests.
+     *
+     * @example
+     * // Node.js / npm import
+     * import { CACHE_STRATEGY_HEADER, CACHE_TTL_HEADER } from "swimple/headers";
+     *
+     * @example
+     * // CDN import
+     * import { CACHE_STRATEGY_HEADER, CACHE_TTL_HEADER } from "https://cdn.jsdelivr.net/npm/swimple@1.0.0/headers.js";
+     */
+    /**
+     * Header name for overriding the caching strategy for a specific request.
+     * Values: "cache-first", "network-first", or "stale-while-revalidate"
+     */
+    export const CACHE_STRATEGY_HEADER: "X-SW-Cache-Strategy";
+    /**
+     * Header name for setting the time-to-live (in seconds) for a cached response.
+     * Set to "0" to completely opt out of caching for a specific request.
+     */
+    export const CACHE_TTL_HEADER: "X-SW-Cache-TTL-Seconds";
+    /**
+     * Header name for setting the stale time-to-live (in seconds) for a cached response.
+     * Used by cache-first (when offline), network-first (when offline), and stale-while-revalidate strategies.
+     */
+    export const CACHE_STALE_TTL_HEADER: "X-SW-Cache-Stale-TTL-Seconds";
+    /**
+     * Header name for explicitly invalidating specific cache entries.
+     * Can be set multiple times to invalidate multiple paths.
+     */
+    export const CACHE_INVALIDATE_HEADER: "X-SW-Cache-Invalidate";
+    /**
+     * Header name for clearing the entire cache.
+     * Any value works - the header's presence triggers cache clearing.
+     */
+    export const CACHE_CLEAR_HEADER: "X-SW-Cache-Clear";
+    /**
+     * Internal header name used to store the cache timestamp in cached responses.
+     * This header is set automatically by the library and should not be set manually.
+     */
+    export const CACHE_TIMESTAMP_HEADER: "x-sw-cache-timestamp";
+}
+declare module "helpers" {
+    /**
+     * Set the logging level
+     * @param {LoggingLevel} level - Logging level: "none", "minimal", or "verbose"
+     */
+    export function setLoggingLevel(level: LoggingLevel): void;
+    /**
+     * Get header value (case-insensitive)
+     * @param {Headers} headers
+     * @param {string} name
+     * @returns {string | null}
+     */
+    export function getHeader(headers: Headers, name: string): string | null;
+    /**
+     * Get all header values for a given header name (case-insensitive)
+     * Useful when a header has been set multiple times (e.g., multiple X-SW-Cache-Invalidate headers)
+     * When headers are set multiple times with append(), they are concatenated with ", " (comma+space)
+     * This function splits them back into individual values
+     * @param {Headers} headers
+     * @param {string} name - Header name to look up
+     * @returns {string[]} Array of all header values for the given name
+     */
+    export function getAllHeaders(headers: Headers, name: string): string[];
+    /**
+     * Get cache timestamp from response
+     * @param {Response} response
+     * @returns {number | null} Timestamp in milliseconds since epoch, or null if not found
+     */
+    export function getCacheTimestamp(response: Response): number | null;
+    /**
+     * Check if response is fresh
+     * @param {Response} response
+     * @param {number} ttl - Time-to-live in seconds
+     * @returns {boolean}
+     */
+    export function isFresh(response: Response, ttl: number): boolean;
+    /**
+     * Check if response is stale (but usable)
+     * @param {Response} response
+     * @param {number} ttl - Time-to-live in seconds
+     * @param {number | null} staleTTL - Stale time-to-live in seconds
+     * @returns {boolean}
+     */
+    export function isStale(response: Response, ttl: number, staleTTL: number | null): boolean;
+    /**
+     * Add timestamp to response
+     * @param {Response} response
+     * @returns {Response}
+     */
+    export function addTimestamp(response: Response): Response;
+    /**
+     * Get inferred invalidation paths
+     * @param {string} url
+     * @returns {string[]}
+     */
+    export function getInferredInvalidationPaths(url: string): string[];
+    /**
+     * Get strategy from request headers or use default
+     * @param {Headers} headers
+     * @param {CacheStrategy} defaultStrategy
+     * @param {string} url - Request URL for logging
+     * @returns {CacheStrategy}
+     */
+    export function getStrategy(headers: Headers, defaultStrategy: CacheStrategy, url?: string): CacheStrategy;
+    /**
+     * Get TTL from request headers or use default
+     * @param {Headers} headers
+     * @param {number} defaultTTL - Default TTL in seconds
+     * @param {string} url - Request URL for logging
+     * @returns {number | null} TTL in seconds, or null if caching is disabled
+     */
+    export function getTTL(headers: Headers, defaultTTL: number, url?: string): number | null;
+    /**
+     * Get stale TTL from request headers or use default
+     * @param {Headers} headers
+     * @param {number} defaultStaleTTL - Default stale TTL in seconds
+     * @param {string} url - Request URL for logging
+     * @returns {number | null} Stale TTL in seconds, or null if stale caching is disabled
+     */
+    export function getStaleTTL(headers: Headers, defaultStaleTTL: number, url?: string): number | null;
+    /**
+     * Check if URL matches scope.  Returns true if scope array is empty or if the URL pathname starts with any of the scope prefixes.
+     * @param {string} url
+     * @param {string[]} scope
+     * @param {number} defaultTTLSeconds
+     * @returns {boolean}
+     */
+    export function matchesScope(url: string, scope: string[], defaultTTLSeconds: number): boolean;
+    /**
+     * Invalidate cache entries
+     * @param {string} cacheName
+     * @param {string[]} urls
+     * @returns {Promise<void>}
+     */
+    export function invalidateCache(cacheName: string, urls: string[]): Promise<void>;
+    /**
+     * Clear entire cache
+     * @param {string} cacheName
+     * @returns {Promise<void>}
+     */
+    export function clearCache(cacheName: string): Promise<void>;
+    /**
+     * Check if a cached response is older than the maximum age
+     * @param {Response} response
+     * @param {number} maxAgeSeconds - Maximum age in seconds
+     * @returns {boolean}
+     */
+    export function isOlderThanMaxAge(response: Response, maxAgeSeconds: number): boolean;
+    /**
+     * Clean up cache entries older than maxAgeSeconds
+     * @param {string} cacheName
+     * @param {number} maxAgeSeconds - Maximum age in seconds
+     * @returns {Promise<void>}
+     */
+    export function cleanupOldCacheEntries(cacheName: string, maxAgeSeconds: number): Promise<void>;
+    /**
+     * Log an informational message (minimal and verbose levels)
+     * @param {string} message - Message to log
+     */
+    export function logInfo(message: string): void;
+    /**
+     * Log a verbose message (verbose level only)
+     * @param {string} message - Message to log
+     */
+    export function logVerbose(message: string): void;
+    /**
+     * Validate configuration object
+     * @param {HandleRequestConfig} config - Configuration object to validate
+     * @throws {Error} If config is invalid
+     */
+    export function validateConfig(config: HandleRequestConfig): void;
+}
+declare module "index" {
+    /**
+     * Creates a request handler function for service worker fetch events.
+     * The handler implements HTTP caching with configurable strategies (cache-first, network-first, stale-while-revalidate),
+     * automatic cache invalidation for mutations, and periodic cache cleanup. Only handles same-origin GET requests
+     * that match the configured scope.
+     *
+     * @param {HandleRequestConfig} config - Configuration options including cache name, scope, default strategy, and TTL settings
+     * @returns {(event: FetchEvent) => Promise<Response> | null} Request handler function that can be used in service worker fetch event listeners
+     */
+    export function createHandleRequest(config: HandleRequestConfig): (event: FetchEvent) => Promise<Response> | null;
+    export { cleanupOldCacheEntries } from "./helpers.js";
+}

package/index.js

@@ -5,8 +5,7 @@
 /// <reference no-default-lib="true"/>
 /// <reference lib="esnext" />
 /// <reference lib="webworker" />
-
-/** @import { HandleRequestConfig, CacheStrategy } from "./types" */
+/// <reference path="./types.js" />
 
 import {
   getHeader,

package/package.json

@@ -1,16 +1,17 @@
 {
   "name": "swimple",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "A simple service worker library for request caching",
   "type": "module",
   "main": "index.js",
+  "types": "./index.d.ts",
   "exports": {
     ".": {
       "types": "./index.d.ts",
       "default": "./index.js"
     },
     "./headers": {
-      "types": "./headers.d.ts",
+      "types": "./index.d.ts",
       "default": "./headers.js"
     }
   },
@@ -21,7 +22,7 @@
     "test:ui": "playwright test",
     "format:check": "prettier --check .",
     "format:fix": "prettier --write .",
-    "prepublishOnly": "tsc --allowJs --declaration --emitDeclarationOnly --outDir ./ --skipLibCheck --target es2022 --module es2022 --moduleResolution node index.js headers.js helpers.js"
+    "prepublishOnly": "tsc index.js headers.js helpers.js --declaration --allowJs --emitDeclarationOnly --outfile index.d.ts --target esnext"
   },
   "keywords": [
     "service-worker",

package/types.js

@@ -0,0 +1,30 @@
+// @ts-check
+
+/**
+ * Caching strategy for handling requests.
+ * - `cache-first`: Return from cache if fresh (within TTL), otherwise fetch from network immediately. Stale cache is only used when offline (network request fails). No background updates.
+ * - `network-first`: Try network first, fall back to stale cache if offline (within stale TTL). Cache updated when network succeeds.
+ * - `stale-while-revalidate`: Return from cache immediately (fresh = no update, stale = update in background). Fetch from network if too stale or missing.
+ * @typedef {"cache-first" | "network-first" | "stale-while-revalidate"} CacheStrategy
+ */
+
+/**
+ * Logging level for cache operations.
+ * - `none`: No logging
+ * - `minimal`: Logs cache hits and cache invalidation only
+ * - `verbose`: Logs all events including cache misses, cleanup, and header usage
+ * @typedef {"none" | "minimal" | "verbose"} LoggingLevel
+ */
+
+/**
+ * @typedef HandleRequestConfig
+ * @property {string} cacheName - Name of the cache, used when calling `Cache.open(cacheName)` internally. Changing this name effectively clears the previous cache entries.
+ * @property {string[]} [scope] - URL prefixes to cache by default (e.g., `['/api/']`). If not set and `defaultTTLSeconds` is set, all same-origin GET requests are cached automatically. If not set and `defaultTTLSeconds` is not set (or 0), no requests are cached by default. Individual requests outside the scope can still enable caching with `X-SW-Cache-TTL-Seconds` header. Note: Cross-origin requests are never cached, regardless of scope or TTL headers.
+ * @property {CacheStrategy} [defaultStrategy] - Default caching strategy: `'cache-first'`, `'network-first'`, or `'stale-while-revalidate'`.
+ * @property {number} [defaultTTLSeconds] - Maximum age for fresh content. Fresh content will be returned from cache for cache-first and stale-while-revalidate strategies, and also from network-first when offline. Fresh content does not get updated from the network. Since this defaults to `300`, caching is automatic by default for GET requests matching the scope. Set to `0` or `undefined` to disable automatic caching (individual requests can still enable caching with `X-SW-Cache-TTL-Seconds` header).
+ * @property {number} [defaultStaleTTLSeconds] - Maximum age for stale content. Stale content will be returned from cache for cache-first (when offline), network-first (when offline), and stale-while-revalidate strategies. That means responses past the fresh TTL but within stale TTL can still be returned from cache. Stale content does get updated from the network.
+ * @property {boolean} [inferInvalidation] - Automatically invalidate cache on POST/PATCH/PUT/DELETE requests.
+ * @property {typeof fetch} [customFetch] - Custom fetch function to use for network requests. Receives a `Request` object and must return a `Promise<Response>`. Useful for handling authentication errors (401/403) or adding custom headers to all requests.
+ * @property {number} [maxCacheAgeSeconds] - Maximum age (in seconds) before cache entries are automatically cleaned up. Entries older than this age are deleted. Defaults to 7200 seconds (2 hours, which is 2x the default stale TTL). Cache entries are cleaned up reactively (when accessed) and periodically (every 100 fetches).
+ * @property {LoggingLevel} [loggingLevel] - Logging level: "none" (no logging), "minimal" (cache hits and invalidation only), or "verbose" (all logging including misses, cleanup, and headers). Defaults to "none".
+ */

package/headers.d.ts

@@ -1,42 +0,0 @@
-/**
- * Header constants used by swimple for cache control.
- * These constants can be imported in non-service-worker code to set headers on requests.
- *
- * @example
- * // Node.js / npm import
- * import { CACHE_STRATEGY_HEADER, CACHE_TTL_HEADER } from "swimple/headers";
- *
- * @example
- * // CDN import
- * import { CACHE_STRATEGY_HEADER, CACHE_TTL_HEADER } from "https://cdn.jsdelivr.net/npm/swimple@1.0.0/headers.js";
- */
-/**
- * Header name for overriding the caching strategy for a specific request.
- * Values: "cache-first", "network-first", or "stale-while-revalidate"
- */
-export const CACHE_STRATEGY_HEADER: "X-SW-Cache-Strategy";
-/**
- * Header name for setting the time-to-live (in seconds) for a cached response.
- * Set to "0" to completely opt out of caching for a specific request.
- */
-export const CACHE_TTL_HEADER: "X-SW-Cache-TTL-Seconds";
-/**
- * Header name for setting the stale time-to-live (in seconds) for a cached response.
- * Used by cache-first (when offline), network-first (when offline), and stale-while-revalidate strategies.
- */
-export const CACHE_STALE_TTL_HEADER: "X-SW-Cache-Stale-TTL-Seconds";
-/**
- * Header name for explicitly invalidating specific cache entries.
- * Can be set multiple times to invalidate multiple paths.
- */
-export const CACHE_INVALIDATE_HEADER: "X-SW-Cache-Invalidate";
-/**
- * Header name for clearing the entire cache.
- * Any value works - the header's presence triggers cache clearing.
- */
-export const CACHE_CLEAR_HEADER: "X-SW-Cache-Clear";
-/**
- * Internal header name used to store the cache timestamp in cached responses.
- * This header is set automatically by the library and should not be set manually.
- */
-export const CACHE_TIMESTAMP_HEADER: "x-sw-cache-timestamp";

package/helpers.d.ts

@@ -1,134 +0,0 @@
-/// <reference no-default-lib="true"/>
-/**
- * Set the logging level
- * @param {LoggingLevel} level - Logging level: "none", "minimal", or "verbose"
- */
-export function setLoggingLevel(level: LoggingLevel): void;
-/**
- * Get header value (case-insensitive)
- * @param {Headers} headers
- * @param {string} name
- * @returns {string | null}
- */
-export function getHeader(headers: Headers, name: string): string | null;
-/**
- * Get all header values for a given header name (case-insensitive)
- * Useful when a header has been set multiple times (e.g., multiple X-SW-Cache-Invalidate headers)
- * When headers are set multiple times with append(), they are concatenated with ", " (comma+space)
- * This function splits them back into individual values
- * @param {Headers} headers
- * @param {string} name - Header name to look up
- * @returns {string[]} Array of all header values for the given name
- */
-export function getAllHeaders(headers: Headers, name: string): string[];
-/**
- * Get cache timestamp from response
- * @param {Response} response
- * @returns {number | null} Timestamp in milliseconds since epoch, or null if not found
- */
-export function getCacheTimestamp(response: Response): number | null;
-/**
- * Check if response is fresh
- * @param {Response} response
- * @param {number} ttl - Time-to-live in seconds
- * @returns {boolean}
- */
-export function isFresh(response: Response, ttl: number): boolean;
-/**
- * Check if response is stale (but usable)
- * @param {Response} response
- * @param {number} ttl - Time-to-live in seconds
- * @param {number | null} staleTTL - Stale time-to-live in seconds
- * @returns {boolean}
- */
-export function isStale(response: Response, ttl: number, staleTTL: number | null): boolean;
-/**
- * Add timestamp to response
- * @param {Response} response
- * @returns {Response}
- */
-export function addTimestamp(response: Response): Response;
-/**
- * Get inferred invalidation paths
- * @param {string} url
- * @returns {string[]}
- */
-export function getInferredInvalidationPaths(url: string): string[];
-/**
- * Get strategy from request headers or use default
- * @param {Headers} headers
- * @param {CacheStrategy} defaultStrategy
- * @param {string} url - Request URL for logging
- * @returns {CacheStrategy}
- */
-export function getStrategy(headers: Headers, defaultStrategy: CacheStrategy, url?: string): CacheStrategy;
-/**
- * Get TTL from request headers or use default
- * @param {Headers} headers
- * @param {number} defaultTTL - Default TTL in seconds
- * @param {string} url - Request URL for logging
- * @returns {number | null} TTL in seconds, or null if caching is disabled
- */
-export function getTTL(headers: Headers, defaultTTL: number, url?: string): number | null;
-/**
- * Get stale TTL from request headers or use default
- * @param {Headers} headers
- * @param {number} defaultStaleTTL - Default stale TTL in seconds
- * @param {string} url - Request URL for logging
- * @returns {number | null} Stale TTL in seconds, or null if stale caching is disabled
- */
-export function getStaleTTL(headers: Headers, defaultStaleTTL: number, url?: string): number | null;
-/**
- * Check if URL matches scope.  Returns true if scope array is empty or if the URL pathname starts with any of the scope prefixes.
- * @param {string} url
- * @param {string[]} scope
- * @param {number} defaultTTLSeconds
- * @returns {boolean}
- */
-export function matchesScope(url: string, scope: string[], defaultTTLSeconds: number): boolean;
-/**
- * Invalidate cache entries
- * @param {string} cacheName
- * @param {string[]} urls
- * @returns {Promise<void>}
- */
-export function invalidateCache(cacheName: string, urls: string[]): Promise<void>;
-/**
- * Clear entire cache
- * @param {string} cacheName
- * @returns {Promise<void>}
- */
-export function clearCache(cacheName: string): Promise<void>;
-/**
- * Check if a cached response is older than the maximum age
- * @param {Response} response
- * @param {number} maxAgeSeconds - Maximum age in seconds
- * @returns {boolean}
- */
-export function isOlderThanMaxAge(response: Response, maxAgeSeconds: number): boolean;
-/**
- * Clean up cache entries older than maxAgeSeconds
- * @param {string} cacheName
- * @param {number} maxAgeSeconds - Maximum age in seconds
- * @returns {Promise<void>}
- */
-export function cleanupOldCacheEntries(cacheName: string, maxAgeSeconds: number): Promise<void>;
-/**
- * Log an informational message (minimal and verbose levels)
- * @param {string} message - Message to log
- */
-export function logInfo(message: string): void;
-/**
- * Log a verbose message (verbose level only)
- * @param {string} message - Message to log
- */
-export function logVerbose(message: string): void;
-/**
- * Validate configuration object
- * @param {HandleRequestConfig} config - Configuration object to validate
- * @throws {Error} If config is invalid
- */
-export function validateConfig(config: HandleRequestConfig): void;
-import type { LoggingLevel } from "./types";
-import type { CacheStrategy } from "./types";
-import type { HandleRequestConfig } from "./types";

package/types.d.ts

@@ -1,41 +0,0 @@
-// NOTE: this is the only .d.ts file that is checked in, other declaration files are generated as part of the prepublishOnly script.
-
-/**
- * Caching strategy for handling requests.
- * - `cache-first`: Return from cache if fresh (within TTL), otherwise fetch from network immediately. Stale cache is only used when offline (network request fails). No background updates.
- * - `network-first`: Try network first, fall back to stale cache if offline (within stale TTL). Cache updated when network succeeds.
- * - `stale-while-revalidate`: Return from cache immediately (fresh = no update, stale = update in background). Fetch from network if too stale or missing.
- */
-export type CacheStrategy =
-  | "cache-first"
-  | "network-first"
-  | "stale-while-revalidate";
-
-/**
- * Logging level for cache operations.
- * - `none`: No logging
- * - `minimal`: Logs cache hits and cache invalidation only
- * - `verbose`: Logs all events including cache misses, cleanup, and header usage
- */
-export type LoggingLevel = "none" | "minimal" | "verbose";
-
-export interface HandleRequestConfig {
-  /** Name of the cache, used when calling `Cache.open(cacheName)` internally. Changing this name effectively clears the previous cache entries. */
-  cacheName: string;
-  /** URL prefixes to cache by default (e.g., `['/api/']`). If not set and `defaultTTLSeconds` is set, all same-origin GET requests are cached automatically. If not set and `defaultTTLSeconds` is not set (or 0), no requests are cached by default. Individual requests outside the scope can still enable caching with `X-SW-Cache-TTL-Seconds` header. Note: Cross-origin requests are never cached, regardless of scope or TTL headers. */
-  scope?: string[];
-  /** Default caching strategy: `'cache-first'`, `'network-first'`, or `'stale-while-revalidate'`. */
-  defaultStrategy?: CacheStrategy;
-  /** Maximum age for fresh content. Fresh content will be returned from cache for cache-first and stale-while-revalidate strategies, and also from network-first when offline. Fresh content does not get updated from the network. Since this defaults to `300`, caching is automatic by default for GET requests matching the scope. Set to `0` or `undefined` to disable automatic caching (individual requests can still enable caching with `X-SW-Cache-TTL-Seconds` header). */
-  defaultTTLSeconds?: number;
-  /** Maximum age for stale content. Stale content will be returned from cache for cache-first (when offline), network-first (when offline), and stale-while-revalidate strategies. That means responses past the fresh TTL but within stale TTL can still be returned from cache. Stale content does get updated from the network. */
-  defaultStaleTTLSeconds?: number;
-  /** Automatically invalidate cache on POST/PATCH/PUT/DELETE requests. */
-  inferInvalidation?: boolean;
-  /** Custom fetch function to use for network requests. Receives a `Request` object and must return a `Promise<Response>`. Useful for handling authentication errors (401/403) or adding custom headers to all requests. */
-  customFetch?: typeof fetch;
-  /** Maximum age (in seconds) before cache entries are automatically cleaned up. Entries older than this age are deleted. Defaults to 7200 seconds (2 hours, which is 2x the default stale TTL). Cache entries are cleaned up reactively (when accessed) and periodically (every 100 fetches). */
-  maxCacheAgeSeconds?: number;
-  /** Logging level: "none" (no logging), "minimal" (cache hits and invalidation only), or "verbose" (all logging including misses, cleanup, and headers). Defaults to "none". */
-  loggingLevel?: LoggingLevel;
-}