Add cache handlers package

.github/workflows/claude.yml

@@ -0,0 +1,72 @@
+name: Claude PR Assistant
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude-code-action:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && contains(github.event.issue.body, '@claude'))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "lts/*"
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Run Claude PR Action
+        uses: anthropics/claude-code-action@beta
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          timeout_minutes: "5"
+          # mcp_config: |
+          #   {
+          #     "mcpServers": {
+          #       "astro-docs": {
+          #         "type": "http",
+          #         "url": "https://mcp.docs.astro.build/mcp"
+          #       }
+          #     }
+          #   }
+          allowed_tools: |
+            Bash(pnpm install)
+            Bash(pnpm run:*)
+            Bash(npm run:*)
+            Bash(npx packages/am-i-vibing)
+          # mcp__astro-docs__search_astro_docs
+          # Optional: Restrict network access to specific domains only
+          # experimental_allowed_domains: |
+          #   .anthropic.com
+          #   .github.com
+          #   api.github.com
+          #   .githubusercontent.com
+          #   bun.sh
+          #   registry.npmjs.org
+          #   .blob.core.windows.net

.github/workflows/release.yaml → .github/workflows/release.yml

@@ -23,29 +23,40 @@ jobs:
           private-key: ${{ secrets.APP_PRIVATE_KEY }}
           app-id: ${{ secrets.APP_ID }}
       - name: Checkout Repo
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Setup PNPM
+        uses: pnpm/action-setup@v3
 
-      - name: Setup Node.js 22
-        uses: actions/setup-node@v3
+      - name: Setup Node
+        uses: actions/setup-node@v4
         with:
-          node-version: 22
+          node-version: latest
+          cache: "pnpm"
 
-      - uses: pnpm/action-setup@v4
+      - uses: denoland/setup-deno@v2
+        with:
+          deno-version: vx.x.x
 
       - name: Install Dependencies
         run: pnpm install
 
       - name: Build Packages
-        run: pnpm build
+        run: pnpm run build
+      - run: pnpm run check
 
-      - name: publint
-        run: pnpm lint:package
+      # Update npm to latest version so that OIDC works correctly
+      - name: Update npm
+        run: npm install -g npm@latest
 
-      - name: Create Release PR or Publish to npm
+      - name: Create Release Pull Request or Publish to npm
         id: changesets
         uses: changesets/action@v1
         with:
-          version: pnpm run version
+          version: pnpm changeset version
           publish: pnpm changeset publish
           commit: "ci: release"
           title: "ci: release"
@@ -55,4 +66,4 @@ jobs:
           NPM_CONFIG_PROVENANCE: true
       - name: Publish to JSR
         if: steps.changesets.outputs.published == 'true'
-        run: npx jsr publish
+        run: deno publish

.github/workflows/semantic-prs.yml

@@ -0,0 +1,55 @@
+name: "Lint PR"
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - edited
+      - synchronize
+
+permissions:
+  pull-requests: write
+
+jobs:
+  main:
+    name: Validate PR title
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        with:
+          types: |
+            fix
+            feat
+            chore
+            docs
+            ci
+            test
+            revert
+        id: lint_pr_title
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: marocchino/sticky-pull-request-comment@v2
+        # When the previous steps fails, the workflow would stop. By adding this
+        # condition you can continue the execution with the populated error message.
+        if: always() && (steps.lint_pr_title.outputs.error_message != null)
+        with:
+          header: pr-title-lint-error
+          message: |
+            Hey there and thank you for opening this pull request! 👋🏼
+
+            We require pull request titles to follow the [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/) and it looks like your proposed title needs to be adjusted.
+            Without this title format, a release will not be triggered
+
+            Details:
+
+            ```
+            ${{ steps.lint_pr_title.outputs.error_message }}
+            ```
+
+      # Delete a previous comment when the issue has been resolved
+      - if: ${{ steps.lint_pr_title.outputs.error_message == null }}
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: pr-title-lint-error
+          delete: true

.github/workflows/test.yml

@@ -0,0 +1,33 @@
+name: Test
+permissions:
+  contents: read
+on:
+  pull_request:
+  push:
+    branches: [main]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v2
+        with:
+          version: 8
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          cache: "pnpm"
+          check-latest: true
+          registry-url: "https://registry.npmjs.org"
+      - name: Install dependencies
+        run: |
+          corepack enable
+          pnpm install
+      - uses: denoland/setup-deno@v2
+        with:
+          deno-version: vx.x.x
+      - name: Build
+        run: pnpm build
+      - name: Test
+        run: pnpm test

.gitignore

@@ -130,3 +130,4 @@ dist
 .pnp.*
 .tsup
 .DS_Store
+.wrangler

CLAUDE.md

@@ -0,0 +1,80 @@
+# CLAUDE.md
+
+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)
+
+## 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 check` - Run type checking and linting for all packages
+- `pnpm lint` - Run linting for all packages
+- `pnpm format` - Format code using Prettier
+
+### Package-level commands (run within individual packages):
+
+- `pnpm build` - Build the package using tsdown (ESM + DTS output)
+- `pnpm dev` - Watch mode for development
+- `pnpm test` - Run tests (specific to each package's test setup)
+- `pnpm check` - Run publint and @arethetypeswrong/cli checks
+
+### Test-specific commands for cache-handlers package:
+
+- `pnpm test:deno` - Run Deno tests from repository root
+- `pnpm test:node` - Run Node.js tests via Vitest
+- `pnpm test:workerd` - Run Cloudflare Workers tests via Vitest
+
+## Development Workflow
+
+- Uses **pnpm** as package manager
+- **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`)
+
+## Package Architecture
+
+### cdn-cache-control
+
+- **API Style**: Class-based (`CacheHeaders` extends `Headers`)
+- **Target**: Simple cache header management with CDN-specific optimizations
+- **Testing**: Node.js only via `node --test`
+- **Build**: ESM + CommonJS outputs
+
+### cache-handlers
+
+- **API Style**: Functional middleware approach
+- **Target**: Web standard cache primitives for modern applications
+- **Key Features**:
+  - Factory functions (`createCacheHandlers`, `createReadHandler`, etc.)
+  - 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)
+- **Build**: ESM-only output
+
+Each package follows this structure:
+
+- `src/index.ts` - Main entry point with comprehensive exports
+- `test/` - Test files (runtime-specific subdirectories for cache-handlers)
+- `dist/` - Built output (ESM + .d.ts files)
+- Package exports configured for proper TypeScript declarations
+
+## TypeScript Configuration
+
+Uses strict TypeScript configuration with:
+
+- Target: ES2022
+- Module: preserve (for bundler compatibility)
+- Strict mode with additional safety checks (`noUncheckedIndexedAccess`, `noImplicitOverride`)
+- Library-focused settings (declaration files, declaration maps)

demos/cache-handlers/.gitignore

@@ -0,0 +1,24 @@
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store
+
+# jetbrains setting folder
+.idea/

demos/cache-handlers/.vscode/extensions.json

@@ -0,0 +1,4 @@
+{
+  "recommendations": ["astro-build.astro-vscode"],
+  "unwantedRecommendations": []
+}

demos/cache-handlers/.vscode/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "command": "./node_modules/.bin/astro dev",
+      "name": "Development server",
+      "request": "launch",
+      "type": "node-terminal"
+    }
+  ]
+}