@blaze-cache/fetch 0.0.0-stage → 0.2.0-beta

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Blaze Cache
+
+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

@@ -1,3 +1,171 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="https://raw.githubusercontent.com/blaze-cache/blaze-cache/main/docs/blaze-cache-logo.png" alt="Blaze Cache logo" width="150">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">@blaze-cache/fetch</h1>
+
+A drop-in `fetch()` replacement backed by a WebAssembly cache — TTLs, `Cache-Control`,
+stale-while-revalidate and an `x-blaze-cache: HIT | MISS` marker.
+
+## Install
+
+```sh
+npm install @blaze-cache/fetch @blaze-cache/core
+```
+
+## Quick start
+
+```ts
+import { createCache } from '@blaze-cache/core';
+import { createBlazeFetch } from '@blaze-cache/fetch';
+
+const cache = await createCache({ capacity: 1000 });
+const fetch = createBlazeFetch(cache, { ttlMs: 30_000 });
+
+const response = await fetch('/api/users');
+response.headers.get('x-blaze-cache'); // 'MISS' …
+```
+
+```ts
+const again = await fetch('/api/users');
+again.headers.get('x-blaze-cache');    // … then 'HIT'
+await again.json();                     // the body replayed from the cache
+```
+
+The wrapper **is** a `fetch`: same signature, same `Response` back. Hand it to anything that
+expects the platform function.
+
+```ts
+const asFetch: typeof fetch = fetch;
+window.fetch = fetch;                   // now every request in the app is cached
+```
+
+## Behaviour
+
+* **Only `GET` is cached** — pass `methods: ['GET', 'HEAD']` to include `HEAD`. Everything
+  else (including errors from uncached methods) always goes to the network.
+* **`Cache-Control` is honoured on both sides** when `cacheControl` is on (the default):
+  `max-age` overrides `ttlMs`, `Age` is deducted, `no-store`/`no-cache` on the request skip
+  the read, and the same directives on the response stop it being stored.
+* **Only successful responses are stored** — the default `shouldCache` keeps `2xx`; replace
+  it to widen or narrow that.
+* **`Authorization` participates in the default key** (hashed, never stored verbatim), so a
+  personalized response is never replayed to a different user. Tune with `varyHeaders`.
+* **A hit is a real `Response`** — status, status text, headers, body, `url` after a
+  redirect and `redirected` are replayed exactly, so your code cannot tell the difference
+  apart from the marker header.
+* **Binary, `Blob` and chunked bodies are first-class** — the payload is buffered as raw
+  bytes whether it arrived as a file, a `ReadableStream` or plain text, so an image
+  replays byte-for-byte with its `content-type` intact and `blob().type`/`blob().size`
+  still correct. A streamed (chunked) response is assembled *before* your `Response` is
+  handed back, so a hit can never half-load.
+* **Transport headers are corrected to the bytes stored** — `fetch` decodes
+  `content-encoding` for you, so the record drops `content-encoding` and
+  `transfer-encoding` and rewrites `content-length` to the payload's real size. Without
+  that, a hit would claim `content-length: 1425` (the compressed size) for 6504 stored
+  bytes — which breaks anything that measures a download. `HEAD` keeps its headers: no
+  body was sent, so its `content-length` is what a GET *would* return.
+* **Failures behave like plain `fetch`** — a rejected network call still rejects; a cache
+  that cannot store a response never breaks the request that produced it.
+
+## Options
+
+```ts
+const fetch = createBlazeFetch(cache, {
+  ttlMs: 30_000,                        // number | (response, url, init) => number
+  methods: ['GET'],                     // which methods are cacheable
+  cacheControl: true,                   // honour Cache-Control on request + response
+  staleWhileRevalidate: false,          // true | milliseconds — see below
+  key: (url, init) => `${init.method} ${url}`,   // custom cache key
+  shouldCache: (response) => response.ok,        // which responses are stored
+  tags: (response, url) => ['fetch', url],       // tags on stored entries
+  varyHeaders: ['authorization'],       // headers folded into the default key
+  markerHeader: 'x-blaze-cache',        // or false to disable the marker
+  fetch: globalThis.fetch,              // the real network function (for tests)
+});
+```
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `ttlMs` | `60_000` | Freshness window. Overridden by a response `max-age`. |
+| `methods` | `['GET']` | Methods eligible for caching. |
+| `cacheControl` | `true` | Honour `Cache-Control`/`Age` on both sides. |
+| `staleWhileRevalidate` | `false` | Serve stale entries while refreshing. A number is the fallback window when the response omits the directive. |
+| `key` | method + URL + vary hash | Custom cache key. |
+| `shouldCache` | `2xx` | Which responses are stored. |
+| `tags` | `['fetch', '<method> <url>']` | Tags for `cache.invalidateTags(...)`. |
+| `varyHeaders` | `['authorization']` | Request headers folded into the default key. |
+| `markerHeader` | `'x-blaze-cache'` | Header carrying `HIT`/`MISS`/`STALE`; `false` disables it. |
+| `fetch` | `globalThis.fetch` | The real network call — pass a stub in tests. |
+
+Requests can force the behaviour per call:
+
+```ts
+await fetch('/api/users', { forceRefresh: true });  // bypass the cache read
+await fetch('/api/users', { cache: 'no-cache' });   // the standard spelling of the same
+await fetch('/api/users', { cache: 'no-store' });   // neither read nor write
+```
+
+## Stale-while-revalidate
+
+```ts
+const fetch = createBlazeFetch(cache, { ttlMs: 10_000, staleWhileRevalidate: 30_000 });
+```
+
+Within the stale window a request is answered **immediately** from the cache with
+`x-blaze-cache: STALE`, while a background refresh rewrites the entry — the next request is
+a fresh `HIT`. One refresh runs per key at a time, and its failure is swallowed: a stale
+entry is better than a failed request.
+
+The window comes from the response's `Cache-Control: stale-while-revalidate=<seconds>`;
+the number you pass is only the fallback for servers that do not send it.
+
+## Invalidating
+
+Stored responses carry two tags, so they plug straight into the cache's tag API:
+
+```ts
+cache.invalidateTags('fetch');                 // everything this wrapper stored
+cache.invalidateTags('get /api/users');        // one resource
+cache.set('get /api/users', /* … */);          // … or just overwrite it
+```
+
+## Custom keys
+
+```ts
+import { createBlazeFetch, defaultCacheKey } from '@blaze-cache/fetch';
+
+const fetch = createBlazeFetch(cache, {
+  // Keep the default (method + URL + vary hash) and add a version prefix:
+  key: (url, init) => `v2:${defaultCacheKey(url, init, ['authorization'])}`,
+});
+```
+
+## Testing
+
+Two suites, both run against the built package:
+
+```sh
+pnpm --filter @blaze-cache/fetch test         # stubbed network — deterministic, offline
+pnpm --filter @blaze-cache/fetch test:live    # real public API — opt-in, needs the network
+```
+
+The live suite calls `api.github.com` (keyless, well under ten requests per run) to prove
+that *real* `Cache-Control` headers are read correctly — a stub can only simulate that.
+Every test in it is skipped unless `BLAZE_CACHE_LIVE=1` is set, so the default suite always
+passes with no network at all.
+
+## Documentation
+
+Setup, core concepts and the complete API reference live in the
+[repository README](https://github.com/blaze-cache/blaze-cache#readme).
+
+## Part of Blaze Cache
+
+* [`@blaze-cache/core`](https://www.npmjs.com/package/@blaze-cache/core) — the cache itself
+* [`@blaze-cache/axios`](https://www.npmjs.com/package/@blaze-cache/axios) — the axios adapter
+* [`@blaze-cache/react-query`](https://www.npmjs.com/package/@blaze-cache/react-query) — TanStack Query v5 mirror
+
+## License
+
+[MIT](https://github.com/blaze-cache/blaze-cache/blob/main/LICENSE) © Blaze Cache

package/dist/cache-control.d.ts

@@ -0,0 +1,35 @@
+/**
+ * What `Cache-Control` (and the related `Age`) say about a request or a response.
+ *
+ * Package-local on purpose: this wrapper needs the `stale-while-revalidate` directive, which
+ * `@blaze-cache/axios` does not, and each package is free to grow its own directives without
+ * dragging the others along.
+ */
+export interface CacheControl {
+    /** `no-store` — neither read nor write the cache. */
+    noStore: boolean;
+    /** `no-cache` — must not be served without revalidating. */
+    noCache: boolean;
+    /** `max-age=<seconds>`, converted to milliseconds. */
+    maxAgeMs: number | undefined;
+    /** `stale-while-revalidate=<seconds>`, converted to milliseconds. */
+    staleWhileRevalidateMs: number | undefined;
+}
+/** The value used when parsing is switched off (`cacheControl: false`) or a header is absent. */
+export declare const NO_DIRECTIVES: CacheControl;
+/**
+ * Minimal `Cache-Control` parser — only the directives a client-side cache acts on.
+ *
+ * ```ts
+ * parseCacheControl('max-age=30, stale-while-revalidate=120').maxAgeMs; // 30_000
+ * ```
+ */
+export declare function parseCacheControl(value: string | undefined | null): CacheControl;
+/**
+ * `Age: <seconds>` — how long an intermediate cache has been holding the response.
+ *
+ * The freshness window shrinks by this much: a response that is already halfway to its
+ * `max-age` deadline must not look brand new to us. Anything unparsable counts as zero.
+ */
+export declare function parseAgeMs(value: string | undefined | null): number;
+//# sourceMappingURL=cache-control.d.ts.map

package/dist/cache-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-control.d.ts","sourceRoot":"","sources":["../src/cache-control.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,YAAY;IAC3B,qDAAqD;IACrD,OAAO,EAAE,OAAO,CAAC;IACjB,4DAA4D;IAC5D,OAAO,EAAE,OAAO,CAAC;IACjB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,qEAAqE;IACrE,sBAAsB,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5C;AAED,iGAAiG;AACjG,eAAO,MAAM,aAAa,EAAE,YAK1B,CAAC;AAEH;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,YAAY,CAsBhF;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAInE"}

package/dist/cache-control.js

@@ -0,0 +1,65 @@
+/**
+ * What `Cache-Control` (and the related `Age`) say about a request or a response.
+ *
+ * Package-local on purpose: this wrapper needs the `stale-while-revalidate` directive, which
+ * `@blaze-cache/axios` does not, and each package is free to grow its own directives without
+ * dragging the others along.
+ */
+/** The value used when parsing is switched off (`cacheControl: false`) or a header is absent. */
+export const NO_DIRECTIVES = Object.freeze({
+    noStore: false,
+    noCache: false,
+    maxAgeMs: undefined,
+    staleWhileRevalidateMs: undefined,
+});
+/**
+ * Minimal `Cache-Control` parser — only the directives a client-side cache acts on.
+ *
+ * ```ts
+ * parseCacheControl('max-age=30, stale-while-revalidate=120').maxAgeMs; // 30_000
+ * ```
+ */
+export function parseCacheControl(value) {
+    const result = {
+        noStore: false,
+        noCache: false,
+        maxAgeMs: undefined,
+        staleWhileRevalidateMs: undefined,
+    };
+    if (!value)
+        return result;
+    for (const rawDirective of value.split(',')) {
+        const directive = rawDirective.trim().toLowerCase();
+        if (directive === 'no-store') {
+            result.noStore = true;
+        }
+        else if (directive === 'no-cache') {
+            result.noCache = true;
+        }
+        else if (directive.startsWith('max-age=')) {
+            result.maxAgeMs = seconds(directive.slice('max-age='.length));
+        }
+        else if (directive.startsWith('stale-while-revalidate=')) {
+            result.staleWhileRevalidateMs = seconds(directive.slice('stale-while-revalidate='.length));
+        }
+    }
+    return result;
+}
+/**
+ * `Age: <seconds>` — how long an intermediate cache has been holding the response.
+ *
+ * The freshness window shrinks by this much: a response that is already halfway to its
+ * `max-age` deadline must not look brand new to us. Anything unparsable counts as zero.
+ */
+export function parseAgeMs(value) {
+    if (!value)
+        return 0;
+    const secondsValue = Number(value.trim());
+    return Number.isFinite(secondsValue) && secondsValue >= 0 ? secondsValue * 1000 : 0;
+}
+/** Seconds → milliseconds, or `undefined` when the value is not a usable non-negative number. */
+function seconds(raw) {
+    const value = Number(raw.trim());
+    return Number.isFinite(value) && value >= 0 ? value * 1000 : undefined;
+}
+//# sourceMappingURL=cache-control.js.map

package/dist/cache-control.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-control.js","sourceRoot":"","sources":["../src/cache-control.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAaH,iGAAiG;AACjG,MAAM,CAAC,MAAM,aAAa,GAAiB,MAAM,CAAC,MAAM,CAAC;IACvD,OAAO,EAAE,KAAK;IACd,OAAO,EAAE,KAAK;IACd,QAAQ,EAAE,SAAS;IACnB,sBAAsB,EAAE,SAAS;CAClC,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAgC;IAChE,MAAM,MAAM,GAAiB;QAC3B,OAAO,EAAE,KAAK;QACd,OAAO,EAAE,KAAK;QACd,QAAQ,EAAE,SAAS;QACnB,sBAAsB,EAAE,SAAS;KAClC,CAAC;IACF,IAAI,CAAC,KAAK;QAAE,OAAO,MAAM,CAAC;IAE1B,KAAK,MAAM,YAAY,IAAI,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5C,MAAM,SAAS,GAAG,YAAY,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACpD,IAAI,SAAS,KAAK,UAAU,EAAE,CAAC;YAC7B,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;QACxB,CAAC;aAAM,IAAI,SAAS,KAAK,UAAU,EAAE,CAAC;YACpC,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;QACxB,CAAC;aAAM,IAAI,SAAS,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YAC5C,MAAM,CAAC,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;QAChE,CAAC;aAAM,IAAI,SAAS,CAAC,UAAU,CAAC,yBAAyB,CAAC,EAAE,CAAC;YAC3D,MAAM,CAAC,sBAAsB,GAAG,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,yBAAyB,CAAC,MAAM,CAAC,CAAC,CAAC;QAC7F,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,KAAgC;IACzD,IAAI,CAAC,KAAK;QAAE,OAAO,CAAC,CAAC;IACrB,MAAM,YAAY,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1C,OAAO,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,YAAY,IAAI,CAAC,CAAC,CAAC,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACtF,CAAC;AAED,iGAAiG;AACjG,SAAS,OAAO,CAAC,GAAW;IAC1B,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IACjC,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AACzE,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,21 @@
+import type { BlazeFetch, BlazeFetchCacheLike, BlazeFetchOptions } from './types.js';
+/**
+ * Wraps the platform `fetch` with a Blaze Cache layer.
+ *
+ * ```ts
+ * import { createCache } from '@blaze-cache/core';
+ * import { createBlazeFetch } from '@blaze-cache/fetch';
+ *
+ * const cache = await createCache({ capacity: 1000 });
+ * const fetch = createBlazeFetch(cache, { ttlMs: 30_000 });
+ *
+ * const response = await fetch('/api/users');
+ * response.headers.get('x-blaze-cache'); // 'MISS', then 'HIT' on the next call
+ * ```
+ *
+ * The returned function keeps the platform signature — hand it to anything expecting
+ * `typeof fetch`. Requests outside {@link BlazeFetchOptions.methods} pass through untouched,
+ * and a failing network call rejects exactly as it would have without the wrapper.
+ */
+export declare function createBlazeFetch(cache: BlazeFetchCacheLike, options?: BlazeFetchOptions): BlazeFetch;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,UAAU,EACV,mBAAmB,EAInB,iBAAiB,EAElB,MAAM,YAAY,CAAC;AAgBpB;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,mBAAmB,EAC1B,OAAO,GAAE,iBAAsB,GAC9B,UAAU,CAqLZ"}

package/dist/client.js

@@ -0,0 +1,243 @@
+import { NO_DIRECTIVES, parseAgeMs, parseCacheControl } from './cache-control.js';
+import { defaultCacheKey } from './key.js';
+import { normalizeInit, resolveMethod, resolveUrl } from './request.js';
+/** Freshness window when neither the option nor `Cache-Control` says otherwise. */
+const DEFAULT_TTL_MS = 60_000;
+/** Only `GET` is cached unless the caller says otherwise. */
+const DEFAULT_METHODS = ['GET'];
+/** A personalized response must never be replayed to a different user. */
+const DEFAULT_VARY_HEADERS = ['authorization'];
+const DEFAULT_MARKER_HEADER = 'x-blaze-cache';
+/** Statuses that cannot carry a body — a replay must pass `null` for them. */
+const NULL_BODY_STATUSES = new Set([101, 204, 205, 304]);
+/**
+ * Wraps the platform `fetch` with a Blaze Cache layer.
+ *
+ * ```ts
+ * import { createCache } from '@blaze-cache/core';
+ * import { createBlazeFetch } from '@blaze-cache/fetch';
+ *
+ * const cache = await createCache({ capacity: 1000 });
+ * const fetch = createBlazeFetch(cache, { ttlMs: 30_000 });
+ *
+ * const response = await fetch('/api/users');
+ * response.headers.get('x-blaze-cache'); // 'MISS', then 'HIT' on the next call
+ * ```
+ *
+ * The returned function keeps the platform signature — hand it to anything expecting
+ * `typeof fetch`. Requests outside {@link BlazeFetchOptions.methods} pass through untouched,
+ * and a failing network call rejects exactly as it would have without the wrapper.
+ */
+export function createBlazeFetch(cache, options = {}) {
+    // Called as a member of `globalThis`, so the receiver stays correct in browsers, where an
+    // unbound `fetch` throws "Illegal invocation".
+    const network = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+    const markerHeader = options.markerHeader === undefined ? DEFAULT_MARKER_HEADER : options.markerHeader;
+    const methods = new Set((options.methods ?? DEFAULT_METHODS).map((method) => method.toUpperCase()));
+    const cacheControl = options.cacheControl ?? true;
+    const varyHeaders = options.varyHeaders ?? DEFAULT_VARY_HEADERS;
+    const shouldCache = options.shouldCache ?? defaultShouldCache;
+    const swr = options.staleWhileRevalidate ?? false;
+    /** Whether stale entries may be served at all, and for how long when the header is absent. */
+    const swrEnabled = swr !== false;
+    const swrFallbackMs = typeof swr === 'number' && swr > 0 ? swr : 0;
+    /** Keys with a background refresh already running — one network call per key at a time. */
+    const revalidating = new Set();
+    const keyOf = (url, init) => options.key ? options.key(url, init) : defaultCacheKey(url, init, varyHeaders);
+    async function dispatch(input, init) {
+        const method = resolveMethod(input, init);
+        const url = resolveUrl(input);
+        const request = normalizeInit(input, init, method);
+        const key = keyOf(url, request);
+        // `init.cache` is the caller's instruction, `Cache-Control` is the server's; with
+        // `cacheControl: false` only the former is still obeyed.
+        const control = cacheControl ? parseCacheControl(request.headers.get('Cache-Control')) : NO_DIRECTIVES;
+        const bypassWrite = control.noStore || request.cache === 'no-store';
+        const bypassRead = bypassWrite ||
+            control.noCache ||
+            init.forceRefresh === true ||
+            request.cache === 'no-cache' ||
+            request.cache === 'reload';
+        const cacheable = methods.has(method);
+        if (cacheable && !bypassRead) {
+            const record = cache.get(key);
+            if (record) {
+                const now = Date.now();
+                // `force-cache` means "use it whatever its age"; otherwise freshness decides.
+                if (request.cache === 'force-cache' || now <= record.freshUntil) {
+                    return replay(record, 'HIT');
+                }
+                if (swrEnabled && now <= record.staleUntil) {
+                    // Refreshed in the background: the caller is served *now*, the next call a `HIT`.
+                    revalidate(input, init, key);
+                    return replay(record, 'STALE');
+                }
+            }
+        }
+        const response = await network(input, init);
+        if (cacheable && !bypassWrite && shouldCache(response, url, request)) {
+            await store(response, key, url, request);
+        }
+        // Marked last, so `shouldCache`/`tags`/`ttlMs` see exactly what the network sent.
+        return mark(response, 'MISS');
+    }
+    /** Fetches a fresh copy of a stale entry so the next read is a `HIT` again. */
+    function revalidate(input, init, key) {
+        if (revalidating.has(key))
+            return;
+        revalidating.add(key);
+        void dispatch(input, { ...init, forceRefresh: true })
+            // A background refresh must never reject into a caller: the stale entry simply stays
+            // until the next attempt.
+            .catch(() => undefined)
+            .finally(() => revalidating.delete(key));
+    }
+    /** Buffers the body and writes the record. Returns early when nothing is worth keeping. */
+    async function store(response, key, url, request) {
+        // An opaque response exposes no status, headers or body: there is nothing to store.
+        if (response.status === 0)
+            return;
+        const control = cacheControl ? parseCacheControl(response.headers.get('Cache-Control')) : NO_DIRECTIVES;
+        // `no-store` forbids storing; `no-cache` demands revalidation on every use, and this
+        // cache has no conditional requests — so neither is worth an entry.
+        if (control.noStore || control.noCache)
+            return;
+        const configured = options.ttlMs;
+        const ttl = typeof configured === 'function' ? configured(response, url, request) : (configured ?? DEFAULT_TTL_MS);
+        const maxAge = control.maxAgeMs ?? ttl;
+        const age = cacheControl ? parseAgeMs(response.headers.get('Age')) : 0;
+        const freshMs = maxAge - age;
+        // Zero, negative or `NaN` means "keep nothing": already stale, or the caller opted out.
+        if (!(freshMs > 0))
+            return;
+        // The response's own directive wins; the numeric option is the fallback for servers that
+        // never send one. When the whole feature is off there is no stale window at all.
+        const staleMs = !swrEnabled
+            ? 0
+            : cacheControl && control.staleWhileRevalidateMs !== undefined
+                ? control.staleWhileRevalidateMs
+                : swrFallbackMs;
+        let body;
+        try {
+            // `clone()` tees the stream: the caller's response still delivers every byte, while
+            // this copy is buffered *before* `dispatch` resolves — so a follow-up read can never
+            // race an in-flight write.
+            body = await response.clone().arrayBuffer();
+        }
+        catch {
+            return; // a body that fails mid-flight must not poison the cache
+        }
+        const storedAt = Date.now();
+        const freshUntil = storedAt + freshMs;
+        const record = {
+            status: response.status,
+            statusText: response.statusText,
+            headers: storedHeaders(response.headers, body),
+            body,
+            url: response.url,
+            redirected: response.redirected,
+            storedAt,
+            freshUntil,
+            staleUntil: freshUntil + staleMs,
+        };
+        const totalMs = freshMs + staleMs;
+        cache.set(key, record, {
+            // `0` is how the core spells "never expires" — reached only via `ttlMs: Infinity`.
+            ttlMs: Number.isFinite(totalMs) ? totalMs : 0,
+            tags: options.tags?.(response, url, request) ?? defaultTags(request.method, url),
+        });
+    }
+    /** Rebuilds a `Response` from a stored record, without touching cache statistics. */
+    function replay(record, marker) {
+        const headers = new Headers(record.headers);
+        if (markerHeader !== false)
+            headers.set(markerHeader, marker);
+        const response = new Response(NULL_BODY_STATUSES.has(record.status) ? null : record.body, { status: record.status, statusText: record.statusText, headers });
+        // `url`/`redirected` are read-only accessors on the prototype; an own property shadows
+        // them so a hit carries the metadata of the network response it stands in for.
+        defineOwn(response, 'url', record.url);
+        defineOwn(response, 'redirected', record.redirected);
+        return response;
+    }
+    /** Stamps the marker on a network response, rebuilding it only if its headers refuse. */
+    function mark(response, marker) {
+        if (markerHeader === false)
+            return response;
+        try {
+            response.headers.set(markerHeader, marker);
+            return response;
+        }
+        catch {
+            // Immutable headers (network responses in undici, `Response.redirect()`): rebuild so
+            // the marker contract holds — the marker goes on the *rebuild*, since the original
+            // refused it. Status 0 cannot be rebuilt at all: pass it through unmarked.
+            if (response.status === 0)
+                return response;
+            const headers = new Headers(response.headers);
+            headers.set(markerHeader, marker);
+            const rebuilt = new Response(response.body, {
+                status: response.status,
+                statusText: response.statusText,
+                headers,
+            });
+            defineOwn(rebuilt, 'url', response.url);
+            defineOwn(rebuilt, 'redirected', response.redirected);
+            return rebuilt;
+        }
+    }
+    return (input, init = {}) => dispatch(input, init);
+}
+/** Successful responses only. The {@link BlazeFetchOptions.methods} gate has already applied. */
+function defaultShouldCache(response) {
+    return response.status >= 200 && response.status < 300;
+}
+/**
+ * `['fetch', '<method> <url>']` — one tag drops everything this wrapper stored
+ * (`cache.invalidateTags('fetch')`), the other drops a single resource.
+ */
+function defaultTags(method, url) {
+    return ['fetch', `${method.toLowerCase()} ${url}`];
+}
+/** Copies headers into a plain, structured-clone-friendly record. */
+function headersToRecord(headers) {
+    const record = {};
+    // `Headers.forEach` reports names already lower-cased.
+    headers.forEach((value, name) => {
+        record[name] = value;
+    });
+    return record;
+}
+/**
+ * Response headers as a plain record, corrected to describe the bytes we actually hold.
+ *
+ * `fetch` decodes `content-encoding` for us, so a stored body is always the plain payload
+ * while the headers still describe the *wire* format — `gzip` plus the compressed
+ * `content-length` (on a real API: 1425 bytes claimed for 6504 stored). Replaying those
+ * would hand back a response that contradicts itself, breaking anything that reads
+ * `content-length` — a file downloader, `blob().size`, a progress bar — or that trusts the
+ * encoding and tries to inflate plain bytes. `transfer-encoding` is hop-by-hop and stops
+ * being true the moment the body is buffered.
+ *
+ * HEAD is the one exception: no body was ever sent, so its `content-length` and
+ * `content-encoding` describe what a GET *would* return and stay as metadata.
+ */
+function storedHeaders(headers, body) {
+    const record = headersToRecord(headers);
+    delete record['transfer-encoding'];
+    if (body.byteLength > 0) {
+        delete record['content-encoding'];
+        if ('content-length' in record)
+            record['content-length'] = String(body.byteLength);
+    }
+    return record;
+}
+/** Shadows a read-only prototype accessor with an own property; never throws. */
+function defineOwn(target, key, value) {
+    try {
+        Object.defineProperty(target, key, { value, writable: true, enumerable: false, configurable: true });
+    }
+    catch {
+        // A frozen response: the missing metadata is cosmetic, never worth failing a hit over.
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A drop-in `fetch()` replacement backed by Blaze Cache.
+ *
+ * `createBlazeFetch` returns a function with the platform signature, so it slots into any
+ * code that expects `typeof fetch` — and gets caching underneath: per-entry TTLs,
+ * `Cache-Control` on both sides of the exchange, tag-based invalidation, SIEVE eviction and
+ * optional IndexedDB persistence, all inherited from {@link createCache | `@blaze-cache/core`}.
+ *
+ * ```ts
+ * import { createCache } from '@blaze-cache/core';
+ * import { createBlazeFetch } from '@blaze-cache/fetch';
+ *
+ * const cache = await createCache({ capacity: 1000 });
+ * const fetch = createBlazeFetch(cache, { ttlMs: 30_000 });
+ *
+ * const response = await fetch('/api/users');
+ * response.headers.get('x-blaze-cache'); // 'MISS', then 'HIT'
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { createBlazeFetch } from './client.js';
+export { parseCacheControl, parseAgeMs } from './cache-control.js';
+export type { CacheControl } from './cache-control.js';
+export { defaultCacheKey, fnv1a } from './key.js';
+export type { BlazeFetch, BlazeFetchCacheLike, BlazeFetchEffectiveInit, BlazeFetchInit, BlazeFetchMarker, BlazeFetchOptions, FetchCacheRecord, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACnE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAElD,YAAY,EACV,UAAU,EACV,mBAAmB,EACnB,uBAAuB,EACvB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,25 @@
+/**
+ * A drop-in `fetch()` replacement backed by Blaze Cache.
+ *
+ * `createBlazeFetch` returns a function with the platform signature, so it slots into any
+ * code that expects `typeof fetch` — and gets caching underneath: per-entry TTLs,
+ * `Cache-Control` on both sides of the exchange, tag-based invalidation, SIEVE eviction and
+ * optional IndexedDB persistence, all inherited from {@link createCache | `@blaze-cache/core`}.
+ *
+ * ```ts
+ * import { createCache } from '@blaze-cache/core';
+ * import { createBlazeFetch } from '@blaze-cache/fetch';
+ *
+ * const cache = await createCache({ capacity: 1000 });
+ * const fetch = createBlazeFetch(cache, { ttlMs: 30_000 });
+ *
+ * const response = await fetch('/api/users');
+ * response.headers.get('x-blaze-cache'); // 'MISS', then 'HIT'
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { createBlazeFetch } from './client.js';
+export { parseCacheControl, parseAgeMs } from './cache-control.js';
+export { defaultCacheKey, fnv1a } from './key.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGnE,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC"}

package/dist/key.d.ts

@@ -0,0 +1,23 @@
+import type { BlazeFetchEffectiveInit } from './types.js';
+/**
+ * FNV-1a, 32-bit.
+ *
+ * Folds sensitive material (bearer tokens, `vary` headers) into a short, stable token. It is
+ * not a security primitive — the point is that a persisted cache key never contains a secret
+ * in readable form.
+ */
+export declare function fnv1a(input: string): string;
+/**
+ * Default cache key: method + URL, plus a hash of the `varyHeaders` values.
+ *
+ * ```ts
+ * defaultCacheKey('/api/users', init, ['authorization']); // "get /api/users/a3f9k"
+ * ```
+ *
+ * The hash is appended whenever `varyHeaders` is non-empty — including when every value is
+ * absent — so keys stay stable across calls. Pass `varyHeaders: []` to get the bare
+ * `"<method> <url>"` form. Call it from the {@link BlazeFetchOptions.key} callback with the
+ * `init` you were handed.
+ */
+export declare function defaultCacheKey(url: string, init: BlazeFetchEffectiveInit, varyHeaders: readonly string[]): string;
+//# sourceMappingURL=key.d.ts.map

package/dist/key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key.d.ts","sourceRoot":"","sources":["../src/key.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO3C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,uBAAuB,EAC7B,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B,MAAM,CAOR"}

package/dist/key.js

@@ -0,0 +1,36 @@
+/**
+ * FNV-1a, 32-bit.
+ *
+ * Folds sensitive material (bearer tokens, `vary` headers) into a short, stable token. It is
+ * not a security primitive — the point is that a persisted cache key never contains a secret
+ * in readable form.
+ */
+export function fnv1a(input) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < input.length; index += 1) {
+        hash ^= input.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(36);
+}
+/**
+ * Default cache key: method + URL, plus a hash of the `varyHeaders` values.
+ *
+ * ```ts
+ * defaultCacheKey('/api/users', init, ['authorization']); // "get /api/users/a3f9k"
+ * ```
+ *
+ * The hash is appended whenever `varyHeaders` is non-empty — including when every value is
+ * absent — so keys stay stable across calls. Pass `varyHeaders: []` to get the bare
+ * `"<method> <url>"` form. Call it from the {@link BlazeFetchOptions.key} callback with the
+ * `init` you were handed.
+ */
+export function defaultCacheKey(url, init, varyHeaders) {
+    const base = `${init.method.toLowerCase()} ${url}`;
+    if (varyHeaders.length === 0)
+        return base;
+    const headers = init.headers instanceof Headers ? init.headers : new Headers(init.headers);
+    const vary = varyHeaders.map((name) => headers.get(name) ?? '').join(' ');
+    return `${base}?${fnv1a(vary)}`;
+}
+//# sourceMappingURL=key.js.map

package/dist/key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key.js","sourceRoot":"","sources":["../src/key.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,UAAU,KAAK,CAAC,KAAa;IACjC,IAAI,IAAI,GAAG,UAAU,CAAC;IACtB,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACrD,IAAI,IAAI,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QAChC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAC7B,GAAW,EACX,IAA6B,EAC7B,WAA8B;IAE9B,MAAM,IAAI,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,GAAG,EAAE,CAAC;IACnD,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAE1C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,YAAY,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3F,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1E,OAAO,GAAG,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;AAClC,CAAC"}

package/dist/request.d.ts

@@ -0,0 +1,33 @@
+import type { BlazeFetchEffectiveInit } from './types.js';
+/**
+ * Normalising a `fetch` input.
+ *
+ * `fetch` accepts three shapes — a URL string, a {@link URL} or a whole {@link Request} —
+ * and the method/headers may live on the `Request`, on the `init` object, or on both (with
+ * `init` winning). Cache keys, `Cache-Control` and every user callback work from the
+ * *resolved* view instead: one absolute URL, one method, one merged header list.
+ *
+ * The network always receives the caller's original `input`/`init`, unchanged.
+ */
+/** `true` when `input` is a `Request`. Guarded, so exotic hosts without one still work. */
+export declare function isRequest(input: RequestInfo | URL): input is Request;
+/**
+ * Absolute URL of the request — the basis of every cache key.
+ *
+ * A `Request` and a `URL` are already absolute. A string is resolved against the page in a
+ * browser; in Node there is no document base, so it is kept verbatim, which is still a
+ * stable key as long as call sites are stable.
+ */
+export declare function resolveUrl(input: RequestInfo | URL): string;
+/** HTTP method, upper-cased — `GET` when nothing says otherwise. */
+export declare function resolveMethod(input: RequestInfo | URL, init: RequestInit): string;
+/**
+ * The **effective** request: `init` as the caller passed it, with `method`, `headers` and
+ * `cache` filled in from `input` when it is a `Request`.
+ *
+ * This is what `key`, `shouldCache`, `tags` and `ttlMs` receive — so a callback can read
+ * `authorization` whether the caller set it on a `Request` or on the `init` object. It never
+ * reaches the network.
+ */
+export declare function normalizeInit(input: RequestInfo | URL, init: RequestInit, method: string): BlazeFetchEffectiveInit;
+//# sourceMappingURL=request.d.ts.map

package/dist/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../src/request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;;;;;;GASG;AAEH,2FAA2F;AAC3F,wBAAgB,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,GAAG,GAAG,KAAK,IAAI,OAAO,CAEpE;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,GAAG,GAAG,MAAM,CAS3D;AAED,oEAAoE;AACpE,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,GAAG,EAAE,IAAI,EAAE,WAAW,GAAG,MAAM,CAGjF;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,WAAW,GAAG,GAAG,EACxB,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,MAAM,GACb,uBAAuB,CAOzB"}

package/dist/request.js

@@ -0,0 +1,55 @@
+/**
+ * Normalising a `fetch` input.
+ *
+ * `fetch` accepts three shapes — a URL string, a {@link URL} or a whole {@link Request} —
+ * and the method/headers may live on the `Request`, on the `init` object, or on both (with
+ * `init` winning). Cache keys, `Cache-Control` and every user callback work from the
+ * *resolved* view instead: one absolute URL, one method, one merged header list.
+ *
+ * The network always receives the caller's original `input`/`init`, unchanged.
+ */
+/** `true` when `input` is a `Request`. Guarded, so exotic hosts without one still work. */
+export function isRequest(input) {
+    return typeof Request !== 'undefined' && input instanceof Request;
+}
+/**
+ * Absolute URL of the request — the basis of every cache key.
+ *
+ * A `Request` and a `URL` are already absolute. A string is resolved against the page in a
+ * browser; in Node there is no document base, so it is kept verbatim, which is still a
+ * stable key as long as call sites are stable.
+ */
+export function resolveUrl(input) {
+    if (isRequest(input))
+        return input.url;
+    const raw = input instanceof URL ? input.href : String(input);
+    try {
+        return new URL(raw).href;
+    }
+    catch {
+        const base = globalThis.location?.href;
+        return base === undefined ? raw : new URL(raw, base).href;
+    }
+}
+/** HTTP method, upper-cased — `GET` when nothing says otherwise. */
+export function resolveMethod(input, init) {
+    const explicit = init.method ?? (isRequest(input) ? input.method : undefined);
+    return (explicit ?? 'GET').toUpperCase();
+}
+/**
+ * The **effective** request: `init` as the caller passed it, with `method`, `headers` and
+ * `cache` filled in from `input` when it is a `Request`.
+ *
+ * This is what `key`, `shouldCache`, `tags` and `ttlMs` receive — so a callback can read
+ * `authorization` whether the caller set it on a `Request` or on the `init` object. It never
+ * reaches the network.
+ */
+export function normalizeInit(input, init, method) {
+    return {
+        ...init,
+        method,
+        headers: new Headers(init.headers ?? (isRequest(input) ? input.headers : undefined)),
+        cache: init.cache ?? (isRequest(input) ? input.cache : undefined),
+    };
+}
+//# sourceMappingURL=request.js.map

package/dist/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../src/request.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,2FAA2F;AAC3F,MAAM,UAAU,SAAS,CAAC,KAAwB;IAChD,OAAO,OAAO,OAAO,KAAK,WAAW,IAAI,KAAK,YAAY,OAAO,CAAC;AACpE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,KAAwB;IACjD,IAAI,SAAS,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC;IACvC,MAAM,GAAG,GAAG,KAAK,YAAY,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC9D,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,EAAE,IAAI,CAAC;QACvC,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC;IAC5D,CAAC;AACH,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,aAAa,CAAC,KAAwB,EAAE,IAAiB;IACvE,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAC9E,OAAO,CAAC,QAAQ,IAAI,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;AAC3C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAwB,EACxB,IAAiB,EACjB,MAAc;IAEd,OAAO;QACL,GAAG,IAAI;QACP,MAAM;QACN,OAAO,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACpF,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;KAClE,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Value written on the `x-blaze-cache` response header by every response the wrapper returns.
+ *
+ * * `MISS` — the response came from the network.
+ * * `HIT` — served from the cache while still fresh.
+ * * `STALE` — served from the cache past its freshness window, only while
+ *   {@link BlazeFetchOptions.staleWhileRevalidate} is enabled. A background revalidation is
+ *   already under way, so the *next* request gets a `HIT`.
+ */
+export type BlazeFetchMarker = 'HIT' | 'MISS' | 'STALE';
+/**
+ * What the wrapper stores in Blaze Cache for one response.
+ *
+ * The record is a plain, structured-clone-friendly object: an `ArrayBuffer` body plus
+ * primitive metadata, so it survives an IndexedDB round-trip when the cache is configured
+ * with persistence.
+ */
+export interface FetchCacheRecord {
+    status: number;
+    statusText: string;
+    /** Response headers as a plain record, names lower-cased (as `Headers` reports them). */
+    headers: Record<string, string>;
+    /**
+     * Raw response body.
+     *
+     * Empty for statuses that cannot carry one (`204`, `205`, `304`) — those are replayed with
+     * a `null` body, exactly like the network sent them.
+     */
+    body: ArrayBuffer;
+    /** Final URL after redirects — replayed as [`Response.url`](https://developer.mozilla.org/en-US/docs/Web/API/Response/url). */
+    url: string;
+    /** Whether the stored response followed a redirect. */
+    redirected: boolean;
+    /** `Date.now()` when the response was received. */
+    storedAt: number;
+    /** `Date.now()` at which the entry stops being *fresh* and switches to revalidation. */
+    freshUntil: number;
+    /** `Date.now()` at which the entry stops being served at all (equal to `freshUntil` when stale-while-revalidate is off). */
+    staleUntil: number;
+}
+/**
+ * `RequestInit` as accepted by the wrapper, plus one non-standard escape hatch.
+ *
+ * Everything the platform defines keeps its meaning; {@link forceRefresh} is additive, and
+ * the standard `cache: 'no-cache' | 'reload'` spellings do the same job if you prefer them.
+ */
+export interface BlazeFetchInit extends RequestInit {
+    /**
+     * Skip the cache **read** and go straight to the network. The fresh response still
+     * replaces whatever was stored, so one forced refresh restores a `HIT` afterwards.
+     *
+     * Standard equivalent: `cache: 'no-cache'`.
+     */
+    forceRefresh?: boolean;
+}
+/**
+ * `BlazeFetchInit` as the callbacks receive it — the *effective* request.
+ *
+ * `headers` is a concrete {@link Headers} (the caller's `init.headers` merged over a
+ * `Request`'s own) and `method` is resolved and upper-cased, so a callback never has to
+ * reproduce the three-shape `fetch` input handling:
+ *
+ * ```ts
+ * key: (url, init) => `${init.method} ${url}?${init.headers.get('authorization') ?? ''}`,
+ * ```
+ */
+export interface BlazeFetchEffectiveInit extends Omit<BlazeFetchInit, 'headers' | 'method'> {
+    /** Resolved HTTP method, upper-cased. */
+    method: string;
+    /** Merged request headers, with `init.headers` winning over a `Request`'s. */
+    headers: Headers;
+}
+/**
+ * The wrapper's call signature — a drop-in replacement for the global `fetch`.
+ *
+ * Assignable to `typeof fetch` (proved at compile time in this file), so it drops into
+ * anything that expects the platform function:
+ *
+ * ```ts
+ * const blazeFetch = createBlazeFetch(cache);
+ * const asFetch: typeof fetch = blazeFetch;
+ * window.fetch = blazeFetch;
+ * ```
+ */
+export type BlazeFetch = (input: RequestInfo | URL, init?: BlazeFetchInit) => Promise<Response>;
+/** Options accepted by {@link createBlazeFetch}. All of them are optional. */
+export interface BlazeFetchOptions {
+    /**
+     * The function performing the real network call. Defaults to the global `fetch`.
+     *
+     * Pass a stub to test callers without a server — it receives exactly the `input`/`init`
+     * the wrapper was called with, never a rewritten request.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Freshness window for a stored response, in milliseconds.
+     *
+     * Ignored when the response carries `Cache-Control: max-age`, which wins. A response
+     * carrying `Age` has that age deducted. Default: `60_000`. A value `<= 0` means
+     * "do not store".
+     */
+    ttlMs?: number | ((response: Response, url: string, init: BlazeFetchEffectiveInit) => number);
+    /**
+     * HTTP methods eligible for caching. Default: `['GET']`.
+     *
+     * Pass `['GET', 'HEAD']` to cache `HEAD` too. Any other method always goes to the network
+     * and is never stored.
+     */
+    methods?: readonly string[];
+    /**
+     * Honour `Cache-Control` on both sides of the exchange. Default: `true`.
+     *
+     * * request `no-store` → neither read nor write the cache;
+     * * request `no-cache` → skip the read, still store the response;
+     * * response `no-store`/`no-cache` → never stored;
+     * * response `max-age` → overrides {@link ttlMs}, minus the response's `Age`;
+     * * response `stale-while-revalidate` → the stale window, when {@link staleWhileRevalidate} is on.
+     *
+     * Set to `false` to treat `ttlMs` as the only authority.
+     */
+    cacheControl?: boolean;
+    /**
+     * Serve responses past their freshness window while refreshing them in the background.
+     * Default: `false` (a stale entry simply falls through to the network).
+     *
+     * * `true` — honour the response's `Cache-Control: stale-while-revalidate=<seconds>`.
+     * * a number — that, **plus** the same many milliseconds as a fallback when the response
+     *   omits the directive, so opting in works against servers that never send it.
+     *
+     * Such responses are marked `x-blaze-cache: STALE` and revalidated once per key: the
+     * refresh is a forced refresh, so it can never re-serve the stale entry to itself.
+     */
+    staleWhileRevalidate?: boolean | number;
+    /**
+     * Builds the cache key. Receives the resolved absolute `url` and the effective `init`
+     * (see {@link BlazeFetchEffectiveInit}).
+     *
+     * The default is `"<method> <url>"` plus a hash of {@link varyHeaders} — {@link defaultCacheKey}
+     * is that default, so you can wrap it and only change the parts you care about. Replacing
+     * the key replaces **everything** the default included, so include `init.method` yourself
+     * when caching more than one method.
+     */
+    key?: (url: string, init: BlazeFetchEffectiveInit) => string;
+    /**
+     * Decide whether a response is worth storing. Default: only `2xx` responses
+     * (the {@link methods} gate has already applied by then).
+     *
+     * A response this rejects is still returned — it is simply not cached, and still carries
+     * `x-blaze-cache: MISS`.
+     */
+    shouldCache?: (response: Response, url: string, init: BlazeFetchEffectiveInit) => boolean;
+    /**
+     * Tags attached to stored responses. Default: `['fetch', '<method> <url>']`.
+     *
+     * The first tag lets one call drop the whole wrapper's content
+     * (`cache.invalidateTags('fetch')`); the second drops a single resource.
+     */
+    tags?: (response: Response, url: string, init: BlazeFetchEffectiveInit) => readonly string[];
+    /**
+     * Request headers whose values participate in the cache key. Default: `['authorization']`.
+     *
+     * A personalized response must never be served to a different user just because the URL
+     * matched. Values are hashed, never stored verbatim.
+     */
+    varyHeaders?: readonly string[];
+    /**
+     * Response header set to `HIT` / `MISS` / `STALE`. Default: `'x-blaze-cache'`.
+     * Pass `false` to disable the marker entirely.
+     */
+    markerHeader?: string | false;
+}
+/** The slice of a cache the wrapper needs — deliberately structural. */
+export interface BlazeFetchCacheLike {
+    get(key: string): FetchCacheRecord | undefined;
+    set(key: string, value: FetchCacheRecord, options?: {
+        ttlMs?: number;
+        tags?: readonly string[];
+    }): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;AAExD;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,yFAAyF;IACzF,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC;;;;;OAKG;IACH,IAAI,EAAE,WAAW,CAAC;IAClB,+HAA+H;IAC/H,GAAG,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,UAAU,EAAE,OAAO,CAAC;IACpB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,wFAAwF;IACxF,UAAU,EAAE,MAAM,CAAC;IACnB,4HAA4H;IAC5H,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAe,SAAQ,WAAW;IACjD;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,uBAAwB,SAAQ,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,QAAQ,CAAC;IACzF,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE,WAAW,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,cAAc,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEhG,8EAA8E;AAC9E,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAErB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,uBAAuB,KAAK,MAAM,CAAC,CAAC;IAE9F;;;;;OAKG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAE5B;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;;;;;;;OAUG;IACH,oBAAoB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAExC;;;;;;;;OAQG;IACH,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,uBAAuB,KAAK,MAAM,CAAC;IAE7D;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,uBAAuB,KAAK,OAAO,CAAC;IAE1F;;;;;OAKG;IACH,IAAI,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,uBAAuB,KAAK,SAAS,MAAM,EAAE,CAAC;IAE7F;;;;;OAKG;IACH,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAEhC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CAC/B;AAED,wEAAwE;AACxE,MAAM,WAAW,mBAAmB;IAClC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAAC;IAC/C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,GAAG,IAAI,CAAC;CACzG"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@blaze-cache/fetch",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0-beta",
+  "description": "Drop-in fetch() replacement backed by a WebAssembly cache — TTLs, Cache-Control, stale-while-revalidate and an x-blaze-cache HIT/MISS marker",
+  "keywords": [
+    "fetch",
+    "http",
+    "request",
+    "cache",
+    "caching",
+    "stale-while-revalidate",
+    "cache-control",
+    "webassembly",
+    "wasm",
+    "ttl"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/blaze-cache/blaze-cache.git",
+    "directory": "packages/fetch"
+  },
+  "homepage": "https://blaze-cache.github.io/docs/",
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@blaze-cache/core": "0.2.0-beta"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "pnpm run build && node --test",
+    "test:live": "pnpm run build && BLAZE_CACHE_LIVE=1 node --test test/live.test.mjs",
+    "typecheck": "tsc -p tsconfig.typecheck.json"
+  }
 }