Add verbose logging controlled by CACHED_MIDDLEWARE_FETCH_LOGGER environment variable

[Copilot]

This PR adds comprehensive verbose logging to help developers debug and understand caching behavior in cached-middleware-fetch-next. The logging can be enabled by setting the CACHED_MIDDLEWARE_FETCH_LOGGER=1 environment variable.

What's Added

Verbose Logging Function

• Added a verboseLog() utility that only outputs when CACHED_MIDDLEWARE_FETCH_LOGGER=1
• Uses the same [cached-middleware-fetch] prefix as existing error logs for consistency
• Zero performance impact when disabled (default behavior)

Comprehensive Logging Coverage

The verbose logging now provides detailed insights into:

Request Flow:

[cached-middleware-fetch] Starting cachedFetch: GET https://api.example.com/data {
  cacheOption: 'auto no cache',
  revalidate: 300,
  expires: undefined,
  tags: ['api-data'],
  fetchCacheKeyPrefix: undefined
}

Cache Operations:

[cached-middleware-fetch] Generated cache key: a1b2c3d4e5f6...
[cached-middleware-fetch] Cache HIT (age: 45s, expires in: 255s)
[cached-middleware-fetch] Cache MISS - no entry found
[cached-middleware-fetch] Cache STALE (age: 320s, expires in: 3280s) - triggering background refresh

Storage and Performance:

[cached-middleware-fetch] Storing in cache with TTL: 86400s, expires at: 2025-01-03T15:30:00.000Z
[cached-middleware-fetch] Background refresh completed and cached (TTL: 300s)

Usage

Enable verbose logging by setting the environment variable:

export CACHED_MIDDLEWARE_FETCH_LOGGER=1

Or in your application:

process.env.CACHED_MIDDLEWARE_FETCH_LOGGER = '1';

Benefits

• Debugging: Easily troubleshoot caching issues and understand cache behavior
• Performance Analysis: See cache hit/miss rates and timing information
• SWR Monitoring: Track stale-while-revalidate background refresh operations
• Zero Impact: No performance cost when disabled (default state)

Documentation

Updated README.md with a new "Debugging and Verbose Logging" section that explains:

• How to enable/disable verbose logging
• What information is logged
• Example log output
• Environment variable values

This enhancement makes it much easier for developers to understand and debug caching behavior in their Next.js middleware implementations.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• jsonplaceholder.typicode.com
  • Triggering command: node test-verbose-logging.js (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.