feat(cache): add tag-based caching and revalidation helpers

[dinwwwh]

Adds @orpc/experimental-cache, a new package for tag-based caching and revalidation of procedure outputs, with stale-while-revalidate, five store adapters, and a handler plugin that reflects cache activity into response headers for client-side revalidation (e.g. TanStack Query auto-invalidation on mutation) or HTTP response caches.

Features

• cache() middleware caches procedure output in the context's cache/store (one store per router). Keys default to the procedure path and full input, canonically encoded so structurally equal keys always hit the same entry; a provided key is used as given. key, tags, ttl, swr, and enabled are all dynamic on middleware options and input.
• Stale-while-revalidate: entries past ttl but within swr are served immediately while the procedure re-executes in the background; a cache/waitUntil context hook keeps refreshes alive on Workers-like runtimes.
• revalidate({ tags }) middleware invalidates tags after successful mutations, with compile-time non-empty tags; resolving tags to undefined skips it.
• CacheHandlerPlugin is inert by default; a headers allowlist enables orpc-cache-tag / orpc-cache-tag-invalidation (client-facing, never consumed by CDNs) and cache-control / cache-tag (for response caches in front, GET/HEAD only, never overriding). Only the root procedure's checks are reflected, never nested calls, and only on successful responses. Tag encoding survives Cloudflare Workers Caching's strict rules: printable ASCII only, and uppercase percent-encoded so case-insensitive matching cannot collide distinct tags.
• Stores: MemoryCacheStore, RedisCacheStore, VercelCacheStore (@orpc/experimental-cache), plus experimental_KVCacheStore and the purge-only experimental_WorkersCacheStore in @orpc/cloudflare, following the experimental_ prefix convention for experimental APIs inside stable packages (with a new-cap lint exception to support it). All share the CacheStore contract and a uniform options-object constructor; revalidateTags takes a non-empty tag list so no store handles an empty or single-string case. Outputs serialize via RPCSerializer (blob and streaming outputs ignored), keys via the shared encodeCacheKey.

Server

• Middlewares between stacked input schemas now receive the full input with the validated fragments merged over it, so whole-input middleware like caching works at any position (matches the behavior already on main; docs updated).
• New deepSortKeys util in @orpc/shared.

Testing

• 100% line/branch/function coverage on both @orpc/experimental-cache and the new @orpc/cloudflare stores: unit, type-level, handler, and e2e tests, mocked-client Redis suites plus env-gated Redis integration tests, and workerd tests against real KV bindings.
• Full monorepo suite, type-check, lint, and docs validation pass.

Docs

• New docs/helpers/cache page (usage, adapters, SWR, handler plugin, cross-origin notes) with JSDoc backlinks, api-reference row, and package lists updated.

[pkg-pr-new]

More templates

• @orpc/bun-playground
• @orpc/cloudflare-playground
• @orpc/nest-playground
• @orpc/next-playground

@orpc/ai-sdk

npm i https://pkg.pr.new/middleapi/orpc/@orpc/ai-sdk@1964

@orpc/arktype

npm i https://pkg.pr.new/middleapi/orpc/@orpc/arktype@1964

@orpc/bun

npm i https://pkg.pr.new/middleapi/orpc/@orpc/bun@1964

@orpc/experimental-cache

npm i https://pkg.pr.new/middleapi/orpc/@orpc/experimental-cache@1964

@orpc/client

npm i https://pkg.pr.new/middleapi/orpc/@orpc/client@1964

@orpc/cloudflare

npm i https://pkg.pr.new/middleapi/orpc/@orpc/cloudflare@1964

@orpc/contract

npm i https://pkg.pr.new/middleapi/orpc/@orpc/contract@1964

@orpc/experimental-effect

npm i https://pkg.pr.new/middleapi/orpc/@orpc/experimental-effect@1964

@orpc/evlog

npm i https://pkg.pr.new/middleapi/orpc/@orpc/evlog@1964

@orpc/hibernation

npm i https://pkg.pr.new/middleapi/orpc/@orpc/hibernation@1964

@orpc/json-schema

npm i https://pkg.pr.new/middleapi/orpc/@orpc/json-schema@1964

@orpc/experimental-msw

npm i https://pkg.pr.new/middleapi/orpc/@orpc/experimental-msw@1964

@orpc/nest

npm i https://pkg.pr.new/middleapi/orpc/@orpc/nest@1964

@orpc/next

npm i https://pkg.pr.new/middleapi/orpc/@orpc/next@1964

@orpc/node

npm i https://pkg.pr.new/middleapi/orpc/@orpc/node@1964

@orpc/openapi

npm i https://pkg.pr.new/middleapi/orpc/@orpc/openapi@1964

@orpc/opentelemetry

npm i https://pkg.pr.new/middleapi/orpc/@orpc/opentelemetry@1964

@orpc/pinia-colada

npm i https://pkg.pr.new/middleapi/orpc/@orpc/pinia-colada@1964

@orpc/pino

npm i https://pkg.pr.new/middleapi/orpc/@orpc/pino@1964

@orpc/publisher

npm i https://pkg.pr.new/middleapi/orpc/@orpc/publisher@1964

@orpc/ratelimit

npm i https://pkg.pr.new/middleapi/orpc/@orpc/ratelimit@1964

@orpc/server

npm i https://pkg.pr.new/middleapi/orpc/@orpc/server@1964

@orpc/shared

npm i https://pkg.pr.new/middleapi/orpc/@orpc/shared@1964

@orpc/swr

npm i https://pkg.pr.new/middleapi/orpc/@orpc/swr@1964

@orpc/tanstack-query

npm i https://pkg.pr.new/middleapi/orpc/@orpc/tanstack-query@1964

@orpc/trpc

npm i https://pkg.pr.new/middleapi/orpc/@orpc/trpc@1964

@orpc/valibot

npm i https://pkg.pr.new/middleapi/orpc/@orpc/valibot@1964

@orpc/zod

npm i https://pkg.pr.new/middleapi/orpc/@orpc/zod@1964

commit: 8a12845

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	orpc	8a12845	Commit Preview URL Branch Preview URL	Sep 04 2026, 03:27 AM

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[codspeed-hq]

Merging this PR will not alter performance

✅ 30 untouched benchmarks

---

_{Comparing claude/orpc-cache-implementation-09e313 (8a12845) with main (e65e810)}

[pullfrog]

Important

One behavioral issue to resolve: a revalidation failure after a committed mutation surfaces as an error on a request whose write already succeeded. See the inline comment on revalidate.

Reviewed changes

• @orpc/cache (new package) — cache()/revalidate() middlewares, CacheStore contract, tag-version invalidation, stale-while-revalidate, CacheHandlerPlugin header reflection, and MemoryCacheStore/RedisCacheStore/VercelCacheStore adapters.
• @orpc/cloudflare — KVCacheStore (real KV bindings) and purge-only WorkersCacheStore, plus workerd coverage.
• @orpc/shared — new deepSortKeys util and tests.
• Docs/config — new docs/helpers/cache page, README/package-list updates, api-reference row, new package package.json with subpath exports, workspace wiring.

Overall this is a careful, well-tested addition. I verified the highest-risk semantics rather than taking them on faith: the tag-version technique errs on the safe side (a lost concurrency race produces a spurious miss and recompute, never a stale hit), the tag header encoding round-trips correctly under case-folding and stays consistent between the reflected cache-tag and WorkersCacheStore purge, blob/streaming outputs are guarded where they cannot be stored, and the docs call out the CDN/purge-store and per-request-shared-key caveats. Two non-blocking nits are inline.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

revalidateTag is awaited with no guard, so when the store is unreachable (e.g. a transient Redis outage) a mutation whose handler already succeeded is reported to the client as a failed request. Clients that retry on error will re-run the mutation, risking a double write/commit. This contrasts with the stale-refresh path just above, which deliberately swallows its background failures (.catch(() => {})).

Consider treating revalidation as best-effort after a successful procedure — catch/log and still return result — so a cache outage can never turn a committed mutation into an error response. If a loud failure is deliberately wanted for observability, that's defensible too, but it should be a documented, conscious choice given the retry implications.

Technical details

# Revalidate errors flip committed mutations into failures

## Affected sites
- packages/cache/src/middleware.ts:167 — `await (…context as CacheContext).cache.revalidateTag(…)` has no try/catch; the error propagates to the caller after `next()` already committed the mutation.

## Required outcome
- A successful procedure must not surface a client-facing error when cache revalidation fails afterward.

## Suggested approach
- Wrap `revalidateTag` (and the tag/value resolution) so revalidation failures are logged/silently dropped and the committed `result` is still returned — mirroring the SWR refresh path's `.catch(() => {})`.

## Open questions
- Is fail-loud is the intended contract here? If so, document it, since the SWR refresh path deliberately does the opposite.

[pullfrog]

Nit: isUncacheableOutput only catches top-level async iterators and ReadableStream, so a top-level Blob output is still passed to store.set. MemoryCacheStore.set stores it (in-memory it works), but RedisCacheStore/KVCacheStore/VercelCacheStore drop it, so caching semantics silently differ per adapter. Consider also gating Blob (and FormData, which RPCSerializer emits for nested blobs) here so the behavior is uniform regardless of store.

[pullfrog]

Important

One behavior to confirm from the delta's cleanup: dropping isUncacheableOutput from the middleware also dropped the "don't record a cache check for streaming outputs" guarantee, so streaming responses are now advertised as cache activity even though every adapter ignores them. Full context inline.

Reviewed changes

This run reviews the single-commit delta e93c93e5 since the last-reviewed head 17c31c21:

• CacheStore.revalidateTags — replaced revalidateTag(string | list) with a non-empty tag list across the interface, all four adapters, and their mocked/integration tests; stores dropped their empty-list branches and the middleware now guards with tags?.length.
• revalidate({ tags }) API — options-object form whose tags is a Value of a non-empty tuple or undefined; resolving to undefined (or []) skips both the store call and the plugin-context recording.
• Context keys — CacheContext moved to namespaced 'cache/store' / 'cache/waitUntil'; tests, type tests, docs, and e2e all updated, with no context.cache / context.waitUntil stragglers.
• cache() key semantics — any provided key (string or object) is now used as given; only the omitted-key default derives [path, input]; documented as "procedures sharing a key share an entry".
• Streaming-output drops moved into stores — isUncacheableOutput deleted; MemoryCacheStore.set now ignores ReadableStream/async-iterator outputs, matching Redis/KV/Vercel.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

With isUncacheableOutput removed, this miss path now records a cache check (pluginContext.caches.push) even when the store declined the write, and CacheHandlerPlugin reflects it: streaming responses (async iterators / ReadableStream) now emit orpc-cache-tag and, on GET/HEAD, cache-tag + cache-control — signaling front caches to cache stream bodies the store will never replay. The removed it.each(...)('never stores %s outputs and records no check') test enforced the opposite, so this surface changed silently.

Technical details

# Streaming responses are advertised as cached

## Affected sites
- packages/cache/src/middleware.ts:117-128 — the miss path calls `store.set` (a no-op for `ReadableStream`/async-iterator outputs in every adapter: MemoryCacheStore added in this delta, Redis/KV/Vercel via RPCSerializer) and then unconditionally pushes a cache check that describes cache activity that never happened.
- packages/cache/src/handler-plugin.ts:139-162 — reflects the root check's tags: `orpc-cache-tag` on every response, and `cache-tag` / `cache-control: public, s-maxage=…` on GET/HEAD, so a streaming response instructs a front cache (e.g. Cloudflare Workers Caching) to cache a stream body.
- packages/cache/src/middleware.test.ts — the streaming-output tests asserting `pluginContext.caches` stays empty were removed alongside the guard.

## Required outcome
- Streaming (async-iterator / `ReadableStream`) outputs must not be advertised as cacheable in reflected headers, matching store behavior and the docs ("every adapter ignores them").

## Suggested approach
- Make the middleware skip the recorded check for outputs it knows are never stored — e.g. have `CacheStore.set` return whether it stored the value and gate the push on it, or restore a narrow raw-output guard matching the stores' `ReadableStream`/`isAsyncIteratorObject` check before `set` + push.

## Open questions
- Is reflecting cache headers for streaming responses intentional? If so, the docs page should say so, since it currently states streaming outputs "cannot be replayed, so every adapter ignores them".

[pullfrog]

Important

Removing the output guards from every store turned "un-storable output → cache miss" into "un-storable output → stored and served as {}", so a procedure returning a Blob/File/FormData/ReadableStream/async iterator now serves a corrupted empty value on every within-ttl hit instead of recomputing. The tag-invalidation semantics themselves check out — a revalidation race can only produce a spurious miss, never a stale serve. Two nits inline (a runtime-only Upstash edge and a stale JSDoc).

Reviewed changes

This run reviews the PR-owned delta since the last-reviewed head e93c93e5. The branch was force-pushed — e93c93e5 was replaced by a rework commit, main was re-merged, and new work landed — so the substantive delta is commits c2356fbc, e9c80635, and 8a12845b.

• Store contract rework — revalidateTag(list) became revalidate({ tags }) with a non-empty tag list; every duration switched from milliseconds to seconds across adapters, envelopes, middleware, and docs; untagged entries now carry undefined instead of []; key serializers are built once per store and encodeCacheKey/nowInSeconds moved to @orpc/shared.
• Output guards removed — every store now passes output straight to its serializer; the blob/stream/iterator drop logic and its tests were deleted, and the docs replaced the "every adapter ignores them" guarantee with a do-not-cache warning.
• Handler plugin rework — headers is now a required list of plain literals (exported constant helpers removed); cache-tag/cache-control are set on any request method and override existing headers; cache-control switched from s-maxage to max-age (proxy-revalidate semantics), with stale hits reflecting max-age=0.
• Background refresh semantics — a stale-hit refresh is handed to cache/waitUntil uncaught so the runtime can report failures, and only .catch(() => {})d when nothing owns it.
• New adapters — UpstashCacheStore (@orpc/experimental-cache/upstash) and BunRedisCacheStore (@orpc/bun), sharing the Redis key/envelope format, plus a cross-adapter compatibility suite; all store constructors now take their client positionally.
• @orpc/shared — nowInSeconds and case-safe encodeCacheTag/encodeCacheTagHeader/decodeCacheTagHeader, each with tests.
• Testing — a shared describeCacheStoreContract suite now runs against Memory/Redis/Upstash/Vercel, with holdResult race tests, concurrency suites for the middleware, and a merge of upstream main (all CI green on the head).

Inline threads

• packages/cache/src/middleware.ts:120 — un-storable outputs are persisted and served as corrupted {} (IMPORTANT).
• packages/cache/src/adapters/upstash.ts:136 — revalidate({ tags: [] }) throws on Upstash, no-ops elsewhere (nit).
• packages/cache/src/handler-plugin.ts:47 — headers JSDoc still claims GET/HEAD-only and never-override (nit).

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

Since this delta removed the blob/stream guards from every store, an output RPCSerializer cannot represent — top-level or nested Blob/File/FormData, ReadableStream, or async iterators — is now persisted with the output silently flattened to {} (serialize returns those as-is, stringifyJSON renders them {}). Every later within-ttl hit serves that corrupted {} instead of missing and recomputing — a regression from the previous drop-the-entry behavior (the old ignores outputs containing blobs tests asserted get → undefined and were deleted with the guards). It also compounds the open streaming-outputs thread: orpc-cache-tag/cache-tag/cache-control now advertise a response the store will serve as {}.

[pullfrog]

At runtime, revalidate({ tags: [] }) throws here — Upstash's Pipeline.exec() rejects with Error: Pipeline is empty — while Redis, Memory, Bun, and KV treat an empty list as a no-op. The middleware only guards if (tags), so a resolver producing [] at runtime reaches the store; the type-level non-empty tuple cannot stop a dynamic resolver. A one-line if (!tags.length) return keeps the adapters consistent.

[pullfrog]

The headers option JSDoc still says cache-tag/cache-control "are only set on GET and HEAD responses and never override existing headers", but this delta removed the GET/HEAD gate and the interceptor now replaces any existing value (both behaviors are asserted in the updated tests). Updating the option doc to match the current behavior — as the docs page already does — would keep the API surface accurate.