swimple 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wes@goulet.dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,714 @@
+# swimple
+
+A simple service worker library for request caching.
+
+## Features
+
+- ⚡ **Low Configuration**: Request caching with automatic invalidation by default - minimal setup required
+- 🔄 **Smart Invalidation**: Automatically invalidate cache on mutations (POST/PATCH/PUT/DELETE)
+- 🎛️ **Flexible Strategies**: Support for cache-first, network-first, and stale-while-revalidate
+- 🪶 **Lightweight**: Single-purpose library with no dependencies
+- 🚀 **Modern**: Designed for ES module service workers (supported by all modern browsers as of January 2026)
+- 🔧 **Configurable**: Automatic caching by default, with per-request control
+
+## Installation
+
+### Direct CDN Import (Recommended)
+
+```javascript
+// sw.js
+import { createHandleRequest } from "https://cdn.jsdelivr.net/npm/swimple@1.0.0/index.js";
+```
+
+### NPM Install
+
+```bash
+npm install swimple
+```
+
+```javascript
+// sw.js
+import { createHandleRequest } from "swimple";
+```
+
+## Quick Start
+
+> NOTE: This documentation focuses on modern browsers with module service workers support. If you aren't using module service workers, you can probably still use this with `importScripts` but I'll leave that to you to figure out.
+
+### 1. Register Your Service Worker
+
+```javascript
+// in javascript in index.html (or app.js or main.js or whatever frameworks use nowadays)
+try {
+  await navigator.serviceWorker.register("/sw.js", { type: "module" });
+} catch (error) {
+  console.error("Error registering module service worker:", error);
+}
+```
+
+### 2. Set Up Request Handler in Service Worker
+
+```javascript
+// sw.js
+import { createHandleRequest } from "https://cdn.jsdelivr.net/npm/swimple@1.0.0/index.js";
+
+// create the request handler
+const handleRequest = createHandleRequest({
+  cacheName: "api-cache-v1",
+  scope: ["/api/"] // this means only GET requests that start with /api/ will be cached
+});
+
+self.addEventListener("fetch", (event) => {
+  const response = handleRequest(event);
+
+  if (response) {
+    event.respondWith(response);
+    return;
+  }
+
+  // fall through to other logic or just let the request go to network by doing nothing
+  return;
+});
+```
+
+That's it! Your service worker will now cache GET requests that start with `/api/` using the default TTL of 300 seconds. Subsequent requests to the same path will return from the cache if the response is fresh (within the TTL). Any mutations (POST/PATCH/PUT/DELETE) will invalidate the cache. For example a PATCH request to `/api/users/123` will invalidate the cache for `/api/users/123` (ie: the details of that user) and `/api/users` (ie: the list of users that likely includes that user).
+
+Any requests outside the scope (ie: not starting with `/api/`) won't be processed by the cache handler (it will return null).
+
+## Configuring the request handler
+
+If you want to use different defaults for all requests, you can pass in a config object to the `createHandleRequest` function.
+
+### Example 1: Network-First Strategy
+
+```javascript
+const handleRequest = createHandleRequest({
+  cacheName: "api-cache-v1",
+  scope: ["/api/"],
+  defaultStrategy: "network-first"
+});
+```
+
+With network-first, requests always try the network first (even if cached and fresh). If the network fails and you're offline, it will return a cached response (if available and within the fresh or stale TTL). The cache is updated in the background when the network succeeds. This is useful when you want the latest data from the network when online, but still work offline with cached data.
+
+### Example 2: Stale-While-Revalidate Strategy
+
+```javascript
+const handleRequest = createHandleRequest({
+  cacheName: "api-cache-v1",
+  scope: ["/api/"],
+  defaultStrategy: "stale-while-revalidate"
+});
+```
+
+With stale-while-revalidate, requests return from cache immediately if available. If the cache is fresh (within 300 seconds), it's returned without updating. If the cache is stale (past the fresh TTL but within the stale TTL of 3600 seconds), the stale response is returned immediately and the cache is updated in the background. If the cache is too stale (past the stale TTL) or missing, it fetches from network. This provides instant responses while keeping data fresh in the background.
+
+### Example 3: Skip Inferring Invalidations
+
+```javascript
+const handleRequest = createHandleRequest({
+  cacheName: "api-cache-v1",
+  scope: ["/api/"],
+  inferInvalidation: false
+});
+```
+
+With inferInvalidation set to false, the library will not automatically invalidate the cache on mutation requests. You will need to manually invalidate the cache on mutation requests using the `X-SW-Cache-Invalidate` header.
+
+```javascript
+fetch("/api/users/123", {
+  method: "PATCH",
+  headers: {
+    "X-SW-Cache-Invalidate": "/api/users/123"
+  }
+});
+```
+
+If you need to invalidate multiple paths at once, you can set the `X-SW-Cache-Invalidate` header multiple times in a single request.
+
+```javascript
+const headers = new Headers();
+headers.append("X-SW-Cache-Invalidate", "/api/users");
+headers.append("X-SW-Cache-Invalidate", "/api/users/123");
+
+fetch("/api/users/123", {
+  method: "PATCH",
+  headers
+});
+```
+
+### Example 4: Custom Fetch Function
+
+You can provide a custom fetch function to intercept and modify requests/responses. This is useful for handling authentication errors (e.g., 401/403 responses) or adding custom headers to all requests.
+
+```javascript
+const handleRequest = createHandleRequest({
+  cacheName: "api-cache-v1",
+  scope: ["/api/"],
+  customFetch: async (request) => {
+    const response = await fetch(request);
+
+    // Handle authentication errors
+    if (response.status === 401 || response.status === 403) {
+      // redirect to login page
+      // ...
+    }
+
+    return response;
+  }
+});
+```
+
+The `customFetch` function has the same signature as the native `fetch` function. It will be used for all network requests made by the cache handler.
+
+## Clearing the cache on logout
+
+It can be useful to clear the cache on logout or other events. You can do this by setting the `X-SW-Cache-Clear` header on a request (any value will work - the header's presence triggers cache clearing).
+
+```javascript
+fetch("/api/logout", {
+  method: "POST",
+  headers: {
+    "X-SW-Cache-Clear": "true" // Any value works - header presence triggers cache clear
+  }
+});
+```
+
+This will clear the entire cache for the cache name specified in the request handler configuration.
+
+## Automatic Cache Cleanup
+
+The library automatically cleans up cache entries that are older than `maxCacheAgeSeconds` (defaults to 7200 seconds). This prevents unbounded cache growth.
+
+Cleanup happens in two ways:
+
+1. **Reactive cleanup**: When a cached entry is accessed and found to be older than `maxCacheAgeSeconds`, it's immediately deleted.
+2. **Periodic cleanup**: Every 100 fetches, the library scans the cache and removes all entries older than `maxCacheAgeSeconds`.
+
+If the service worker restarts (which can happen at any time), cleanup runs again on the first fetch after restart, ensuring cleanup happens even if the service worker restarts frequently.
+
+### Manual Cleanup
+
+You can also manually trigger cleanup in your service worker's `activate` handler:
+
+```javascript
+// sw.js
+import { cleanupOldCacheEntries } from "https://cdn.jsdelivr.net/npm/swimple@1.0.0/index.js";
+
+self.addEventListener("activate", (event) => {
+  event.waitUntil(
+    cleanupOldCacheEntries("api-cache-v1", 7200) // cacheName, maxAgeSeconds
+  );
+});
+```
+
+## Understanding Fresh vs Stale TTL
+
+- **Fresh TTL** (`defaultTTLSeconds`): Responses within this time are considered "fresh". For `cache-first` and `stale-while-revalidate` strategies, fresh responses are returned from cache without background network updates.
+
+- **Stale TTL** (`defaultStaleTTLSeconds`): Responses past the fresh TTL but within the stale TTL are considered "stale". Stale responses can still be returned from cache:
+  - For `cache-first`: Used as a fallback when offline
+  - For `network-first`: Used as a fallback when offline
+  - For `stale-while-revalidate`: Returned immediately while updating in the background
+
+If a response is past the stale TTL (or no stale TTL is set), it's too stale and must be fetched from the network.
+
+## API Reference
+
+### `createHandleRequest(config)`
+
+Creates a request handler function for your service worker fetch handler.
+
+#### Configuration Options
+
+| Option                   | Type       | Required | Default         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| ------------------------ | ---------- | -------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cacheName`              | `string`   | Yes      | -               | Name of the cache, used when calling `Cache.open(cacheName)` internally. Changing this name effectively clears the previous cache entries.                                                                                                                                                                                                                                                                                                                                    |
+| `scope`                  | `string[]` | No       | `undefined`     | 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.                                                                                                                         |
+| `defaultStrategy`        | `string`   | No       | `'cache-first'` | Default caching strategy: `'cache-first'`, `'network-first'`, or `'stale-while-revalidate'`.                                                                                                                                                                                                                                                                                                                                                                                  |
+| `defaultTTLSeconds`      | `number`   | No       | `300`           | 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). |
+| `defaultStaleTTLSeconds` | `number`   | No       | `3600`          | 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.                                                                                                                                                 |
+| `inferInvalidation`      | `boolean`  | No       | `true`          | Automatically invalidate cache on POST/PATCH/PUT/DELETE requests.                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `customFetch`            | `function` | No       | `fetch`         | 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.                                                                                                                                                                                                                                                           |
+| `maxCacheAgeSeconds`     | `number`   | No       | `7200`          | 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).                                                                                                                                                                                     |
+
+#### Returns
+
+A request handler function `(event: FetchEvent) => Promise<Response> | null` that:
+
+- Returns a `Promise<Response>` if the request is handled by the cache handler
+- Returns `null` if the request should fall through to other handlers (e.g., when `X-SW-Cache-TTL-Seconds` is set to `0`, or when the request doesn't match the configured scope and has no TTL header)
+
+## HTTP Headers
+
+Control caching behavior on a per-request basis using these headers:
+
+### `X-SW-Cache-Strategy`
+
+Override the default caching strategy for a specific request.
+
+**Values:**
+
+- `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.
+
+**Example:**
+
+```javascript
+fetch("/api/users", {
+  headers: {
+    "X-SW-Cache-Strategy": "network-first"
+  }
+});
+```
+
+### `X-SW-Cache-TTL-Seconds`
+
+Set the time-to-live (in seconds) used to validate a cached response when it's requested. The TTL is not stored with the cached response; only the timestamp of when it was cached is stored. Each request can specify a different TTL to use for validation.
+
+**Example:**
+
+```javascript
+fetch("/api/users", {
+  headers: {
+    "X-SW-Cache-TTL-Seconds": "600" // Cache for 10 minutes
+  }
+});
+```
+
+To completely opt out of caching for a specific request (the handler will return `null` and not process the request at all):
+
+```javascript
+fetch("/api/random", {
+  headers: {
+    "X-SW-Cache-TTL-Seconds": "0" // Handler returns null
+  }
+});
+```
+
+**Important:** Setting TTL to `0` is a complete opt-out. The handler returns `null` immediately without checking cache, making network requests, or processing the request in any way.
+
+### `X-SW-Cache-Stale-TTL-Seconds`
+
+Maximum age before a cache entry is considered too stale to use. Used by `cache-first` (when offline), `network-first` (when offline) and `stale-while-revalidate` strategies.
+
+**How it works:**
+
+- **Fresh** (within TTL): Return from cache without background update
+- **Stale** (past TTL but within stale TTL): Return from cache and update in background (or use as offline fallback for cache-first and network-first)
+- **Too stale** (past stale TTL): Must fetch from network, not returned from cache
+
+**Example:**
+
+```javascript
+fetch("/api/users", {
+  headers: {
+    "X-SW-Cache-Strategy": "stale-while-revalidate",
+    "X-SW-Cache-TTL-Seconds": "300", // Fresh for 5 minutes
+    "X-SW-Cache-Stale-TTL-Seconds": "3600" // Usable for 1 hour total
+  }
+});
+```
+
+**Timeline:**
+
+- 0-300s: Return from cache (fresh) - no background update
+- 300-3600s: Return from cache (stale) - update in background
+- 3600s+: Cache too stale - fetch from network
+
+### `X-SW-Cache-Invalidate`
+
+Explicitly invalidate specific cache entries. Can be set multiple times for multiple paths.
+
+**Important:** When `X-SW-Cache-Invalidate` headers are present, they **take precedence** over automatically inferred invalidation paths. If headers are provided, only the header-specified paths are invalidated - inferred paths are not added. This allows you to have fine-grained control over invalidation even when `inferInvalidation: true`.
+
+**Example:**
+
+```javascript
+const headers = new Headers();
+headers.append("X-SW-Cache-Invalidate", "/api/users");
+headers.append("X-SW-Cache-Invalidate", "/api/users/123");
+headers.append("X-SW-Cache-Invalidate", "/api/teams");
+
+fetch("/api/users/123", {
+  method: "PATCH",
+  headers,
+  body: JSON.stringify(userData)
+});
+```
+
+**Example: Headers override inferred paths**
+
+```javascript
+// PATCH /api/users/123 with inferInvalidation: true
+// Without header, would invalidate: /api/users/123 AND /api/users
+// With header, only invalidates: /api/users (header takes precedence)
+
+fetch("/api/users/123", {
+  method: "PATCH",
+  headers: {
+    "X-SW-Cache-Invalidate": "/api/users" // Only this path is invalidated
+  },
+  body: JSON.stringify(userData)
+});
+```
+
+### `X-SW-Cache-Clear`
+
+Clear the entire cache. Typically used on logout to remove all user-specific cached data.
+
+**Important:** If this header is present (regardless of its value), the cache will be cleared.
+
+**Important behavior:**
+
+- When this header is present, the handler **always goes to network** - it does not check cache or return cached values
+- Stale responses are **never used**, even if offline
+- If the network request fails (e.g., offline), the error **bubbles up** to the caller
+- The cache is **always cleared** before making the network request, regardless of whether the network request succeeds or fails
+
+**Example:**
+
+```javascript
+fetch("/api/logout", {
+  method: "POST",
+  headers: {
+    "X-SW-Cache-Clear": "true" // Any value works - header presence triggers cache clear
+  }
+});
+```
+
+**Note:** While this header is typically used on mutation requests (POST/PATCH/PUT/DELETE), if used on a GET request, it will still clear the cache and attempt to fetch from network. If the network fails, the error will propagate to the caller.
+
+## Caching Behavior
+
+### Automatic Caching (Default)
+
+Since `defaultTTLSeconds` defaults to `300`, caching is automatic by default. All GET requests matching the configured scope are cached automatically.
+
+```javascript
+const handleRequest = createHandleRequest({
+  cacheName: "api-cache-v1",
+  scope: ["/api/"]
+  // defaultTTLSeconds defaults to 300, so all /api/* GETs cached automatically
+});
+
+// Automatically cached with default TTL of 300 seconds
+fetch("/api/users");
+
+// Completely opt out of caching for specific requests (handler returns null)
+fetch("/api/random", {
+  headers: {
+    "X-SW-Cache-TTL-Seconds": "0"
+  }
+});
+```
+
+### Disabling Automatic Caching
+
+To disable automatic caching, set `defaultTTLSeconds` to `0` or `undefined`. Individual requests can still enable caching with the `X-SW-Cache-TTL-Seconds` header.
+
+```javascript
+const handleRequest = createHandleRequest({
+  cacheName: "api-cache-v1",
+  scope: ["/api/"],
+  defaultTTLSeconds: 0 // Disable automatic caching
+});
+
+// Must explicitly enable caching per request
+fetch("/api/users", {
+  headers: {
+    "X-SW-Cache-TTL-Seconds": "300"
+  }
+});
+```
+
+## Automatic Cache Invalidation
+
+When `inferInvalidation: true` (default), the library automatically invalidates relevant cache entries on mutation requests:
+
+| Request                 | Invalidates                               |
+| ----------------------- | ----------------------------------------- |
+| `POST /api/users`       | `GET /api/users`                          |
+| `PATCH /api/users/123`  | `GET /api/users/123` AND `GET /api/users` |
+| `PUT /api/users/123`    | `GET /api/users/123` AND `GET /api/users` |
+| `DELETE /api/users/123` | `GET /api/users/123` AND `GET /api/users` |
+
+The library strips the last path segment to find the collection endpoint. This works for most REST API patterns, but may not handle all edge cases (e.g., nested resources like `/api/users/123/avatar`). For edge cases, you can manually specify invalidation paths using the `X-SW-Cache-Invalidate` header.
+
+**Note:** If you provide `X-SW-Cache-Invalidate` headers, they take precedence over inferred paths. Only the header-specified paths will be invalidated, not the inferred ones.
+
+**Example: Handling nested resources**
+
+```javascript
+// DELETE /api/users/123/avatar - inferred invalidation would only handle
+// /api/users/123/avatar and /api/users/123, but we also want to invalidate
+// /api/users since the user list might show avatar thumbnails
+const headers = new Headers();
+headers.append("X-SW-Cache-Invalidate", "/api/users/123/avatar");
+headers.append("X-SW-Cache-Invalidate", "/api/users/123");
+headers.append("X-SW-Cache-Invalidate", "/api/users");
+
+fetch("/api/users/123/avatar", {
+  method: "DELETE",
+  headers
+});
+```
+
+You can disable automatic invalidation:
+
+```javascript
+const handleRequest = createHandleRequest({
+  cacheName: "api-cache-v1",
+  scope: ["/api/"],
+  inferInvalidation: false // Disable automatic invalidation
+});
+```
+
+## More Usage Examples
+
+### Example 1: Basic API Caching
+
+```javascript
+// sw.js
+import { createHandleRequest } from "swimple";
+
+const handleRequest = createHandleRequest({
+  cacheName: "api-cache-v1",
+  scope: ["/api/"]
+});
+
+self.addEventListener("fetch", (event) => {
+  const response = handleRequest(event);
+  if (response) {
+    event.respondWith(response);
+  }
+});
+
+// Client code
+// Cache user list for 10 minutes
+fetch("/api/users", {
+  headers: {
+    "X-SW-Cache-TTL-Seconds": "600"
+  }
+});
+
+// Update user - automatically invalidates /api/users and /api/users/123
+fetch("/api/users/123", {
+  method: "PATCH",
+  body: JSON.stringify({ name: "Jane Doe" })
+});
+```
+
+### Example 2: Automatic Caching with Custom TTL
+
+```javascript
+// sw.js
+const handleRequest = createHandleRequest({
+  cacheName: "api-cache-v1",
+  scope: ["/api/"],
+  defaultStrategy: "cache-first",
+  defaultTTLSeconds: 600 // Cache all API calls for 10 minutes
+});
+
+self.addEventListener("fetch", (event) => {
+  const response = handleRequest(event);
+  if (response) {
+    event.respondWith(response);
+  }
+});
+
+// Client code
+// Automatically cached
+fetch("/api/users");
+
+// Completely opt out of caching for specific request (handler returns null)
+fetch("/api/live-data", {
+  headers: {
+    "X-SW-Cache-TTL-Seconds": "0"
+  }
+});
+```
+
+### Example 3: Stale-While-Revalidate
+
+```javascript
+// sw.js
+const handleRequest = createHandleRequest({
+  cacheName: "api-cache-v1",
+  scope: ["/api/"],
+  defaultStrategy: "stale-while-revalidate",
+  defaultTTLSeconds: 300, // Fresh for 5 minutes - return from cache without background update
+  defaultStaleTTLSeconds: 3600 // Stale for up to 1 hour - return from cache and update in background
+});
+
+self.addEventListener("fetch", (event) => {
+  const response = handleRequest(event);
+  if (response) {
+    event.respondWith(response);
+  }
+});
+
+// Client code
+// Returns cached data immediately (fresh = no update, stale = update in background)
+fetch("/api/users");
+```
+
+### Example 4: Multiple Scopes
+
+```javascript
+// sw.js
+const handleRequest = createHandleRequest({
+  cacheName: "api-cache-v1",
+  scope: ["/api/", "/graphql/", "/data/"],
+  defaultTTLSeconds: 300
+});
+
+self.addEventListener("fetch", (event) => {
+  const response = handleRequest(event);
+  if (response) {
+    event.respondWith(response);
+  }
+});
+```
+
+### Example 5: Logout with Cache Clear
+
+```javascript
+// Client code
+async function logout() {
+  await fetch("/api/logout", {
+    method: "POST",
+    headers: {
+      "X-SW-Cache-Clear": "true" // Clear all cached user data
+    }
+  });
+
+  window.location.href = "/login";
+}
+```
+
+### Example 6: Custom Request Handler Chain
+
+Your service worker might have other "handlers" or "middlewares" that need to be called before the cache handler.
+
+```javascript
+// sw.js
+import { createHandleRequest } from "swimple";
+
+const handleRequest = createHandleRequest({
+  cacheName: "api-cache-v1",
+  scope: ["/api/"],
+  defaultTTLSeconds: 300
+});
+
+// Custom handler for special handling
+const customHandler = (event) => {
+  const url = new URL(event.request.url);
+
+  // Special handling for auth endpoints
+  if (url.pathname.startsWith("/api/auth")) {
+    return fetch(event.request);
+  }
+
+  return null; // Fall through
+};
+
+self.addEventListener("fetch", (event) => {
+  // Try custom handler first
+  let response = customHandler(event);
+  if (response) {
+    event.respondWith(response);
+    return;
+  }
+
+  // Then try cache handler
+  response = handleRequest(event);
+  if (response) {
+    event.respondWith(response);
+    return;
+  }
+
+  // Default fetch
+  event.respondWith(fetch(event.request));
+});
+```
+
+## How It Works
+
+1. **GET Requests**: The request handler checks if a GET request matches the configured scope and caching criteria
+2. **Cache Lookup**: For eligible requests, it checks the Cache API for a valid cached response
+3. **Strategy Execution**: Based on the strategy (cache-first, network-first, stale-while-revalidate), it either returns cached data or fetches from network
+4. **TTL Management**: Cached responses store only the timestamp of when they were cached. When a request is made, the TTL from the request (or default) is used to calculate if the cached response is fresh or stale by comparing the current time with the cached timestamp. Responses within the TTL are "fresh" (returned without background updates). Responses past the TTL but within the stale TTL are "stale" (returned with background updates or used as offline fallback)
+5. **Mutation Handling**: POST/PATCH/PUT/DELETE requests trigger cache invalidation based on inferred or explicit paths
+6. **Cache Clearing**: Requests with `X-SW-Cache-Clear` header wipe the entire cache
+
+## Important Notes
+
+- Only GET requests are cached
+- Only 2xx (OK) GET responses are cached. Non-OK responses (4xx, 5xx, etc.) are not cached
+- Non-GET and non-mutating requests (POST/PATCH/PUT/DELETE) are not processed by the cache handler - it will return null. Practically, this means HEAD requests are not handled by the cache handler.
+- Query strings are part of the cache key. Different query strings create different cache entries (e.g., `/api/users?page=1` and `/api/users?page=2` are separate cache entries)
+- Cache invalidation happens automatically for mutations when `inferInvalidation: true`
+- All headers are case-insensitive (per HTTP spec)
+- TTL of `0` completely opts out of caching for a request - the handler returns `null` immediately without checking cache, making network requests, or processing the request.
+- Cache entries store only the timestamp of when they were cached. The TTL is not stored; it's provided by each request (or set with a default via `createHandleRequest` config) and the freshness or staleness is calculated at request time. This means one request could use a longer TTL than another request and therefore allow a later expiration time.
+
+## Error Handling
+
+The library follows a straightforward error handling approach:
+
+### Configuration Validation Errors
+
+Invalid configuration values passed to `createHandleRequest` will throw errors immediately. This helps catch configuration mistakes early.
+
+```javascript
+// This will throw an error
+const handleRequest = createHandleRequest({
+  cacheName: "api-cache-v1",
+  defaultStrategy: "invalid-strategy" // Error: invalid strategy
+});
+```
+
+### Exceptional Errors
+
+The library does not catch or swallow exceptional errors. If an internal operation like `cache.delete()` throws an exception (which is truly exceptional since browsers don't throw in normal cases), that error will bubble up to your code.
+
+This means you can wrap your `handleRequest` calls in try/catch if you want to handle errors:
+
+```javascript
+self.addEventListener("fetch", (event) => {
+  try {
+    const response = handleRequest(event);
+    if (response) {
+      event.respondWith(response);
+    }
+  } catch (error) {
+    // Handle exceptional errors
+    console.error("Cache handler error:", error);
+    // Fall back to network
+    event.respondWith(fetch(event.request));
+  }
+});
+```
+
+If you don't wrap `handleRequest` in try/catch, any exceptional errors will propagate normally, which may cause the service worker fetch handler to fail. Whether you need error handling depends on your application's requirements.
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please open an issue or PR on GitHub.
+
+## Links
+
+- [GitHub Repository](#)
+- [NPM Package](#)
+- [Documentation](#)
+- [Report Issues](#)
+
+## TODO
+
+- [ ] make a landing page (at https://swimple.goulet.dev) with example usage and a link to the documentation

package/helpers.js

@@ -0,0 +1,304 @@
+// @ts-check
+
+// This library is meant to be called from service workers, so we include
+// webworker types and exclude DOM types (which don't exist in service workers)
+/// <reference no-default-lib="true"/>
+/// <reference lib="esnext" />
+/// <reference lib="webworker" />
+
+/** @import { CacheStrategy, HandleRequestConfig } from "./types" */
+
+/**
+ * Get header value (case-insensitive)
+ * @param {Headers} headers
+ * @param {string} name
+ * @returns {string | null}
+ */
+export function getHeader(headers, name) {
+  const lowerName = name.toLowerCase();
+  // Headers is iterable in browsers, iterate through entries
+  const entries = /** @type {unknown} */ (headers);
+  const iterable = /** @type {Iterable<[string, string]>} */ (entries);
+  for (const [key, value] of iterable) {
+    if (key.toLowerCase() === lowerName) {
+      return value;
+    }
+  }
+  return 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, name) {
+  const lowerName = name.toLowerCase();
+  const values = [];
+  // Headers is iterable in browsers, iterate through entries
+  const entries = /** @type {unknown} */ (headers);
+  const iterable = /** @type {Iterable<[string, string]>} */ (entries);
+  for (const [key, value] of iterable) {
+    if (key.toLowerCase() === lowerName) {
+      // Split comma+space separated values (HTTP spec: multiple header values are comma-separated)
+      // Split on ", " (comma+space) to handle concatenated values from multiple append() calls
+      const splitValues = value.split(", ");
+      values.push(...splitValues);
+    }
+  }
+  return values;
+}
+
+/**
+ * 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) {
+  const timestampHeader = getHeader(response.headers, "x-sw-cache-timestamp");
+  if (!timestampHeader) {
+    return null;
+  }
+  const timestamp = parseInt(timestampHeader, 10);
+  return isNaN(timestamp) ? null : timestamp;
+}
+
+/**
+ * Check if response is fresh
+ * @param {Response} response
+ * @param {number} ttl - Time-to-live in seconds
+ * @returns {boolean}
+ */
+export function isFresh(response, ttl) {
+  const timestamp = getCacheTimestamp(response);
+  if (timestamp === null) {
+    return false;
+  }
+  const age = Date.now() - timestamp;
+  return age < ttl * 1000;
+}
+
+/**
+ * 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, ttl, staleTTL) {
+  if (staleTTL === null) {
+    return false;
+  }
+  const timestamp = getCacheTimestamp(response);
+  if (timestamp === null) {
+    return false;
+  }
+  const age = Date.now() - timestamp;
+  return age >= ttl * 1000 && age < staleTTL * 1000;
+}
+
+/**
+ * Add timestamp to response
+ * @param {Response} response
+ * @returns {Response}
+ */
+export function addTimestamp(response) {
+  const headers = new Headers(response.headers);
+  headers.set("x-sw-cache-timestamp", Date.now().toString());
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: headers
+  });
+}
+
+/**
+ * Get inferred invalidation paths
+ * @param {string} url
+ * @returns {string[]}
+ */
+export function getInferredInvalidationPaths(url) {
+  const urlObj = new URL(url);
+  const path = urlObj.pathname;
+  const paths = [url]; // Exact path
+
+  // Strip last path segment to get parent collection
+  const lastSlash = path.lastIndexOf("/");
+  if (lastSlash > 0) {
+    const parentPath = path.substring(0, lastSlash);
+    if (parentPath) {
+      const parentUrl = new URL(parentPath, urlObj.origin);
+      paths.push(parentUrl.toString());
+    }
+  }
+
+  return paths;
+}
+
+/**
+ * Get strategy from request headers or use default
+ * @param {Headers} headers
+ * @param {CacheStrategy} defaultStrategy
+ * @returns {CacheStrategy}
+ */
+export function getStrategy(headers, defaultStrategy) {
+  const strategyHeader = getHeader(headers, "X-SW-Cache-Strategy");
+  if (
+    strategyHeader &&
+    ["cache-first", "network-first", "stale-while-revalidate"].includes(
+      strategyHeader
+    )
+  ) {
+    return /** @type {CacheStrategy} */ (strategyHeader);
+  }
+  return defaultStrategy;
+}
+
+/**
+ * Get TTL from request headers or use default
+ * @param {Headers} headers
+ * @param {number} defaultTTL - Default TTL in seconds
+ * @returns {number | null} TTL in seconds, or null if caching is disabled
+ */
+export function getTTL(headers, defaultTTL) {
+  const ttlHeader = getHeader(headers, "X-SW-Cache-TTL-Seconds");
+  if (ttlHeader === null) {
+    return defaultTTL > 0 ? defaultTTL : null;
+  }
+  const ttl = parseInt(ttlHeader, 10);
+  if (isNaN(ttl) || ttl <= 0) {
+    return null;
+  }
+  return ttl;
+}
+
+/**
+ * Get stale TTL from request headers or use default
+ * @param {Headers} headers
+ * @param {number} defaultStaleTTL - Default stale TTL in seconds
+ * @returns {number | null} Stale TTL in seconds, or null if stale caching is disabled
+ */
+export function getStaleTTL(headers, defaultStaleTTL) {
+  const staleTTLHeader = getHeader(headers, "X-SW-Cache-Stale-TTL-Seconds");
+  if (staleTTLHeader === null) {
+    return defaultStaleTTL > 0 ? defaultStaleTTL : null;
+  }
+  const staleTTL = parseInt(staleTTLHeader, 10);
+  if (isNaN(staleTTL) || staleTTL <= 0) {
+    return null;
+  }
+  return staleTTL;
+}
+
+/**
+ * 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, scope, defaultTTLSeconds) {
+  if (scope.length === 0) {
+    return defaultTTLSeconds > 0;
+  }
+  const urlObj = new URL(url);
+  return scope.some((prefix) => urlObj.pathname.startsWith(prefix));
+}
+
+/**
+ * Invalidate cache entries
+ * @param {string} cacheName
+ * @param {string[]} urls
+ * @returns {Promise<void>}
+ */
+export async function invalidateCache(cacheName, urls) {
+  const cache = await caches.open(cacheName);
+  await Promise.allSettled(urls.map((url) => cache.delete(url)));
+}
+
+/**
+ * Clear entire cache
+ * @param {string} cacheName
+ * @returns {Promise<void>}
+ */
+export async function clearCache(cacheName) {
+  const cache = await caches.open(cacheName);
+  const keys = await cache.keys();
+  await Promise.allSettled(keys.map((request) => cache.delete(request)));
+}
+
+/**
+ * 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, maxAgeSeconds) {
+  const timestamp = getCacheTimestamp(response);
+  if (timestamp === null) {
+    return false;
+  }
+  const age = Date.now() - timestamp;
+  return age >= maxAgeSeconds * 1000;
+}
+
+/**
+ * Clean up cache entries older than maxAgeSeconds
+ * @param {string} cacheName
+ * @param {number} maxAgeSeconds - Maximum age in seconds
+ * @returns {Promise<void>}
+ */
+export async function cleanupOldCacheEntries(cacheName, maxAgeSeconds) {
+  const cache = await caches.open(cacheName);
+  const keys = await cache.keys();
+  const cleanupPromises = [];
+
+  for (const request of keys) {
+    const response = await cache.match(request);
+    if (response && isOlderThanMaxAge(response, maxAgeSeconds)) {
+      cleanupPromises.push(cache.delete(request));
+    }
+  }
+
+  await Promise.allSettled(cleanupPromises);
+}
+
+/**
+ * Validate configuration object
+ * @param {HandleRequestConfig} config - Configuration object to validate
+ * @throws {Error} If config is invalid
+ */
+export function validateConfig(config) {
+  if (!config || typeof config !== "object") {
+    throw new Error("config is required and must be an object");
+  }
+  const cfg = config;
+  if (!cfg.cacheName || typeof cfg.cacheName !== "string") {
+    throw new Error("config.cacheName is required and must be a string");
+  }
+  if (
+    cfg.defaultStrategy &&
+    !["cache-first", "network-first", "stale-while-revalidate"].includes(
+      String(cfg.defaultStrategy)
+    )
+  ) {
+    throw new Error(
+      "config.defaultStrategy must be one of: 'cache-first', 'network-first', 'stale-while-revalidate'"
+    );
+  }
+  if (cfg.customFetch !== undefined && typeof cfg.customFetch !== "function") {
+    throw new Error("config.customFetch must be a function");
+  }
+  if (
+    cfg.maxCacheAgeSeconds !== undefined &&
+    (typeof cfg.maxCacheAgeSeconds !== "number" || cfg.maxCacheAgeSeconds <= 0)
+  ) {
+    throw new Error(
+      "config.maxCacheAgeSeconds must be a positive number if provided"
+    );
+  }
+}

package/index.js

@@ -0,0 +1,256 @@
+// @ts-check
+
+// This library is meant to be called from service workers, so we include
+// webworker types and exclude DOM types (which don't exist in service workers)
+/// <reference no-default-lib="true"/>
+/// <reference lib="esnext" />
+/// <reference lib="webworker" />
+
+/** @import { HandleRequestConfig, CacheStrategy } from "./types" */
+
+import {
+  getHeader,
+  getAllHeaders,
+  isFresh,
+  isStale,
+  addTimestamp,
+  getInferredInvalidationPaths,
+  getStrategy,
+  getTTL,
+  getStaleTTL,
+  matchesScope,
+  invalidateCache,
+  clearCache,
+  validateConfig,
+  isOlderThanMaxAge,
+  cleanupOldCacheEntries
+} from "./helpers.js";
+
+/**
+ * Creates a request handler function for service worker fetch events.
+ *
+ * @param {HandleRequestConfig} config - Configuration options
+ * @returns {(event: FetchEvent) => Promise<Response> | null} Request handler function
+ */
+export function createHandleRequest(config) {
+  validateConfig(config);
+
+  // Set defaults
+  const cacheName = config.cacheName;
+  const scope = config.scope || [];
+  const defaultStrategy = /** @type {CacheStrategy} */ (
+    config.defaultStrategy || "cache-first"
+  );
+  const defaultTTLSeconds = config.defaultTTLSeconds ?? 300;
+  const defaultStaleTTLSeconds = config.defaultStaleTTLSeconds ?? 3600;
+  const maxCacheAgeSeconds = config.maxCacheAgeSeconds ?? 7200;
+  const inferInvalidation = config.inferInvalidation ?? true;
+  const customFetch = config.customFetch || fetch;
+
+  // Track fetch counter for periodic cleanup
+  let fetchCounter = 0;
+
+  // Main request handler
+  return function handleRequest(event) {
+    const request = event.request;
+    const url = request.url;
+    const method = request.method;
+    const headers = request.headers;
+
+    // Handle cache clearing - header presence (any value) triggers cache clear
+    if (getHeader(headers, "X-SW-Cache-Clear") !== null) {
+      return (async () => {
+        await clearCache(cacheName);
+        return customFetch(request);
+      })();
+    }
+
+    // Handle invalidation for mutations
+    // Check for explicit invalidation headers first (works even if inferInvalidation is false)
+    const invalidateHeaders = getAllHeaders(headers, "X-SW-Cache-Invalidate");
+    const isMutation = ["POST", "PATCH", "PUT", "DELETE"].includes(method);
+
+    if (invalidateHeaders.length > 0 || (inferInvalidation && isMutation)) {
+      return (async () => {
+        let pathsToInvalidate = [...invalidateHeaders];
+
+        // Only add inferred paths if no explicit headers were provided
+        // Headers take precedence over inferred paths
+        if (pathsToInvalidate.length === 0 && inferInvalidation && isMutation) {
+          pathsToInvalidate.push(...getInferredInvalidationPaths(url));
+        }
+
+        if (pathsToInvalidate.length > 0) {
+          await invalidateCache(cacheName, pathsToInvalidate);
+        }
+
+        return customFetch(request);
+      })();
+    }
+
+    // Only handle GET requests
+    if (method !== "GET") {
+      return null;
+    }
+
+    // Periodic cleanup: run on first fetch and every 100 fetches
+    fetchCounter++;
+    if (fetchCounter === 1 || fetchCounter % 100 === 0) {
+      // Run cleanup asynchronously, don't block the fetch
+      cleanupOldCacheEntries(cacheName, maxCacheAgeSeconds).catch(() => {
+        // Ignore cleanup errors
+      });
+      if (fetchCounter % 100 === 0) {
+        fetchCounter = 1; // Reset to 1 after cleanup, not 0
+      }
+    }
+
+    // Check if request matches scope and should be cached
+    const hasExplicitTTLHeader =
+      getHeader(headers, "X-SW-Cache-TTL-Seconds") !== null;
+    const ttl = getTTL(headers, defaultTTLSeconds);
+
+    // If scope doesn't match and there's no explicit TTL header, don't handle the request
+    if (!matchesScope(url, scope, defaultTTLSeconds) && !hasExplicitTTLHeader) {
+      return null;
+    }
+
+    // If TTL is 0 or null, don't cache
+    if (ttl === null || ttl === 0) {
+      return null;
+    }
+
+    const staleTTL = getStaleTTL(headers, defaultStaleTTLSeconds);
+    const strategy = getStrategy(headers, defaultStrategy);
+
+    // Handle cache-first strategy
+    if (strategy === "cache-first") {
+      return (async () => {
+        const cache = await caches.open(cacheName);
+        const cachedResponse = await cache.match(request);
+
+        if (cachedResponse) {
+          if (isFresh(cachedResponse, ttl)) {
+            return cachedResponse;
+          }
+
+          // Reactive cleanup: delete if older than maxCacheAgeSeconds
+          if (isOlderThanMaxAge(cachedResponse, maxCacheAgeSeconds)) {
+            await cache.delete(request); // Fire-and-forget cleanup
+          }
+        }
+
+        // No fresh cache, fetch from network
+        let networkResponse;
+        try {
+          networkResponse = await customFetch(request);
+        } catch (error) {
+          // Network failed, return stale cache if available
+          if (cachedResponse && isStale(cachedResponse, ttl, staleTTL)) {
+            return cachedResponse;
+          }
+          throw error;
+        }
+
+        // Cache the response if successful
+        if (networkResponse.ok) {
+          const responseToCache = addTimestamp(networkResponse.clone());
+          await cache.put(request, responseToCache);
+        }
+        return networkResponse;
+      })();
+    }
+
+    // Handle network-first strategy
+    if (strategy === "network-first") {
+      return (async () => {
+        const cache = await caches.open(cacheName);
+
+        let networkResponse;
+        try {
+          networkResponse = await customFetch(request);
+        } catch (error) {
+          // Network failed, try cache
+          const cachedResponse = await cache.match(request);
+          if (cachedResponse) {
+            // Reactive cleanup: delete if older than maxCacheAgeSeconds
+            if (isOlderThanMaxAge(cachedResponse, maxCacheAgeSeconds)) {
+              cache.delete(request); // Fire-and-forget cleanup
+              throw error;
+            }
+            if (
+              isFresh(cachedResponse, ttl) ||
+              isStale(cachedResponse, ttl, staleTTL)
+            ) {
+              return cachedResponse;
+            }
+          }
+          throw error;
+        }
+
+        // Cache the response if successful
+        if (networkResponse.ok) {
+          const responseToCache = addTimestamp(networkResponse.clone());
+          await cache.put(request, responseToCache);
+        }
+        return networkResponse;
+      })();
+    }
+
+    // Handle stale-while-revalidate strategy
+    if (strategy === "stale-while-revalidate") {
+      return (async () => {
+        const cache = await caches.open(cacheName);
+        const cachedResponse = await cache.match(request);
+
+        if (cachedResponse) {
+          // Reactive cleanup: delete if older than maxCacheAgeSeconds
+          if (isOlderThanMaxAge(cachedResponse, maxCacheAgeSeconds)) {
+            cache.delete(request); // Fire-and-forget cleanup
+            // Continue to fetch from network
+          } else {
+            const fresh = isFresh(cachedResponse, ttl);
+            const stale = isStale(cachedResponse, ttl, staleTTL);
+
+            if (fresh || stale) {
+              // Return cached response immediately
+              // Update cache in background if stale
+              if (stale) {
+                customFetch(request)
+                  .then((networkResponse) => {
+                    if (networkResponse.ok) {
+                      const responseToCache = addTimestamp(
+                        networkResponse.clone()
+                      );
+                      cache.put(request, responseToCache);
+                    }
+                  })
+                  .catch(() => {
+                    // Ignore background update errors
+                  });
+              }
+              return cachedResponse;
+            }
+          }
+        }
+
+        // No cache or too stale, fetch from network, no need for fallback if offline
+        // because we already know if there was a cached response it won't be
+        // fresh or stale if we've reached this point
+        const networkResponse = await customFetch(request);
+
+        // Cache the response if successful
+        if (networkResponse.ok) {
+          const responseToCache = addTimestamp(networkResponse.clone());
+          await cache.put(request, responseToCache);
+        }
+        return networkResponse;
+      })();
+    }
+
+    return null;
+  };
+}
+
+// Export cleanup function for manual use
+export { cleanupOldCacheEntries } from "./helpers.js";

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "swimple",
+  "version": "0.1.0",
+  "description": "A simple service worker library for request caching",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "scripts": {
+    "test": "npm run test:unit && npm run test:e2e && npm run test:ui",
+    "test:unit": "node --test tests/**/*.unit.test.js",
+    "test:e2e": "node --test tests/**/*.e2e.test.js",
+    "test:ui": "playwright test",
+    "format:check": "prettier --check .",
+    "format:fix": "prettier --write ."
+  },
+  "keywords": [
+    "service-worker",
+    "cache",
+    "caching",
+    "sw",
+    "offline",
+    "pwa"
+  ],
+  "author": "wes@goulet.dev",
+  "license": "MIT",
+  "devDependencies": {
+    "@playwright/test": "^1.57.0",
+    "prettier": "^3.7.4"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "volta": {
+    "node": "24.12.0"
+  }
+}

package/types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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";
+
+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. */
+  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;
+}