@ayepi/cache 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,88 @@
+# @ayepi/cache
+
+Response-caching middleware for [`@ayepi/core`](../core). It keys a response by the
+**request** (method + path + query, plus an optional dev-defined `vary` — e.g. the
+authenticated user), and on a **hit** replays the stored response without running the
+handler. Entries live in memory for a bounded **time** (`ttl`, with optional
+`stale-while-revalidate`) and a bounded **space** (`maxBytes` / `maxEntryBytes` /
+`maxEntries`, LRU-evicted).
+
+```sh
+pnpm add @ayepi/cache @ayepi/core zod
+```
+
+It ships as a **def / impl split** (like `@ayepi/rate`):
+
+- `@ayepi/cache` (frontend-safe) exports `cache(opts?)`, a middleware **def factory**,
+  plus the standalone `memoryCache` / `cacheKey` / `cacheHeaders` / `isCacheableResult`
+  primitives. A spec importing only this entry is safe to bundle for the frontend.
+- `@ayepi/cache/server` augments `cache` with **`.server(def, opts)`**, which binds the
+  policy (`ttl`, `vary`, bounds, …). Bind the pair with `implement(api).middleware(...)`.
+
+## Quick start
+
+```ts
+// shared.ts — frontend-safe
+import { cache } from '@ayepi/cache';
+const cached = cache({ requires: [auth] });          // ctx.user typed in `vary`/`key`/`skip`
+const api = spec({ endpoints: { ...cached.group({ report: { method: 'GET', response: Report } }) } });
+
+// server.ts — bind the policy
+import { cache } from '@ayepi/cache/server';
+implement(api)
+  .middleware(auth, authImpl)
+  .middleware(cache.server(cached, {
+    ttl: 30_000,                       // fresh for 30s
+    staleWhileRevalidate: 60_000,      // then serve stale up to 60s more while refreshing
+    vary: (io) => io.ctx.user.id,      // per-user cache
+    maxBytes: 64 * 1024 * 1024,        // bound the memory it can use
+  }))
+  .handlers({ report: ({ user }) => buildReport(user.id) });
+```
+
+The first request runs the handler and stores the JSON response (`X-Cache: MISS`);
+repeats within `ttl` are replayed (`X-Cache: HIT`, with `Age` / `Cache-Control`) — over
+HTTP and (as a result frame) over WebSocket. Place `cache` **last** in a chain (closest
+to the handler) so `auth` / `rateLimit` / telemetry still run on a hit.
+
+## Controls
+
+- **Time** — `ttl` (freshness) and `staleWhileRevalidate` (serve-stale grace; the stale
+  response goes out immediately while a single background refresh updates the entry).
+- **Space** — the default `memoryCache` is an LRU store bounded by `maxBytes` (total),
+  `maxEntryBytes` (per response — larger ones aren't cached), and `maxEntries` (count).
+- **Key** — `method + path + query + body + vary` by default (the body is canonicalized, so
+  property order doesn't matter); `key(io)` overrides it entirely. Works over HTTP **and
+  WebSocket** (where the call args replace query+body). Only the endpoint's declared
+  `methods` (default `['GET']`) are cached; everything else passes through.
+- **Big keys** — `hash` shrinks the key to a short store key (`hash: hashKey`, or a crypto
+  digest); `checkKey` (on by default when hashing) keeps + verifies the full key so a
+  collision misses safely.
+- **Per-response** — `shouldCache(io, result)`, or from the handler via
+  `io.ctx.cache.noStore()` / `io.ctx.cache.ttl(ms)`.
+- **Request `Cache-Control`** — `no-store` bypasses; `no-cache` revalidates.
+- **Invalidation** — hold the `store` you pass in and call `store.delete(cacheKey(...))`,
+  `store.clear()`, or `store.invalidate(meta => …)` after a mutation.
+- **Fail-open** — if any cache step throws (the store, key derivation, hashing), the request
+  falls through to the handler as if uncached; the endpoint never errors because of caching.
+  Pass `onError(err, phase)` to observe those swallowed errors (off by default).
+
+## What is cached
+
+Single-response (`response:`) endpoints returning a JSON body with a 2xx status, over HTTP
+or WebSocket, for the configured `methods`. Streams, multi-status (`responses:`) results,
+downstream short-circuit `Response`s, empty (204) bodies, and **multipart/file-upload**
+requests pass through uncached. Replays are emitted at status 200.
+
+See **[`ayepi-cache.md`](./ayepi-cache.md)** for the full reference, and
+[`examples/09-cache`](../../examples/09-cache) for a runnable demo.
+
+## For AI coding agents
+
+This package ships dense, machine-oriented reference docs written for **AI coding agents**
+(Claude Code, Cursor, and the like) to understand and drive the package — point your agent at them:
+
+- [`ayepi-cache.md`](./ayepi-cache.md)
+
+They live next to the source in the [repo](https://github.com/ClickerMonkey/ayepi/tree/main/packages/cache) and are **not** shipped in the npm tarball.
+

package/dist/index.cjs

@@ -0,0 +1,216 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _ayepi_core = require("@ayepi/core");
+//#region src/index.ts
+/**
+* # @ayepi/cache
+*
+* Response-caching middleware for [`@ayepi/core`](https://www.npmjs.com/package/@ayepi/core).
+* {@link cache} builds a middleware that derives a **key from the request** (method +
+* path + query, plus an optional dev-defined `vary` — e.g. the authenticated user) and,
+* on a **hit**, replays the stored response without running the handler. Entries live in
+* memory for a bounded **time** (`ttl`, with optional `stale-while-revalidate`) and a
+* bounded **space** (`maxBytes` / `maxEntryBytes` / `maxEntries`, LRU-evicted).
+*
+* ```ts
+* // shared.ts (frontend-safe): the def declares what it contributes
+* import { cache } from '@ayepi/cache'
+* const cached = cache()                                   // provides { cache } to handlers
+* spec({ endpoints: { ...cached.group({ … }) } })
+*
+* // server.ts: bind the policy (ttl, vary, bounds)
+* import { cache } from '@ayepi/cache/server'
+* implement(api).middleware(cache.server(cached, {
+*   ttl: 30_000,                                           // fresh for 30s
+*   vary: (io) => io.ctx.user.id,                          // per-user cache
+*   maxBytes: 64 * 1024 * 1024,
+* }))
+* ```
+*
+* - **Bounded memory** — the default {@link memoryCache} is an LRU store with total/entry
+*   byte caps and an entry-count cap; dead entries are swept lazily.
+* - **Time controls** — `ttl` (freshness) and `staleWhileRevalidate` (serve-stale grace).
+* - **Customizable** — `key`/`vary`, `methods`, `shouldCache`, response headers, `skip`,
+*   request `Cache-Control` respect, and per-response opt-out via `io.ctx.cache`.
+*
+* @module
+*/
+/** Default middleware name. */
+const DEFAULT_NAME = "cache";
+/** Milliseconds per second — `Age` / `Cache-Control: max-age` are expressed in seconds. */
+const MS_PER_SECOND = 1e3;
+/** Default total cache capacity (bytes) for {@link memoryCache}. */
+const DEFAULT_MAX_BYTES = 64 * 1024 * 1024;
+/** Default per-entry cap (bytes) — larger responses are not cached. */
+const DEFAULT_MAX_ENTRY_BYTES = 1024 * 1024;
+/** Default entry-count cap. */
+const DEFAULT_MAX_ENTRIES = 1e4;
+/**
+* Create an in-process LRU {@link CacheStore} bounded by total bytes, per-entry bytes,
+* and entry count. The default store — fine for a single instance. Most-recently-used
+* on `get`/`set`; when over a bound, evicts least-recently-used entries (or skips a
+* `set` whose entry alone exceeds `maxEntryBytes`).
+*/
+function memoryCache(opts = {}) {
+	const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+	const maxEntryBytes = opts.maxEntryBytes ?? DEFAULT_MAX_ENTRY_BYTES;
+	const maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;
+	const entries = /* @__PURE__ */ new Map();
+	let totalBytes = 0;
+	const drop = (key) => {
+		const e = entries.get(key);
+		if (e) {
+			totalBytes -= e.bytes;
+			entries.delete(key);
+		}
+	};
+	const evictLRU = () => {
+		for (const key of entries.keys()) {
+			if (totalBytes <= maxBytes && entries.size <= maxEntries) break;
+			drop(key);
+		}
+	};
+	return {
+		get(key) {
+			const e = entries.get(key);
+			if (!e) return;
+			entries.delete(key);
+			entries.set(key, e);
+			return e;
+		},
+		set(key, entry) {
+			drop(key);
+			if (entry.bytes > maxEntryBytes) return;
+			entries.set(key, entry);
+			totalBytes += entry.bytes;
+			evictLRU();
+		},
+		delete(key) {
+			const existed = entries.has(key);
+			drop(key);
+			return existed;
+		},
+		clear() {
+			entries.clear();
+			totalBytes = 0;
+		},
+		invalidate(pred) {
+			let removed = 0;
+			for (const e of [...entries.values()]) if (pred(e)) {
+				drop(e.key);
+				removed++;
+			}
+			return removed;
+		}
+	};
+}
+/** Normalize a query input into a stable, order-independent list of `[k, v]` pairs. */
+function normalizeQuery(query) {
+	if (query === void 0) return [];
+	return [...typeof query === "string" ? new URLSearchParams(query) : query instanceof URLSearchParams ? query : new URLSearchParams([...query].map(([k, v]) => [k, v]))].sort((a, b) => a[0] === b[0] ? a[1] < b[1] ? -1 : 1 : a[0] < b[0] ? -1 : 1);
+}
+/** Recursively sort object keys so semantically-equal values serialize identically. */
+function sortDeep(v) {
+	if (Array.isArray(v)) return v.map(sortDeep);
+	if (v && typeof v === "object") {
+		const out = {};
+		for (const k of Object.keys(v).sort()) out[k] = sortDeep(v[k]);
+		return out;
+	}
+	return v;
+}
+/** Deterministic `JSON.stringify` — object keys sorted at every depth, so key order never matters. */
+function stableStringify(value) {
+	return JSON.stringify(sortDeep(value)) ?? "null";
+}
+/**
+* Build a stable cache key from request parts — the same string the middleware uses.
+* Query parameters are sorted and the body is canonicalized (sorted keys at every depth),
+* so equal requests share a key regardless of property order. Exported so you can target
+* {@link CacheStore.delete} after a mutation (e.g. bust a user's cached report).
+*/
+function cacheKey(parts) {
+	return stableStringify([
+		parts.method.toUpperCase(),
+		parts.path,
+		normalizeQuery(parts.query),
+		parts.body ?? null,
+		parts.vary ?? null
+	]);
+}
+/**
+* A fast, **non-cryptographic** hash (cyrb53 → base36) for shrinking a large cache key —
+* pass it as the `hash` option so the store keys on a short digest instead of the full
+* (possibly huge) JSON. Collisions are unlikely but possible; keep `checkKey` on (the
+* default when hashing) to fall through on one, or supply a crypto hash (e.g. sha-256)
+* for stronger guarantees.
+*/
+function hashKey(key) {
+	let h1 = 3735928559;
+	let h2 = 1103547991;
+	for (let i = 0; i < key.length; i++) {
+		const ch = key.charCodeAt(i);
+		h1 = Math.imul(h1 ^ ch, 2654435761);
+		h2 = Math.imul(h2 ^ ch, 1597334677);
+	}
+	h1 = Math.imul(h1 ^ h1 >>> 16, 2246822507) ^ Math.imul(h2 ^ h2 >>> 13, 3266489909);
+	h2 = Math.imul(h2 ^ h2 >>> 16, 2246822507) ^ Math.imul(h1 ^ h1 >>> 13, 3266489909);
+	return (4294967296 * (2097151 & h2) + (h1 >>> 0)).toString(36);
+}
+/**
+* Compute the informational cache headers for an entry: `Age` (seconds since it was
+* stored) and `Cache-Control: max-age` (seconds of freshness remaining). The middleware
+* adds the `X-Cache: HIT|STALE|MISS` marker separately.
+*/
+function cacheHeaders(entry, now) {
+	const age = Math.max(0, Math.floor((now - entry.storedAt) / MS_PER_SECOND));
+	const maxAge = Math.max(0, Math.ceil((entry.expires - now) / MS_PER_SECOND));
+	return {
+		age: String(age),
+		"cache-control": `max-age=${maxAge}`
+	};
+}
+/** The shape core produces for a multi-status (`responses:`) endpoint — `{ status, data }`. */
+function looksMultiStatus(r) {
+	const keys = Object.keys(r);
+	return keys.length === 2 && keys.includes("status") && keys.includes("data") && typeof r.status === "number";
+}
+/**
+* Whether a handler's result is a plain JSON response body the cache can store and
+* replay. `false` for an empty body (`null`/`undefined` → 204), a short-circuit
+* `Response`, a function, a streamed body (async-iterable / `ReadableStream`), or a
+* multi-status `{ status, data }` wrapper (whose replay status would be wrong). Useful in
+* a custom `shouldCache` or a custom {@link CacheStore}.
+*/
+function isCacheableResult(result) {
+	if (result === null || result === void 0) return false;
+	if (result instanceof Response) return false;
+	if (typeof result === "function") return false;
+	if (typeof result === "object") {
+		const o = result;
+		if (typeof o[Symbol.asyncIterator] === "function" || typeof o.getReader === "function") return false;
+		if (looksMultiStatus(result)) return false;
+	}
+	return true;
+}
+/**
+* Create a response-caching middleware **def**. The def declares what the middleware
+* contributes (`{ cache: CacheControl }`) but **no** policy. Bind the
+* ttl/vary/bounds with [`cache.server(def, { ttl })`](./server).
+*
+* @typeParam R - inferred from `requires`; their context types flow into the
+*   server-side `key`/`vary`/`skip`/`shouldCache`.
+*/
+function cache(opts) {
+	return (0, _ayepi_core.middleware)(opts?.name ?? DEFAULT_NAME, {
+		provides: (0, _ayepi_core.ctx)(),
+		requires: opts?.requires ?? []
+	});
+}
+//#endregion
+exports.cache = cache;
+exports.cacheHeaders = cacheHeaders;
+exports.cacheKey = cacheKey;
+exports.hashKey = hashKey;
+exports.isCacheableResult = isCacheableResult;
+exports.memoryCache = memoryCache;
+exports.stableStringify = stableStringify;

package/dist/index.d.cts

@@ -0,0 +1,156 @@
+import { AnyMiddleware, Json, MaybePromise, MiddlewareDef } from "@ayepi/core";
+
+//#region src/index.d.ts
+
+/** A stored response, ready to replay. */
+interface CacheEntry {
+  /** The serialized JSON response body. */
+  readonly body: string;
+  /** The HTTP status to replay (a 2xx). */
+  readonly status: number;
+  /** Response headers to replay (e.g. `content-type`). */
+  readonly headers: readonly (readonly [string, string])[];
+  /** When the entry was stored (ms epoch). */
+  readonly storedAt: number;
+  /** Fresh until this time (ms epoch) — served as a `HIT` before it. */
+  readonly expires: number;
+  /** Serve-stale grace boundary (ms epoch) — `>= expires`; a `STALE` hit until it, then dead. */
+  readonly staleUntil: number;
+  /** The serialized body's byte length (what counts toward the store's space bounds). */
+  readonly bytes: number;
+  /** The request method this entry answers. */
+  readonly method: string;
+  /** The request path this entry answers. */
+  readonly path: string;
+  /** The full cache key (used to double-check against hash collisions); the hashed store key when `checkKey` is off. */
+  readonly key: string;
+}
+/** The subset of an entry exposed to {@link CacheStore.invalidate} predicates. */
+interface EntryMeta {
+  readonly key: string;
+  readonly method: string;
+  readonly path: string;
+  readonly storedAt: number;
+  readonly expires: number;
+  readonly staleUntil: number;
+  readonly bytes: number;
+}
+/**
+ * Pluggable cache backend. The default is the in-process {@link memoryCache}; implement
+ * this interface to back the cache with another store. The store owns **space** (which
+ * entries to keep); the middleware owns **time** (freshness vs `entry.expires`).
+ */
+interface CacheStore {
+  /** Fetch a stored entry (and mark it most-recently-used), or `undefined`. */
+  get(key: string): MaybePromise<CacheEntry | undefined>;
+  /** Store an entry, evicting as needed to stay within the store's bounds. */
+  set(key: string, entry: CacheEntry): MaybePromise<void>;
+  /** Remove one entry; returns whether it existed. */
+  delete(key: string): MaybePromise<boolean>;
+  /** Drop every entry. */
+  clear(): MaybePromise<void>;
+  /** Remove every entry matching `pred`; returns how many were removed. Powers manual invalidation and the time-sweep. */
+  invalidate(pred: (meta: EntryMeta) => boolean): MaybePromise<number>;
+}
+/** Options for {@link memoryCache}. */
+interface MemoryCacheOptions {
+  /** Total capacity in bytes (default 64 MiB) — LRU-evicted when exceeded. */
+  readonly maxBytes?: number;
+  /** Per-entry cap in bytes (default 1 MiB) — larger responses are skipped. */
+  readonly maxEntryBytes?: number;
+  /** Maximum number of entries (default 10 000) — LRU-evicted when exceeded. */
+  readonly maxEntries?: number;
+}
+/**
+ * Create an in-process LRU {@link CacheStore} bounded by total bytes, per-entry bytes,
+ * and entry count. The default store — fine for a single instance. Most-recently-used
+ * on `get`/`set`; when over a bound, evicts least-recently-used entries (or skips a
+ * `set` whose entry alone exceeds `maxEntryBytes`).
+ */
+declare function memoryCache(opts?: MemoryCacheOptions): CacheStore;
+/** The parts a default cache key is built from. */
+interface CacheKeyParts {
+  /** The request method (upper-cased). */
+  readonly method: string;
+  /** The request path. */
+  readonly path: string;
+  /** The query string (raw, e.g. `io` URL search) or parsed entries — normalized by sorting. */
+  readonly query?: string | URLSearchParams | Iterable<readonly [string, string]>;
+  /** The request body (parsed JSON / form object) or ws call args — included so POST-style caches key on the payload. */
+  readonly body?: Json;
+  /** An optional extra discriminator (e.g. the authenticated user id) appended verbatim. */
+  readonly vary?: Json;
+}
+/** Deterministic `JSON.stringify` — object keys sorted at every depth, so key order never matters. */
+declare function stableStringify(value: unknown): string;
+/**
+ * Build a stable cache key from request parts — the same string the middleware uses.
+ * Query parameters are sorted and the body is canonicalized (sorted keys at every depth),
+ * so equal requests share a key regardless of property order. Exported so you can target
+ * {@link CacheStore.delete} after a mutation (e.g. bust a user's cached report).
+ */
+declare function cacheKey(parts: CacheKeyParts): string;
+/**
+ * A fast, **non-cryptographic** hash (cyrb53 → base36) for shrinking a large cache key —
+ * pass it as the `hash` option so the store keys on a short digest instead of the full
+ * (possibly huge) JSON. Collisions are unlikely but possible; keep `checkKey` on (the
+ * default when hashing) to fall through on one, or supply a crypto hash (e.g. sha-256)
+ * for stronger guarantees.
+ */
+declare function hashKey(key: string): string;
+/**
+ * Compute the informational cache headers for an entry: `Age` (seconds since it was
+ * stored) and `Cache-Control: max-age` (seconds of freshness remaining). The middleware
+ * adds the `X-Cache: HIT|STALE|MISS` marker separately.
+ */
+declare function cacheHeaders(entry: CacheEntry, now: number): Record<string, string>;
+/**
+ * Whether a handler's result is a plain JSON response body the cache can store and
+ * replay. `false` for an empty body (`null`/`undefined` → 204), a short-circuit
+ * `Response`, a function, a streamed body (async-iterable / `ReadableStream`), or a
+ * multi-status `{ status, data }` wrapper (whose replay status would be wrong). Useful in
+ * a custom `shouldCache` or a custom {@link CacheStore}.
+ */
+declare function isCacheableResult(result: unknown): boolean;
+/**
+ * The handle a cached endpoint's handler reads as `io.ctx.cache` — present only on a
+ * **miss** (a hit never runs the handler). Use it to opt this response out of caching
+ * ({@link CacheControl.noStore}) or override its lifetime ({@link CacheControl.ttl}).
+ */
+interface CacheControl {
+  /** The cache key computed for this request. */
+  readonly key: string;
+  /** Always `false` here — the handler only runs when the cache missed. */
+  readonly hit: boolean;
+  /** Do not store this response (e.g. it depends on something the key doesn't capture). */
+  noStore(): void;
+  /** Override the freshness lifetime for this response (ms). */
+  ttl(ms: number): void;
+}
+/**
+ * Options for the {@link cache} **def** — frontend-safe only.
+ *
+ * @typeParam R - middleware this one depends on (their context is typed in the
+ *   server-side `key`/`vary`/`skip`/`shouldCache`).
+ */
+interface CacheDefOptions<R extends readonly AnyMiddleware[]> {
+  /** Middleware this one depends on — their context is available (and typed) in `key`/`vary`/`skip`. */
+  readonly requires?: R;
+  /** Middleware name for docs/debugging (default `'cache'`). */
+  readonly name?: string;
+}
+/**
+ * Create a response-caching middleware **def**. The def declares what the middleware
+ * contributes (`{ cache: CacheControl }`) but **no** policy. Bind the
+ * ttl/vary/bounds with [`cache.server(def, { ttl })`](./server).
+ *
+ * @typeParam R - inferred from `requires`; their context types flow into the
+ *   server-side `key`/`vary`/`skip`/`shouldCache`.
+ */
+declare function cache<const R extends readonly AnyMiddleware[] = readonly []>(opts?: CacheDefOptions<R>): CacheDef<R>;
+/** The def type a {@link cache} call produces — what `cache.server` binds against. */
+type CacheDef<R extends readonly AnyMiddleware[] = readonly []> = MiddlewareDef<{
+  cache: CacheControl;
+}, R>;
+//#endregion
+export { CacheControl, CacheDef, CacheDefOptions, CacheEntry, CacheKeyParts, CacheStore, EntryMeta, MemoryCacheOptions, cache, cacheHeaders, cacheKey, hashKey, isCacheableResult, memoryCache, stableStringify };

package/dist/index.d.ts

@@ -0,0 +1,156 @@
+import { AnyMiddleware, Json, MaybePromise, MiddlewareDef } from "@ayepi/core";
+
+//#region src/index.d.ts
+
+/** A stored response, ready to replay. */
+interface CacheEntry {
+  /** The serialized JSON response body. */
+  readonly body: string;
+  /** The HTTP status to replay (a 2xx). */
+  readonly status: number;
+  /** Response headers to replay (e.g. `content-type`). */
+  readonly headers: readonly (readonly [string, string])[];
+  /** When the entry was stored (ms epoch). */
+  readonly storedAt: number;
+  /** Fresh until this time (ms epoch) — served as a `HIT` before it. */
+  readonly expires: number;
+  /** Serve-stale grace boundary (ms epoch) — `>= expires`; a `STALE` hit until it, then dead. */
+  readonly staleUntil: number;
+  /** The serialized body's byte length (what counts toward the store's space bounds). */
+  readonly bytes: number;
+  /** The request method this entry answers. */
+  readonly method: string;
+  /** The request path this entry answers. */
+  readonly path: string;
+  /** The full cache key (used to double-check against hash collisions); the hashed store key when `checkKey` is off. */
+  readonly key: string;
+}
+/** The subset of an entry exposed to {@link CacheStore.invalidate} predicates. */
+interface EntryMeta {
+  readonly key: string;
+  readonly method: string;
+  readonly path: string;
+  readonly storedAt: number;
+  readonly expires: number;
+  readonly staleUntil: number;
+  readonly bytes: number;
+}
+/**
+ * Pluggable cache backend. The default is the in-process {@link memoryCache}; implement
+ * this interface to back the cache with another store. The store owns **space** (which
+ * entries to keep); the middleware owns **time** (freshness vs `entry.expires`).
+ */
+interface CacheStore {
+  /** Fetch a stored entry (and mark it most-recently-used), or `undefined`. */
+  get(key: string): MaybePromise<CacheEntry | undefined>;
+  /** Store an entry, evicting as needed to stay within the store's bounds. */
+  set(key: string, entry: CacheEntry): MaybePromise<void>;
+  /** Remove one entry; returns whether it existed. */
+  delete(key: string): MaybePromise<boolean>;
+  /** Drop every entry. */
+  clear(): MaybePromise<void>;
+  /** Remove every entry matching `pred`; returns how many were removed. Powers manual invalidation and the time-sweep. */
+  invalidate(pred: (meta: EntryMeta) => boolean): MaybePromise<number>;
+}
+/** Options for {@link memoryCache}. */
+interface MemoryCacheOptions {
+  /** Total capacity in bytes (default 64 MiB) — LRU-evicted when exceeded. */
+  readonly maxBytes?: number;
+  /** Per-entry cap in bytes (default 1 MiB) — larger responses are skipped. */
+  readonly maxEntryBytes?: number;
+  /** Maximum number of entries (default 10 000) — LRU-evicted when exceeded. */
+  readonly maxEntries?: number;
+}
+/**
+ * Create an in-process LRU {@link CacheStore} bounded by total bytes, per-entry bytes,
+ * and entry count. The default store — fine for a single instance. Most-recently-used
+ * on `get`/`set`; when over a bound, evicts least-recently-used entries (or skips a
+ * `set` whose entry alone exceeds `maxEntryBytes`).
+ */
+declare function memoryCache(opts?: MemoryCacheOptions): CacheStore;
+/** The parts a default cache key is built from. */
+interface CacheKeyParts {
+  /** The request method (upper-cased). */
+  readonly method: string;
+  /** The request path. */
+  readonly path: string;
+  /** The query string (raw, e.g. `io` URL search) or parsed entries — normalized by sorting. */
+  readonly query?: string | URLSearchParams | Iterable<readonly [string, string]>;
+  /** The request body (parsed JSON / form object) or ws call args — included so POST-style caches key on the payload. */
+  readonly body?: Json;
+  /** An optional extra discriminator (e.g. the authenticated user id) appended verbatim. */
+  readonly vary?: Json;
+}
+/** Deterministic `JSON.stringify` — object keys sorted at every depth, so key order never matters. */
+declare function stableStringify(value: unknown): string;
+/**
+ * Build a stable cache key from request parts — the same string the middleware uses.
+ * Query parameters are sorted and the body is canonicalized (sorted keys at every depth),
+ * so equal requests share a key regardless of property order. Exported so you can target
+ * {@link CacheStore.delete} after a mutation (e.g. bust a user's cached report).
+ */
+declare function cacheKey(parts: CacheKeyParts): string;
+/**
+ * A fast, **non-cryptographic** hash (cyrb53 → base36) for shrinking a large cache key —
+ * pass it as the `hash` option so the store keys on a short digest instead of the full
+ * (possibly huge) JSON. Collisions are unlikely but possible; keep `checkKey` on (the
+ * default when hashing) to fall through on one, or supply a crypto hash (e.g. sha-256)
+ * for stronger guarantees.
+ */
+declare function hashKey(key: string): string;
+/**
+ * Compute the informational cache headers for an entry: `Age` (seconds since it was
+ * stored) and `Cache-Control: max-age` (seconds of freshness remaining). The middleware
+ * adds the `X-Cache: HIT|STALE|MISS` marker separately.
+ */
+declare function cacheHeaders(entry: CacheEntry, now: number): Record<string, string>;
+/**
+ * Whether a handler's result is a plain JSON response body the cache can store and
+ * replay. `false` for an empty body (`null`/`undefined` → 204), a short-circuit
+ * `Response`, a function, a streamed body (async-iterable / `ReadableStream`), or a
+ * multi-status `{ status, data }` wrapper (whose replay status would be wrong). Useful in
+ * a custom `shouldCache` or a custom {@link CacheStore}.
+ */
+declare function isCacheableResult(result: unknown): boolean;
+/**
+ * The handle a cached endpoint's handler reads as `io.ctx.cache` — present only on a
+ * **miss** (a hit never runs the handler). Use it to opt this response out of caching
+ * ({@link CacheControl.noStore}) or override its lifetime ({@link CacheControl.ttl}).
+ */
+interface CacheControl {
+  /** The cache key computed for this request. */
+  readonly key: string;
+  /** Always `false` here — the handler only runs when the cache missed. */
+  readonly hit: boolean;
+  /** Do not store this response (e.g. it depends on something the key doesn't capture). */
+  noStore(): void;
+  /** Override the freshness lifetime for this response (ms). */
+  ttl(ms: number): void;
+}
+/**
+ * Options for the {@link cache} **def** — frontend-safe only.
+ *
+ * @typeParam R - middleware this one depends on (their context is typed in the
+ *   server-side `key`/`vary`/`skip`/`shouldCache`).
+ */
+interface CacheDefOptions<R extends readonly AnyMiddleware[]> {
+  /** Middleware this one depends on — their context is available (and typed) in `key`/`vary`/`skip`. */
+  readonly requires?: R;
+  /** Middleware name for docs/debugging (default `'cache'`). */
+  readonly name?: string;
+}
+/**
+ * Create a response-caching middleware **def**. The def declares what the middleware
+ * contributes (`{ cache: CacheControl }`) but **no** policy. Bind the
+ * ttl/vary/bounds with [`cache.server(def, { ttl })`](./server).
+ *
+ * @typeParam R - inferred from `requires`; their context types flow into the
+ *   server-side `key`/`vary`/`skip`/`shouldCache`.
+ */
+declare function cache<const R extends readonly AnyMiddleware[] = readonly []>(opts?: CacheDefOptions<R>): CacheDef<R>;
+/** The def type a {@link cache} call produces — what `cache.server` binds against. */
+type CacheDef<R extends readonly AnyMiddleware[] = readonly []> = MiddlewareDef<{
+  cache: CacheControl;
+}, R>;
+//#endregion
+export { CacheControl, CacheDef, CacheDefOptions, CacheEntry, CacheKeyParts, CacheStore, EntryMeta, MemoryCacheOptions, cache, cacheHeaders, cacheKey, hashKey, isCacheableResult, memoryCache, stableStringify };