Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dinwwwh wants to merge 59 commits into
base: main
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
59 commits
Select commit Hold shift + click to select a range
282fd1a
feat(cache): add tag-based caching and revalidation helpers
dinwwwh Aug 27, 2026
1faf825
Merge remote-tracking branch 'middleapi/main' into claude/orpc-cache-…
dinwwwh Aug 27, 2026
faa7836
refactor(cloudflare): drop the Cache API cache store
dinwwwh Aug 28, 2026
9b503ad
refactor(cache): default store key prefixes to none
dinwwwh Aug 28, 2026
93288dd
refactor(cloudflare): rename cache stores to KVCacheStore and Workers…
dinwwwh Aug 28, 2026
f35e3ad
refactor(cache): unify store constructors on a single options object
dinwwwh Aug 28, 2026
6c3f4dd
chore(cloudflare): shorten package description
dinwwwh Aug 28, 2026
8d5c356
chore: shorten the cloudflare package description in package lists
dinwwwh Aug 28, 2026
71cf231
refactor(cache): serialize outputs with RPCSerializer and ignore blob…
dinwwwh Aug 28, 2026
9329af7
refactor(cache): encode keys inside stores with sorted key material
dinwwwh Aug 28, 2026
4649b4c
refactor(shared): recurse into Maps and Sets in deepSortKeys
dinwwwh Aug 28, 2026
b2b1ba5
refactor(cache): canonicalize keys after serialization via shared enc…
dinwwwh Aug 28, 2026
87232ff
refactor(cache): construct the default key serializer per call
dinwwwh Aug 28, 2026
99ff5a3
feat(cache): allow configuring the memory store key serializer
dinwwwh Aug 28, 2026
b70ec44
docs(cache): document key encoding in the adapters section
dinwwwh Aug 28, 2026
1cca86b
refactor(cache): make the handler plugin inert until headers are conf…
dinwwwh Aug 28, 2026
f95ba53
fix(cache): percent-encode uppercase tag characters for case-insensit…
dinwwwh Aug 28, 2026
8129954
test(cache): reach full adapter coverage and hoist key encoding
dinwwwh Aug 28, 2026
17c31c2
refactor(cache)!: publish as @orpc/experimental-cache with prefixed c…
dinwwwh Aug 28, 2026
c2356fb
refactor(cache)!: rework the store contract and header reflection
dinwwwh Sep 3, 2026
313a01f
Merge remote-tracking branch 'upstream/main' into claude/orpc-cache-i…
dinwwwh Sep 3, 2026
e9c8063
refactor(shared): split encodeCacheTag out of encodeCacheTagHeader
dinwwwh Sep 4, 2026
8a12845
feat!: add Upstash and Bun cache stores, take store clients positionally
dinwwwh Sep 4, 2026
49afa3d
test(cache): add cross-adapter compatibility suites for the Redis stores
dinwwwh Sep 4, 2026
1d9265f
docs: sync the packages tables across every package README
dinwwwh Sep 4, 2026
7958a2a
fix(cache): wait for the stale-while-revalidate refresh without cache…
dinwwwh Sep 4, 2026
479d744
fix(cache): hand the stale-while-revalidate refresh to cache/waitUnti…
dinwwwh Sep 4, 2026
f81e29c
docs(cache): describe the headers option's current override behavior
dinwwwh Sep 4, 2026
3aaafb6
Update handler-plugin.ts
dinwwwh Sep 4, 2026
12694be
improve
dinwwwh Sep 4, 2026
1c71159
feat(cloudflare)!: remove experimental_KVCacheStore
dinwwwh Sep 4, 2026
082d46f
feat(cache): add per-key locks so concurrent misses fill an entry once
dinwwwh Sep 5, 2026
685f61f
refactor(shared): move MemoryLock out of the cache package
dinwwwh Sep 5, 2026
0844fe7
Merge remote-tracking branch 'upstream/main' into claude/orpc-cache-i…
dinwwwh Sep 8, 2026
e9f5f59
feat(cache)!: fold get, set, and lock into one fetch method
dinwwwh Sep 8, 2026
cb97a43
feat(cache): let the Vercel store take any Lock, defaulting to Memory…
dinwwwh Sep 8, 2026
10d3af0
Revert "feat(cache): let the Vercel store take any Lock, defaulting t…
dinwwwh Sep 8, 2026
26f97f9
refactor(cache): share the Redis flow through BaseRedisCacheStore
dinwwwh Sep 8, 2026
7fed718
Merge remote-tracking branch 'upstream/main' into claude/orpc-cache-i…
dinwwwh Sep 9, 2026
ebf06cc
refactor(cache): move BaseRedisCacheStore to adapters/base-redis
dinwwwh Sep 9, 2026
2a368bb
refactor(cache): simplify the stores and unify their serializers
dinwwwh Sep 9, 2026
5b6652c
fix(cache): capture tag versions when a fill starts and report evicti…
dinwwwh Sep 9, 2026
69f8cc8
fix(cache): retry a NOSCRIPT script exactly once
dinwwwh Sep 9, 2026
468cd88
refactor(cache): replace the key-value snapshot hook with a fill hook
dinwwwh Sep 9, 2026
36eff4f
fix(cache): keep the later fill after a lock takeover, and address re…
dinwwwh Sep 10, 2026
9c0d0f4
refactor(cache): rename CacheStore.fetch to getOrSet
dinwwwh Sep 10, 2026
b7d077f
fix(cache): fence Redis stores with a lock generation, and encode lon…
dinwwwh Sep 10, 2026
2d6aa9a
revert(shared): keep throwing on lone surrogates in cache tags
dinwwwh Sep 10, 2026
e4667ae
Merge remote-tracking branch 'upstream/main' into claude/orpc-cache-i…
dinwwwh Sep 10, 2026
3a72922
fix(cache): record stacked cache lookups in lookup order, and cover t…
dinwwwh Sep 10, 2026
a1dd378
refactor(bun): prefix the Redis cache store with experimental_
dinwwwh Sep 10, 2026
59beee0
feat(cache): sweep expired and revalidated entries from the memory st…
dinwwwh Sep 10, 2026
6ee2f55
feat(cache): add a BentoCache adapter
dinwwwh Sep 10, 2026
84268ab
feat(cache): add TieredCacheStore to layer stores front to back
dinwwwh Sep 10, 2026
7b9bd3d
Merge remote-tracking branch 'upstream/main' into claude/orpc-cache-i…
dinwwwh Sep 15, 2026
18715c6
refactor(cache): replace the Redis scripts with single-key commands, …
dinwwwh Sep 15, 2026
20976bf
feat(cache): add a Cacheable adapter
dinwwwh Sep 15, 2026
76a79a5
chore(cache): drop the BentoCache adapter
dinwwwh Sep 15, 2026
67ea012
refactor(cache): switch durations to milliseconds, and share envelope…
dinwwwh Sep 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 8 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,13 +46,14 @@ You can read the documentation [here](https://orpc.dev).

**Built-in features**

| Package | Purpose | Docs |
| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| [@orpc/publisher](https://www.npmjs.com/package/@orpc/publisher) | Pub/Sub with memory, Redis, and Upstash adapters. | [Publisher](https://orpc.dev/docs/helpers/publisher) |
| [@orpc/ratelimit](https://www.npmjs.com/package/@orpc/ratelimit) | Rate limiting with memory, Redis, and Upstash adapters. | [Rate Limit](https://orpc.dev/docs/helpers/ratelimit) |
| [@orpc/experimental-lock](https://www.npmjs.com/package/@orpc/experimental-lock) | Locking with memory, Redis, and Upstash adapters. | [Lock](https://orpc.dev/docs/helpers/lock) |
| [@orpc/hibernation](https://www.npmjs.com/package/@orpc/hibernation) | Leverage Hibernation APIs like [Cloudflare's Hibernation WebSocket](https://developers.cloudflare.com/durable-objects/best-practices/websockets/#durable-objects-hibernation-websocket-api). | [Hibernation](https://orpc.dev/docs/integrations/hibernation) |
| [@orpc/json-schema](https://www.npmjs.com/package/@orpc/json-schema) | Smart coercion for OpenAPI requests. | [Smart Coercion](https://orpc.dev/docs/plugins/smart-coercion) |
| Package | Purpose | Docs |
| ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| [@orpc/publisher](https://www.npmjs.com/package/@orpc/publisher) | Pub/Sub with memory, Redis, and Upstash adapters. | [Publisher](https://orpc.dev/docs/helpers/publisher) |
| [@orpc/ratelimit](https://www.npmjs.com/package/@orpc/ratelimit) | Rate limiting with memory, Redis, and Upstash adapters. | [Rate Limit](https://orpc.dev/docs/helpers/ratelimit) |
| [@orpc/experimental-cache](https://www.npmjs.com/package/@orpc/experimental-cache) | Tag-based caching and revalidation with memory, Redis, Upstash, Vercel, and Cacheable adapters. | [Cache](https://orpc.dev/docs/helpers/cache) |
| [@orpc/experimental-lock](https://www.npmjs.com/package/@orpc/experimental-lock) | Locking with memory, Redis, and Upstash adapters. | [Lock](https://orpc.dev/docs/helpers/lock) |
| [@orpc/hibernation](https://www.npmjs.com/package/@orpc/hibernation) | Leverage Hibernation APIs like [Cloudflare's Hibernation WebSocket](https://developers.cloudflare.com/durable-objects/best-practices/websockets/#durable-objects-hibernation-websocket-api). | [Hibernation](https://orpc.dev/docs/integrations/hibernation) |
| [@orpc/json-schema](https://www.npmjs.com/package/@orpc/json-schema) | Smart coercion for OpenAPI requests. | [Smart Coercion](https://orpc.dev/docs/plugins/smart-coercion) |

**Framework & ecosystem integrations**

Expand Down
5 changes: 3 additions & 2 deletions apps/content/docs/api-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ For questions the reference does not answer, [oRPC on DeepWiki](https://deepwiki

| Package | Purpose | Related Guides |
| ------- | ------- | -------------- |
| [@orpc/experimental-cache](https://npmx.dev/package-docs/@orpc/experimental-cache) | Tag-based caching and revalidation with memory, Redis, Upstash, and Vercel adapters. | [Cache](/docs/helpers/cache) |
| [@orpc/publisher](https://npmx.dev/package-docs/@orpc/publisher) | Pub/Sub with memory, Redis, and Upstash adapters. | [Publisher](/docs/helpers/publisher) |
| [@orpc/ratelimit](https://npmx.dev/package-docs/@orpc/ratelimit) | Rate limiting with memory, Redis, and Upstash adapters. | [Rate Limit](/docs/helpers/ratelimit) |
| [@orpc/experimental-lock](https://npmx.dev/package-docs/@orpc/experimental-lock) | Locking with memory, Redis, and Upstash adapters. | [Lock](/docs/helpers/lock) |
Expand All @@ -51,8 +52,8 @@ For questions the reference does not answer, [oRPC on DeepWiki](https://deepwiki
| [@orpc/experimental-msw](https://npmx.dev/package-docs/@orpc/experimental-msw) | Mock procedures at the network level with typed MSW request handlers. | [MSW](/docs/integrations/msw) |
| [@orpc/nest](https://npmx.dev/package-docs/@orpc/nest) | Implement your contract with NestJS. | [NestJS](/docs/integrations/nest) |
| [@orpc/node](https://npmx.dev/package-docs/@orpc/node) | Node.js plugins for static file serving and large uploads. | [Static File](/docs/plugins/static-file), [Tmp File Upload](/docs/plugins/tmp-file-upload), [Batch Response Compression](/docs/plugins/batch-response-compression) |
| [@orpc/bun](https://npmx.dev/package-docs/@orpc/bun) | Bun Redis adapters for Publisher, Rate Limit, and Lock. | [Publisher](/docs/helpers/publisher), [Rate Limit](/docs/helpers/ratelimit), [Lock](/docs/helpers/lock) |
| [@orpc/cloudflare](https://npmx.dev/package-docs/@orpc/cloudflare) | Adapters for Cloudflare Workers. | [Publisher](/docs/helpers/publisher), [Rate Limit](/docs/helpers/ratelimit), [Lock](/docs/helpers/lock), [Traces](/docs/integrations/cloudflare-traces) |
| [@orpc/bun](https://npmx.dev/package-docs/@orpc/bun) | Bun Redis adapters for Cache, Publisher, Rate Limit, and Lock. | [Cache](/docs/helpers/cache), [Publisher](/docs/helpers/publisher), [Rate Limit](/docs/helpers/ratelimit), [Lock](/docs/helpers/lock) |
| [@orpc/cloudflare](https://npmx.dev/package-docs/@orpc/cloudflare) | Adapters for Cloudflare Workers. | [Cache](/docs/helpers/cache), [Publisher](/docs/helpers/publisher), [Rate Limit](/docs/helpers/ratelimit), [Lock](/docs/helpers/lock), [Traces](/docs/integrations/cloudflare-traces) |
| [@orpc/trpc](https://npmx.dev/package-docs/@orpc/trpc) | Reuse existing tRPC routers within oRPC. | [tRPC](/docs/integrations/trpc) |

## Observability
Expand Down
Loading
Loading