Skip to content
actor-ts

Redis cache

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

import { RedisCache } from 'actor-ts';


const cache = new RedisCache({
  url: 'redis://redis.example.com:6379',
});

When to use Redis

Section titled “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

Section titled “Configuration”
interface RedisCacheSettings {
  url?:       string;                // 'redis://host:port'
  host?:      string;
  port?:      number;
  password?:  string;
  username?:  string;
  db?:        number;
  keyPrefix?: string;
  tls?:       boolean;               // true for `rediss://`
  cluster?:   ClusterNodes;          // for Redis Cluster
}

URL form:

new RedisCache({ url: 'redis://localhost:6379/0' });
new RedisCache({ url: 'rediss://redis.example.com:6380' });  // TLS
new RedisCache({ url: 'redis://user:pass@host:6379' });

Field form:

new RedisCache({
  host:    'redis.example.com',
  port:    6379,
  password: process.env.REDIS_PASS,
  db:      1,
  keyPrefix: 'my-app:',
});

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

Section titled “Cluster mode”
new RedisCache({
  cluster: {
    nodes: [
      { host: 'redis-1', port: 6379 },
      { host: 'redis-2', port: 6379 },
      { host: 'redis-3', port: 6379 },
    ],
  },
});

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

TLS

Section titled “TLS”
new RedisCache({ url: 'rediss://redis.example.com:6380' });
// or:
new RedisCache({ host: '...', port: 6380, tls: true });

rediss:// URL prefix or explicit tls: true. 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

Section titled “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

Section titled “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.

Pipelining

Section titled “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

Section titled “Peer dependency”
Terminal window
npm install ioredis
# or: bun add ioredis

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

Redis persistence settings

Section titled “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

Section titled “TLS to managed Redis”
new RedisCache({
  url: 'rediss://default:password@my-cluster.cache.amazonaws.com:6380',
});

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

Cluster connection handling

Section titled “Cluster connection handling”
new RedisCache({
  cluster: { nodes: [...] },
  options: {
    enableReadyCheck:    true,
    maxRetriesPerRequest: 3,
  },
});

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

Where to next

Section titled “Where to next”