コンテンツにスキップ
日本語

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,
);

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.

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.

The framework registers the Memcached factory itself, so a cache comes up on Memcached with no registerCache call and no new MemcachedCache(...) anywhere in your code — just a plugin id and a block:

actor-ts.cache {
sessions.plugin = "actor-ts.cache.memcached" # cache('sessions') is Memcached
memcached {
servers = "memcache-a:11211,memcache-b:11211"
username = ${?MEMCACHED_USERNAME}
password = ${?MEMCACHED_PASSWORD}
key-prefix = "my-app:"
}
}

The leaves are the kebab-case of the MemcachedCacheOptionsType fields above. servers is one comma-separated string, not a list, because that is what memjs’s Client.create takes.

An empty string means unset. username, password and key-prefix ship as "" so you can see the shape of the key; the reader drops them rather than handing them on, and an empty servers falls through to the built-in localhost:11211 instead of being refused.

Each named cache can have its own connection settings, layered over the global block leaf by leaf:

actor-ts.cache {
memcached.servers = "memcache-a:11211"
sessions { plugin = "actor-ts.cache.memcached", memcached.key-prefix = "sess:" }
}

memjs is a lazy optional peer, so the block costs nothing until a cache actually resolves onto it: the driver is imported on the first cache operation, not at startup.

Terminal window
npm install memjs
# or: bun add memjs
Cache methodMemcached implementation
get/set/deleteDirect Memcached commands.
incrMemcached INCR/ADD combination.
setIfAbsentMemcached ADD (atomic).
mget/msetParallel single-key operations.

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

AspectMemcachedRedis
Memory overhead per entryLowerHigher
Multi-key operationsSlower (parallel single-key)Faster (MGET, MSET)
PersistenceNoneRDB / AOF available
Pub/subNoYes
Data typesString onlyStrings, lists, sets, hashes, sorted sets
Cluster supportClient-side hashingBuilt-in clustering
ReplicationNo (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.

// 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.

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