cache

Encore Caching (Redis)

Instructions

Encore's cache is a typed wrapper around Redis. Declare a CacheCluster once, then create Keyspace objects for each shape of data you need.

Cluster

import { CacheCluster } from "encore.dev/storage/cache";

const cluster = new CacheCluster("my-cache", {
  evictionPolicy: "allkeys-lru",
});

Reference a cluster from another service: const cluster = CacheCluster.named("my-cache");

Keyspaces on a shared cluster are not isolated from each other. Start each key pattern with the owning service name. Let the owning service handle writes. Keep sensitive data in a separate cluster, and share data with other services through explicit APIs.

Eviction policies: "allkeys-lru" (default), "noeviction", "allkeys-lfu", "allkeys-random", "volatile-lru", "volatile-lfu", "volatile-ttl", "volatile-random". With "noeviction", writes fail with an error once memory is full.

Keyspace types

Each keyspace has a key shape (used to build the Redis key from keyPattern) and a value type.

import {
  StringKeyspace,
  IntKeyspace,
  FloatKeyspace,
  StructKeyspace,
  StringListKeyspace,
  NumberListKeyspace,
  StringSetKeyspace,
  NumberSetKeyspace,
  expireIn,
} from "encore.dev/storage/cache";

// Strings
const tokens = new StringKeyspace<{ tokenId: string }>(cluster, {
  keyPattern: "token/:tokenId",
  defaultExpiry: expireIn(3600 * 1000),
});
await tokens.set({ tokenId: "abc" }, "value");
const val = await tokens.get({ tokenId: "abc" }); // undefined on miss

// Integers (atomic counters)
const counters = new IntKeyspace<{ userId: string }>(cluster, {
  keyPattern: "requests/:userId",
  defaultExpiry: expireIn(10 * 1000),
});
const count = await counters.increment({ userId: "user123" }, 1);

// Structs (JSON)
interface UserProfile { name: string; email: string; }
const profiles = new StructKeyspace<{ userId: string }, UserProfile>(cluster, {
  keyPattern: "profile/:userId",
  defaultExpiry: expireIn(3600 * 1000),
});
await profiles.set({ userId: "123" }, { name: "Alice", email: "alice@example.com" });

// Lists
const recent = new StringListKeyspace<{ userId: string }>(cluster, {
  keyPattern: "recent/:userId",
  defaultExpiry: expireIn(3600 * 1000),
});
await recent.pushRight({ userId: "user123" }, "item1", "item2");

// Sets
const tags = new StringSetKeyspace<{ articleId: string }>(cluster, {
  keyPattern: "tags/:articleId",
  defaultExpiry: expireIn(3600 * 1000),
});
await tags.add({ articleId: "post1" }, "typescript", "encore");
const has = await tags.contains({ articleId: "post1" }, "typescript");

Multi-field key patterns

interface Key { userId: string; resourcePath: string; }

const requests = new IntKeyspace<Key>(cluster, {
  keyPattern: "requests/:userId/:resourcePath",
  defaultExpiry: expireIn(10 * 1000),
});

Expiry helpers

import {
  expireIn,          // milliseconds
  expireInSeconds,
  expireInMinutes,
  expireInHours,
  expireDailyAt,     // a specific UTC time each day
  neverExpire,
  keepTTL,           // keep existing TTL when updating
} from "encore.dev/storage/cache";

Write options

await keyspace.set(key, value, { expiry: expireInMinutes(30) });
await keyspace.set(key, value, { expiry: keepTTL });
await keyspace.setIfNotExists(key, value);  // throws CacheKeyExists if present
await keyspace.replace(key, value);          // throws CacheMiss if absent

Errors

import { CacheMiss, CacheKeyExists } from "encore.dev/storage/cache";

const value = await keyspace.get(key);  // undefined on miss (does not throw)

Wrap calls to setIfNotExists() in error handling that catches CacheKeyExists. Wrap calls to replace() in error handling that catches CacheMiss. Handle each case explicitly so the caller gets a clear result rather than a server error.

Guidelines

• Declare CacheCluster and keyspaces at package level.
• Pick the most specific keyspace type — IntKeyspace for counters gives you atomic increment/decrement for free.
• get() returns undefined on miss. setIfNotExists() throws CacheKeyExists when the key is present, and replace() throws CacheMiss when the key is absent.
• Local development uses an in-memory Redis with a ~100-key cap — don't load-test it.
• Take key fields such as userId from the authenticated caller rather than from request input. Check free-form fields such as resourcePath against an allowlist or a strict pattern that rejects the slash separator, so a value in one segment cannot collide with another key.
• Under the default "allkeys-lru" policy, counters and tokens can be evicted under memory pressure. That resets rate limits and drops sessions. Keep security related counters and session data in a dedicated, adequately sized cluster using "noeviction" or a volatile policy. Treat limits backed by the cache as best effort, and choose explicitly whether to fail open or fail closed on cache errors.
• Use the cache only for short-lived token data with short expiry times. Store a hash of a token rather than the token itself, in both values and key fields, because key names appear in Redis monitoring and key listing output. Keep authoritative session state in encore-database.
• Cap or trim list and set sizes when user input drives pushes or adds, and give collection keyspaces an expiry.
• Confirm how expiry applies to each increment before you rely on a counter for a fixed window. For fixed windows, include the current time window as a key field, and give every counter an expiry rather than neverExpire.
• For durable storage, use encore-database (Postgres) or encore-bucket (object storage) instead.