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

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,192 @@
+/**
+ * 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. Non-cacheable methods are also never coalesced with an identical
+     * in-flight request — replaying a side effect would be worse than repeating one.
+     */
+    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` / `max-age=0` → skip the read, still store the response;
+     * * response `no-store` → never stored;
+     * * response `no-cache` (even per-field, `no-cache="field1"`) → 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;
+     * * response `must-revalidate` / `proxy-revalidate` → no stale window, however short the fresh one.
+     *
+     * Set to `false` to treat `ttlMs` as the only authority. The response's `Vary` header is
+     * *always* honoured (see {@link varyHeaders}) — variant correctness is not a preference.
+     */
+    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. A
+     * response carrying `must-revalidate`/`proxy-revalidate` never opens the stale window,
+     * and the refresh never inherits the caller's `signal` — it is the wrapper's own work.
+     */
+    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`. A callback that *throws* is treated exactly the same way (after
+     * one console warning): a cache-layer failure never fails a response the network answered
+     * well.
+     */
+    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.
+     *
+     * A response's own `Vary` header is checked against this list before it is stored: a
+     * response varying on anything *not* listed cannot be keyed correctly, so it is left
+     * uncached — and `Vary: *` is never stored at all (RFC 9111 §3).
+     */
+    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;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAE5B;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;;;;;;;;;OAYG;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;;;;;;;;OAQG;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;;;;;;;;;OASG;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.1-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.1-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"
+  }
 }