Simplify types

Author: ascorbic

demos/cache-handlers/src/worker.ts

@@ -1,19 +1,20 @@
 import { App } from "astro/app";
 import type { SSRManifest } from "astro";
 import { handle, type Runtime } from "@astrojs/cloudflare/handler";
-import type { ExportedHandlerFetchHandler } from "@cloudflare/workers-types";
+import type {
+	ExportedHandler,
+	Response as CFResponse,
+} from "@cloudflare/workers-types";
 import { createCacheHandler } from "cache-handlers";
 
-type CFRequest = Parameters<ExportedHandlerFetchHandler>[0];
-
 export function createExports(manifest: SSRManifest) {
 	const app = new App(manifest);
 	return {
 		default: {
 			async fetch(
-				request: CFRequest,
-				env: Runtime["runtime"]["env"],
-				ctx: Runtime["runtime"]["ctx"],
+				request,
+				env,
+				ctx,
 			) {
 				if (request.method !== "GET") {
 					// Directly invoke Astro for non-GET (no cache)
@@ -23,14 +24,18 @@ export function createExports(manifest: SSRManifest) {
 						request,
 						env,
 						ctx,
-					);
+					) as unknown as Promise<CFResponse>;
 				}
 				const url = new URL(request.url);
 				const cacheHandle = createCacheHandler<
-					CFRequest
+					typeof request,
+					CFResponse
 				>({
 					swr: "background",
-					handler: (req) => handle(manifest, app, req, env, ctx),
+					handler: (req) =>
+						handle(manifest, app, req, env, ctx) as unknown as Promise<
+							CFResponse
+						>,
 					features: {
 						conditionalRequests: { etag: "generate" },
 						cacheStatusHeader: "demo-cache",
@@ -53,8 +58,10 @@ export function createExports(manifest: SSRManifest) {
 						runInBackground: ctx.waitUntil.bind(ctx),
 					});
 				}
-				return cacheHandle(request, { runInBackground: ctx.waitUntil.bind(ctx) });
+				return cacheHandle(request, {
+					runInBackground: ctx.waitUntil.bind(ctx),
+				});
 			},
-		},
+		} satisfies ExportedHandler<Runtime["runtime"]["env"]>,
 	};
 }

packages/cache-handlers/README.md

@@ -196,32 +196,6 @@ createCacheHandler({
 });
 ```
 
-### Stand‑alone Helpers
-
-Exported for advanced/manual workflows:
-
-```ts
-import {
-	compareETags,
-	create304Response,
-	generateETag,
-	getDefaultConditionalConfig,
-	parseETag,
-	validateConditionalRequest,
-} from "cache-handlers";
-```
-
-Example manual validation:
-
-```ts
-const cached = new Response("data", {
-	headers: { etag: await generateETag(new Response("data")) },
-});
-const validation = validateConditionalRequest(request, cached);
-if (validation.shouldReturn304) {
-	return create304Response(cached);
-}
-```
 
 ## Backend-Driven Variations (`Cache-Vary` – custom header)
 
@@ -273,9 +247,7 @@ Notes:
 import type {
 	CacheConfig,
 	CacheHandle,
-	CacheInvokeOptions,
 	ConditionalRequestConfig,
-	ConditionalValidationResult,
 	HandlerFunction,
 	HandlerInfo,
 	HandlerMode,
@@ -320,7 +292,6 @@ Different platforms implement the Web Standard `CacheStorage` API with varying c
 // ✅ Works via undici polyfill
 // ⚠️  In-memory only by default - not persistent across restarts
 // ⚠️  Limited to single process - no cross-process sharing
-// 💡 Consider using Redis or similar for production Node.js deployments
 ```
 
 #### Netlify Edge Functions

packages/cache-handlers/src/conditional.ts

@@ -11,8 +11,6 @@
 import type {
 	ConditionalRequestConfig,
 	ConditionalValidationResult,
-	MinimalRequest,
-	MinimalResponse,
 } from "./types.ts";
 
 /**
@@ -143,12 +141,9 @@ export function parseHttpDate(dateString: string): Date | null {
  * @param config - Conditional request configuration
  * @returns Validation result indicating whether to return 304
  */
-export function validateConditionalRequest<
-	TRequest extends MinimalRequest,
-	TResponse extends MinimalResponse,
->(
-	request: TRequest,
-	cachedResponse: TResponse,
+export function validateConditionalRequest(
+	request: Request,
+	cachedResponse: Response,
 	config: ConditionalRequestConfig = {},
 ): ConditionalValidationResult {
 	const ifNoneMatch = request.headers.get("if-none-match");
@@ -220,9 +215,9 @@ export function validateConditionalRequest<
  * @param cachedResponse - The cached response to base the 304 response on
  * @returns A 304 Not Modified response
  */
-export function create304Response<TResponse extends MinimalResponse>(
-	cachedResponse: TResponse,
-): TResponse {
+export function create304Response(
+	cachedResponse: Response,
+): Response {
 	const headers = new Headers();
 
 	// Headers that MUST be included if they would have been sent in a 200 response
@@ -270,7 +265,7 @@ export function create304Response<TResponse extends MinimalResponse>(
 		status: 304,
 		statusText: "Not Modified",
 		headers,
-	}) as unknown as TResponse;
+	});
 }
 
 /**

packages/cache-handlers/src/handlers.ts

@@ -1,72 +1,80 @@
-import type {
-	CacheConfig,
-	CacheHandle,
-	HandlerFunction,
-	MinimalRequest,
-	MinimalResponse,
-	SWRPolicy,
-} from "./types.ts";
+import type { CacheConfig, CacheHandle, SWRPolicy } from "./types.ts";
 import { readFromCache } from "./read.ts";
 import { writeToCache } from "./write.ts";
 import { createDebugLogger } from "./debug.ts";
 
 export function createCacheHandler<
-	TRequest extends MinimalRequest = Request,
-	TResponse extends MinimalResponse = Response,
+	TRequest = Request,
+	TResponse = Response,
 >(
 	options: CacheConfig<TRequest, TResponse> = {},
 ): CacheHandle<TRequest, TResponse> {
-	const baseHandler: HandlerFunction<TRequest, TResponse> | undefined =
-		options.handler;
-	const debug = createDebugLogger(options.debug);
+	const opts = options as unknown as CacheConfig<Request, Response>;
 
-	const handle: CacheHandle<TRequest, TResponse> = async (
+	const baseHandler = opts.handler;
+	const debug = createDebugLogger(opts.debug);
+
+	const handle: CacheHandle<Request, Response> = async (
 		request,
 		callOpts = {},
-	): Promise<TResponse> => {
+	): Promise<Response> => {
 		// Only cache GET
 		if (request.method !== "GET") {
-			debug.log('handler', `Non-GET request (${request.method}), bypassing cache: ${request.url}`);
+			debug.log(
+				"handler",
+				`Non-GET request (${request.method}), bypassing cache: ${request.url}`,
+			);
 			const handler = callOpts.handler || baseHandler;
 			if (!handler) {
 				return new Response("No handler provided", {
 					status: 500,
-				}) as unknown as TResponse;
+				});
 			}
 			return handler(request, { mode: "miss", background: false });
 		}
 
 		const { cached, needsBackgroundRevalidation } = await readFromCache(
-			request,
-			options,
+			request as Request,
+			opts,
 		);
-		
+
 		if (cached) {
-			debug.logCacheRead(request.url, needsBackgroundRevalidation ? 'stale' : 'hit');
+			debug.logCacheRead(
+				request.url,
+				needsBackgroundRevalidation ? "stale" : "hit",
+			);
 		} else {
-			debug.logCacheRead(request.url, 'miss');
+			debug.logCacheRead(request.url, "miss");
 		}
-		const statusSetting = options.features?.cacheStatusHeader;
+		const statusSetting = opts.features?.cacheStatusHeader;
 		const enableStatus = !!statusSetting;
 		const cacheStatusName =
 			typeof statusSetting === "string" && statusSetting.trim()
 				? statusSetting.trim()
 				: "cache-handlers";
 		if (cached) {
-			const policy: SWRPolicy = callOpts.swr || options.swr || "background";
+			const policy: SWRPolicy = callOpts.swr || opts.swr || "background";
 			if (needsBackgroundRevalidation) {
 				if (policy === "blocking") {
 					const handler = baseHandler || callOpts.handler;
 					if (handler) {
 						try {
-							debug.log('handler', `Blocking revalidation for ${request.url}`);
+							debug.log("handler", `Blocking revalidation for ${request.url}`);
 							const fresh = await handler(request, {
 								mode: "stale",
 								background: false,
 							});
-							return await writeToCache(request, fresh, options);
+							return await writeToCache(
+								request,
+								fresh,
+								opts,
+							);
 						} catch (err) {
-							debug.logError('handler', err as Error, 'SWR blocking revalidation');
+							debug.logError(
+								"handler",
+								err as Error,
+								"SWR blocking revalidation",
+							);
 							console.warn(
 								"SWR blocking revalidation failed; serving stale",
 								err,
@@ -78,18 +86,32 @@ export function createCacheHandler<
 					if (handler) {
 						debug.logBackgroundRevalidation(request.url, true);
 						const scheduler = callOpts.runInBackground ||
-							options.runInBackground;
+							opts.runInBackground;
 						const revalidatePromise = (async () => {
 							try {
-								debug.log('handler', `Background revalidation starting for ${request.url}`);
+								debug.log(
+									"handler",
+									`Background revalidation starting for ${request.url}`,
+								);
 								const response = await handler(request, {
 									mode: "stale",
 									background: true,
 								});
-								await writeToCache(request, response, options);
-								debug.log('handler', `Background revalidation completed for ${request.url}`);
+								await writeToCache(
+									request,
+									response,
+									opts,
+								);
+								debug.log(
+									"handler",
+									`Background revalidation completed for ${request.url}`,
+								);
 							} catch (err) {
-								debug.logError('handler', err as Error, 'SWR background revalidation');
+								debug.logError(
+									"handler",
+									err as Error,
+									"SWR background revalidation",
+								);
 								console.warn("SWR background revalidation failed", err);
 							}
 						})();
@@ -101,10 +123,13 @@ export function createCacheHandler<
 					}
 				} else if (policy === "off") {
 					// Treat stale-while-revalidate as disabled: delete and proceed as miss
-					debug.log('handler', `SWR disabled, deleting stale entry for ${request.url}`);
+					debug.log(
+						"handler",
+						`SWR disabled, deleting stale entry for ${request.url}`,
+					);
 					try {
-						await caches.open(options.cacheName || "cache-primitives-default")
-							.then((c) => c.delete(request as unknown as Request));
+						await caches.open(opts.cacheName || "cache-primitives-default")
+							.then((c) => c.delete(request));
 					} catch (_) {
 						// ignore
 					}
@@ -132,7 +157,7 @@ export function createCacheHandler<
 							status: cached.status,
 							statusText: cached.statusText,
 							headers,
-						}) as unknown as TResponse;
+						});
 					}
 					return cached;
 				}
@@ -152,25 +177,29 @@ export function createCacheHandler<
 						status: cached.status,
 						statusText: cached.statusText,
 						headers,
-					}) as unknown as TResponse;
+					});
 				}
 				return cached;
 			}
 		}
 
 		// Cache miss
-		debug.log('handler', `Cache miss, calling handler for ${request.url}`);
+		debug.log("handler", `Cache miss, calling handler for ${request.url}`);
 		const handler = callOpts.handler || baseHandler;
 		if (!handler) {
 			return new Response("Cache miss and no handler provided", {
 				status: 500,
-			}) as unknown as TResponse;
+			});
 		}
 		const response = await handler(request, {
 			mode: "miss",
 			background: false,
 		});
-		const stored = await writeToCache(request, response, options);
+		const stored = await writeToCache(
+			request as Request,
+			response as Response,
+			opts,
+		);
 		if (enableStatus) {
 			const headers = new Headers(stored.headers as HeadersInit);
 			const parts = [cacheStatusName, "miss"];
@@ -186,10 +215,10 @@ export function createCacheHandler<
 				status: stored.status,
 				statusText: stored.statusText,
 				headers,
-			}) as unknown as TResponse;
+			});
 		}
 		return stored;
 	};
 
-	return handle;
+	return handle as unknown as CacheHandle<TRequest, TResponse>;
 }