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

[dinwwwh]

Adds @orpc/experimental-cache: tag-based caching and revalidation for procedure output, with stale-while-revalidate, a CacheStore contract with memory, Redis, Upstash, Bun, Vercel, and BentoCache adapters plus a purge-only Cloudflare Workers Caching store, and a handler plugin that reflects cache tags into response headers for client-side revalidation or response caches in front. Concurrent callers of one key run the procedure once.

Resolves #1262

Features

• cache() middleware: a hit returns the cached output without running the handler; a miss runs it once, even across concurrent callers, and stores the result. key defaults to the procedure path and input, canonically encoded so structurally equal keys share an entry; key, tags, ttl, swr, and enabled accept static values or functions of the middleware options and input, and enabled: false skips the store and the other resolvers.
• Stale-while-revalidate: past ttl but within swr, stale output is served at once while one caller refreshes in the background. cache/waitUntil hands the refresh to runtimes that stop pending work after the response; without it, refresh failures surface as unhandled rejections rather than being swallowed.
• revalidate({ tags }) middleware invalidates tags after a successful mutation; tags are non-empty at compile time, and resolving to null or undefined skips it.
• CacheHandlerPlugin sets only the headers listed: orpc-cache-tag and orpc-cache-tag-invalidation for clients, cache-control and cache-tag for caches in front. cache-control uses max-age because s-maxage carries proxy-revalidate semantics that forbid stale reuse. Only the root procedure's activity is reflected, only on successful responses, and tags are percent-encoded so case-insensitive caches cannot collide distinct tags.
• Stores implement getOrSet(key, fill, options) and revalidate({ tags }). The Redis, Upstash, and Bun stores keep entries as Redis hashes driven by Lua scripts: one round trip per hit, two per miss, with the lock taken in the same script that reads the entry and lockTtl freeing waiters if a holder dies. They share BaseRedisCacheStore and one entry format, so any two can serve the same database. The memory and Vercel stores share BaseKeyValueCacheStore and coalesce within the process. The BentoCache store drives BentoCache's own getOrSet, mapping swr to its grace period and tags to deleteByTag. TieredCacheStore layers stores front to back, so a miss in one tier fills from the next and only the last runs the procedure, with per-tier ttl and swr caps. Every store carries one RPCJsonSerializer for keys and outputs.

Shared

• @orpc/shared gains nowInSeconds, deepSortKeys, and the cache tag header codec; @orpc/bun and @orpc/cloudflare gain their stores.

Testing

• 100% coverage on @orpc/experimental-cache, with a store contract shared by every adapter, env-gated Redis and Upstash integration suites, a Bun suite, cross-adapter compatibility suites proving Redis, Upstash, and Bun share entries, counters, retention, and locks, workerd tests for the Workers store, and race and lock-takeover tests.
• Full type-check, lint, and docs validation pass.

Docs

• New docs/helpers/cache page with per-adapter sections; API reference 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: 84268ab

[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	84268ab	Commit Preview URL Branch Preview URL	Sep 10 2026, 08:59 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 degrade performance by 70.71%

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

❌ 1 regressed benchmark
✅ 29 untouched benchmarks

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
❌	flat object from query params	106 µs	361.9 µs	-70.71%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing claude/orpc-cache-implementation-09e313 (84268ab) with main (d6062a8)¹}

Footnotes

1. No successful run was found on main (b0bdad5) during the generation of this report, so d6062a8 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[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]

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) ｜ 𝕏}

[Copilot]

🟡 Changes recommended

Redis lock takeover can overwrite newer values, cache keys can collide, and the package lacks the repository-standard publishing hook.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

Suppressed comments (2)

Previously missed (2) — in code that hasn't changed since the last review.

packages/shared/src/http.ts:162

• An unpaired UTF-16 surrogate matches this branch, but encodeURIComponent throws URIError for it. Such strings can arrive through JSON and are accepted by the tag APIs, so reflecting or purging one can turn an otherwise successful request into an error. Either validate tags before executing the procedure or use a reversible encoding that handles lone surrogates.
  packages/cache/README.md:71
• This new package README omits the Cloudflare Traces guide, while every other synchronized package README includes it in the same row (for example README.md:71 and packages/cloudflare/README.md:71). Keep the generated package listing consistent.

• Files reviewed: 77/78 changed files
• Comments generated: 4
• Review effort level: Balanced

[pullfrog]

✅ No new issues in this delta — the NOSCRIPT retry is now bounded to exactly one reload, closing the last open thread.

Reviewed changes

This run reviews the delta since the prior pullfrog review at 5b6652c7 — the single commit 69f8cc89:

• Bounded the NOSCRIPT script reload to exactly once — RedisCacheStore.run (packages/cache/src/adapters/redis.ts) and BunRedisCacheStore.run (packages/bun/src/redis-cache.ts) dropped the while (true) loop for a single retry: on NOSCRIPT the cached sha is deleted and evalSha runs again (which reloads the script), and a second NOSCRIPT — or any other error — propagates instead of hanging forever. This is precisely the reload-once-then-throw contract the open thread asked for; the JSDoc on both stores now matches.
• Added real-server regression tests in both packages/cache/src/adapters/redis.test.ts and packages/bun/src/redis-cache.test.ts that seed an unknown sha ('0'.repeat(40)) into the store's scriptShas map and assert the fetch still succeeds after the single reload, across both the read and store scripts. Verified passing against live Redis in the node-26 CI log.

Notes:

• The lingering RESP3 output !== null miss-guard is unchanged (correct on the default RESP2 config) — still worth hardening eventually, but not part of this delta and not blocking.
• test_matrix (26) is red, but only on tests/batch/batch-plugin.test.ts:128 (expected 13 to be less than or equal to 10, a Date.now() - start timing assertion in a file this PR does not touch) — a timing flake unrelated to the cache feature; every cache/bun/cloudflare suite passes on node 26 in the same run.

  ^{｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ No new issues in this delta — the fill-hook refactor is a clean internal simplification with no behavioral change.

Reviewed changes

This run reviews the delta since the prior review at 69f8cc8 — the single commit 468cd88:

• Replaced the key-value snapshot + write hooks with one fill hook — BaseKeyValueCacheStore dropped its TSnapshot generic; subclasses now own the full miss/refresh path via fill(encodedKey, fill, options). MemoryCacheStore.fill captures the tag versions at the top of the method, before await fill(), preserving the fill-start snapshot timing the old split had (a revalidation landing mid-fill still invalidates what the fill stores); the mid-fill race tests in memory.test.ts still pass. VercelCacheStore.fill mirrors its old snapshot-less write exactly.
• Docs/JSDoc updated to match — the store class doc now says "read entries by their encoded key and fill the missing ones", and the entry-field comment notes the tag versions "each had when the fill started".

Verified: memory (18) and middleware (21) suites pass locally; head CI is green on every node plus lint/typecheck/builds.

  ^{｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}

[Copilot]

🟡 Changes recommended

Cache-key collisions, malformed-tag failures, and an incomplete Redis lock-takeover fence can produce incorrect or failed requests.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

• Files reviewed: 77/78 changed files
• Comments generated: 3
• Review effort level: Balanced

[pullfrog]

ℹ️ No new issues in this delta — the fetch→getOrSet rename, the key-collision hardening, and the lock-takeover fix read clean, with the memory, middleware, handler-plugin, and utils suites and type:check passing locally. One new operational assumption is flagged in the body below for the docs.

Reviewed changes

This run reviews the delta since the prior pullfrog review at 468cd88 — commits 36eff4f8 and 9c0d0f46:

• Renamed CacheStore.fetch to getOrSet — applied consistently across types.ts, the middleware, every store adapter, the @orpc/bun and @orpc/cloudflare stores, tests, and the docs page; no stray fetch/CacheFetchOptions references remain (grep-verified).
• Hardened encodeCacheKey against string/serialized-key collisions — serialized keys moved from an array to a { j, m } object form, and any string shaped like a serialized key (starts {, ends }) is serialized too, so a plain string key can never share an entry with a structural key. The object form is what makes the brace heuristic a reliable discriminator. Regression tests cover brace-shaped strings and the re-encode non-fixed-point.
• Kept the later fill on lock takeover — STORE_SCRIPT now persists startedAt and skips the write when a later-started fill's entry is already present, so a holder whose lock expired can no longer clobber the takeover's fresher entry. Covered by new real-server takeover tests in both the Redis and Bun suites (each would fail without the guard).
• Measured Workers-store expiry from fill completion — experimental_WorkersCacheStore.getOrSet now resolves expiry after await fill(), matching the Redis/memory/Vercel stores; the new test fails under the previous pre-fill timing.
• Aligned the package publishing hook — packages/cache/package.json build → prepack, matching the other packages; closes Copilot's missing-hook nit.

ℹ️ The startedAt guard leans on cross-process clock alignment

The new STORE_SCRIPT ordering arbitrates between two concurrent fills by wall-clock startedAt, so among processes sharing one Redis the fill that started latest (by clock) is kept. Under reasonably-synced clocks this is exactly the takeover semantics intended, and because the discard is always the globally-older fill, callers are never served stale data — a dropped fill still returns its fresh output to its own caller, it just isn't persisted, and the tag-version snapshot still invalidates a store that predates a mid-fill revalidation. If one process ever runs persistently behind the others' clocks, its fills for contended keys keep getting discarded (every request recomputes until the skew resolves); that self-heals and never corrupts, but it is a new assumption for a store whose own docs emphasize cross-process operation. A sentence in the Redis adapter docs noting that the store assumes roughly-aligned process clocks would save a future operator a confusing throughput regression.

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

[pullfrog]

✅ No new issues found in this delta — the Redis generation fence replaces the clock-based store guard cleanly (dropping the clock-alignment assumption the prior review flagged), and the surrogate fix closes the encode-time URIError on unrepresentable tags. Verified against live Redis 7.0.15: the full Redis integration suite (21 tests, including both lock-takeover races) passes.

Reviewed changes

This run reviews the single commit b7d077f2 since the prior pullfrog review at 9c0d0f4:

• Fenced Redis stores with a per-key lock generation — GET_SCRIPT now INCRs a g:<key> counter in the same atomic step that takes the SET NX PX lock; STORE_SCRIPT writes only while the counter still equals the value handed out, then deletes it; RELEASE_SCRIPT clears lock and generation only while they are still the caller's. A holder whose lock expired and was taken over can no longer land its store even once the takeover entry is gone, and — because the fence is a monotonic counter rather than wall-clock startedAt — it also removes the cross-process clock-alignment assumption the previous review flagged. The dropped fill is always the globally-older one, so callers keep their own fresh output and never see stale data; the generation key resetting to 1 after delete is benign since the fence is equality-based and exactly one fill is live per key at a time.
• Made encodeCacheTag safe on lone surrogates — an unpaired surrogate (which has no UTF-8 form) is replaced with U+FFFD before percent-encoding, so encodeURIComponent no longer throws on tags arriving through JSON, closing the codec URIError risk; well-formed astral pairs still encode as their real code points.
• Added regression coverage — "stores nothing from a holder that lost its lock, even once the takeover entry is gone" in both the node-redis and Bun suites (plus g: key-cleanliness asserts), and lone-surrogate assertions in http.test.ts that would throw before the fix. Docs note the U+FFFD substitution.

Verified locally against a live Redis 7.0.15: all 21 Redis integration tests pass, the shared http.test.ts (95) and cache unit suites (72) pass, and type:check is clean for @orpc/experimental-cache and @orpc/shared. The head's own CI (beyond Workers Builds) had not reported at review time.

  ^{｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

ℹ️ The lone-surrogate revert reads clean — the collision rationale is sound — one documentation nit below. Verified: shared http.test.ts and the cache suites pass on this head.

Reviewed changes

This run reviews the single commit 2d6aa9aa since the prior pullfrog review at b7d077f:

• Reverted the lone-surrogate handling in encodeCacheTag — the U+FFFD substitution, its tests, and the docs sentence are removed from @orpc/shared, restoring the pre-b7d077f2 behavior where a lone-surrogate tag makes encodeURIComponent throw. The retreat is well-founded: substituting U+FFFD would have made two distinct tags (e.g. a\uD800 and a\uFFFD) encode to the same header value, silently merging them in a case-insensitive cache — an error is more honest than that collision, and no lossless UTF-8 encoding of a lone surrogate exists to fall back on. The revert is limited to http.ts, http.test.ts, and the docs page; no dangling references remain.

Re-ran the affected suites on this head: shared http.test.ts and the cache unit suites all pass.

ℹ️ Nitpicks

• packages/shared/src/http.ts — encodeCacheTag now throws a URIError on lone-surrogate tags again, but its JSDoc (and the "Every non-empty tag list round-trips exactly" note on decodeCacheTagHeader) still reads as if every string encodes cleanly. This throw can also surface from the handler-plugin header reflection and the Workers purge path after the request already committed, so a sentence in the JSDoc noting the throwing contract would save a future operator from misreading a 500 as a plugin bug. Not asking to re-fix the behavior — the revert's rationale stands.

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

[Copilot]

🟡 Changes recommended

Nested cache middleware can emit inconsistent tags and TTL metadata, and the new adapter exports lack barrel-test coverage.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

Suppressed comments (2)

Previously missed (2) — in code that hasn't changed since the last review.

packages/bun/src/index.ts:1

• The existing Bun barrel test (packages/bun/src/index.test.ts:3-7) enumerates public exports but was not updated for BunRedisCacheStore, so this new entry point is not covered. Add it to that assertion to catch packaging/export regressions.
  packages/cloudflare/src/index.ts:6
• The existing Cloudflare barrel test (packages/cloudflare/src/index.test.ts:3-9) enumerates public exports but omits experimental_WorkersCacheStore, leaving this new entry point unverified. Add the store to that assertion.

• Files reviewed: 77/78 changed files
• Comments generated: 1
• Review effort level: Balanced

[pullfrog]

ℹ️ No critical issues in this delta — the lookup-order fix and barrel coverage read clean, with CI green on the head. One consistency nit inline.

Reviewed changes

This run reviews the delta since the prior pullfrog review at 2d6aa9aa (commits e4667ae4 and 3a729227):

• Merged upstream main — @orpc/bun, @orpc/experimental-cache, and @orpc/cloudflare bumped to 2.0.0-beta.35 to match main's release; no other net changes.
• Recorded stacked cache lookups in lookup order — the cache() middleware now captures its position in the plugin context before awaiting store.getOrSet and splices its record there, so stacked caches land outermost-first and the handler plugin reflects the outer cache's tags on misses and hits alike (previously inner-first, flip-flopping between miss and hit). The new regression test in middleware.test.ts fails without the fix (verified).
• Covered the new barrel exports — BunRedisCacheStore (@orpc/bun) and experimental_WorkersCacheStore (@orpc/cloudflare) are now asserted in their packages' export tests.

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

[pullfrog]

The revalidate middleware still appends its record after next() completes, so a stacked pair records inner-first — the same reverse-order pattern this commit just fixed for caches. The revalidations JSDoc claims "in the order they ran", and the plugin's find(isRoot) will reflect the inner revalidation's tags for a stacked pair. Mirroring the lookupIndex splice would keep the two paths consistent.

[pullfrog]

ℹ️ No new issues in this delta — the store rename and the memory-store sweep read clean, with head CI green on all nodes.

Reviewed changes

This run covers the delta since the prior pullfrog review at 3a729227: a1dd3785 and 59beee06.

• Renamed BunRedisCacheStore to experimental_BunRedisCacheStore — applied consistently across the @orpc/bun export, its integration tests, the cross-adapter compatibility suite, the barrel test, and the docs page. No dangling references remain, and the experimental_ prefix matches the convention already used for experimental_WorkersCacheStore.
• Swept expired and revalidated entries from the memory store on writes — MemoryCacheStore tracks the earliest pending eviction in nextSweepAt and runs a full-map sweep on the next fill once that time (or a revalidate) has passed, re-arming the schedule from the surviving entries. The read path keeps its prior eager eviction, so the sweep is pure garbage collection and can never serve stale data. The new regression test fails against the pre-change store (verified locally), and the nextSweepAt bookkeeping checks out under both the expiring and revalidated scenarios.

The only open thread from the prior review (the revalidate record-order consistency nit at middleware.ts:136) is untouched by this window and remains so.

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

[pullfrog]

✅ No new issues found in the BentoCache delta. This review is non-approving only because the single open Pullfrog thread on the revalidate record order (middleware.ts:136) remains open — untouched by this commit and not re-raised here.

Reviewed changes

This run reviews the delta since the prior pullfrog review at 59beee06 — the single commit 6ee2f55e:

• Added BentoCacheStore (packages/cache/src/adapters/bentocache.ts, subpath @orpc/experimental-cache/bentocache) — drives any BentoCache setup through its own getOrSet/getOrSetForever under BentoCache's lock, maps ttl/swr to BentoCache's TTL and grace period (milliseconds), serves stale entries within grace while BentoCache refreshes them in the background, and hands a failed refresh to waitUntil — without a waiter it surfaces as an unhandled rejection, matching the documented SWR contract across stores.
• Mapped revalidation to deleteByTag — tags delete natively, so with swr a revalidated entry is served once more while a refresh runs; a mid-fill revalidation is documented as undetected. Fill errors are unwrapped via E_FACTORY_ERROR, with non-background onFactoryError invocations guarded out so a sync miss failure isn't double-surfaced.
• Wired the adapter in — optional peer dependency + dev dependency + lockfile for bentocache@^1.6.1, subpath export entry, a new docs page section with a setup example, and the README package-table/description sync across the monorepo.
• Adjusted the shared store contract and the memory suite — the contract's keeps entries filled after a revalidation now sleep(1) before refilling (BentoCache's tag invalidation is millisecond-granular), and memory.test.ts fakes only Date so that shared sleep isn't blocked by fully faked timers.

I verified the load-bearing BentoCache API assumptions against the installed bentocache@1.6.1 type declarations (grace/ttl/onFactoryError accepted by both getOrSet and getOrSetForever; FactoryError.cause + isBackgroundFactory; E_FACTORY_ERROR; deleteByTag) and ran the local suite: bentocache (16) and memory (19) pass, the full cache unit run (90) passes, and pnpm --filter @orpc/experimental-cache type:check is clean.

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

[pullfrog]

✅ No new issues found in the TieredCacheStore delta. Non-approving for the same reason as the prior review: the single open Pullfrog thread on the revalidate record order (middleware.ts:136) remains open.

Reviewed changes

This run reviews the delta since 6ee2f55 — the single commit 84268ab6:

• Added TieredCacheStore (exported from the @orpc/experimental-cache barrel) — layers two or more stores front to back; a miss in any tier fills from the next via a recursive getOrSetFrom, so only the last tier runs the user's fill, and revalidate fans out to every tier through Promise.all. Each tier receives the shared options with ttl/swr capped against the tier's caps (Math.min, with an undefined option falling back to the tier cap), so a front tier's copy expires before the entry behind it can change.
• Documented the tier semantics — the docs page gains a "Tiered Store" section (anchor #tiered-store, matching the class JSDoc @see), covering a miss filling from the next tier, revalidation reaching every tier, and the "measure ttl from when it stored its copy — cap it on front tiers" caveat. The barrel export test now asserts TieredCacheStore.
• Tested with teeth — a shared store-contract run against two memory tiers, plus tier-specific tests: a front miss fills from a pre-populated back tier without invoking the user's fill; per-tier ttl/swr caps are honored on both capped and uncapped requests (expiry asserted under a frozen clock); waitUntil is handed out by every stale tier (two refresh promises for one two-tier stale request, with the front's refresh copying the back's stale value while the back's refresh runs the real fill); and revalidate reaches all tiers.

I traced the layered-SWR flows (stale front + stale back, stale front + fresh back, hard-miss front + stale back) and verified the recursion, the cap fallback rules, and the next returns-.output-only delegation all behave as documented and as the assertions describe; the local suite passes (tiered 11, full cache unit run 101) and pnpm --filter @orpc/experimental-cache type:check is clean. The one prior thread (middleware.ts:136) is untouched by this commit.

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