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 is the implementation path discussed in honojs/hono#3857:
honojs/hono#3857

This middleware has been running internally in our production systems for a while. After validating behavior under real traffic and edge cases, we are open-sourcing it so it can be reviewed and improved with community feedback.

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) with background refresh
• in-flight deduplication for revalidation/refresh paths
• configurable cache keys (getKey) and integrity (integrity/hash)
• custom serialize / deserialize hooks for response and function entries
• cache control hooks: shouldBypassCache, shouldInvalidateCache, validate
• configurable HTTP methods and varies support for cache key variation
• configurable revalidation header (x-cache-revalidate by default)
• keepPreviousOn5xx behavior for safer refresh failures
• global helpers for cache defaults and storage instance management

Test Coverage

Added extensive tests for:

• middleware caching behavior across methods
• bypass/invalidation flows
• SWR stale serving and background refresh behavior
• vary-based keying
• custom serialization/deserialization
• function cache deduplication and validation
• global defaults/storage helpers

Validation

• 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
• corepack yarn prettier --check packages/universal-cache/src/cache.ts packages/universal-cache/src/types.ts packages/universal-cache/src/index.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: 2f9ec51

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