Cache Helpers

Cache oRPC procedure output with tag-based revalidation, stale-while-revalidate, storage adapters, and a handler plugin that reflects cache tags in HTTP headers.

Installation

npm install @orpc/experimental-cache@beta

pnpm add @orpc/experimental-cache@beta

yarn add @orpc/experimental-cache@beta

bun add @orpc/experimental-cache@beta

Basic Usage

Everything builds on the CacheStore interface: getOrSet returns the entry under a key and fills it when there is none, and revalidate invalidates entries by tag. A router shares one store, passed through the request context as cache/store, as the CacheContext interface describes. Use one of these adapters or write your own:

const const store: MemoryCacheStorestore = new new MemoryCacheStore(options?: BaseKeyValueCacheStoreOptions): MemoryCacheStore
In-memory cache store with tag-based invalidation, intended for
development, testing, and single-instance deployments. Expired and
revalidated entries are dropped when their key is read again, and otherwise
swept on the next write once an eviction time or a revalidation has passed.
@see{@link https://orpc.dev/docs/helpers/cache#adapters Cache Helpers - Adapters}MemoryCacheStore()

const const entry: CacheEntryentry = await const store: MemoryCacheStorestore.BaseKeyValueCacheStore.getOrSet(key: unknown, compute: () => Promise<unknown>, options?: CacheGetOrSetOptions): Promise<CacheEntry>
Resolves the entry stored under `key`, filling it through `fill` when
there is none. Concurrent callers of one key fill once and share that
entry. A stale entry, past `expiresAt` but within `swr`, is returned as is
while one caller refreshes it in the background. Keys may be any
serializable value; implementations encode them stably, so structurally
equal keys resolve the same entry.getOrSet('planet:1', async () => ({ id: numberid: 1, name: stringname: 'Earth' }), {
  CacheGetOrSetOptions.tags?: readonly string[] | undefined
Tags associated with the entry. Revalidating any of them invalidates the entry.
@default[]tags: ['planets', 'planet:1'],
  CacheGetOrSetOptions.ttl?: number | undefined
Fresh lifetime in milliseconds. `undefined` means the entry never expires by time.
@defaultundefinedttl: 60_000,
})

await const store: MemoryCacheStorestore.MemoryCacheStore.revalidate({ tags }: CacheRevalidateOptions): Promise<void>
Invalidates every entry associated with any of the given tags.revalidate({ CacheRevalidateOptions.tags: readonly [string, ...string[]]
The tags to revalidate.tags: ['planets'] }) // the next `getOrSet` fills again

An entry is fresh for ttl milliseconds and kept for a further swr window, during which getOrSet still returns it with a past expiresAt while one caller refreshes it in the background. Revalidating a tag invalidates every entry carrying it, fresh or stale. Durations are in milliseconds throughout.

Cache Middleware

The cache helper creates middleware that caches the output of procedures. A hit returns the cached output without running the handler; a miss runs the handler once, even for concurrent callers, and stores the result. The key, tags, ttl, swr, and enabled options accept static values or functions of the middleware options and input.

key defaults to the procedure path and input. When provided, it is used as given, so procedures sharing a key share an entry.

import { cache, CacheContext } from '@orpc/experimental-cache'
import { MemoryCacheStore } from '@orpc/experimental-cache/memory'

const findPlanet = os
  .$context<CacheContext>()
  .input(z.object({ id: z.number() }))
  .use(
    cache({
      key: (_, input) => `planet:${input.id}`,
      tags: (_, input) => ['planets', `planet:${input.id}`],
      ttl: 60_000, // Optional fresh lifetime in milliseconds, default is no expiry
      swr: 300_000, // Optional stale-while-revalidate window in milliseconds, default is 0
    }),
  )
  .handler(({ input }) => {
    return { id: input.id, name: `Planet ${input.id}` }
  })

const result = await call(
  findPlanet,
  { id: 1 },
  { context: { 'cache/store': new MemoryCacheStore() } },
)

Stale While Revalidate

Past ttl but within swr, the middleware returns the stale output at once and re-runs the procedure in the background to refresh the entry. Concurrent stale hits refresh once, and nothing older than ttl + swr is ever served.

On runtimes that stop pending work once the response is sent, such as Cloudflare Workers, pass cache/waitUntil through the context so refreshes can finish:

export default {
  async fetch(request, env, ctx) {
    const { response } = await handler.handle(request, {
      context: {
        'cache/store': store,
        'cache/waitUntil': ctx.waitUntil.bind(ctx),
      },
    })

    return response ?? new Response('Not Found', { status: 404 })
  },
}

The promise it receives rejects when a refresh fails, so cache/waitUntil is also where those failures are handled. Without it they surface as unhandled rejections, so on other runtimes pass one that reports them, for example promise => promise.catch(console.error).

Revalidate Middleware

The revalidate helper creates middleware that revalidates tags after the procedure succeeds, typically on mutations. The required tags option accepts a non-empty list or a function of the middleware options and input. When the procedure throws, or tags resolves to null or undefined, nothing is revalidated. When the store fails to revalidate, the request fails even though the mutation already ran, so the failure is visible; retrying such a request repeats the mutation.

import { revalidate } from '@orpc/experimental-cache'

const updatePlanet = os
  .$context<CacheContext>()
  .input(z.object({ id: z.number(), name: z.string() }))
  .use(
    revalidate({ tags: (_, input) => ['planets', `planet:${input.id}`] }),
  )
  .handler(({ input }) => {
    return input
  })

Handler Plugin

The CacheHandlerPlugin reflects the activity of Cache Middleware and Revalidate Middleware into response headers. Only the headers you list are set:

• orpc-cache-tag carries the tags the response depends on.
• orpc-cache-tag-invalidation carries the tags the request revalidated, for invalidating tagged data in client caches.
• cache-control and cache-tag are the standard HTTP counterparts for response caches in front, such as CDNs or Cloudflare Workers Caching.

The plugin sets these over anything already on the response. To override them, set your own afterwards with ResponseHeadersPlugin.

Tags are joined with commas. Only %, ,, uppercase letters, and characters that cannot appear in a header value are percent-encoded, so typical tags stay readable. Uppercase letters are encoded because caches like Cloudflare Workers Caching match tags case-insensitively, and the encoded form stays unambiguous under case folding. decodeCacheTagHeader from @orpc/shared parses a header back into tags.

import { CacheHandlerPlugin } from '@orpc/experimental-cache'

const handler = new RPCHandler(router, {
  plugins: [
    new CacheHandlerPlugin({
      headers: ['orpc-cache-tag', 'orpc-cache-tag-invalidation'],
    }),
  ],
})

Link Plugin

The CacheLinkPlugin is the client counterpart of the Handler Plugin. It reads orpc-cache-tag and orpc-cache-tag-invalidation from responses for client cache integrations, such as the TanStack Query Cache Revalidation Plugin, to track and revalidate tagged data. Other calls pass through untouched.

import { CacheLinkPlugin } from '@orpc/experimental-cache'

const link = new RPCLink({
  url: '/rpc',
  plugins: [
    new CacheLinkPlugin(),
  ],
})

Server-Side Clients

Server-side clients call procedures directly, without headers or links, such as when rendering TanStack Query on the server. cacheRouterClientInterceptor reports the same tags for them. Router clients keep their client context from procedures, so forward it through the context option:

import type { CacheLinkPluginContext } from '@orpc/experimental-cache'
import { CACHE_LINK_PLUGIN_CONTEXT_SYMBOL, cacheRouterClientInterceptor } from '@orpc/experimental-cache'

const client = createRouterClient(router, {
  context: async (clientContext: CacheLinkPluginContext) => ({
    'cache/store': store,
    [CACHE_LINK_PLUGIN_CONTEXT_SYMBOL]: clientContext[CACHE_LINK_PLUGIN_CONTEXT_SYMBOL],
  }),
  interceptors: [cacheRouterClientInterceptor],
})

Tiered Store

TieredCacheStore layers several stores front to back, such as a memory store in front of a Redis one. A miss in one tier fills from the next, so only the last tier runs the procedure, and a revalidation reaches every tier. Each tier measures ttl from when it stored its copy, so cap it on front tiers to bound how long they may outlive the entry behind them.

import { TieredCacheStore } from '@orpc/experimental-cache'
import { MemoryCacheStore } from '@orpc/experimental-cache/memory'
import { RedisCacheStore } from '@orpc/experimental-cache/redis'
import { createClient } from 'redis'

const store = new TieredCacheStore([
  { store: new MemoryCacheStore(), ttl: 5_000 },
  { store: new RedisCacheStore(createClient({ url: process.env.REDIS_URL })) },
])

Adapters

Memory

Stores entries in the process. Suited to development, testing, and single-instance deployments.

import { MemoryCacheStore } from '@orpc/experimental-cache/memory'

const store = new MemoryCacheStore({
  /**
   * Serializer used to encode non-string keys.
   *
   * @default RPCJsonSerializer
   */
  serializer: undefined,
})

Redis

Stores entries as JSON strings retained for ttl + swr, and one counter per tag that revalidation increments, using single-key commands only, so it works with standalone servers and Redis Cluster alike. A hit costs one round trip when the lookup’s tags match the entry’s, and a miss three. Fills are coalesced by the locker, within the process by default; a RedisLocker on the same server coalesces them across processes. The client is connected lazily when needed.

import { RedisCacheStore } from '@orpc/experimental-cache/redis'
import { RedisLocker } from '@orpc/experimental-lock/redis'
import { createClient } from 'redis'

const client = createClient({ url: 'redis://localhost:6379' })

const store = new RedisCacheStore(client, {
  /**
   * The prefix to use for Redis keys.
   *
   * @default undefined
   */
  prefix: undefined,

  /**
   * Serializer for keys and cached outputs.
   *
   * @default RPCJsonSerializer
   */
  serializer: undefined,

  /**
   * Coalesces concurrent fills of one key. A caller that times out waiting fills on its own.
   *
   * @default new MemoryLocker()
   */
  locker: new RedisLocker(client, { prefix: 'cache-lock:', ttl: 10_000 }),
})

The Redis, Upstash, and Bun stores share BaseRedisCacheStore from @orpc/experimental-cache/base-redis, which holds the key layout and the flow. A store for another Redis-compatible client only has to implement five commands.

Upstash

The Redis adapter for Upstash’s REST client. It shares the key and entry format with RedisCacheStore, so both can serve the same database, and pairs with the UpstashLocker to coalesce fills across instances.

import { UpstashCacheStore } from '@orpc/experimental-cache/upstash'
import { UpstashLocker } from '@orpc/experimental-lock/upstash'
import { Redis } from '@upstash/redis'

const redis = Redis.fromEnv()

const store = new UpstashCacheStore(redis, {
  /**
   * The prefix to use for Redis keys.
   *
   * @default undefined
   */
  prefix: undefined,

  /**
   * Serializer for keys and cached outputs.
   *
   * @default RPCJsonSerializer
   */
  serializer: undefined,

  /**
   * Coalesces concurrent fills of one key. A caller that times out waiting fills on its own.
   *
   * @default new MemoryLocker()
   */
  locker: new UpstashLocker(redis, { prefix: 'cache-lock:', ttl: 10_000 }),
})

Bun

The Redis adapter for Bun’s built-in Redis client, from @orpc/bun. It shares the key and entry format with RedisCacheStore, so both can serve the same database, and pairs with the experimental_BunRedisLocker to coalesce fills across processes.

import { experimental_BunRedisCacheStore, experimental_BunRedisLocker } from '@orpc/bun'
import { redis } from 'bun'

const store = new experimental_BunRedisCacheStore(redis, {
  /**
   * The prefix to use for Redis keys.
   *
   * @default undefined
   */
  prefix: undefined,

  /**
   * Serializer for keys and cached outputs.
   *
   * @default RPCJsonSerializer
   */
  serializer: undefined,

  /**
   * Coalesces concurrent fills of one key. A caller that times out waiting fills on its own.
   *
   * @default new MemoryLocker()
   */
  locker: new experimental_BunRedisLocker(redis, { prefix: 'cache-lock:', ttl: 10_000 }),
})

Vercel

Stores entries in the Vercel Runtime Cache, expiring tags natively through expireTag. Outside Vercel, the default getCache() falls back to an in-memory cache.

import { VercelCacheStore } from '@orpc/experimental-cache/vercel'
import { getCache } from '@vercel/functions'

const store = new VercelCacheStore({
  /**
   * The Vercel Runtime Cache to use.
   *
   * @default getCache()
   */
  cache: getCache(),

  /**
   * Serializer for keys and cached outputs.
   *
   * @default RPCJsonSerializer
   */
  serializer: undefined,

  /**
   * Coalesces concurrent fills of one key within the process. A caller that times out waiting fills on its own.
   *
   * @default new MemoryLocker()
   */
  locker: undefined,
})

Cacheable

Stores entries through a Cacheable instance, so its primary and secondary stores back the cache, such as a memory tier in front of any Keyv store. Tags are invalidated natively through its tag service, which the store enables.

import { CacheableCacheStore } from '@orpc/experimental-cache/cacheable'
import { Cacheable, Keyv } from 'cacheable'

const cacheable = new Cacheable({
  secondary: new Keyv('redis://localhost:6379'),
})

const store = new CacheableCacheStore(cacheable, {
  /**
   * Serializer for keys and cached outputs.
   *
   * @default RPCJsonSerializer
   */
  serializer: undefined,

  /**
   * Coalesces concurrent fills of one key within the process. A caller that times out waiting fills on its own.
   *
   * @default new MemoryLocker()
   */
  locker: undefined,
})

Cloudflare Workers Caching

A purge-only store from @orpc/cloudflare. Workers Caching caches whole responses in front of the Worker through the cache-control and cache-tag headers of the Handler Plugin, so every getOrSet runs the procedure and stores nothing, and revalidate purges the tags from the front cache.

It requires "cache": { "enabled": true } in your wrangler configuration. Purges are scoped to the calling entrypoint, tags match case-insensitively, and purge calls use the Free tier rate limits regardless of your plan.

import { experimental_WorkersCacheStore as WorkersCacheStore } from '@orpc/cloudflare'

const store = new WorkersCacheStore({
  /**
   * The Workers Caching purge surface, such as `ctx.cache`.
   *
   * @default cache from `cloudflare:workers`
   */
  cache: undefined,
})