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: 26f97f9

[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	26f97f9	Commit Preview URL Branch Preview URL	Sep 08 2026, 02:17 PM

[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 12.9%

⚠️ 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
❌	octet stream	645.9 µs	741.6 µs	-12.9%

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 (26f97f9) with main (03ac086)}

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

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]

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]

Important

This delta removes the fallback .catch from the stale-while-revalidate refresh path, so on the common Node setup (no cache/waitUntil wired) a failed background refresh now becomes an unhandled rejection — which terminates the process by default. Prior reviews' IMPORTANT threads on revalidate fail-loud and un-storable outputs stored as {} also remain open.

Reviewed changes

This run reviews the PR-owned delta since the prior pullfrog review at 8a12845b:

• Removed experimental_KVCacheStore from @orpc/cloudflare — breaking; only the purge-only WorkersCacheStore remains. Clean: no dangling references in code, exports, tsconfig.json, README, wrangler KV binding, or the docs page.
• Reworked SWR refresh ownership — the middleware now hands the refresh to cache/waitUntil unconditionally with no fallback catch, so without a waiter a refresh failure surfaces as an unhandled rejection.
• Updated the handler-plugin headers JSDoc to match current behavior (any method, overriding), and dropped the now-orphaned "overrides existing headers" test, leaving the presetHeadersPlugin/preset test scaffolding unused.
• Hardened the shared holdResult race-test helper with a read promise so the racing-revalidation tests sequence deterministically across Memory/Redis/Upstash/Bun.
• Expanded cross-adapter compatibility suites (tag counters, retention staging) and gated the Upstash integration suite off Node 26 with a TODO.
• Synced the packages table across every package README (markdown-table restyle).

Inline feedback anchors on the SWR refresh change. The two prior IMPORTANT threads (revalidate fail-loud; un-storable outputs persisted and served as {}) are unchanged by this delta and remain to address. Two nits are inline.

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

[pullfrog]

Without cache/waitUntil in the context — the default on runtimes other than Workers, since nothing auto-wires it — a failed stale-while-revalidate refresh is now an unhandled rejection, and Node terminates the process on an unhandled rejection by default. The previous delta deliberately .catch(() => {})d the refresh when nothing owned it; this delta drops that fallback. The new 'leaves refresh failures unhandled without waitUntil' test asserts the new contract, but outside the test runner a transient origin error during a background refresh would take the whole server down.

[pullfrog]

Removing the "sets its headers over existing ones" test left presetHeadersPlugin and the preset parameter of createTestingHandler with no callers, yet the docs/headers JSDoc still claim the plugin sets headers over anything already on the response — a documented behavior now without test coverage. Either restore the override test or drop the dead preset scaffolding.

[pullfrog]

Pullfrog stalled

The agent stopped emitting events for 125s and was killed by the activity-timeout watchdog. The model produced no output at all before the stall — the request was sent but nothing came back. This is usually transient; re-running often succeeds.

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

[pullfrog]

ℹ️ No new issues in this delta — the per-key locking rework and the MemoryLock relocation to @orpc/shared review clean.

Reviewed changes

This run covers the delta since the prior pullfrog review at 1c711593: commits 082d46f7 (per-key locks) and 685f61fa (MemoryLock → @orpc/shared).

• Added CacheStore.lock(key, fn) — an optional per-key lock on the store contract; the cache() middleware fills a miss and refreshes a stale entry under it, re-reading store.get(key) after waiting so concurrent callers fill/refresh once instead of once each (middleware.ts).
• Implemented lock in the Redis-family adapters — a SET NX lease with PX lockTtl and a token-checked EVAL release in RedisCacheStore, UpstashCacheStore, and BunRedisCacheStore, so locks span processes; a crashed holder's lease expires and a taken-over lock is released only by its own token. Covered by mocked, integration, and cross-adapter (Redis↔Upstash↔Bun) tests.
• Implemented lock in-process via MemoryLock for MemoryCacheStore and VercelCacheStore, handing the turn on after failures.
• Moved MemoryLock to @orpc/shared (lock.ts, exported with tests) — clean move, no dangling references, and @orpc/experimental-cache already depends on @orpc/shared.
• Docs updated — lock semantics, lockTtl, and "one fill / one refresh under lock" claims on the cache page.

I verified the highest-risk spots rather than taking them on faith: lock re-entry through serve() inside the miss-path lock does not deadlock on either lock kind (in-process callers queue behind the running callback; the Redis release fires as soon as serve returns, since the refresh isn't awaited), the waited re-read refuses a still-stale entry to the refresh path, and each open thread's code is untouched by this delta.

Carried forward from prior reviews and left open (unchanged by this delta): the revalidate fail-loud path, un-storable outputs persisted and served as {}, the SWR refresh unhandled-rejection default without cache/waitUntil, and the Upstash empty-tags / dead-preset scaffolding nits.

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

[pullfrog]

Caution

The fetch-fold rewrite (e9f5f591) mis-decodes the cache-miss sentinel on RESP3 clients — the default for the pinned redis@^6.2.1 client and for Bun's built-in client — so every cache miss is treated as a hit and the first request for each key is answered with an empty output. The head's CI is red on the new cross-adapter cache suite, and the PR description's "full suite passes" claim no longer holds.

Reviewed changes

• Folded get/set/lock into CacheStore.fetch(key, fill, options) — stores now own entry coalescing and stale-refresh; a stale entry is served while one caller refreshes it in the background; the middleware became a thin passthrough.
• Rewrote the Redis-family stores as prefix-scoped hashes driven by two EVALSHA Lua scripts — the read script validates tag versions and takes the SET NX PX lock in one step; the store script snapshots the versions, writes the entry with PEXPIRE, and releases the lock by token, with per-store script-sha caching and NOSCRIPT reload.
• Moved the SWR refresh-failure contract into CacheFetchOptions.waitUntil — the option documents that without a waiter, failures surface as unhandled rejections, and the middleware test now asserts that contract.
• Simplified the handler-plugin check recording — the middleware derives the reflected ttl from entry.expiresAt instead of carrying per-path refresh logic.
• Merged upstream main — README package tables and description renames across every package README.

🚨 The head's CI is red

Run 34232486693 on e9f5f591 fails every test_matrix job in the new cache redis adapters compatibility suite, and lint_and_typecheck cannot resolve @standardserver/core from packages/cache/src/handler-plugin.ts. The PR description's "Full monorepo suite, type-check, lint, and docs validation pass" no longer holds for this head and should be restored before merging. The test failures — TypeError: null is not an object while destructuring the EVALSHA reply, a stale entry served back as its refreshed value, 20 s timeouts, and ERR_REDIS_CONNECTION_CLOSED — all sit in the newly scripted fetch path and corroborate the inline finding at packages/cache/src/adapters/redis.ts:158.

Technical details

# Head CI is red (run 34232486693, head e9f5f591)

## Evidence
- test_matrix (node 20/22/24/26): `packages/bun` → `tests/cache-redis-adapters-compatibility.test.ts` — all eight cross-adapter scenarios fail in both directions (redis → bun redis and bun redis → redis). node 22 first error: `TypeError: null is not an object (evaluating '[output, tags, expiresAt, shouldFill]')` at `redis-cache.ts:152`; node 20/22: `Expected: "v" Received: "refilled"` (the stale-serve assertion in the "shares retention" scenario); node 24/26: 20 s timeouts plus `ERR_REDIS_CONNECTION_CLOSED` in the harness.
- The root-vitest `redis-adapters-compatibility.test.ts` is skipped in CI: it requires `UPSTASH_REDIS_REST_URL`/`_TOKEN` (`stores.length < 2` guard) while CI only exports `REDIS_URL`, so the node-redis `RedisCacheStore` has no CI-enforced real-client coverage.
- lint_and_typecheck: `packages/cache/src/handler-plugin.ts(3,38): error TS2307 Cannot find module '@standardserver/core'`. `packages/cache` declares `@standardserver/core@^0.8.2` (resolved 0.8.3 in the lockfile); the runner logged a "pnpm v10 installation layout" warning, so this could be a toolchain artifact rather than a packaging gap — not yet attributed.

## Required outcome
- The cross-adapter cache suite must pass on the head before the rewrite merges; re-run the full suite after fixing the RESP3 sentinel decoding (inline comment at `redis.ts:158`).
- Re-attribute the `@standardserver/core` lint failure on a clean install; if it reproduces, the new package's dependency resolution is incomplete.
- Consider dropping the Upstash-credential gate so the node-redis store gets real-client CI coverage.

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

[pullfrog]

On a miss the script's reply leads with the Lua false sentinel (return { output or false, ... } at line 40), and this output !== null guard only decodes it correctly under RESP2, where Lua false becomes a null bulk reply. The pinned redis@^6.2.1 client (@redis/client@6.2.1) enables RESP3 by default (DEFAULT_RESP = 3, handshake HELLO 3) and its decoder maps a RESP3 boolean back to JS false — so every miss is decoded as a hit, the store returns { output: undefined, tags: false, expiresAt: 0 }, and the middleware answers the request with an empty output. Redis v4/v5 (RESP2 default) and Upstash (RESP2-style REST) happen to be safe, which is why the defect is client-version-dependent.

Technical details

# `fetch` mis-decodes the miss sentinel under RESP3 clients

## Affected sites
- packages/cache/src/adapters/redis.ts:40 and :158 — `return { output or false, ... }` + `if (output !== null)`
- packages/bun/src/redis-cache.ts:40 and :158 — same
- packages/cache/src/adapters/upstash.ts:40 and :168 — same pattern; Upstash's REST gateway replies RESP2-style, so nil decodes to `null` and it is unaffected
- packages/cache/src/middleware.ts:82-97 — `done({ output: entry.output })` returns the corrupted entry on the miss path

## Root cause
Lua `false` inside a returned array becomes a RESP2 null-bulk but a RESP3 boolean. `redis@6.2.1` / `@redis/client@6.2.1` (resolved in pnpm-lock.yaml, pinned in the cache and bun package.json devDependencies) ships `DEFAULT_RESP = 3` (`dist/lib/RESP/types.js`), handshakes `HELLO 3` unless `RESP: 2` (`dist/lib/client/index.js`), and its RESP3 decoder returns a JS boolean for a boolean reply (`dist/lib/RESP/decoder.js` `#decodeBoolean`) — consistent with Redis's Lua→RESP3 conversion docs. Bun's built-in Redis client also negotiates RESP3. Under RESP3 a miss decodes to `[false, false, false, …]`, so `output !== null` is true, the entry built is `{ output: deserialize(JSON.parse(false).body) → undefined, tags: JSON.parse(false) → false, expiresAt: Number(false) → 0 }`, and the middleware responds with empty output. The fill still runs detached (no `waitUntil` on plain Node), so a later request finds the real entry and the failure looks transient.

## Required outcome
- A miss must never decode as a hit on any supported client/RESP version. Stop using Lua booleans as miss markers (return explicit `''`/integer markers), or normalize the reply on the JS side for all three stores (e.g. `typeof output === 'string'`).
- Add a CI-enforced real-client test of a miss-then-fill against the node-redis v6 client (and ideally the Bun client) so the reply shape cannot regress again; the current integration suites only run when env-gated credentials are present.

## Evidence
- CI run 34232486693 on head e9f5f591: test_matrix fails in `packages/bun` `cache redis adapters compatibility` in both directions — `TypeError: null is not an object (evaluating '[output, tags, expiresAt, shouldFill]')` at `redis-cache.ts:152`, `Expected: "v" Received: "refilled"` stale-serve failures, 20 s timeouts, and `ERR_REDIS_CONNECTION_CLOSED`. The single-store bun integration suite passes, so the shared script reply shape is the common defect.

[pullfrog]

Same guard and sentinel as redis.ts:158 — see that comment for the full analysis and fix. Bun's Redis client also negotiates RESP3, and this head's own CI is failing exactly here: TypeError: null is not an object (evaluating '[output, tags, expiresAt, shouldFill]') at redis-cache.ts:152 in the cross-adapter suite, followed by the stale-serve failures and timeouts.

[pullfrog]

Important

The BaseRedisCacheStore extraction reads clean, but it consolidates the flagged miss-decode into a shared base the three Redis-family adapters now all depend on without fixing it, and the head's CI is still red on the cross-adapter cache suite plus the @standardserver/core type error. The two prior inline threads on the output !== null guard remain open.

Reviewed changes

This run reviews the delta since the prior pullfrog review at e9f5f591: cb97a43a + 10d3af0d (Vercel-lock feature added then reverted — net zero) and 26f97f95, the head commit.

• BaseRedisCacheStore extraction — the two Lua scripts, the fetch loop, the store step, and revalidate now live once in an abstract base in packages/cache/src/adapters/redis.ts; RedisCacheStore, UpstashCacheStore, and BunRedisCacheStore only run a script through their client (EVALSHA with per-script sha caching for node-redis/bun, createScript for Upstash).
• parseReply normalization — replies now take the same path whether the client returns raw strings (node-redis, bun) or pre-parsed values (Upstash); the fetch entry is decoded from parseReply(output).body.
• REVALIDATE_SCRIPT — tag revalidation is a single INCR loop script shared by all three stores, replacing the per-store incr/multi paths.
• NOSCRIPT recursion guard — the reload path now takes a reloaded flag so a persistent server-side script eviction cannot recurse forever (an improvement over the previous retry).
• Test/doc churn — the bun integration suite drops its afterAll client close ("breaks the next file's client on Bun 1.4") and sets per-test timeouts; the cross-adapter suite hoists client setup to module scope with a combined afterAll; the cache docs note the shared base.

⚠️ The refactor preserves the open miss-decode blocker and head CI is still red

The extraction keeps the exact if (output !== null) guard (packages/cache/src/adapters/redis.ts:164) and the return { output or false, ... } sentinel (:40) that the prior review flagged as mis-decoding every miss as a hit on RESP3 clients — it moved them into the base rather than fixing them, which widens the blast radius to all three adapters instead of narrowing it.

Head CI on 26f97f95 (run 34237043815) confirms the blocker is live: test_matrix fails on node 20/22/24/26 in packages/bun/tests/cache-redis-adapters-compatibility.test.ts (20 s timeouts on entries/tag-counters/locks, stale-serve Expected "v" Received "refilled" on retention, ERR_REDIS_CONNECTION_CLOSED), and lint_and_typecheck still fails packages/cache/src/handler-plugin.ts(3,38) TS2307 Cannot find module '@standardserver/core'. The PR description's "full suite passes" claim still does not hold.

Technical details

# Base extraction is clean but the RESP3 miss-decode is unaddressed

## Affected sites
- packages/cache/src/adapters/redis.ts:40 and :164 (base) — `false` miss sentinel + `output !== null` guard; unchanged from the flagged e9f5f591 version, now shared by Redis/Upstash/Bun
- packages/bun/src/redis-cache.ts — thin `run` override inherits the base decode
- packages/cache/src/handler-plugin.ts:3 — `@standardserver/core` (no hyphen, deprecated) vs `@standard-server/core` used elsewhere; `StandardHeaders` is re-exported by `@orpc/server` (packages/server/src/index.ts:130), so the import source could change

## Required outcome
- Fix the miss sentinel so a miss never decodes as a hit on any client/RESP version (stop using Lua booleans as miss markers, or normalize in JS, e.g. `typeof output === 'string'`), then get the cross-adapter suite green.
- Resolve the `@standardserver/core` import/dependency so `type:check` passes.

## Open questions for the human
- Is `@standardserver/core@0.8.x` intentionally pinned (legacy deprecated name), or should the import come from `@orpc/server` / `@standard-server/core`?

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