Merge branch 'main' into add-cache-handlers

Author: ascorbic

.changeset/README.md

@@ -1,11 +1,5 @@
 # Changesets
 
-Hello and welcome! This folder has been automatically generated by
-`@changesets/cli`, a build tool that works with multi-package repos, or
-single-package repos to help you version and publish your code. You can find the
-full documentation for it
-[in our repository](https://github.com/changesets/changesets)
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works with multi-package repos, or single-package repos to help you version and publish your code. You can find the full documentation for it [in our repository](https://github.com/changesets/changesets)
 
-We have a quick list of common questions to get you started engaging with this
-project in
-[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)
+We have a quick list of common questions to get you started engaging with this project in [our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

.prettierignore

@@ -1,8 +1,6 @@
 {
 	"typescript.tsdk": "node_modules/typescript/lib",
-	"deno.enablePaths": [
-		"packages/cache-handlers/"
-	],
+	"deno.enable": true,
 	"deno.config": "./deno.json",
 	"deno.suggest.imports.hosts": {
 		"https://deno.land": true,
@@ -13,5 +11,9 @@
 	},
 	"[javascript]": {
 		"editor.defaultFormatter": "denoland.vscode-deno"
-	}
+	},
+	"prettier.enable": false,
+	"deno.enablePaths": [
+		"packages"
+	]
 }

.prettierrc

@@ -1,26 +1,22 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with
-code in this repository.
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
 ## Repository Structure
 
 This is a monorepo for CDN cache control libraries using pnpm workspaces:
 
 - **Root**: Workspace configuration and shared tooling
 - **packages/**: Individual library packages
-  - `cdn-cache-control`: Easy, opinionated CDN cache header handling (TypeScript
-    class-based API)
-  - `cache-handlers`: Modern CDN cache primitives using web-standard middleware
-    (functional API)
+  - `cdn-cache-control`: Easy, opinionated CDN cache header handling (TypeScript class-based API)
+  - `cache-handlers`: Modern CDN cache primitives using web-standard middleware (functional API)
 
 ## Commands
 
 ### Root-level commands (run from repository root):
 
 - `pnpm build` - Build all packages
-- `pnpm test` - Run tests for all packages (includes Deno, Node.js, and Workerd
-  tests)
+- `pnpm test` - Run tests for all packages (includes Deno, Node.js, and Workerd tests)
 - `pnpm check` - Run type checking and linting for all packages
 - `pnpm lint` - Run linting for all packages
 - `pnpm format` - Format code using Prettier
@@ -41,8 +37,7 @@ This is a monorepo for CDN cache control libraries using pnpm workspaces:
 ## Development Workflow
 
 - Uses **pnpm** as package manager
-- **tsdown** for building TypeScript packages with ESM output and declaration
-  files
+- **tsdown** for building TypeScript packages with ESM output and declaration files
 - **deno** for testing
 - **publint** and **@arethetypeswrong/cli** for package validation
 - **Prettier** for code formatting (configured to use tabs in `.prettierrc`)
@@ -65,8 +60,7 @@ This is a monorepo for CDN cache control libraries using pnpm workspaces:
   - HTTP conditional requests (ETag, Last-Modified, 304 responses)
   - Cache invalidation by tags and paths
   - Multi-runtime support (Deno, Node.js, Cloudflare Workers)
-- **Testing**: Multi-runtime (Deno tests, Node.js via Vitest, Workerd via
-  Vitest)
+- **Testing**: Multi-runtime (Deno tests, Node.js via Vitest, Workerd via Vitest)
 - **Build**: ESM-only output
 
 Each package follows this structure:
@@ -82,22 +76,15 @@ Uses strict TypeScript configuration with:
 
 - Target: ES2022
 - Module: preserve (for bundler compatibility)
-- Strict mode with additional safety checks (`noUncheckedIndexedAccess`,
-  `noImplicitOverride`)
+- Strict mode with additional safety checks (`noUncheckedIndexedAccess`, `noImplicitOverride`)
 - Library-focused settings (declaration files, declaration maps)
 
 ## Use Specialized Agents for Complex Tasks
 
 ALWAYS use the appropriate specialized agents for complex work:
 
-- **technical-architect**: For designing system architecture, evaluating
-  technical approaches, planning major features
-- **code-reviewer**: For comprehensive code review after implementing
-  significant code changes
-- **test-engineer**: For analyzing test failures, creating new tests, and
-  enhancing test coverage. Should NOT fix application code - only
-  creates/updates test files
-- **docs-author**: For creating or updating documentation, READMEs, changesets,
-  or PR descriptions
-- **package-installer**: For installing npm packages with proper dependency
-  management
+- **technical-architect**: For designing system architecture, evaluating technical approaches, planning major features
+- **code-reviewer**: For comprehensive code review after implementing significant code changes
+- **test-engineer**: For analyzing test failures, creating new tests, and enhancing test coverage. Should NOT fix application code - only creates/updates test files
+- **docs-author**: For creating or updating documentation, READMEs, changesets, or PR descriptions
+- **package-installer**: For installing npm packages with proper dependency management

.vscode/settings.json

@@ -1,7 +1,6 @@
 # cache-primitives
 
-This repository is a monorepo containing several packages related to CDN cache
-control.
+This repository is a monorepo containing several packages related to CDN cache control.
 
 ## Packages
 

CLAUDE.md

@@ -7,6 +7,7 @@
 		"useTabs": true,
 		"useBraces": "always",
 		"singleBodyPosition": "nextLine",
+		"proseWrap": "never",
 		"exclude": [
 			"**/*/package.json",
 			"pnpm-lock.yaml",

README.md

@@ -1,23 +1,14 @@
 # cache-handlers
 
-Unified, modern HTTP caching + invalidation + conditional requests built
-directly on standard Web APIs (`Request`, `Response`, `CacheStorage`). One small
-API: `createCacheHandler` – works on Cloudflare Workers, Netlify Edge, Deno,
-workerd, and Node 20+ (with Undici polyfills).
+Unified, modern HTTP caching + invalidation + conditional requests built directly on standard Web APIs (`Request`, `Response`, `CacheStorage`). One small API: `createCacheHandler` – works on Cloudflare Workers, Netlify Edge, Deno, workerd, and Node 20+ (with Undici polyfills).
 
 ## Highlights
 
-- Single handler: read -> serve (fresh/stale) -> optional background revalidate
-  (SWR) -> write
-- Uses only standard headers for core caching logic: `Cache-Control` (+
-  `stale-while-revalidate`), `CDN-Cache-Control`, `Cache-Tag`, `Vary`, `ETag`,
-  `Last-Modified`
-- Optional custom extension header: `Cache-Vary` (library-defined – lets your
-  backend declare specific header/cookie/query components for key derivation
-  without bloating the standard `Vary` header)
+- Single handler: read -> serve (fresh/stale) -> optional background revalidate (SWR) -> write
+- Uses only standard headers for core caching logic: `Cache-Control` (+ `stale-while-revalidate`), `CDN-Cache-Control`, `Cache-Tag`, `Vary`, `ETag`, `Last-Modified`
+- Optional custom extension header: `Cache-Vary` (library-defined – lets your backend declare specific header/cookie/query components for key derivation without bloating the standard `Vary` header)
 - Stale-While-Revalidate implemented purely via directives (no custom headers)
-- Tag & path invalidation helpers (`invalidateByTag`, `invalidateByPath`,
-  `invalidateAll` + stats)
+- Tag & path invalidation helpers (`invalidateByTag`, `invalidateByPath`, `invalidateAll` + stats)
 - Optional automatic ETag generation & conditional 304 responses
 - Backend-driven Vary via custom `Cache-Vary` (header= / cookie= / query=)
 - Zero runtime dependencies, ESM only, fully typed
@@ -63,15 +54,12 @@ addEventListener("fetch", (event: FetchEvent) => {
 1. Request arrives; cache checked (GET only is cached)
 2. Miss -> `handler` runs, response cached
 3. Hit & still fresh -> served instantly
-4. Expired but inside `stale-while-revalidate` window -> stale response served,
-   background revalidation queued
-5. Conditional client request (If-None-Match / If-Modified-Since) may yield a
-   304
+4. Expired but inside `stale-while-revalidate` window -> stale response served, background revalidation queued
+5. Conditional client request (If-None-Match / If-Modified-Since) may yield a 304
 
 ## Node 20+ Usage (Undici Polyfill)
 
-Node 20 ships `fetch` et al, but _not_ `caches` yet. Use `undici` to polyfill
-CacheStorage.
+Node 20 ships `fetch` et al, but _not_ `caches` yet. Use `undici` to polyfill CacheStorage.
 
 ```ts
 import { createServer } from "node:http";
@@ -146,9 +134,7 @@ Just send the directive in your upstream response:
 Cache-Control: public, max-age=30, stale-while-revalidate=300
 ```
 
-No custom headers are added. While inside the SWR window the _stale_ cached
-response is returned immediately and a background revalidation run is triggered
-(if a `handler` was supplied).
+No custom headers are added. While inside the SWR window the _stale_ cached response is returned immediately and a background revalidation run is triggered (if a `handler` was supplied).
 
 To use a runtime scheduler (eg Workers' `event.waitUntil`):
 
@@ -245,21 +231,15 @@ if (validation.shouldReturn304) {
 
 ## Backend-Driven Variations (`Cache-Vary` – custom header)
 
-`Cache-Vary` is a _non-standard_, library-specific response header. It augments
-the standard `Vary` mechanism by letting you list only the precise components
-you want included in the cache key (headers, cookies, query params) without
-emitting a large `Vary` header externally. The library consumes & strips it when
-constructing the internal key.
+`Cache-Vary` is a _non-standard_, library-specific response header. It augments the standard `Vary` mechanism by letting you list only the precise components you want included in the cache key (headers, cookies, query params) without emitting a large `Vary` header externally. The library consumes & strips it when constructing the internal key.
 
 Add selective vary dimensions without inflating the standard `Vary` header:
 
 ```http
 Cache-Vary: header=Accept-Language, cookie=session_id, query=version
 ```
 
-Each listed dimension becomes part of the derived cache key. Standard `Vary`
-remains fully respected; `Cache-Vary` is additive and internal – safe to use
-even if unknown to intermediaries.
+Each listed dimension becomes part of the derived cache key. Standard `Vary` remains fully respected; `Cache-Vary` is additive and internal – safe to use even if unknown to intermediaries.
 
 ## Types
 

deno.json

@@ -95,7 +95,6 @@ export default async function handler(req: Request) => {
   });
   return new Response("Purged!", { status: 202 })
 };
-
 ```
 
 #### Using the generated headers
@@ -106,9 +105,9 @@ The headers object can be used anywhere that accepts a `fetch` `Headers` object.
 import { CacheHeaders } from "cdn-cache-control";
 
 export default async function handler(request: Request): Promise<Response> {
-  const headers = new CacheHeaders().swr();
-  // The `Response` constructor accepts the object directly
-  return new Response("Hello", { headers });
+	const headers = new CacheHeaders().swr();
+	// The `Response` constructor accepts the object directly
+	return new Response("Hello", { headers });
 }
 ```
 
@@ -120,7 +119,6 @@ import { CacheHeaders, ONE_HOUR } from "cdn-cache-control";
 
 new CacheHeaders().swr(ONE_HOUR).copyTo(Astro.response.headers);
 ---
-
 ```
 
 ## API
@@ -181,32 +179,32 @@ Number of seconds in one year
 
 - [Installation](#installation)
 - [Usage](#usage)
-	- [Use cases](#use-cases)
-		- [stale-while-revalidate](#stale-while-revalidate)
-		- [Immutable content](#immutable-content)
-		- [Cache tags](#cache-tags)
-		- [Using the generated headers](#using-the-generated-headers)
+  - [Use cases](#use-cases)
+    - [stale-while-revalidate](#stale-while-revalidate)
+    - [Immutable content](#immutable-content)
+    - [Cache tags](#cache-tags)
+    - [Using the generated headers](#using-the-generated-headers)
 - [API](#api)
 - [:wrench: Constants](#wrench-constants)
-	- [:gear: ONE\_MINUTE](#gear-one_minute)
-	- [:gear: ONE\_HOUR](#gear-one_hour)
-	- [:gear: ONE\_DAY](#gear-one_day)
-	- [:gear: ONE\_WEEK](#gear-one_week)
-	- [:gear: ONE\_YEAR](#gear-one_year)
+  - [:gear: ONE\_MINUTE](#gear-one_minute)
+  - [:gear: ONE\_HOUR](#gear-one_hour)
+  - [:gear: ONE\_DAY](#gear-one_day)
+  - [:gear: ONE\_WEEK](#gear-one_week)
+  - [:gear: ONE\_YEAR](#gear-one_year)
 - [:factory: CacheHeaders](#factory-cacheheaders)
-	- [Methods](#methods)
-		- [:gear: tag](#gear-tag)
-		- [:gear: swr](#gear-swr)
-		- [:gear: immutable](#gear-immutable)
-		- [:gear: ttl](#gear-ttl)
-		- [:gear: toObject](#gear-toobject)
-		- [:gear: copyTo](#gear-copyto)
-		- [:gear: getCdnCacheControl](#gear-getcdncachecontrol)
-		- [:gear: setCdnCacheControl](#gear-setcdncachecontrol)
-		- [:gear: getCacheControl](#gear-getcachecontrol)
-		- [:gear: setCacheControl](#gear-setcachecontrol)
-		- [:gear: getCacheTags](#gear-getcachetags)
-		- [:gear: setCacheTags](#gear-setcachetags)
+  - [Methods](#methods)
+    - [:gear: tag](#gear-tag)
+    - [:gear: swr](#gear-swr)
+    - [:gear: immutable](#gear-immutable)
+    - [:gear: ttl](#gear-ttl)
+    - [:gear: toObject](#gear-toobject)
+    - [:gear: copyTo](#gear-copyto)
+    - [:gear: getCdnCacheControl](#gear-getcdncachecontrol)
+    - [:gear: setCdnCacheControl](#gear-setcdncachecontrol)
+    - [:gear: getCacheControl](#gear-getcachecontrol)
+    - [:gear: setCacheControl](#gear-setcachecontrol)
+    - [:gear: getCacheTags](#gear-getcachetags)
+    - [:gear: setCacheTags](#gear-setcachetags)
 
 #### :gear: tag
 
@@ -222,8 +220,7 @@ Parameters:
 
 #### :gear: swr
 
-Sets stale-while-revalidate directive for the CDN cache. By default the browser is sent a must-revalidate
-directive to ensure that the browser always revalidates the cache with the server.
+Sets stale-while-revalidate directive for the CDN cache. By default the browser is sent a must-revalidate directive to ensure that the browser always revalidates the cache with the server.
 
 | Method | Type                       |
 | ------ | -------------------------- |
@@ -235,10 +232,7 @@ Parameters:
 
 #### :gear: immutable
 
-Sets cache headers for content that should be cached for a long time and never revalidated.
-The CDN cache will cache the content for the specified time, and the browser will cache the content
-indefinitely without revalidating. Do not use this unless the URL is fingerprinted or otherwise unique.
-Otherwise, the browser will cache the content indefinitely and never check for updates, including for new deploys.
+Sets cache headers for content that should be cached for a long time and never revalidated. The CDN cache will cache the content for the specified time, and the browser will cache the content indefinitely without revalidating. Do not use this unless the URL is fingerprinted or otherwise unique. Otherwise, the browser will cache the content indefinitely and never check for updates, including for new deploys.
 
 | Method      | Type                       |
 | ----------- | -------------------------- |
@@ -250,9 +244,7 @@ Parameters:
 
 #### :gear: ttl
 
-Sets the s-maxage for items in the CDN cache. This is the maximum amount of time that the CDN will cache the content.
-If used with swr, the content will revalidate in the background after the max age has passed. Otherwise, the content will be
-removed from the cache after the max age has passed.
+Sets the s-maxage for items in the CDN cache. This is the maximum amount of time that the CDN will cache the content. If used with swr, the content will revalidate in the background after the max age has passed. Otherwise, the content will be removed from the cache after the max age has passed.
 
 | Method | Type                      |
 | ------ | ------------------------- |

packages/cache-handlers/README.md

@@ -1,9 +1,9 @@
 {
-  "name": "@ascorbic/cdn-cache-control",
-  "version": "1.3.1",
-  "exports": "./src/index.ts",
-  "license": "MIT",
-  "publish": {
-    "include": ["README.md", "src/index.ts"]
-  }
+	"name": "@ascorbic/cdn-cache-control",
+	"version": "1.3.1",
+	"exports": "./src/index.ts",
+	"license": "MIT",
+	"publish": {
+		"include": ["README.md", "src/index.ts"]
+	}
 }