@baukit/pwa-web 0.7.1 → 0.7.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baukit/pwa-web",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Cache strategy, cleanup, and a classic worker artifact for web PWAs.",
   "license": "MIT",
   "author": "Patrick Koss",
@@ -34,6 +34,7 @@
   },
   "files": [
     "dist",
+    "src",
     "README.md",
     "LICENSE"
   ],

package/src/cache-cleanup.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { cleanupCaches } from './cache-cleanup.js';
+
+describe('cleanupCaches', () => {
+  it('removes old cache versions without touching the current or unrelated caches', async () => {
+    const deleted: string[] = [];
+
+    await expect(
+      cleanupCaches({
+        ports: {
+          listCacheNames: () =>
+            Promise.resolve(['notes-app-v1', 'notes-app-v2', 'notes-media', 'another-product-v1']),
+          deleteCache: (name) => {
+            deleted.push(name);
+            return Promise.resolve(true);
+          },
+        },
+        shouldDelete: (name) => name.startsWith('notes-app-') && name !== 'notes-app-v2',
+      }),
+    ).resolves.toEqual({ matchedCount: 1, deletedCount: 1 });
+
+    expect(deleted).toEqual(['notes-app-v1']);
+  });
+
+  it('removes only the previous identity partition after an account switch', async () => {
+    const deleted: string[] = [];
+    const previousPartition = 'account-17';
+
+    await cleanupCaches({
+      ports: {
+        listCacheNames: () =>
+          Promise.resolve([
+            `notes-private-${previousPartition}`,
+            'notes-private-account-42',
+            'notes-static-v3',
+          ]),
+        deleteCache: (name) => {
+          deleted.push(name);
+          return Promise.resolve(true);
+        },
+      },
+      shouldDelete: (name) => name === `notes-private-${previousPartition}`,
+    });
+
+    expect(deleted).toEqual(['notes-private-account-17']);
+  });
+
+  it('counts a cache that disappeared during cleanup as matched but not deleted', async () => {
+    await expect(
+      cleanupCaches({
+        ports: {
+          listCacheNames: () => Promise.resolve(['notes-app-v1']),
+          deleteCache: () => Promise.resolve(false),
+        },
+        shouldDelete: () => true,
+      }),
+    ).resolves.toEqual({ matchedCount: 1, deletedCount: 0 });
+  });
+
+  it('starts all matching deletes before waiting for completion', async () => {
+    const started: string[] = [];
+    const finish: (() => void)[] = [];
+    const cleanup = cleanupCaches({
+      ports: {
+        listCacheNames: () => Promise.resolve(['notes-app-v1', 'notes-app-v2']),
+        deleteCache: (name) => {
+          started.push(name);
+          return new Promise((resolve) => {
+            finish.push(() => {
+              resolve(true);
+            });
+          });
+        },
+      },
+      shouldDelete: () => true,
+    });
+
+    await vi.waitFor(() => {
+      expect(started).toEqual(['notes-app-v1', 'notes-app-v2']);
+    });
+    for (const resolve of finish) {
+      resolve();
+    }
+    await expect(cleanup).resolves.toEqual({ matchedCount: 2, deletedCount: 2 });
+  });
+
+  it('does not start deletion when cache selection fails', async () => {
+    const deleteCache = vi.fn<(name: string) => Promise<boolean>>();
+
+    await expect(
+      cleanupCaches({
+        ports: {
+          listCacheNames: () => Promise.resolve(['notes-app-v1']),
+          deleteCache,
+        },
+        shouldDelete: () => {
+          throw new Error('invalid product cache policy');
+        },
+      }),
+    ).rejects.toThrow('invalid product cache policy');
+    expect(deleteCache).not.toHaveBeenCalled();
+  });
+
+  it('preserves cache deletion failures', async () => {
+    const failure = new Error('cache storage unavailable');
+
+    await expect(
+      cleanupCaches({
+        ports: {
+          listCacheNames: () => Promise.resolve(['notes-app-v1']),
+          deleteCache: () => Promise.reject(failure),
+        },
+        shouldDelete: () => true,
+      }),
+    ).rejects.toBe(failure);
+  });
+});

package/src/cache-cleanup.ts

@@ -0,0 +1,25 @@
+export interface CacheCleanupPorts {
+  readonly listCacheNames: () => Promise<readonly string[]>;
+  readonly deleteCache: (name: string) => Promise<boolean>;
+}
+
+export interface CacheCleanupOptions {
+  readonly ports: CacheCleanupPorts;
+  readonly shouldDelete: (name: string) => boolean;
+}
+
+export interface CacheCleanupResult {
+  readonly matchedCount: number;
+  readonly deletedCount: number;
+}
+
+export async function cleanupCaches(options: CacheCleanupOptions): Promise<CacheCleanupResult> {
+  const names = await options.ports.listCacheNames();
+  const selected = names.filter(options.shouldDelete);
+  const deleted = await Promise.all(selected.map((name) => options.ports.deleteCache(name)));
+
+  return {
+    matchedCount: selected.length,
+    deletedCount: deleted.filter(Boolean).length,
+  };
+}

package/src/cache-strategy.test.ts

@@ -0,0 +1,184 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  CACHE_STRATEGIES,
+  createCacheStrategyDecider,
+  decideCacheStrategy,
+} from './cache-strategy.js';
+
+const APP_ORIGIN = 'https://app.example.com';
+const OPTIONS = { appOrigin: APP_ORIGIN };
+
+describe('decideCacheStrategy', () => {
+  it('treats non-GET methods as network-only', () => {
+    for (const method of ['POST', 'put', 'DELETE', 'PATCH']) {
+      expect(decideCacheStrategy({ url: `${APP_ORIGIN}/plans`, method }, OPTIONS)).toBe(
+        CACHE_STRATEGIES.networkOnly,
+      );
+    }
+  });
+
+  it('defaults to GET when the method is omitted', () => {
+    expect(decideCacheStrategy({ url: `${APP_ORIGIN}/api/v1/me` }, OPTIONS)).toBe(
+      CACHE_STRATEGIES.networkFirst,
+    );
+  });
+
+  it('caches no API path by default beyond network-first', () => {
+    expect(decideCacheStrategy({ url: `${APP_ORIGIN}/api` }, OPTIONS)).toBe(
+      CACHE_STRATEGIES.networkFirst,
+    );
+    expect(decideCacheStrategy({ url: `${APP_ORIGIN}/api/v1/me` }, OPTIONS)).toBe(
+      CACHE_STRATEGIES.networkFirst,
+    );
+  });
+
+  it('does not treat a path that merely shares a prefix as an API path', () => {
+    expect(
+      decideCacheStrategy({ url: `${APP_ORIGIN}/apiary/photo.png`, destination: 'image' }, OPTIONS),
+    ).toBe(CACHE_STRATEGIES.cacheFirst);
+  });
+
+  it('never caches a configured sync path and its subpaths', () => {
+    const options = { appOrigin: APP_ORIGIN, neverCachedPathPrefixes: ['/api/v1/sync'] };
+    expect(decideCacheStrategy({ url: `${APP_ORIGIN}/api/v1/sync` }, options)).toBe(
+      CACHE_STRATEGIES.networkOnly,
+    );
+    expect(decideCacheStrategy({ url: `${APP_ORIGIN}/api/v1/sync/pull?since=12` }, options)).toBe(
+      CACHE_STRATEGIES.networkOnly,
+    );
+    expect(
+      decideCacheStrategy({ url: `${APP_ORIGIN}/api/v1/sync/push`, method: 'POST' }, options),
+    ).toBe(CACHE_STRATEGIES.networkOnly);
+  });
+
+  it('leaves the sync path unconfigured by default', () => {
+    expect(decideCacheStrategy({ url: `${APP_ORIGIN}/api/v1/sync` }, OPTIONS)).toBe(
+      CACHE_STRATEGIES.networkFirst,
+    );
+  });
+
+  it('accepts a trailing slash on a configured prefix', () => {
+    const options = { appOrigin: APP_ORIGIN, neverCachedPathPrefixes: ['/api/v1/sync/'] };
+    expect(decideCacheStrategy({ url: `${APP_ORIGIN}/api/v1/sync` }, options)).toBe(
+      CACHE_STRATEGIES.networkOnly,
+    );
+  });
+
+  it('ignores an empty prefix entry', () => {
+    const options = { appOrigin: APP_ORIGIN, neverCachedPathPrefixes: [''] };
+    expect(decideCacheStrategy({ url: `${APP_ORIGIN}/plans` }, options)).toBe(
+      CACHE_STRATEGIES.networkFirst,
+    );
+  });
+
+  it('uses network-first for navigations even when the path looks static', () => {
+    expect(
+      decideCacheStrategy({ url: `${APP_ORIGIN}/report.json`, mode: 'navigate' }, OPTIONS),
+    ).toBe(CACHE_STRATEGIES.networkFirst);
+  });
+
+  it('keeps navigation classification network-first when a fallback is configured', () => {
+    const options = { appOrigin: APP_ORIGIN, navigationFallback: '/index.html' };
+    expect(decideCacheStrategy({ url: `${APP_ORIGIN}/plans`, mode: 'navigate' }, options)).toBe(
+      CACHE_STRATEGIES.networkFirst,
+    );
+  });
+
+  it('uses cache-first for same-origin static destinations', () => {
+    for (const destination of ['audio', 'font', 'image', 'script', 'style', 'video', 'worker']) {
+      expect(decideCacheStrategy({ url: `${APP_ORIGIN}/asset`, destination }, OPTIONS)).toBe(
+        CACHE_STRATEGIES.cacheFirst,
+      );
+    }
+  });
+
+  it('uses cache-first for same-origin static extensions without a destination', () => {
+    expect(decideCacheStrategy({ url: `${APP_ORIGIN}/icon-512.png` }, OPTIONS)).toBe(
+      CACHE_STRATEGIES.cacheFirst,
+    );
+    expect(decideCacheStrategy({ url: `${APP_ORIGIN}/manifest.webmanifest` }, OPTIONS)).toBe(
+      CACHE_STRATEGIES.cacheFirst,
+    );
+    expect(decideCacheStrategy({ url: `${APP_ORIGIN}/app.a1b2c3.JS` }, OPTIONS)).toBe(
+      CACHE_STRATEGIES.cacheFirst,
+    );
+    expect(decideCacheStrategy({ url: `${APP_ORIGIN}/bundle.js?v=3` }, OPTIONS)).toBe(
+      CACHE_STRATEGIES.cacheFirst,
+    );
+  });
+
+  it('does not read an extension out of a directory segment or a dotfile', () => {
+    expect(decideCacheStrategy({ url: `${APP_ORIGIN}/v1.2/plans` }, OPTIONS)).toBe(
+      CACHE_STRATEGIES.networkFirst,
+    );
+    expect(decideCacheStrategy({ url: `${APP_ORIGIN}/.png` }, OPTIONS)).toBe(
+      CACHE_STRATEGIES.networkFirst,
+    );
+    expect(decideCacheStrategy({ url: `${APP_ORIGIN}/plans` }, OPTIONS)).toBe(
+      CACHE_STRATEGIES.networkFirst,
+    );
+  });
+
+  it('uses cache-first for a configured static path prefix with no extension', () => {
+    const options = { appOrigin: APP_ORIGIN, staticPathPrefixes: ['/_expo/static/'] };
+    expect(decideCacheStrategy({ url: `${APP_ORIGIN}/_expo/static/js/web/app` }, options)).toBe(
+      CACHE_STRATEGIES.cacheFirst,
+    );
+  });
+
+  it('keeps cross-origin static assets on the default strategy', () => {
+    expect(
+      decideCacheStrategy(
+        { url: 'https://cdn.example.com/logo.png', destination: 'image' },
+        OPTIONS,
+      ),
+    ).toBe(CACHE_STRATEGIES.networkFirst);
+  });
+
+  it('resolves a relative URL against the app origin', () => {
+    expect(decideCacheStrategy({ url: '/icon-192.png', destination: 'image' }, OPTIONS)).toBe(
+      CACHE_STRATEGIES.cacheFirst,
+    );
+  });
+
+  it('honors overridden strategies and destination lists', () => {
+    const options = {
+      appOrigin: APP_ORIGIN,
+      apiPathPrefixes: ['/graphql'],
+      apiStrategy: CACHE_STRATEGIES.networkOnly,
+      staticStrategy: CACHE_STRATEGIES.staleWhileRevalidate,
+      defaultStrategy: CACHE_STRATEGIES.staleWhileRevalidate,
+      staticDestinations: ['image'],
+      staticExtensions: ['png'],
+    } as const;
+
+    expect(decideCacheStrategy({ url: `${APP_ORIGIN}/graphql` }, options)).toBe(
+      CACHE_STRATEGIES.networkOnly,
+    );
+    expect(decideCacheStrategy({ url: `${APP_ORIGIN}/api/v1/me` }, options)).toBe(
+      CACHE_STRATEGIES.staleWhileRevalidate,
+    );
+    expect(decideCacheStrategy({ url: `${APP_ORIGIN}/logo.png` }, options)).toBe(
+      CACHE_STRATEGIES.staleWhileRevalidate,
+    );
+    expect(
+      decideCacheStrategy({ url: `${APP_ORIGIN}/app.js`, destination: 'script' }, options),
+    ).toBe(CACHE_STRATEGIES.staleWhileRevalidate);
+  });
+});
+
+describe('createCacheStrategyDecider', () => {
+  it('binds options once and classifies many requests', () => {
+    const decide = createCacheStrategyDecider({
+      appOrigin: APP_ORIGIN,
+      neverCachedPathPrefixes: ['/api/v1/sync'],
+    });
+
+    expect(decide({ url: `${APP_ORIGIN}/api/v1/sync/pull` })).toBe(CACHE_STRATEGIES.networkOnly);
+    expect(decide({ url: `${APP_ORIGIN}/icon.png` })).toBe(CACHE_STRATEGIES.cacheFirst);
+    expect(decide({ url: `${APP_ORIGIN}/plans`, mode: 'navigate' })).toBe(
+      CACHE_STRATEGIES.networkFirst,
+    );
+  });
+});

package/src/cache-strategy.ts

@@ -0,0 +1,156 @@
+export const CACHE_STRATEGIES = {
+  cacheFirst: 'cache-first',
+  networkFirst: 'network-first',
+  networkOnly: 'network-only',
+  staleWhileRevalidate: 'stale-while-revalidate',
+} as const;
+
+export type CacheStrategy = (typeof CACHE_STRATEGIES)[keyof typeof CACHE_STRATEGIES];
+
+export interface CacheStrategyRequest {
+  readonly url: string;
+  readonly method?: string;
+  readonly mode?: string;
+  readonly destination?: string;
+}
+
+export interface CacheStrategyOptions {
+  readonly appOrigin: string;
+  readonly apiPathPrefixes?: readonly string[];
+  readonly neverCachedPathPrefixes?: readonly string[];
+  readonly navigationFallback?: string;
+  readonly staticPathPrefixes?: readonly string[];
+  readonly staticDestinations?: readonly string[];
+  readonly staticExtensions?: readonly string[];
+  readonly apiStrategy?: CacheStrategy;
+  readonly staticStrategy?: CacheStrategy;
+  readonly defaultStrategy?: CacheStrategy;
+}
+
+export interface CacheStrategyDecision {
+  readonly strategy: CacheStrategy;
+  readonly navigationFallback?: string;
+}
+
+const DEFAULT_API_PATH_PREFIXES: readonly string[] = ['/api'];
+
+const DEFAULT_STATIC_DESTINATIONS: readonly string[] = [
+  'audio',
+  'font',
+  'image',
+  'script',
+  'style',
+  'video',
+  'worker',
+];
+
+const DEFAULT_STATIC_EXTENSIONS: readonly string[] = [
+  'avif',
+  'css',
+  'gif',
+  'ico',
+  'jpeg',
+  'jpg',
+  'js',
+  'json',
+  'mjs',
+  'mp3',
+  'mp4',
+  'ogg',
+  'otf',
+  'png',
+  'svg',
+  'ttf',
+  'webmanifest',
+  'webp',
+  'woff',
+  'woff2',
+];
+
+function matchesPathPrefix(pathname: string, prefix: string): boolean {
+  if (prefix.length === 0) {
+    return false;
+  }
+  const normalized = prefix.endsWith('/') ? prefix.slice(0, -1) : prefix;
+  return pathname === normalized || pathname.startsWith(`${normalized}/`);
+}
+
+function matchesAnyPathPrefix(pathname: string, prefixes: readonly string[]): boolean {
+  return prefixes.some((prefix) => matchesPathPrefix(pathname, prefix));
+}
+
+function hasStaticExtension(pathname: string, extensions: readonly string[]): boolean {
+  const lastSegment = pathname.slice(pathname.lastIndexOf('/') + 1);
+  const dotIndex = lastSegment.lastIndexOf('.');
+  if (dotIndex <= 0) {
+    return false;
+  }
+  const extension = lastSegment.slice(dotIndex + 1).toLowerCase();
+  return extensions.includes(extension);
+}
+
+function startsWithAny(pathname: string, prefixes: readonly string[]): boolean {
+  return prefixes.some((prefix) => prefix.length > 0 && pathname.startsWith(prefix));
+}
+
+export function decideCacheStrategyDecision(
+  request: CacheStrategyRequest,
+  options: CacheStrategyOptions,
+): CacheStrategyDecision {
+  const {
+    appOrigin,
+    apiPathPrefixes = DEFAULT_API_PATH_PREFIXES,
+    navigationFallback,
+    neverCachedPathPrefixes = [],
+    staticPathPrefixes = [],
+    staticDestinations = DEFAULT_STATIC_DESTINATIONS,
+    staticExtensions = DEFAULT_STATIC_EXTENSIONS,
+    apiStrategy = CACHE_STRATEGIES.networkFirst,
+    staticStrategy = CACHE_STRATEGIES.cacheFirst,
+    defaultStrategy = CACHE_STRATEGIES.networkFirst,
+  } = options;
+
+  const parsed = new URL(request.url, appOrigin);
+  const { pathname } = parsed;
+  const sameOrigin = parsed.origin === appOrigin;
+
+  if (matchesAnyPathPrefix(pathname, neverCachedPathPrefixes)) {
+    return { strategy: CACHE_STRATEGIES.networkOnly };
+  }
+
+  const method = (request.method ?? 'GET').toUpperCase();
+  if (method !== 'GET') {
+    return { strategy: CACHE_STRATEGIES.networkOnly };
+  }
+
+  if (matchesAnyPathPrefix(pathname, apiPathPrefixes)) {
+    return { strategy: apiStrategy };
+  }
+
+  if (request.mode === 'navigate') {
+    if (navigationFallback !== undefined && sameOrigin) {
+      return { strategy: defaultStrategy, navigationFallback };
+    }
+    return { strategy: defaultStrategy };
+  }
+
+  const staticAsset =
+    (request.destination !== undefined && staticDestinations.includes(request.destination)) ||
+    hasStaticExtension(pathname, staticExtensions) ||
+    startsWithAny(pathname, staticPathPrefixes);
+
+  return { strategy: sameOrigin && staticAsset ? staticStrategy : defaultStrategy };
+}
+
+export function decideCacheStrategy(
+  request: CacheStrategyRequest,
+  options: CacheStrategyOptions,
+): CacheStrategy {
+  return decideCacheStrategyDecision(request, options).strategy;
+}
+
+export function createCacheStrategyDecider(
+  options: CacheStrategyOptions,
+): (request: CacheStrategyRequest) => CacheStrategy {
+  return (request) => decideCacheStrategy(request, options);
+}

package/src/fetch-handler.test.ts

@@ -0,0 +1,279 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { CACHE_STRATEGIES, type CacheStrategy } from './cache-strategy.js';
+import {
+  createFetchHandler,
+  type FetchHandlerPorts,
+  type FetchLikeRequest,
+} from './fetch-handler.js';
+
+const APP_ORIGIN = 'https://app.example.com';
+
+interface TestResponse {
+  readonly body: string;
+  readonly cacheable?: boolean;
+}
+
+interface Harness {
+  readonly ports: FetchHandlerPorts<FetchLikeRequest, TestResponse>;
+  readonly puts: { strategy: CacheStrategy; url: string; body: string }[];
+  readonly fetchCalls: { url: string; noStore: boolean }[];
+  readonly matchCalls: string[];
+}
+
+function harness(overrides: {
+  cached?: TestResponse;
+  cachedByUrl?: Readonly<Record<string, TestResponse>>;
+  network?: TestResponse | (() => Promise<TestResponse>);
+}): Harness {
+  const puts: Harness['puts'] = [];
+  const fetchCalls: Harness['fetchCalls'] = [];
+  const matchCalls: string[] = [];
+  const network = overrides.network ?? { body: 'network' };
+
+  return {
+    puts,
+    fetchCalls,
+    matchCalls,
+    ports: {
+      fetch: async (request, init) => {
+        fetchCalls.push({ url: request.url, noStore: init?.cache === 'no-store' });
+        return typeof network === 'function' ? network() : network;
+      },
+      matchCache: (request) => {
+        const url = typeof request === 'string' ? request : request.url;
+        matchCalls.push(url);
+        return Promise.resolve(overrides.cachedByUrl?.[url] ?? overrides.cached);
+      },
+      putCache: (strategy, request, response) => {
+        puts.push({ strategy, url: request.url, body: response.body });
+        return Promise.resolve();
+      },
+      isCacheable: (response) => response.cacheable !== false,
+      cloneResponse: (response) => ({ ...response }),
+    },
+  };
+}
+
+describe('createFetchHandler', () => {
+  it('bypasses the cache for a never-cached path', async () => {
+    const { ports, fetchCalls, puts } = harness({ cached: { body: 'stale' } });
+    const handle = createFetchHandler({
+      appOrigin: APP_ORIGIN,
+      neverCachedPathPrefixes: ['/api/v1/sync'],
+      ports,
+    });
+
+    await expect(handle({ url: `${APP_ORIGIN}/api/v1/sync/pull` })).resolves.toEqual({
+      body: 'network',
+    });
+    expect(fetchCalls).toEqual([{ url: `${APP_ORIGIN}/api/v1/sync/pull`, noStore: true }]);
+    expect(puts).toEqual([]);
+  });
+
+  it('serves a cache-first hit without touching the network', async () => {
+    const { ports, fetchCalls } = harness({ cached: { body: 'cached-icon' } });
+    const handle = createFetchHandler({ appOrigin: APP_ORIGIN, ports });
+
+    await expect(handle({ url: `${APP_ORIGIN}/icon.png` })).resolves.toEqual({
+      body: 'cached-icon',
+    });
+    expect(fetchCalls).toEqual([]);
+  });
+
+  it('fetches and stores a cache-first miss', async () => {
+    const { ports, puts } = harness({});
+    const handle = createFetchHandler({ appOrigin: APP_ORIGIN, ports });
+
+    await expect(handle({ url: `${APP_ORIGIN}/icon.png` })).resolves.toEqual({ body: 'network' });
+    expect(puts).toEqual([
+      { strategy: CACHE_STRATEGIES.cacheFirst, url: `${APP_ORIGIN}/icon.png`, body: 'network' },
+    ]);
+  });
+
+  it('does not store an uncacheable cache-first response', async () => {
+    const { ports, puts } = harness({ network: { body: 'error', cacheable: false } });
+    const handle = createFetchHandler({ appOrigin: APP_ORIGIN, ports });
+
+    await expect(handle({ url: `${APP_ORIGIN}/icon.png` })).resolves.toEqual({
+      body: 'error',
+      cacheable: false,
+    });
+    expect(puts).toEqual([]);
+  });
+
+  it('stores a successful network-first response', async () => {
+    const { ports, puts } = harness({});
+    const handle = createFetchHandler({ appOrigin: APP_ORIGIN, ports });
+
+    await expect(handle({ url: `${APP_ORIGIN}/plans`, mode: 'navigate' })).resolves.toEqual({
+      body: 'network',
+    });
+    expect(puts).toEqual([
+      { strategy: CACHE_STRATEGIES.networkFirst, url: `${APP_ORIGIN}/plans`, body: 'network' },
+    ]);
+  });
+
+  it('falls back to the cache when a network-first fetch fails', async () => {
+    const { ports } = harness({
+      cached: { body: 'shell' },
+      network: () => Promise.reject(new Error('offline')),
+    });
+    const handle = createFetchHandler({ appOrigin: APP_ORIGIN, ports });
+
+    await expect(handle({ url: `${APP_ORIGIN}/plans`, mode: 'navigate' })).resolves.toEqual({
+      body: 'shell',
+    });
+  });
+
+  it('uses the configured app shell after a navigation request misses the cache', async () => {
+    const { ports, matchCalls } = harness({
+      cachedByUrl: { '/index.html': { body: 'app-shell' } },
+      network: () => Promise.reject(new Error('offline')),
+    });
+    const handle = createFetchHandler({
+      appOrigin: APP_ORIGIN,
+      navigationFallback: '/index.html',
+      ports,
+    });
+
+    await expect(handle({ url: `${APP_ORIGIN}/plans/active`, mode: 'navigate' })).resolves.toEqual({
+      body: 'app-shell',
+    });
+    expect(matchCalls).toEqual([`${APP_ORIGIN}/plans/active`, '/index.html']);
+  });
+
+  it('runs an overridden navigation strategy before the fallback lookup', async () => {
+    const { ports, matchCalls } = harness({
+      cachedByUrl: { '/index.html': { body: 'app-shell' } },
+      network: () => Promise.reject(new Error('offline')),
+    });
+    const handle = createFetchHandler({
+      appOrigin: APP_ORIGIN,
+      defaultStrategy: CACHE_STRATEGIES.cacheFirst,
+      navigationFallback: '/index.html',
+      ports,
+    });
+
+    await expect(handle({ url: `${APP_ORIGIN}/plans`, mode: 'navigate' })).resolves.toEqual({
+      body: 'app-shell',
+    });
+    expect(matchCalls).toEqual([`${APP_ORIGIN}/plans`, '/index.html']);
+  });
+
+  it('does not use the navigation fallback for an API route', async () => {
+    const { ports, matchCalls } = harness({
+      cachedByUrl: { '/index.html': { body: 'app-shell' } },
+      network: () => Promise.reject(new Error('offline')),
+    });
+    const handle = createFetchHandler({
+      appOrigin: APP_ORIGIN,
+      navigationFallback: '/index.html',
+      ports,
+    });
+
+    await expect(handle({ url: `${APP_ORIGIN}/api/v1/me`, mode: 'navigate' })).rejects.toThrow(
+      'offline',
+    );
+    expect(matchCalls).toEqual([`${APP_ORIGIN}/api/v1/me`]);
+  });
+
+  it('does not use the navigation fallback for a non-navigation request', async () => {
+    const { ports, matchCalls } = harness({
+      cachedByUrl: { '/index.html': { body: 'app-shell' } },
+      network: () => Promise.reject(new Error('offline')),
+    });
+    const handle = createFetchHandler({
+      appOrigin: APP_ORIGIN,
+      navigationFallback: '/index.html',
+      ports,
+    });
+
+    await expect(handle({ url: `${APP_ORIGIN}/plans` })).rejects.toThrow('offline');
+    expect(matchCalls).toEqual([`${APP_ORIGIN}/plans`]);
+  });
+
+  it('keeps navigation misses unchanged when no fallback is configured', async () => {
+    const { ports, matchCalls } = harness({
+      network: () => Promise.reject(new Error('offline')),
+    });
+    const handle = createFetchHandler({ appOrigin: APP_ORIGIN, ports });
+
+    await expect(handle({ url: `${APP_ORIGIN}/plans`, mode: 'navigate' })).rejects.toThrow(
+      'offline',
+    );
+    expect(matchCalls).toEqual([`${APP_ORIGIN}/plans`]);
+  });
+
+  it('rethrows when a network-first fetch fails with nothing cached', async () => {
+    const { ports } = harness({ network: () => Promise.reject(new Error('offline')) });
+    const handle = createFetchHandler({ appOrigin: APP_ORIGIN, ports });
+
+    await expect(handle({ url: `${APP_ORIGIN}/api/v1/me` })).rejects.toThrow('offline');
+  });
+
+  it('returns the cached response and revalidates in the background', async () => {
+    const { ports, puts } = harness({ cached: { body: 'stale' } });
+    const handle = createFetchHandler({
+      appOrigin: APP_ORIGIN,
+      staticStrategy: CACHE_STRATEGIES.staleWhileRevalidate,
+      ports,
+    });
+
+    await expect(handle({ url: `${APP_ORIGIN}/icon.png` })).resolves.toEqual({ body: 'stale' });
+    await vi.waitFor(() => {
+      expect(puts).toEqual([
+        {
+          strategy: CACHE_STRATEGIES.staleWhileRevalidate,
+          url: `${APP_ORIGIN}/icon.png`,
+          body: 'network',
+        },
+      ]);
+    });
+  });
+
+  it('awaits the network on a stale-while-revalidate miss', async () => {
+    const { ports, puts } = harness({});
+    const handle = createFetchHandler({
+      appOrigin: APP_ORIGIN,
+      staticStrategy: CACHE_STRATEGIES.staleWhileRevalidate,
+      ports,
+    });
+
+    await expect(handle({ url: `${APP_ORIGIN}/icon.png` })).resolves.toEqual({ body: 'network' });
+    expect(puts).toHaveLength(1);
+  });
+
+  it('reports a background revalidation failure instead of rejecting', async () => {
+    const onRevalidateError = vi.fn();
+    const { ports } = harness({
+      cached: { body: 'stale' },
+      network: () => Promise.reject(new Error('offline')),
+    });
+    const handle = createFetchHandler({
+      appOrigin: APP_ORIGIN,
+      staticStrategy: CACHE_STRATEGIES.staleWhileRevalidate,
+      ports,
+      onRevalidateError,
+    });
+
+    await expect(handle({ url: `${APP_ORIGIN}/icon.png` })).resolves.toEqual({ body: 'stale' });
+    await vi.waitFor(() => {
+      expect(onRevalidateError).toHaveBeenCalledWith(new Error('offline'));
+    });
+  });
+
+  it('swallows a background revalidation failure with no reporter', async () => {
+    const { ports } = harness({
+      cached: { body: 'stale' },
+      network: () => Promise.reject(new Error('offline')),
+    });
+    const handle = createFetchHandler({
+      appOrigin: APP_ORIGIN,
+      staticStrategy: CACHE_STRATEGIES.staleWhileRevalidate,
+      ports,
+    });
+
+    await expect(handle({ url: `${APP_ORIGIN}/icon.png` })).resolves.toEqual({ body: 'stale' });
+  });
+});

package/src/fetch-handler.ts

@@ -0,0 +1,124 @@
+import {
+  CACHE_STRATEGIES,
+  decideCacheStrategyDecision,
+  type CacheStrategy,
+  type CacheStrategyOptions,
+  type CacheStrategyRequest,
+} from './cache-strategy.js';
+
+export interface FetchLikeRequest extends CacheStrategyRequest {
+  readonly url: string;
+}
+
+export interface FetchHandlerPorts<TRequest extends FetchLikeRequest, TResponse> {
+  readonly fetch: (request: TRequest, init?: { readonly cache?: 'no-store' }) => Promise<TResponse>;
+  readonly matchCache: (request: TRequest | string) => Promise<TResponse | undefined>;
+  readonly putCache: (
+    strategy: CacheStrategy,
+    request: TRequest,
+    response: TResponse,
+  ) => Promise<void>;
+  readonly isCacheable: (response: TResponse) => boolean;
+  readonly cloneResponse: (response: TResponse) => TResponse;
+}
+
+export interface FetchHandlerOptions<
+  TRequest extends FetchLikeRequest,
+  TResponse,
+> extends CacheStrategyOptions {
+  readonly ports: FetchHandlerPorts<TRequest, TResponse>;
+  readonly onRevalidateError?: (error: unknown) => void;
+}
+
+async function cacheFirst<TRequest extends FetchLikeRequest, TResponse>(
+  request: TRequest,
+  ports: FetchHandlerPorts<TRequest, TResponse>,
+): Promise<TResponse> {
+  const cached = await ports.matchCache(request);
+  if (cached !== undefined) {
+    return cached;
+  }
+
+  const response = await ports.fetch(request);
+  if (ports.isCacheable(response)) {
+    await ports.putCache(CACHE_STRATEGIES.cacheFirst, request, ports.cloneResponse(response));
+  }
+  return response;
+}
+
+async function networkFirst<TRequest extends FetchLikeRequest, TResponse>(
+  request: TRequest,
+  ports: FetchHandlerPorts<TRequest, TResponse>,
+): Promise<TResponse> {
+  try {
+    const response = await ports.fetch(request);
+    if (ports.isCacheable(response)) {
+      await ports.putCache(CACHE_STRATEGIES.networkFirst, request, ports.cloneResponse(response));
+    }
+    return response;
+  } catch (error) {
+    const cached = await ports.matchCache(request);
+    if (cached !== undefined) {
+      return cached;
+    }
+    throw error;
+  }
+}
+
+async function staleWhileRevalidate<TRequest extends FetchLikeRequest, TResponse>(
+  request: TRequest,
+  ports: FetchHandlerPorts<TRequest, TResponse>,
+  onRevalidateError: ((error: unknown) => void) | undefined,
+): Promise<TResponse> {
+  const cached = await ports.matchCache(request);
+  const revalidate = (async () => {
+    const response = await ports.fetch(request);
+    if (ports.isCacheable(response)) {
+      await ports.putCache(
+        CACHE_STRATEGIES.staleWhileRevalidate,
+        request,
+        ports.cloneResponse(response),
+      );
+    }
+    return response;
+  })();
+
+  if (cached === undefined) {
+    return revalidate;
+  }
+
+  revalidate.catch((error: unknown) => {
+    onRevalidateError?.(error);
+  });
+  return cached;
+}
+
+export function createFetchHandler<TRequest extends FetchLikeRequest, TResponse>(
+  options: FetchHandlerOptions<TRequest, TResponse>,
+): (request: TRequest) => Promise<TResponse> {
+  const { ports, onRevalidateError, ...strategyOptions } = options;
+
+  return async (request) => {
+    const { strategy, navigationFallback } = decideCacheStrategyDecision(request, strategyOptions);
+    try {
+      switch (strategy) {
+        case CACHE_STRATEGIES.networkOnly:
+          return await ports.fetch(request, { cache: 'no-store' });
+        case CACHE_STRATEGIES.cacheFirst:
+          return await cacheFirst(request, ports);
+        case CACHE_STRATEGIES.staleWhileRevalidate:
+          return await staleWhileRevalidate(request, ports, onRevalidateError);
+        case CACHE_STRATEGIES.networkFirst:
+          return await networkFirst(request, ports);
+      }
+    } catch (error) {
+      if (navigationFallback !== undefined) {
+        const fallback = await ports.matchCache(navigationFallback);
+        if (fallback !== undefined) {
+          return fallback;
+        }
+      }
+      throw error;
+    }
+  };
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+export {
+  cleanupCaches,
+  type CacheCleanupOptions,
+  type CacheCleanupPorts,
+  type CacheCleanupResult,
+} from './cache-cleanup.js';
+export {
+  CACHE_STRATEGIES,
+  createCacheStrategyDecider,
+  decideCacheStrategy,
+  type CacheStrategy,
+  type CacheStrategyOptions,
+  type CacheStrategyRequest,
+} from './cache-strategy.js';
+export {
+  createFetchHandler,
+  type FetchHandlerOptions,
+  type FetchHandlerPorts,
+  type FetchLikeRequest,
+} from './fetch-handler.js';

package/src/worker-entry.ts

@@ -0,0 +1 @@
+export * from './index.js';