feat(universal-cache): add universal cache middleware package

[lord007tn]

Summary

This PR introduces @hono/universal-cache as a new third-party middleware package for Hono.

It follows the direction discussed in honojs/hono#3857:
honojs/hono#3857

This middleware has been running internally in our production systems for a while. After validating it under real traffic and edge cases, we felt it was in a good place to open-source and get broader feedback on it.

Dependency Model

@hono/universal-cache depends on unstorage as the storage abstraction.

That gives us:

• in-memory cache by default
• adapter-based backends through unstorage drivers (Redis, KV, filesystem, and others)
• one consistent cache API across runtimes

Major Features

• response caching for Hono handlers via cacheMiddleware()
• function-level caching via cacheFunction()
• request-scoped defaults via cacheDefaults()
• stale-while-revalidate (SWR)
• in-flight deduplication for refresh paths
• configurable cache keys (getKey) and integrity (integrity / hash)
• custom serialize / deserialize hooks for response and function entries
• cache control hooks: shouldBypassCache, shouldInvalidateCache, shouldRevalidate, validate
• configurable HTTP methods and varies support for cache key variation
• opt-in manual revalidation via revalidateHeader
• keepPreviousOn5xx behavior for safer refresh failures
• global helpers for cache defaults and storage instance management

Runtime Notes

• default maxAge is 60
• manual revalidation is disabled by default
• on workerd, stale middleware entries refresh synchronously instead of relying on background self-fetch

Test Coverage

Added coverage for:

• middleware caching behavior across methods
• bypass / invalidation / manual revalidation flows
• shouldRevalidate gating
• SWR behavior in standard runtimes and workerd
• vary-based keying
• custom serialization / deserialization
• function cache deduplication and validation
• global defaults / storage helpers

Validation

• corepack yarn eslint packages/universal-cache/src packages/universal-cache/vitest.config.ts packages/universal-cache/vitest.workerd.config.ts --cache --cache-location .cache/.eslintcache
• corepack yarn workspace @hono/universal-cache typecheck
• corepack yarn workspace @hono/universal-cache test --run
• corepack yarn workspace @hono/universal-cache test:workerd --run
• cd packages/universal-cache && bunx vitest run src/index.test.ts src/utils.test.ts

Related

• Docs PR: docs: add universal-cache to third-party middleware docs website#825

Merge Note

Please merge this together with the docs PR above.

The author should do the following, if applicable

• Add tests
• Run tests
• yarn changeset at the top of this repo and push the changeset
• Follow the contribution guide

[changeset-bot]

🦋 Changeset detected

Latest commit: 336c344

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@hono/universal-cache	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[codecov]

Codecov Report

❌ Patch coverage is 93.04462% with 53 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.28%. Comparing base (40f956e) to head (336c344).
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
packages/universal-cache/src/cache.ts	92.60%	46 Missing and 6 partials ⚠️
packages/universal-cache/src/utils.ts	98.30%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1764      +/-   ##
==========================================
+ Coverage   92.14%   92.28%   +0.14%     
==========================================
  Files         115      117       +2     
  Lines        4113     4875     +762     
  Branches     1072     1314     +242     
==========================================
+ Hits         3790     4499     +709     
- Misses        287      334      +47     
- Partials       36       42       +6     

Flag	Coverage Δ
auth-js	64.34% <ø> (ø)
clerk-auth	90.00% <ø> (ø)
conform-validator	96.15% <ø> (ø)
react-renderer	88.88% <ø> (ø)
ua-blocker	90.00% <ø> (ø)
universal-cache	93.04% <93.04%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[lord007tn]

Addressed the Codecov coverage gaps with additional targeted tests.

What I added

• New utility test suite:
  • packages/universal-cache/src/utils.test.ts
  • Covers all utils.ts branches and lines (normalizePathToName, stableStringify, TTL logic, expiry helpers).
• Expanded index.test.ts with cache edge-case scenarios:
  • malformed path decoding fallback key path
  • cache entry rejection on integrity mismatch
  • cache entry rejection via validate()
  • rejection of cached headers containing etag: "undefined" / last-modified: "undefined"
  • invalidation behavior for non-cacheable no-store responses
  • function cache default key hashing path (without getKey)
  • removal of malformed function cache entries

Validation run

• corepack yarn eslint packages/universal-cache/src --cache --cache-location .cache/.eslintcache
• corepack yarn workspace @hono/universal-cache typecheck
• corepack yarn workspace @hono/universal-cache test --run

All passed locally.

The new commit is: d79c864

[lord007tn]

could you check it please
@yusukebe @usualoma

[drag0n-app]

could you check it please
@yusukebe @usualoma

[drag0n-app]

@yusukebe @usualoma I really need this feature. Could you please review it? Thanks!

[yusukebe]

@lord007tn

Sorry to be late. Can you merge the main branch into this branch to use the current stack (like pnpm instead of yarn) for honojs/middleware?

[lord007tn]

@yusukebe Done,
I also merged the new tweaks that we have internally.

[lord007tn]

@yusukebe done, fixed the remaining edge cases and pushed. all checks pass locally.

[lord007tn]

@yusukebe can you please check