Memcached cache

MemcachedCache is the Memcached-backed Cache implementation. Distributed cache across pods, shared across processes.

import { MemcachedCache, MemcachedCacheOptions } from 'actor-ts/cache';

const memcachedCacheOptions = MemcachedCacheOptions.create().withServers('memcached-1:11211,memcached-2:11211');
const cache = new MemcachedCache(
  memcachedCacheOptions,
);

When to use Memcached

Two main reasons:

1. Existing Memcached infrastructure — your team runs it already.
2. Pure cache use case — you don’t need Redis’s extra features (persistence, pub/sub, scripting, sorted sets).

Memcached is simpler than Redis — fewer features, smaller operational footprint, smaller memory overhead. For pure key-value caching with TTLs, it’s plenty.

Configuration

type MemcachedCacheOptionsType = {
  servers?:   string;                // comma-separated, default 'localhost:11211'
  username?:  string;
  password?:  string;
  keyPrefix?: string;                // server-side, applied to every operation
  client?:    MemcachedClientLike;   // pre-built memjs client
};

memjs (the underlying client) supports SASL auth via username/password. Multiple servers are hash-distributed.

Peer dependency

npm install memjs
# or: bun add memjs

What works

Cache method	Memcached implementation
get/set/delete	Direct Memcached commands.
incr	Memcached INCR/ADD combination.
setIfAbsent	Memcached ADD (atomic).
mget/mset	Parallel single-key operations.

mget/mset aren’t single-round-trip on Memcached (no multi-key commands). The framework parallelizes the individual operations.

Memcached vs Redis

Aspect	Memcached	Redis
Memory overhead per entry	Lower	Higher
Multi-key operations	Slower (parallel single-key)	Faster (MGET, MSET)
Persistence	None	RDB / AOF available
Pub/sub	No	Yes
Data types	String only	Strings, lists, sets, hashes, sorted sets
Cluster support	Client-side hashing	Built-in clustering
Replication	No (or via sidecars)	Built-in replication

For pure cache: either works. Redis wins for almost everything else the framework might want. Memcached wins for minimum operational footprint when caching is the only need.

Eviction

// Memcached configured with --memory-limit=2048 (MB)
// → LRU eviction once full

Memcached’s eviction is LRU, configured at the Memcached-server level (not from the cache client). No client-side eviction policy.

For a fixed-size cache, this is fine — Memcached drops old entries to make room.

For anything carrying a guarantee it is not. InMemoryCache evicts entries that carry none before it touches a lock, a rate-limit counter or an idempotency record; there is no equivalent here, because the decision is made in the server and the client is not consulted. So an entry written by setIfAbsent can disappear with most of its TTL left — a lock handed out twice, a limit reset, a retry that re-runs its handler — and nothing in the API reports it. Size the Memcached instance for the guarantees it holds, keep it off the same instance as a key space callers can enumerate, and see what eviction protects and what it does not for what the guarantee rests on. This is separate from the topology hazard below: that one needs a server to join or leave, this one needs only memory pressure.

Connection pooling

memjs maintains its own connection pool; the framework doesn’t manage it directly. Tune via memjs options if needed (usually defaults are fine).

No persistence

# systemctl restart memcached
# → entire cache gone

Memcached has zero persistence. Treat caches as rebuild-from-source — never store anything you can’t recompute.

No multi-key atomic operations

// Two operations: read A, set B based on A → race possible

Memcached doesn’t have transactions / atomic multi-key operations. For “atomic counter + check” patterns, the framework’s incr and setIfAbsent are the only atomic primitives.

Memcached cluster scaling

servers: 'm1:11211,m2:11211';
// Adding m3: keys rebalance via consistent-hashing — some cache misses during the rebalance

Memcached scaling requires client-side consistent-hashing awareness. memjs handles it; expect a brief cache-miss spike when the cluster topology changes.

ADD is atomic per server, not per cluster

servers: 'm1:11211,m2:11211';
// 'lock:job' hashes to m1 — ADD there is atomic, so one caller wins
// Add m3: the key may rehash to a server that has never seen it
// → setIfAbsent('lock:job') succeeds a second time, while the first
//   holder still believes it holds the lock

Memcached has no cluster-wide coordination. ADD is atomic on the one server a key hashes to, which is what makes setIfAbsent and acquireLock correct in steady state — every contender for a given key reaches the same server. A topology change breaks that assumption: memjs rehashes the keyspace, the key can land on a different server with no entry for it, and the lock is handed out twice.

There is no client-side fix — the framework cannot detect a rehash without reaching into memjs’s internal hashring, which is precisely the detail memjs exists to hide. If you use acquireLock on Memcached, either keep the server list fixed for the lifetime of the lock, or treat a double-grant as possible and guard the resource with a fencing token. Redis is the better backend for locking; Memcached locks are best kept to optimisations where a duplicate run costs time, not correctness.

Where to next

• Cache overview — the bigger picture.
• In-memory cache — for single-pod.
• Redis cache — more features.