@ayepi/cache 0.1.0

package/dist/server.js

@@ -0,0 +1,177 @@
+import { cache as cache$1, cacheHeaders, cacheKey, isCacheableResult, memoryCache, stableStringify } from "./index.js";
+//#region src/server.ts
+/** The default methods whose responses are cached. */
+const DEFAULT_METHODS = ["GET"];
+/** Replayed responses are served as JSON. */
+const JSON_CONTENT_TYPE = "application/json";
+/** Parse the request `Cache-Control` directives we honor. */
+function parseCacheControl(header) {
+	if (!header) return {
+		noStore: false,
+		noCache: false
+	};
+	const directives = header.toLowerCase().split(",").map((d) => d.trim());
+	return {
+		noStore: directives.includes("no-store"),
+		noCache: directives.includes("no-cache")
+	};
+}
+/** Bind a {@link cache} def to its runtime policy. */
+function cacheServer(def, opts) {
+	const store = opts.store ?? memoryCache(opts);
+	const ttl = opts.ttl;
+	const swr = opts.staleWhileRevalidate ?? 0;
+	const methods = new Set((opts.methods ?? DEFAULT_METHODS).map((m) => m.toUpperCase()));
+	const emitHeaders = opts.headers !== false;
+	const now = opts.now ?? Date.now;
+	const checkKey = opts.checkKey ?? opts.hash !== void 0;
+	const inflight = /* @__PURE__ */ new Set();
+	/** Hand a swallowed error to `onError` (best-effort — a throwing handler is itself ignored). */
+	const reportError = (err, phase) => {
+		try {
+			opts.onError?.(err, phase);
+		} catch {}
+	};
+	const makeControl = (key) => ({
+		key,
+		hit: false,
+		store: true,
+		noStore() {
+			this.store = false;
+		},
+		ttl(ms) {
+			this.ttlOverride = ms;
+		}
+	});
+	/** The full (pre-hash) key — endpoint identity + the request's query/body (or ws args) + `vary`. */
+	const keyOf = (io, route) => {
+		const kio = {
+			req: io.req,
+			ctx: io.ctx
+		};
+		if (opts.key) return stableStringify(opts.key(kio));
+		const vary = opts.vary?.(kio);
+		if (io.transport === "ws") return cacheKey({
+			method: route.method,
+			path: route.path,
+			body: io.ws?.data,
+			vary
+		});
+		const url = new URL(io.req.url);
+		return cacheKey({
+			method: route.method,
+			path: route.path,
+			query: url.searchParams,
+			body: io.body,
+			vary
+		});
+	};
+	const replay = (entry, marker, at) => {
+		const headers = new Headers(entry.headers);
+		if (emitHeaders) {
+			headers.set("x-cache", marker);
+			for (const [k, v] of Object.entries(cacheHeaders(entry, at))) headers.set(k, v);
+		}
+		return new Response(entry.body, {
+			status: entry.status,
+			headers
+		});
+	};
+	/** Serialize + store a handler result, honoring the handler's `io.ctx.cache` opt-out and the store's bounds. */
+	const persist = async (io, storeKey, fullKey, control, result, route) => {
+		if (!control.store) return;
+		if (!isCacheableResult(result)) return;
+		if (opts.shouldCache && !opts.shouldCache({
+			req: io.req,
+			ctx: io.ctx
+		}, result)) return;
+		const body = JSON.stringify(result);
+		const bytes = new TextEncoder().encode(body).length;
+		const at = now();
+		const expires = at + (control.ttlOverride ?? ttl);
+		const entry = {
+			body,
+			status: 200,
+			headers: [["content-type", JSON_CONTENT_TYPE]],
+			storedAt: at,
+			expires,
+			staleUntil: expires + swr,
+			bytes,
+			method: route.method,
+			path: route.path,
+			key: checkKey ? fullKey : storeKey
+		};
+		await store.set(storeKey, entry);
+	};
+	/** Background refresh for a stale entry — single-flight per store key; failures leave the stale entry in place. */
+	const revalidate = (io, storeKey, fullKey, route) => {
+		if (inflight.has(storeKey)) return;
+		inflight.add(storeKey);
+		const control = makeControl(fullKey);
+		Promise.resolve(io.next({ cache: control })).then((result) => persist(io, storeKey, fullKey, control, result, route)).catch((err) => reportError(err, "revalidate")).finally(() => inflight.delete(storeKey));
+	};
+	/** The read phase — key derivation + store lookup. Runs no handler, so any throw here is a pure cache failure. */
+	const decide = async (io) => {
+		const kio = {
+			req: io.req,
+			ctx: io.ctx
+		};
+		const route = io.route;
+		const cc = parseCacheControl(io.req.headers.get("cache-control"));
+		const multipart = io.transport === "http" && (io.req.headers.get("content-type") ?? "").toLowerCase().includes("multipart/form-data");
+		if (route.kind !== "endpoint" || !methods.has(route.method) || opts.skip?.(kio) || cc.noStore || multipart) return { bypass: true };
+		const fullKey = keyOf(io, route);
+		const storeKey = opts.hash ? opts.hash(fullKey) : fullKey;
+		const control = makeControl(fullKey);
+		if (!cc.noCache) {
+			const entry = await store.get(storeKey);
+			if (entry && (!checkKey || entry.key === fullKey)) {
+				const at = now();
+				if (at < entry.expires) return { serve: replay(entry, "HIT", at) };
+				if (at < entry.staleUntil) {
+					revalidate(io, storeKey, fullKey, route);
+					return { serve: replay(entry, "STALE", at) };
+				}
+				await store.delete(storeKey);
+			} else if (entry) await store.delete(storeKey);
+		}
+		return {
+			proceed: true,
+			storeKey,
+			fullKey,
+			route,
+			control
+		};
+	};
+	const run = async (io) => {
+		let decision;
+		try {
+			decision = await decide(io);
+		} catch (err) {
+			reportError(err, "read");
+			return io.next({ cache: makeControl("") });
+		}
+		if ("serve" in decision) return decision.serve;
+		if ("bypass" in decision) return io.next({ cache: makeControl("") });
+		const result = await io.next({ cache: decision.control });
+		try {
+			if (emitHeaders) io.setHeader("x-cache", "MISS");
+			await persist(io, decision.storeKey, decision.fullKey, decision.control, result, decision.route);
+		} catch (err) {
+			reportError(err, "write");
+		}
+		return result;
+	};
+	return {
+		def,
+		impl: run
+	};
+}
+/**
+* The {@link cache} def factory, augmented with a `.server(def, opts)` binder. Import
+* from `@ayepi/cache/server` in your server entry to bind a def created in a
+* frontend-safe spec.
+*/
+const cache = Object.assign(cache$1, { server: cacheServer });
+//#endregion
+export { cache };

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@ayepi/cache",
+  "version": "0.1.0",
+  "description": "Response-caching middleware for @ayepi/core — keyed by request + a dev-defined vary, with time (ttl/stale-while-revalidate) and space (maxBytes/maxEntries) bounds",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ClickerMonkey/ayepi.git",
+    "directory": "packages/cache"
+  },
+  "homepage": "https://github.com/ClickerMonkey/ayepi/tree/main/packages/cache#readme",
+  "bugs": {
+    "url": "https://github.com/ClickerMonkey/ayepi/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./server": {
+      "import": {
+        "types": "./dist/server.d.ts",
+        "default": "./dist/server.js"
+      },
+      "require": {
+        "types": "./dist/server.d.cts",
+        "default": "./dist/server.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "@ayepi/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^2.1.8",
+    "publint": "^0.3.0",
+    "tsdown": "^0.12.0",
+    "vitest": "^2.1.8",
+    "zod": "^4.4.3",
+    "@ayepi/core": "0.1.0"
+  },
+  "keywords": [
+    "ayepi",
+    "@ayepi/core",
+    "cache",
+    "caching",
+    "middleware",
+    "response-cache",
+    "stale-while-revalidate"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --coverage",
+    "publint": "publint"
+  }
+}