Redis cache

RedisCache is the Redis-backed Cache implementation. Production-ready, multi-pod-safe, with single-round-trip bulk operations.

import { RedisCache, RedisCacheOptions } from 'actor-ts';

const redisCacheOptions = RedisCacheOptions.create().withUrl('redis://redis.example.com:6379');
const cache = new RedisCache(
  redisCacheOptions,
);

When to use Redis

Most multi-pod production cases:

• Multi-pod cache sharing — pods see the same cache state.
• Bulk operations matter — MGET / MSET single round-trip.
• Persistence wanted — AOF / RDB survive Redis restart.
• You already run Redis — reuse existing infrastructure.

For single-pod, in-memory is simpler.

Configuration

type RedisCacheOptionsType = {
  url?:       string;                // 'redis://host:port'
  host?:      string;
  port?:      number;
  password?:  string;
  db?:        number;
  keyPrefix?: string;
  client?:    RedisClientLike;       // pre-built ioredis client
};

URL form:

const redisCacheOptions = RedisCacheOptions.create().withUrl('redis://localhost:6379/0');
new RedisCache(redisCacheOptions);
const redisCache2Options = RedisCacheOptions.create().withUrl('rediss://redis.example.com:6380');
new RedisCache(redisCache2Options);  // TLS
const redisCache3Options = RedisCacheOptions.create().withUrl('redis://user:pass@host:6379');
new RedisCache(redisCache3Options);

Field form:

const redisCacheOptions = RedisCacheOptions.create()
  .withHost('redis.example.com')
  .withPort(6379)
  .withPassword(process.env.REDIS_PASS)
  .withDb(1)
  .withKeyPrefix('my-app:');
new RedisCache(
  redisCacheOptions,
);

keyPrefix is applied to every key — useful when sharing a Redis instance across multiple apps:

keyPrefix: 'my-app:cache:'
// → 'my-app:cache:user:42', 'my-app:cache:session:abc', ...

Cluster mode

import { Cluster } from 'ioredis';

const redisCacheOptions = RedisCacheOptions.create().withClient(
    new Cluster([
      { host: 'redis-1', port: 6379 },
      { host: 'redis-2', port: 6379 },
      { host: 'redis-3', port: 6379 },
    ]),
  );
new RedisCache(
  redisCacheOptions,
);

ioredis handles the cluster protocol (MOVED / ASK redirects, slot tracking). Use Redis Cluster for horizontal scale beyond a single Redis server’s memory.

TLS

const redisCacheOptions = RedisCacheOptions.create().withUrl('rediss://redis.example.com:6380');
new RedisCache(redisCacheOptions);
// TLS is selected by the `rediss://` URL scheme:
const redisCache2Options = RedisCacheOptions.create().withUrl('rediss://redis.example.com:6380');
new RedisCache(redisCache2Options);

rediss:// URL prefix selects TLS — or pass a pre-built TLS client via withClient. Cert verification goes through Node’s TLS defaults; for self-signed in dev, you’d need explicit ioredis TLS options.

Bulk operations are real bulk

const users = await cache.mget<User>(['user:1', 'user:2', 'user:3']);
//                                              ↑
//                                       single MGET round-trip

mget on RedisCache → single Redis MGET command → one network round-trip. Critical for the sharded-entity hydration pattern (rebuilding state for many entities on node startup).

Atomic incr + setIfAbsent

Both map to Redis primitives:

• incr → Redis INCR (atomic, no race).
• setIfAbsent → Redis SET NX (atomic CAS).

Used by the framework’s rate-limit + idempotency-key middleware. Safe across pods.

Redis is the best-supported backend for locking: a key lives on one logical keyspace, so SET NX decides a race the same way for every pod. See acquireLock for the token-checked release that pairs with it.

Pipelining

// Not exposed directly in Cache; ioredis pipelining is automatic
// for batched calls within the same tick.

ioredis pipelines commands issued in the same JS turn, sending them in a single TCP write. The Cache interface doesn’t expose pipelining explicitly; the framework’s implementation uses pipelining where helpful.

Peer dependency

npm install ioredis
# or: bun add ioredis

ioredis is the underlying client. Versions 5+ are tested.

Redis persistence settings

Redis supports two persistence modes:

• RDB — periodic snapshots. Default in many configs.
• AOF — append-only log. More durable, slower.

The framework’s Cache doesn’t care about Redis-side persistence config — caches are opportunistic. But for cache survival across Redis restarts, enable RDB at minimum.

TLS to managed Redis

const redisCacheOptions = RedisCacheOptions.create().withUrl(
    'rediss://default:password@my-cluster.cache.amazonaws.com:6380',
  );
new RedisCache(
  redisCacheOptions,
);

AWS ElastiCache, GCP Memorystore, Azure Cache for Redis — all support rediss:// URLs. Use them.

Cluster connection handling

import { Cluster } from 'ioredis';

const redisCacheOptions = RedisCacheOptions.create().withClient(
    new Cluster([...], {
      enableReadyCheck:    true,
      redisOptions: { maxRetriesPerRequest: 3 },
    }),
  );
new RedisCache(
  redisCacheOptions,
);

Defaults to ioredis sensible-defaults. For very-tight latency or specific connection-pool sizing, pass ioredis-style options explicitly.

Large objects in the cache

cache.set('user:full', user, 60_000);   // 5 MB user object

Redis is a memory database. Large values consume server memory + network bandwidth. Cache identifiers + fetch full objects from the source store on miss.

Don't run two unrelated apps on the same Redis without keyPrefix

// App-A and App-B both write `user:42`

Without keyPrefix, key collisions corrupt both apps. Use distinct prefixes (my-app-a:, my-app-b:) or separate Redis DBs / instances.

Redis Cluster + cross-slot operations

// mget(['user:1', 'user:2']) — keys hash to different slots

In Redis Cluster, MGET requires all keys to be in the same slot. ioredis handles cross-slot MGETs by fanning out per-slot, but each fan-out is a separate round-trip. For performance, design keys to hash-tag related keys to the same slot: {user:42}:profile, {user:42}:settings.

Where to next

• Cache overview — the bigger picture.
• In-memory cache — for single-pod.
• Memcached cache — alternative.
• HTTP middleware — primary consumers of the cache.