feat: export CacheOverride API for cross-platform cache control

[trieloff]

Summary

Implements issue #82 by exporting a unified CacheOverride API from the @adobe/fetch polyfill that provides cross-platform cache control for both Fastly Compute and Cloudflare Workers.

Design Principle: Only includes options that work on BOTH platforms to maximize cross-platform compatibility.

Changes

• CacheOverride Class: New unified class supporting three modes:

  • "none": Respect origin cache control headers
  • "pass": Prevent caching regardless of origin headers
  • "override": Apply custom cache settings

• Cross-Platform Options Only:

  • ttl: Time-to-live in seconds
  • cacheKey: Custom cache key
  • surrogateKey: Surrogate keys for cache purging

• Platform-Specific Implementation:

  • Fastly: Dynamically imports native fastly:cache-override module using async initialization
  • Cloudflare: Automatically maps to cf object options (cacheTtl, cacheKey, cacheTags)

• Fetch Wrapper: Enhanced async fetch function that accepts cacheOverride option

• Validation: Warns users if they pass platform-specific options (like swr, pci, beforeSend, afterSend) which are intentionally excluded for cross-platform compatibility

Platform Mapping

Option	Fastly	Cloudflare
Mode: "pass"	Native mode	cf.cacheTtl = 0
Mode: "none"	Native mode	No cf options
ttl	Native ttl	cf.cacheTtl
cacheKey	Native cacheKey	cf.cacheKey
surrogateKey	Native surrogateKey	cf.cacheTags (array)

Test Plan

• Unit tests for CacheOverride constructor (all modes and options)
• Tests for Cloudflare option mapping
• Tests for async module loading on Fastly
• Tests for validation warnings on unsupported options
• 19 tests passing with 75% code coverage
• Documentation added to docs/API.md

Usage Example

import { fetch, CacheOverride } from '@adobe/fetch';

// Basic TTL override
const cacheOverride = new CacheOverride('override', { ttl: 3600 });
const response = await fetch('https://example.com/api', { cacheOverride });

// Prevent caching
const noCache = new CacheOverride('pass');
const response2 = await fetch('https://example.com/api', { cacheOverride: noCache });

// Advanced configuration with all cross-platform options
const advanced = new CacheOverride({
  ttl: 3600,
  cacheKey: 'my-key',
  surrogateKey: 'api v1'
});
const response3 = await fetch('https://example.com/api', { cacheOverride: advanced });

Breaking Changes

None - this is a new export added to the existing API.

Notes

• Platform-specific options (like Fastly's swr, pci, beforeSend, afterSend) are intentionally excluded to maintain true cross-platform compatibility
• If you pass unsupported options, they will be ignored with a console warning
• For platform-specific features, use platform detection and native APIs directly

Closes #82

🤖 Generated with Claude Code

[github-actions]

This PR will trigger a minor release when merged.

[codecov]

Codecov Report

❌ Patch coverage is 72.71127% with 155 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
test/cache-demo.integration.js	30.00%	98 Missing ⚠️
src/template/polyfills/fetch.js	75.10%	57 Missing ⚠️

📢 Thoughts on this report? Let us know!

[trieloff]

don't skip

[trieloff]

not ok to skip

[trieloff]

depends on #88 for integration tests to run on cloudflare