@alxia/cache 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steve Tsala
+
+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,144 @@
-# Temporary Holding Version
+# @alxia/cache
 
-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.
+HTTP response caching for [alxia](https://www.npmjs.com/package/@alxia/core),
+with no dependency: fresh responses served again, stale ones served while
+they refresh, one route run for many concurrent misses, tags to empty it,
+ETags and 304s. In memory, or in Redis with
+[`@alxia/redis`](https://www.npmjs.com/package/@alxia/redis)'s
+`redisCacheStore`.
+
+```sh
+bun add @alxia/cache @alxia/core
+bun add -d typescript
+```
+
+## Usage
+
+```ts
+import { cache } from '@alxia/cache';
+import { alxia } from '@alxia/core';
+import { z } from 'zod'; // any Standard Schema validates a body; zod is one
+
+const Product = z.object({ id: z.string(), name: z.string() });
+const catalogue = new Map<string, z.infer<typeof Product>>();
+
+const products = cache({ ttl: 60, staleWhileRevalidate: 300, statuses: [200, 404], tags: () => ['products'] });
+
+const app = alxia()
+	.post('/products', { body: Product }, async ({ body, reply }) => {
+		catalogue.set(body.id, body);
+		await products.invalidateTag('products');           // the next GET runs the route
+		return reply(201, body);
+	})
+	.use(products)                                         // the GETs after it are cached
+	.get('/products', ({ reply }) => reply(200, [...catalogue.values()]))
+	.get('/products/:id', ({ params, cache, reply }) => {
+		cache.tag(`product:${params.id}`);                // a tag of its own
+		const product = catalogue.get(params.id);
+		return product ? reply(200, product) : reply(404, { error: 'not_found' });
+	});
+
+app.listen({ port: 3000 });
+```
+
+## What it does
+
+- **Fresh** (`ttl` seconds): answered from the store, `X-Cache: HIT`.
+- **Stale** (`staleWhileRevalidate` seconds more): answered from the store at
+  once, `X-Cache: STALE`, while one request refreshes it behind.
+- **Missing**: the route runs once, however many requests wait for it, and
+  its response is kept: `X-Cache: MISS`.
+- **A weak `ETag`** from the body when the route set none: a client whose
+  copy is current gets a 304.
+- **Never kept**: a status outside `statuses` (`200`), a response that says
+  `Cache-Control: private` or `no-store`, sets a cookie, or streams events —
+  and one whose route called `cache.skip()`. Nor is it handed to a
+  concurrent request: each runs the route itself.
+- **A store that cannot answer** costs the cache, not the response: the
+  route runs, nothing is kept, and the outage's first error is logged.
+- Only `GET` and `HEAD` — not `QUERY`, whose key would have to include its
+  body; only the routes declared after the plugin.
+
+## The key
+
+The path and the query, by default. A response that differs by a header —
+the language — lists it in `vary`, which keys by its value and says `Vary`:
+
+```ts
+cache({ ttl: 60, vary: ['accept-language', 'cookie'] });
+cache({ ttl: 60, key: (ctx) => (ctx.request.headers.has('authorization') ? undefined : ctx.url.pathname) });
+```
+
+`key` returning `undefined` is not cached: a request with a session, say.
+Whatever the key, `invalidate(path)` forgets every response kept for the
+path and query as the request asked them:
+
+```ts
+await products.invalidate('/products');          // under each `vary` value, or a key of your own
+await products.invalidate('/products?page=2');   // another path: the query is part of it
+```
+
+A `key` or `tags` that reads what an earlier plugin added names it as the
+type argument; an app that does not give it before the cache cannot use it:
+
+```ts
+const perTenant = cache<{ user: { tenantId: string } }>({
+	ttl: 60,
+	key: ({ user, url }) => `${user.tenantId}:${url.pathname}${url.search}`,
+	tags: ({ user }) => [`tenant:${user.tenantId}`],
+});
+
+const auth = alxia().derive(() => ({ user: { tenantId: 'acme' } })); // your session plugin
+
+alxia().use(auth).use(perTenant);   // compiles: auth derives user
+alxia().use(perTenant);             // a compile error: no `user` in this app's context
+```
+
+## Two stores
+
+```ts
+import { MemoryCacheStore } from '@alxia/cache';
+import { redisCacheStore } from '@alxia/redis';
+
+cache({ ttl: 60, store: new MemoryCacheStore({ maxEntries: 5_000, maxBytes: 128 * 1024 * 1024 }) });
+cache({ ttl: 60, store: redisCacheStore(connection.client, { name: 'shop' }) });
+```
+
+The memory store keeps the most recently read responses of one process. The
+Redis store, on `@nxgt/redis`, shares them — and their invalidation —
+across every process. A store of your own implements `CacheStore`: `get`,
+`set`, `delete`, `deleteTag` — and remembers each response's `tags`, which
+`invalidate` relies on too.
+
+## Options
+
+| option | default | |
+| --- | --- | --- |
+| `ttl` | required | seconds fresh |
+| `staleWhileRevalidate` | 0 | seconds served stale while refreshed |
+| `store` | `MemoryCacheStore` | |
+| `key` | path and query | `(ctx) => string \| undefined`; `cache<{ user: User }>(…)` lets it read a `user` an earlier plugin adds |
+| `vary` | none | request headers the response depends on |
+| `statuses` | `[200]` | |
+| `tags` | none | `(ctx) => string[]`, typed like `key` |
+| `honorClientNoCache` | `false` | a client's `no-cache` skips the cache |
+| `debugHeaders` | `true` | `X-Cache` and `Age` |
+
+## API
+
+| export | |
+| --- | --- |
+| `cache<Requires>(options)` | the plugin, with `invalidate(path)`, `invalidateTag(tag)` and `store`; routes after it read `cache.tag()` and `cache.skip()` |
+| `CacheOptions<Requires>` | its options: `ttl`, `staleWhileRevalidate`, `store`, `key`, `vary`, `statuses`, `tags`, `honorClientNoCache`, `debugHeaders` |
+| `defaultKey(path, vary, headers)` | the default key: the path and query, then each varying header's value |
+| `pathTag(path)` | the tag every kept response carries for its path, `alxia:path:<path>`: what `invalidate(path)` deletes |
+| `MemoryCacheStore` | the in-process store: least recently used |
+| `MemoryCacheOptions` | its options: `maxEntries`, `maxBytes` |
+| `CacheStore`, `CachedResponse` | a store's contract |
+| `Cache`, `CacheControls` | the plugin's handles, and what the routes behind it read |
+
+## Documentation
+
+- [Guide](https://github.com/softistx/alxia/tree/develop/packages/cache/docs): a page per area — caching responses and its options, keys and `Vary`, invalidation by path and by tag, and stores, the memory one, Redis, or your own.
+- [Troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/cache/docs/troubleshooting.md): an error message, or a cache that does not hit, and what to do about it.
+- [Roadmap](https://github.com/softistx/alxia/blob/develop/packages/cache/docs/roadmap.md): what is coming, and what is not planned.

package/dist/cache.d.ts

@@ -0,0 +1,74 @@
+import { type BaseContext, type Empty } from '@alxia/core';
+import { type CacheStore } from './store';
+/**
+ * `Requires` is what `key` and `tags` read from the context beyond
+ * `BaseContext` — a `user` an earlier plugin adds — and what the app that
+ * uses the cache must then give.
+ */
+export interface CacheOptions<Requires extends object = Empty> {
+    /** Seconds a response is fresh. */
+    readonly ttl: number;
+    /**
+     * Seconds a response is served stale after, while one request refreshes
+     * it in the background: no client waits for a slow route. None by default.
+     */
+    readonly staleWhileRevalidate?: number;
+    /** Where responses are kept: this process's memory by default. */
+    readonly store?: CacheStore;
+    /**
+     * The key of a request: its path and query by default, and the headers
+     * in `vary`. `undefined` is not cached: a request with a session, say.
+     */
+    readonly key?: (ctx: BaseContext & Requires) => string | undefined;
+    /** Request headers the response varies by: `accept-language`. Each is part of the key, and of `Vary`. */
+    readonly vary?: readonly string[];
+    /** The statuses kept. `200` by default; a 404 may be worth keeping too. */
+    readonly statuses?: readonly number[];
+    /** Tags every response of these routes carries, for `invalidateTag`. */
+    readonly tags?: (ctx: BaseContext & Requires) => readonly string[];
+    /** Whether `Cache-Control: no-cache` from the client skips the cache. Off by default: a client cannot empty yours. */
+    readonly honorClientNoCache?: boolean;
+    /** Says `X-Cache: HIT`, `STALE` or `MISS`, and `Age`. On by default. */
+    readonly debugHeaders?: boolean;
+}
+/** What the routes behind the cache read. */
+export interface CacheControls {
+    /** Tags the response being built, beyond the plugin's `tags`. Tags starting `alxia:` are the plugin's own. */
+    tag(...tags: string[]): void;
+    /** Keeps this response out of the cache. */
+    skip(): void;
+}
+/** A cache of responses, and the hands to empty it. */
+export interface Cache {
+    /**
+     * Forgets every response kept for `path` — `/users/1?x=y`, as the request
+     * asked it — whatever its key: each `vary` value, a `key` of your own.
+     */
+    invalidate(path: string): Promise<void>;
+    /** Forgets every response tagged `tag`. */
+    invalidateTag(tag: string): Promise<void>;
+    readonly store: CacheStore;
+}
+/**
+ * Responses kept and served again, as a plugin: a `GET` to a route declared
+ * after it is answered from the store while fresh, and from the route
+ * otherwise. Concurrent misses run the route once. Stale, it is served at
+ * once and refreshed behind. A response that says `no-store` or `private`,
+ * sets a cookie, or has another status is never kept.
+ *
+ * Every kept response gets a weak `ETag` from its body when it has none, so
+ * a client whose copy is current gets a 304.
+ *
+ * ```ts
+ * const products = cache({ ttl: 60, staleWhileRevalidate: 300, tags: () => ['products'] });
+ * app.use(products).get('/products', ...);
+ * await products.invalidateTag('products');
+ * ```
+ *
+ * A `key` or `tags` that reads what an earlier plugin added names it, and
+ * the app must then give it: `cache<{ user: User }>({ tags: ({ user }) => [user.id], … })`.
+ */
+export declare function cache<Requires extends object = Empty>(options: CacheOptions<Requires>): import("@alxia/core").Alxia<Requires & {
+    cache: CacheControls;
+}, Empty, "", never> & import("@alxia/core").Requiring<Requires> & Cache;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAgB,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAQzE,OAAO,EAAE,KAAK,UAAU,EAAoB,MAAM,SAAS,CAAC;AAE5D;;;;GAIG;AACH,MAAM,WAAW,YAAY,CAAC,QAAQ,SAAS,MAAM,GAAG,KAAK;IAC5D,mCAAmC;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,kEAAkE;IAClE,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,GAAG,QAAQ,KAAK,MAAM,GAAG,SAAS,CAAC;IACnE,yGAAyG;IACzG,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,wEAAwE;IACxE,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,GAAG,QAAQ,KAAK,SAAS,MAAM,EAAE,CAAC;IACnE,sHAAsH;IACtH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC,wEAAwE;IACxE,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,6CAA6C;AAC7C,MAAM,WAAW,aAAa;IAC7B,8GAA8G;IAC9G,GAAG,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC7B,4CAA4C;IAC5C,IAAI,IAAI,IAAI,CAAC;CACb;AAED,uDAAuD;AACvD,MAAM,WAAW,KAAK;IACrB;;;OAGG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,2CAA2C;IAC3C,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,KAAK,CAAC,QAAQ,SAAS,MAAM,GAAG,KAAK,EACpD,OAAO,EAAE,YAAY,CAAC,QAAQ,CAAC;;yEA8E/B"}

package/dist/control.d.ts

@@ -0,0 +1,16 @@
+/** What each route behind the cache says through `ctx.cache`, kept by request. */
+/** What a route said through `ctx.cache`, for the response it is building. */
+export interface Control {
+    readonly tags: string[];
+    skipped: boolean;
+}
+export declare function requestControls(): {
+    /** What the route said for `request`, once it has run. */
+    get: (request: Request) => Control | undefined;
+    /** A fresh control for `request`, and the hands a route is given to it. */
+    open(request: Request): {
+        tag: (...tags: string[]) => void;
+        skip: () => void;
+    };
+};
+//# sourceMappingURL=control.d.ts.map

package/dist/control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control.d.ts","sourceRoot":"","sources":["../src/control.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAElF,8EAA8E;AAC9E,MAAM,WAAW,OAAO;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;CACjB;AAED,wBAAgB,eAAe;IAG7B,0DAA0D;mBAC3C,OAAO,KAAG,OAAO,GAAG,SAAS;IAC5C,2EAA2E;kBAC7D,OAAO;uBAIJ,MAAM,EAAE;;;EAS1B"}

package/dist/flight.d.ts

@@ -0,0 +1,24 @@
+import type { CachedResponse } from './store';
+/** What a run of the route gives: a response it kept, or its own when it kept nothing. */
+export type Loaded = {
+    kept: CachedResponse;
+} | {
+    own: Response;
+};
+/**
+ * Runs the route once for every concurrent miss of a key. Only a response
+ * that is kept is shared: one that is not — private, skipped, a cookie,
+ * another status — answers the request that ran the route, and every other
+ * waiting request runs the route itself, through its own `next`.
+ */
+export declare function singleFlight(): {
+    /** Whether a run of `key` is under way. */
+    has: (key: string) => boolean;
+    load(key: string, run: () => Promise<Loaded>, next: () => Promise<Response>): Promise<CachedResponse | Response>;
+};
+/**
+ * A stale response's refresh, run behind it: the route's own error is its to
+ * log, and a response it does not keep is read by no one.
+ */
+export declare function refreshBehind(loading: Promise<CachedResponse | Response>): void;
+//# sourceMappingURL=flight.d.ts.map

package/dist/flight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flight.d.ts","sourceRoot":"","sources":["../src/flight.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,0FAA0F;AAC1F,MAAM,MAAM,MAAM,GAAG;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,QAAQ,CAAA;CAAE,CAAC;AAElE;;;;;GAKG;AACH,wBAAgB,YAAY;IAI1B,2CAA2C;eAChC,MAAM,KAAG,OAAO;cAErB,MAAM,OACN,MAAM,OAAO,CAAC,MAAM,CAAC,QACpB,MAAM,OAAO,CAAC,QAAQ,CAAC,GAC3B,OAAO,CAAC,cAAc,GAAG,QAAQ,CAAC;EAoBtC;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC5B,OAAO,EAAE,OAAO,CAAC,cAAc,GAAG,QAAQ,CAAC,GACzC,IAAI,CAMN"}

package/dist/guard.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A store that cannot answer is a miss, or keeps nothing: a cache is never
+ * worth a 500. Said to the log once per outage — again only after the store
+ * has answered since.
+ */
+export declare function storeGuard(): <T>(work: () => Promise<T> | T, fallback: T) => Promise<T>;
+//# sourceMappingURL=guard.d.ts.map

package/dist/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,UAAU,KAEX,CAAC,EAAE,MAAM,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,UAAU,CAAC,KAAG,OAAO,CAAC,CAAC,CAAC,CAWrE"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { type Cache, type CacheControls, type CacheOptions, cache, } from './cache';
+export { defaultKey, pathTag } from './keys';
+export { type CachedResponse, type CacheStore, type MemoryCacheOptions, MemoryCacheStore, } from './store';
+//# 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,OAAO,EACN,KAAK,KAAK,EACV,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,GACL,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,EACN,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,gBAAgB,GAChB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,276 @@
+// src/cache.ts
+import { definePlugin } from "@alxia/core";
+
+// src/control.ts
+function requestControls() {
+  const controls = new WeakMap;
+  return {
+    get: (request) => controls.get(request),
+    open(request) {
+      const control = { tags: [], skipped: false };
+      controls.set(request, control);
+      return {
+        tag: (...tags) => {
+          control.tags.push(...tags);
+        },
+        skip: () => {
+          control.skipped = true;
+        }
+      };
+    }
+  };
+}
+
+// src/flight.ts
+function singleFlight() {
+  const loading = new Map;
+  return {
+    has: (key) => loading.has(key),
+    load(key, run, next) {
+      const running = loading.get(key);
+      if (running !== undefined) {
+        return running.then((cached) => cached ?? next(), () => next());
+      }
+      const ran = run();
+      const shared = ran.then((loaded) => ("kept" in loaded) ? loaded.kept : undefined);
+      loading.set(key, shared);
+      shared.finally(() => loading.delete(key)).catch(() => {});
+      return ran.then((loaded) => ("kept" in loaded) ? loaded.kept : loaded.own);
+    }
+  };
+}
+function refreshBehind(loading) {
+  loading.then((loaded) => loaded instanceof Response ? loaded.body?.cancel() : undefined).catch((error) => console.error(error));
+}
+
+// src/guard.ts
+function storeGuard() {
+  let failing = false;
+  return async (work, fallback) => {
+    try {
+      const value = await work();
+      failing = false;
+      return value;
+    } catch (error) {
+      if (!failing)
+        console.error(error);
+      failing = true;
+      return fallback;
+    }
+  };
+}
+
+// src/keep.ts
+import { vary as addVary } from "@alxia/core";
+var PRIVATE = /\b(no-store|private)\b/i;
+function keepable(response, control, statuses) {
+  return !(control?.skipped || !statuses.has(response.status) || PRIVATE.test(response.headers.get("cache-control") ?? "") || response.headers.has("set-cookie") || response.headers.get("content-type")?.startsWith("text/event-stream"));
+}
+async function toCached(response, keep) {
+  const body = new Uint8Array(await response.arrayBuffer());
+  const headers = new Headers(response.headers);
+  headers.delete("content-length");
+  headers.delete("date");
+  if (!headers.has("etag")) {
+    headers.set("etag", `W/"${Bun.hash(body).toString(36)}"`);
+  }
+  for (const name of keep.vary)
+    addVary(headers, name);
+  return {
+    status: response.status,
+    headers: [...headers],
+    body,
+    storedAt: Date.now(),
+    ttl: keep.ttl,
+    stale: keep.stale,
+    tags: keep.tags()
+  };
+}
+
+// src/keys.ts
+var pathTag = (path) => `alxia:path:${path}`;
+function defaultKey(path, vary, headers) {
+  if (vary.length === 0)
+    return path;
+  return `${path}|${vary.map((name) => `${name}=${headers.get(name) ?? ""}`).join("|")}`;
+}
+
+// src/lookup.ts
+function bypasses(request, honorClientNoCache) {
+  if (request.method !== "GET" && request.method !== "HEAD")
+    return true;
+  return honorClientNoCache && /\bno-cache\b/i.test(request.headers.get("cache-control") ?? "");
+}
+function freshness(found, now = Date.now()) {
+  const age = now - found.storedAt;
+  if (age < found.ttl)
+    return "fresh";
+  if (age < found.ttl + found.stale)
+    return "stale";
+  return;
+}
+
+// src/respond.ts
+function respond(request, cached, state) {
+  const headers = new Headers(cached.headers);
+  if (state !== undefined) {
+    headers.set("x-cache", state);
+    headers.set("age", String(Math.max(0, Math.floor((Date.now() - cached.storedAt) / 1000))));
+  }
+  const etag = headers.get("etag");
+  const match = request.headers.get("if-none-match");
+  if (etag !== null && match !== null) {
+    const weak = (tag) => tag.trim().replace(/^W\//, "");
+    if (match.split(",").some((tag) => tag.trim() === "*" || weak(tag) === weak(etag))) {
+      return new Response(null, { status: 304, headers });
+    }
+  }
+  return new Response(cached.status === 204 ? null : cached.body, {
+    status: cached.status,
+    headers
+  });
+}
+
+// src/store.ts
+class MemoryCacheStore {
+  #entries = new Map;
+  #tags = new Map;
+  #maxEntries;
+  #maxBytes;
+  #bytes = 0;
+  constructor(options = {}) {
+    this.#maxEntries = options.maxEntries ?? 1000;
+    this.#maxBytes = options.maxBytes ?? 64 * 1024 * 1024;
+  }
+  get(key) {
+    const entry = this.#entries.get(key);
+    if (entry === undefined)
+      return;
+    if (entry.expiresAt <= Date.now()) {
+      this.delete(key);
+      return;
+    }
+    this.#entries.delete(key);
+    this.#entries.set(key, entry);
+    return entry.value;
+  }
+  set(key, value, keepFor) {
+    this.delete(key);
+    if (value.body.byteLength > this.#maxBytes)
+      return;
+    this.#entries.set(key, { value, expiresAt: Date.now() + keepFor });
+    this.#bytes += value.body.byteLength;
+    for (const tag of value.tags) {
+      let keys = this.#tags.get(tag);
+      if (keys === undefined) {
+        keys = new Set;
+        this.#tags.set(tag, keys);
+      }
+      keys.add(key);
+    }
+    for (const oldest of this.#entries.keys()) {
+      if (this.#entries.size <= this.#maxEntries && this.#bytes <= this.#maxBytes)
+        break;
+      this.delete(oldest);
+    }
+  }
+  delete(key) {
+    const entry = this.#entries.get(key);
+    if (entry === undefined)
+      return;
+    this.#entries.delete(key);
+    this.#bytes -= entry.value.body.byteLength;
+    for (const tag of entry.value.tags) {
+      const keys = this.#tags.get(tag);
+      keys?.delete(key);
+      if (keys?.size === 0)
+        this.#tags.delete(tag);
+    }
+  }
+  deleteTag(tag) {
+    for (const key of [...this.#tags.get(tag) ?? []])
+      this.delete(key);
+  }
+  get size() {
+    return this.#entries.size;
+  }
+}
+
+// src/cache.ts
+function cache(options) {
+  const store = options.store ?? new MemoryCacheStore;
+  const ttl = options.ttl * 1000;
+  const stale = (options.staleWhileRevalidate ?? 0) * 1000;
+  const vary = (options.vary ?? []).map((name) => name.toLowerCase());
+  const statuses = new Set(options.statuses ?? [200]);
+  const debug = options.debugHeaders ?? true;
+  const honorNoCache = options.honorClientNoCache ?? false;
+  const keyOf = options.key ?? ((ctx) => defaultKey(`${ctx.url.pathname}${ctx.url.search}`, vary, ctx.request.headers));
+  const controls = requestControls();
+  const attempt = storeGuard();
+  const flight = singleFlight();
+  const keepOnMiss = async (key, ctx, next) => {
+    const response = await next();
+    const control = controls.get(ctx.request);
+    if (!keepable(response, control, statuses))
+      return { own: response };
+    const cached = await toCached(response, {
+      ttl,
+      stale,
+      vary,
+      tags: () => [
+        ...options.tags?.(ctx) ?? [],
+        ...control?.tags ?? [],
+        pathTag(`${ctx.url.pathname}${ctx.url.search}`)
+      ]
+    });
+    await attempt(() => store.set(key, cached, ttl + stale), undefined);
+    return { kept: cached };
+  };
+  const load = (key, ctx, next) => flight.load(key, () => keepOnMiss(key, ctx, next), next);
+  const label = (says) => debug ? says : undefined;
+  const plugin = definePlugin()((app) => app.derive(({ request }) => {
+    const cacheControls = controls.open(request);
+    return { cache: cacheControls };
+  }).wrap(async (ctx, next) => {
+    const { request } = ctx;
+    const key = bypasses(request, honorNoCache) ? undefined : keyOf(ctx);
+    if (key === undefined)
+      return next();
+    const found = await attempt(() => store.get(key), undefined);
+    const worth = found === undefined ? undefined : freshness(found);
+    if (found !== undefined && worth === "fresh") {
+      return respond(request, found, label("HIT"));
+    }
+    if (found !== undefined && worth === "stale") {
+      if (!flight.has(key))
+        refreshBehind(load(key, ctx, next));
+      return respond(request, found, label("STALE"));
+    }
+    const loaded = await load(key, ctx, next);
+    if (loaded instanceof Response)
+      return loaded;
+    return respond(request, loaded, label("MISS"));
+  }));
+  return Object.assign(plugin, handlesOf(store));
+}
+function handlesOf(store) {
+  return {
+    store,
+    invalidate: async (path) => {
+      await store.deleteTag(pathTag(path));
+    },
+    invalidateTag: async (tag) => {
+      await store.deleteTag(tag);
+    }
+  };
+}
+export {
+  MemoryCacheStore,
+  cache,
+  defaultKey,
+  pathTag
+};
+
+//# debugId=01EFC24056EEAC7464756E2164756E21
+//# sourceMappingURL=index.js.map