Nodejs Memcache Client
nodes: MemcacheNode[] (readonly)nodeIds: string[] (readonly)hash: HashProvidertimeout: numbermaxPendingCommands: numberkeepAlive: booleankeepAliveDelay: numberretries: numberretryDelay: numberretryBackoff: RetryBackoffFunctionretryOnlyIdempotent: booleanmaxKeySize: numbermaxValueSize: numbermaxExpiration: numberhashLargeKey: booleanhashery: HasherylazyConnect: boolean (readonly)getNodes(): MemcacheNode[]getNode(id: string): MemcacheNode | undefinedaddNode(uri: string | MemcacheNode, weight?: number): Promise<void>removeNode(uri: string): Promise<void>getNodesByKey(key: string): Promise<MemcacheNode[]>parseUri(uri: string): { host: string; port: number; secure?: boolean }get(key: string): Promise<string | undefined>gets(keys: string[]): Promise<Map<string, string>>set(key: string, value: string, exptime?: number, flags?: number): Promise<boolean>add(key: string, value: string, exptime?: number, flags?: number): Promise<boolean>replace(key: string, value: string, exptime?: number, flags?: number): Promise<boolean>cas(key: string, value: string, casToken: string, exptime?: number, flags?: number): Promise<boolean>npm install memcache
or with pnpm:
pnpm add memcache
import { Memcache } from 'memcache';
// Create a new client
const client = new Memcache();
// Set a value
await client.set('mykey', 'Hello, Memcache!');
// Get a value
const value = await client.get('mykey');
console.log(value); // ['Hello, Memcache!']
// Delete a value
await client.delete('mykey');
// Close the connection
await client.quit();
You can also just pass in the uri into the constructor
// Single node as string
const client = new Memcache('localhost:11211');
// Single node with protocol
const client = new Memcache('memcache://192.168.1.100:11211');
// Multiple nodes with options
const client = new Memcache({
nodes: ['localhost:11211', 'server2:11211'],
timeout: 10000
});
You can specify multiple Memcache nodes by passing an array of connection strings:
import { Memcache } from 'memcache';
// Create a client with multiple nodes
const client = new Memcache({
nodes: ['localhost:11211', '192.168.1.100:11211', 'memcache://192.168.1.101:11211']
});
// Set and get values (automatically distributed across nodes)
await client.set('mykey', 'Hello, Memcache!');
const value = await client.get('mykey');
console.log(value); // ['Hello, Memcache!']
// Close the connection
await client.quit();
You can also pass an array of MemcacheNode instances for advanced configuration:
import { Memcache, createNode } from 'memcache';
// Create nodes with custom settings
const node1 = createNode('localhost', 11211, { weight: 2 });
const node2 = createNode('192.168.1.100', 11211, { weight: 1 });
const node3 = createNode('192.168.1.101', 11211, { weight: 1 });
// Create a client with MemcacheNode instances
const client = new Memcache({
nodes: [node1, node2, node3],
timeout: 10000
});
// node1 will receive twice as much traffic due to higher weight
await client.set('mykey', 'Hello, Memcache!');
const value = await client.get('mykey');
console.log(value); // ['Hello, Memcache!']
// Close the connection
await client.quit();
new Memcache(options?: string | MemcacheOptions)
Creates a new Memcache client instance. You can pass either:
Examples:
// Single node as string
const client = new Memcache('localhost:11211');
// Single node with protocol
const client = new Memcache('memcache://192.168.1.100:11211');
// Multiple nodes with options
const client = new Memcache({
nodes: ['localhost:11211', 'server2:11211'],
timeout: 10000
});
nodes?: (string | MemcacheNode)[] - Array of node URIs or MemcacheNode instances
["localhost:11211", "memcache://192.168.1.100:11212"]timeout?: number - Milliseconds to wait for a connection to open, and for the server to respond while commands are pending (default: 5000). If pending commands get no response in time, the node emits timeout, the pending commands fail and the connection is closed; the next command reconnects. Idle connections stay open.maxPendingCommands?: number - The most requests each node keeps waiting for a response or for its connection to open (default: 0, no limit). While a node has that many, a new request to it fails at once instead of waiting, so a slow or unreachable server can't build up an unbounded backlog. Refused requests are not retried. On an open connection a refused request fails like any other command: set() and the other writes resolve false, and get() resolves undefined. While the connection is being opened it fails the way a failed connection does: get(), set() and the other single-key commands reject, and gets() leaves out that node's keys. quit() still goes out, after the requests ahead of it. Called directly, node.command() and the node's binary* methods reject with a "Too many pending commands" error.keepAlive?: boolean - Keep connection alive (default: true)keepAliveDelay?: number - Keep alive delay in milliseconds (default: 1000)hash?: HashProvider - Hash provider for consistent hashing (default: KetamaHash)retries?: number - Number of retry attempts for failed commands (default: 0)retryDelay?: number - Base delay in milliseconds between retries (default: 100)retryBackoff?: RetryBackoffFunction - Function to calculate backoff delay (default: fixed delay)retryOnlyIdempotent?: boolean - Only retry commands marked as idempotent (default: true)sasl?: SASLCredentials - SASL PLAIN credentials for all nodes (see SASL Authentication)lazyConnect?: boolean - When true, nodes will not connect until the first command is executed. When false, nodes connect eagerly during construction (default: true)maxKeySize?: number - Maximum allowed key size in characters (default: 250, memcache protocol max)maxValueSize?: number - Maximum allowed value size in bytes (default: 1048576, memcached default)maxExpiration?: number - Maximum allowed expiration in seconds (default: 2592000, memcached's 30-day relative-time boundary). Values above this throw. 0 (no expiration) is always allowed. Raise this if you need to pass absolute Unix timestamps as expirations.hashLargeKey?: boolean | Hashery - When true, keys longer than maxKeySize are deterministically hashed via hashery (djb2 sync by default) before being sent to the server, instead of throwing. Pass a configured Hashery instance (e.g. new Hashery({ defaultAlgorithmSync: 'fnv1' })) to choose a different sync algorithm or plug in custom providers. When false, oversized keys throw a validation error (default: false). Note: hashing is one-way and can collide; two distinct long keys could map to the same hashed key.autoDiscover?: AutoDiscoverOptions - AWS ElastiCache Auto Discovery configuration (see Auto Discovery)tls?: boolean | tls.ConnectionOptions - Enable TLS for all node connections. true uses Node's default trust store (enough for publicly-trusted server certs such as AWS ElastiCache Serverless); an object is passed through to tls.connect() for custom CAs, client certs, or SNI overrides (see TLS Support)nodes: MemcacheNode[] (readonly)Returns the list of all MemcacheNode instances in the cluster.
nodeIds: string[] (readonly)Returns the list of node IDs (e.g., ["localhost:11211", "127.0.0.1:11212"]).
hash: HashProviderGet or set the hash provider used for consistent hashing distribution.
timeout: numberGet or set the timeout in milliseconds (default: 5000). Setting it updates existing nodes and the Auto Discovery connection, and applies to commands that are already waiting.
maxPendingCommands: numberGet or set the most requests each node keeps waiting for a response or for its connection to open (default: 0, no limit). The value is rounded down, and anything below 1, or not a finite number, means no limit. Setting it updates existing nodes and applies to the next request; requests already waiting are not affected.
keepAlive: booleanGet or set the keepAlive setting. Updates all existing nodes. Requires reconnect() to apply changes.
keepAliveDelay: numberGet or set the keep alive delay in milliseconds. Updates all existing nodes. Requires reconnect() to apply changes.
retries: numberGet or set the number of retry attempts for failed commands (default: 0).
retryDelay: numberGet or set the base delay in milliseconds between retry attempts (default: 100).
retryBackoff: RetryBackoffFunctionGet or set the backoff function for calculating retry delays.
retryOnlyIdempotent: booleanGet or set whether retries are restricted to idempotent commands only (default: true).
maxKeySize: numberGet or set the maximum allowed key size in characters (default: 250). Memcache protocol max is 250.
maxValueSize: numberGet or set the maximum allowed value size in bytes (default: 1048576). Writes (set, add, replace, append, prepend, cas) throw when the encoded value exceeds this limit. Raise it if your memcached server is started with a larger -I item size.
maxExpiration: numberGet or set the maximum allowed expiration in seconds (default: 2592000). Writes that accept an expiration (set, add, replace, cas, touch) throw when exptime exceeds this limit. 0 (no expiration) is always allowed. Memcached treats any exptime greater than 2592000 as an absolute Unix timestamp, so the default guards against accidentally setting a TTL that memcached interprets as "already expired." Raise this if you need to pass Unix timestamps.
hashLargeKey: booleanGet or set whether keys exceeding maxKeySize are hashed instead of throwing (default: false). When enabled, oversized keys are replaced with a short, deterministic hex digest (via the hashery library, djb2 by default) before being sent to memcache, so any string length is accepted. The same input always produces the same hashed key, but distinct long keys can collide. To change algorithm or providers, configure the hashery property.
const client = new Memcache({ hashLargeKey: true });
const longKey = 'user:profile:' + 'x'.repeat(500);
await client.set(longKey, 'value'); // hashed automatically
await client.get(longKey); // same hash, returns 'value'
hashery: HasheryGet or set the Hashery instance used to hash oversized keys when hashLargeKey is enabled. Always returns an instance, even when hashing is disabled, so you can pre-configure it (algorithm, custom providers, caching) before flipping hashLargeKey on. Hashery is re-exported from this package for convenience.
import Memcache, { Hashery } from 'memcache';
// Simple — defaults to djb2 sync hashing
const simple = new Memcache({ hashLargeKey: true });
// Advanced — supply a Hashery preconfigured for fnv1
const advanced = new Memcache({
hashLargeKey: new Hashery({ defaultAlgorithmSync: 'fnv1' }),
});
// Or mutate the instance after construction
simple.hashery.defaultAlgorithmSync = 'murmur';
lazyConnect: boolean (readonly)Whether nodes defer connecting until the first command is executed (default: true).
connect(nodeId?: string): Promise<void>Connect to all Memcache servers or a specific node.
disconnect(): Promise<void>Disconnect all connections.
reconnect(): Promise<void>Reconnect all nodes by disconnecting and connecting them again.
quit(): Promise<void>Quit all connections gracefully.
isConnected(): booleanCheck if any node is connected to a Memcache server.
getNodes(): MemcacheNode[]Get an array of all MemcacheNode instances.
getNode(id: string): MemcacheNode | undefinedGet a specific node by its ID (e.g., "localhost:11211").
addNode(uri: string | MemcacheNode, weight?: number): Promise<void>Add a new node to the cluster. Throws error if node already exists.
removeNode(uri: string): Promise<void>Remove a node from the cluster.
getNodesByKey(key: string): Promise<MemcacheNode[]>Get the nodes for a given key using consistent hashing. Automatically connects to nodes if not already connected. With maxPendingCommands set, a call waiting for a node's connection counts toward that node's limit and, past it, rejects at once.
parseUri(uri: string): { host: string; port: number; secure?: boolean }Parse a URI string into host and port. Supports formats:
"localhost:11211" or "localhost""memcache://localhost:11211", "tcp://localhost:11211""memcaches://localhost:11211" (secure: true; enables TLS for that node)"[::1]:11211" or "memcache://[2001:db8::1]:11212""/var/run/memcached.sock" or "unix:///var/run/memcached.sock"get(key: string): Promise<string | undefined>Get a value from the Memcache server. Returns the first successful result from replica nodes.
gets(keys: string[]): Promise<Map<string, string>>Get multiple values from the Memcache server. Returns a Map with keys to values.
set(key: string, value: string, exptime?: number, flags?: number): Promise<boolean>Set a value in the Memcache server. Returns true only if all replica nodes succeed.
exptime - Expiration time in seconds (default: 0 = never expire)flags - Flags/metadata (default: 0)add(key: string, value: string, exptime?: number, flags?: number): Promise<boolean>Add a value (only if key doesn't exist). Returns true only if all replica nodes succeed.
replace(key: string, value: string, exptime?: number, flags?: number): Promise<boolean>Replace a value (only if key exists). Returns true only if all replica nodes succeed.
cas(key: string, value: string, casToken: string, exptime?: number, flags?: number): Promise<boolean>Check-And-Set: Store a value only if it hasn't been modified since last fetch. Returns true only if all replica nodes succeed.
append(key: string, value: string): Promise<boolean>Append a value to an existing key. Returns true only if all replica nodes succeed.
prepend(key: string, value: string): Promise<boolean>Prepend a value to an existing key. Returns true only if all replica nodes succeed.
delete(key: string): Promise<boolean>Delete a value from the Memcache server. Returns true only if all replica nodes succeed.
touch(key: string, exptime: number): Promise<boolean>Update expiration time without retrieving value. Returns true only if all replica nodes succeed.
incr(key: string, value?: number): Promise<number | undefined>Increment a value. Returns the new value or undefined on failure.
value - Amount to increment (default: 1)decr(key: string, value?: number): Promise<number | undefined>Decrement a value. Returns the new value or undefined on failure.
value - Amount to decrement (default: 1)flush(delay?: number): Promise<boolean>Flush all values from all Memcache servers. Returns true if all nodes successfully flushed.
delay - Optional delay in seconds before flushingstats(type?: string): Promise<Map<string, MemcacheStats>>Get statistics from all Memcache servers. Returns a Map of node IDs to their stats.
version(): Promise<Map<string, string>>Get the Memcache server version from all nodes. Returns a Map of node IDs to version strings.
validateKey(key: string): voidValidates a Memcache key according to protocol requirements. Throws error if:
resolveKey(key: string): stringReturns the key that will actually be sent to memcache. When hashLargeKey is true and the key length exceeds maxKeySize, returns a short hex digest produced by the configured hashery instance (djb2 by default — 8 hex chars). Otherwise returns the original key unchanged. Called automatically before validateKey in every command, so calling it manually is only needed when you want to inspect the on-wire key.
createNode(host: string, port: number, options?: MemcacheNodeOptions): MemcacheNodeFactory function to create a new MemcacheNode instance.
import { createNode } from 'memcache';
const node = createNode('localhost', 11211, {
timeout: 5000,
keepAlive: true,
weight: 1
});
The Memcache client extends Hookified to provide powerful hooks and events for monitoring and customizing behavior.
The client emits various events during operations that you can listen to:
const client = new Memcache();
// Connection events
client.on('connect', () => {
console.log('Connected to Memcache server');
});
client.on('close', () => {
console.log('Connection closed');
});
client.on('error', (error) => {
console.error('Error:', error);
});
client.on('timeout', (nodeId) => {
console.log(`No response from ${nodeId} in time`);
});
// Cache hit/miss events
client.on('hit', (key, value) => {
console.log(`Cache hit for key: ${key}`);
});
client.on('miss', (key) => {
console.log(`Cache miss for key: ${key}`);
});
connect - Emitted when connection to Memcache server is establishedclose - Emitted when connection is closederror - Emitted when an error occurstimeout - Emitted when a connection can't be opened within timeout, or pending commands get no response within timeout (the connection is then closed)hit - Emitted when a key is found in cache (includes key and value)miss - Emitted when a key is not found in cachequit - Emitted when quit command is sentwarn - Emitted for warning messagesinfo - Emitted for informational messagesautoDiscover - Emitted on initial auto discovery with the cluster configautoDiscoverUpdate - Emitted when auto discovery detects a topology changeautoDiscoverError - Emitted when auto discovery encounters an errorHooks allow you to intercept and modify behavior before and after operations. Every operation supports before and after hooks.
const client = new Memcache();
// Add a before hook for get operations
client.onHook('before:get', async ({ key }) => {
console.log(`Getting key: ${key}`);
});
// Add an after hook for set operations
client.onHook('after:set', async ({ key, value, success }) => {
if (success) {
console.log(`Successfully set ${key}`);
}
});
// Hooks can be async and modify behavior
client.onHook('before:set', async ({ key, value }) => {
console.log(`About to set ${key} = ${value}`);
// Perform validation, logging, etc.
});
All operations support before and after hooks with specific parameters:
before:get - { key }after:get - { key, value } (value is array or undefined)before:set - { key, value, exptime, flags }after:set - { key, value, exptime, flags, success }before:gets - { keys }after:gets - { keys, values } (values is a Map)before:add - { key, value, exptime, flags }after:add - { key, value, exptime, flags, success }before:replace - { key, value, exptime, flags }after:replace - { key, value, exptime, flags, success }before:append - { key, value }after:append - { key, value, success }before:prepend - { key, value }after:prepend - { key, value, success }before:delete - { key }after:delete - { key, success }before:incr - { key, value }after:incr - { key, value, newValue }before:decr - { key, value }after:decr - { key, value, newValue }before:touch - { key, exptime }after:touch - { key, exptime, success }const client = new Memcache();
// Log all get operations
client.onHook('before:get', async ({ key }) => {
console.log(`[GET] Fetching key: ${key}`);
});
client.onHook('after:get', async ({ key, value }) => {
console.log(`[GET] Key: ${key}, Found: ${value !== undefined}`);
});
// Log all set operations with timing
client.onHook('before:set', async (context) => {
context.startTime = Date.now();
});
client.onHook('after:set', async (context) => {
const duration = Date.now() - context.startTime;
console.log(`[SET] Key: ${context.key}, Success: ${context.success}, Time: ${duration}ms`);
});
Memcache supports pluggable distribution algorithms to determine how keys are distributed across nodes. You can configure the algorithm using the hash option.
KetamaHash uses the Ketama consistent hashing algorithm, which minimizes key redistribution when nodes are added or removed. This is the default and recommended algorithm for production environments with dynamic scaling.
import { Memcache } from 'memcache';
// KetamaHash is used by default
const client = new Memcache({
nodes: ['server1:11211', 'server2:11211', 'server3:11211']
});
Characteristics:
ModulaHash uses a simple modulo-based hashing algorithm (hash(key) % nodeCount). This is a simpler algorithm that may redistribute all keys when nodes change.
import { Memcache, ModulaHash } from 'memcache';
// Use ModulaHash for distribution
const client = new Memcache({
nodes: ['server1:11211', 'server2:11211', 'server3:11211'],
hash: new ModulaHash()
});
// With a custom hash algorithm (default is sha1)
const client2 = new Memcache({
nodes: ['server1:11211', 'server2:11211'],
hash: new ModulaHash('md5')
});
Characteristics:
ModulaHash supports weighted nodes, where nodes with higher weights receive proportionally more keys:
import { Memcache, ModulaHash, createNode } from 'memcache';
// Create nodes with different weights
const node1 = createNode('server1', 11211, { weight: 3 }); // 3x traffic
const node2 = createNode('server2', 11211, { weight: 1 }); // 1x traffic
const client = new Memcache({
nodes: [node1, node2],
hash: new ModulaHash()
});
// server1 will receive approximately 75% of keys
// server2 will receive approximately 25% of keys
BroadcastHash sends every operation to all nodes in the cluster. Instead of partitioning keys across nodes, every getNodesByKey() call returns all nodes, so reads and writes are broadcast to every server.
import { Memcache, BroadcastHash } from 'memcache';
// Use BroadcastHash for full replication
const client = new Memcache({
nodes: ['server1:11211', 'server2:11211', 'server3:11211'],
hash: new BroadcastHash()
});
// Every set/get/delete hits all three nodes
await client.set('mykey', 'Hello!');
Characteristics:
| Feature | KetamaHash | ModulaHash | BroadcastHash |
|---|---|---|---|
| Key redistribution on node change | Minimal (~1/n keys) | All keys may move | N/A (all nodes always) |
| Complexity | Higher (virtual nodes) | Lower (simple modulo) | Simplest |
| Performance | Slightly slower | Faster | Depends on node count |
| Best for | Dynamic scaling | Fixed clusters | Replication |
| Weighted nodes | Yes | Yes | No |
Use KetamaHash (default) when:
Use ModulaHash when:
Use BroadcastHash when:
The Memcache client supports automatic retry of failed commands with configurable backoff strategies.
Enable retries by setting the retries option:
import { Memcache } from 'memcache';
const client = new Memcache({
nodes: ['localhost:11211'],
retries: 3, // Retry up to 3 times
retryDelay: 100 // 100ms between retries
});
You can also modify retry settings at runtime:
client.retries = 5;
client.retryDelay = 200;
The client includes two built-in backoff functions:
import { Memcache, defaultRetryBackoff } from 'memcache';
const client = new Memcache({
retries: 3,
retryDelay: 100,
retryBackoff: defaultRetryBackoff // 100ms, 100ms, 100ms
});
import { Memcache, exponentialRetryBackoff } from 'memcache';
const client = new Memcache({
retries: 3,
retryDelay: 100,
retryBackoff: exponentialRetryBackoff // 100ms, 200ms, 400ms
});
You can provide your own backoff function:
const client = new Memcache({
retries: 3,
retryDelay: 100,
retryBackoff: (attempt, baseDelay) => {
// Exponential backoff with jitter
const delay = baseDelay * Math.pow(2, attempt);
return delay + Math.random() * delay * 0.1;
}
});
The backoff function receives:
attempt - The current attempt number (0-indexed)baseDelay - The configured retryDelay valueImportant: By default, retries are only performed for commands explicitly marked as idempotent. This prevents accidental double-execution of non-idempotent operations like incr, decr, append, and prepend.
If a network timeout occurs after the server applies a mutation but before the client receives the response, retrying would apply the mutation twice:
For read operations (always safe to retry):
// Mark read operations as idempotent
await client.execute('get mykey', nodes, { idempotent: true });
For idempotent writes (safe to retry):
// SET with the same value is idempotent
await client.execute('set mykey 0 0 5\r\nhello', nodes, { idempotent: true });
Disable safety for all commands (use with caution):
const client = new Memcache({
retries: 3,
retryOnlyIdempotent: false // Allow retries for ALL commands
});
retryOnlyIdempotent |
idempotent flag |
Retries enabled? |
|---|---|---|
true (default) |
false (default) |
No |
true (default) |
true |
Yes |
false |
(any) | Yes |
The following methods do not use the retry mechanism and have their own error handling:
get() - Returns undefined on failuregets() - Returns partial results on node failureflush() - Operates directly on nodesstats() - Operates directly on nodesversion() - Operates directly on nodesTo use retries with read operations, use the execute() method directly:
const nodes = await client.getNodesByKey('mykey');
const results = await client.execute('get mykey', nodes, { idempotent: true });
The Memcache client supports SASL (Simple Authentication and Security Layer) authentication using the PLAIN mechanism. This allows you to connect to memcached servers that require authentication.
import { Memcache } from 'memcache';
const client = new Memcache({
nodes: ['localhost:11211'],
sasl: {
username: 'myuser',
password: 'mypassword',
},
});
await client.connect();
// Client is now authenticated and ready to use
The sasl option accepts an object with the following properties:
username: string - The username for authentication (required)password: string - The password for authentication (required)mechanism?: 'PLAIN' - The SASL mechanism to use (default: 'PLAIN')Currently, only the PLAIN mechanism is supported.
Important: Memcached servers with SASL enabled (-S flag) require the binary protocol for all operations after authentication. The standard text-based methods (client.get(), client.set(), etc.) will not work on SASL-enabled servers.
Use the binary* methods on nodes for SASL-enabled servers:
import { Memcache } from 'memcache';
const client = new Memcache({
nodes: ['localhost:11211'],
sasl: { username: 'user', password: 'pass' },
});
await client.connect();
// Access the node directly for binary operations
const node = client.nodes[0];
// Binary protocol operations
await node.binarySet('mykey', 'myvalue', 3600); // Set with 1 hour expiry
const value = await node.binaryGet('mykey'); // Get value
await node.binaryDelete('mykey'); // Delete key
// Other binary operations
await node.binaryAdd('newkey', 'value'); // Add (only if not exists)
await node.binaryReplace('existingkey', 'newvalue'); // Replace (only if exists)
await node.binaryIncr('counter', 1); // Increment
await node.binaryDecr('counter', 1); // Decrement
await node.binaryAppend('mykey', '-suffix'); // Append to value
await node.binaryPrepend('mykey', 'prefix-'); // Prepend to value
await node.binaryTouch('mykey', 7200); // Update expiration
await node.binaryFlush(); // Flush all
const version = await node.binaryVersion(); // Get server version
const stats = await node.binaryStats(); // Get server stats
The binary* methods can run concurrently on the same node. Requests are pipelined on the node's connection, and each caller gets the response to its own request:
const [a, b] = await Promise.all([node.binaryGet('key-a'), node.binaryGet('key-b')]);
If a response doesn't match the request it should answer, every pending binary request is rejected and the connection is closed instead of returning another request's data.
You can also configure SASL credentials when creating individual nodes:
import { createNode } from 'memcache';
// Create a node with SASL credentials
const node = createNode('localhost', 11211, {
sasl: { username: 'user', password: 'pass' },
});
// Connect and use binary methods
await node.connect();
await node.binarySet('mykey', 'hello');
const value = await node.binaryGet('mykey');
You can listen for authentication events on both nodes and the client:
import { Memcache, MemcacheNode } from 'memcache';
// Node-level events
const node = new MemcacheNode('localhost', 11211, {
sasl: { username: 'user', password: 'pass' },
});
node.on('authenticated', () => {
console.log('Node authenticated successfully');
});
node.on('error', (error) => {
if (error.message.includes('SASL authentication failed')) {
console.error('Authentication failed:', error.message);
}
});
await node.connect();
// Client-level events (forwarded from nodes)
const client = new Memcache({
nodes: ['localhost:11211'],
sasl: { username: 'user', password: 'pass' },
});
client.on('authenticated', () => {
console.log('Client authenticated');
});
await client.connect();
node.hasSaslCredentials - Returns true if SASL credentials are configurednode.isAuthenticated - Returns true if the node has successfully authenticatedTo use SASL authentication, your memcached server must be configured with SASL support:
Build memcached with SASL support - Ensure memcached was compiled with --enable-sasl
Create SASL users - Use saslpasswd2 to create users:
saslpasswd2 -a memcached -c username
Configure SASL mechanism - Create /etc/sasl2/memcached.conf:
mech_list: plain
Start memcached with SASL - Use the -S flag:
memcached -S -m 64 -p 11211
For more details, see the memcached SASL documentation.
The Memcache client supports AWS ElastiCache Auto Discovery, which automatically detects cluster topology changes and adds or removes nodes as needed. When enabled, the client connects to a configuration endpoint, retrieves the current list of cache nodes, and periodically polls for changes.
import { Memcache } from 'memcache';
const client = new Memcache({
nodes: [],
autoDiscover: {
enabled: true,
configEndpoint: 'my-cluster.cfg.use1.cache.amazonaws.com:11211',
},
});
await client.connect();
// The client automatically discovers and connects to all cluster nodes
If you omit configEndpoint, the first node in the nodes array is used as the configuration endpoint:
const client = new Memcache({
nodes: ['my-cluster.cfg.use1.cache.amazonaws.com:11211'],
autoDiscover: {
enabled: true,
},
});
The autoDiscover option accepts an object with the following properties:
enabled: boolean - Enable auto discovery of cluster nodes (required)pollingInterval?: number - How often to poll for topology changes, in milliseconds (default: 60000)configEndpoint?: string - The configuration endpoint to use for discovery. This is typically the .cfg endpoint from ElastiCache. If not specified, the first node in the nodes array will be useduseLegacyCommand?: boolean - Use the legacy get AmazonElastiCache:cluster command instead of config get cluster (default: false)The client emits events during the auto discovery lifecycle:
const client = new Memcache({
nodes: [],
autoDiscover: {
enabled: true,
configEndpoint: 'my-cluster.cfg.use1.cache.amazonaws.com:11211',
},
});
// Emitted on initial discovery with the full cluster config
client.on('autoDiscover', (config) => {
console.log('Discovered nodes:', config.nodes);
console.log('Config version:', config.version);
});
// Emitted when polling detects a topology change
client.on('autoDiscoverUpdate', (config) => {
console.log('Cluster topology changed:', config.nodes);
});
// Emitted when discovery encounters an error (non-fatal, retries on next poll)
client.on('autoDiscoverError', (error) => {
console.error('Discovery error:', error.message);
});
await client.connect();
For ElastiCache engine versions older than 1.4.14, use the legacy discovery command:
const client = new Memcache({
nodes: [],
autoDiscover: {
enabled: true,
configEndpoint: 'my-cluster.cfg.use1.cache.amazonaws.com:11211',
useLegacyCommand: true, // Uses 'get AmazonElastiCache:cluster' instead of 'config get cluster'
},
});
The Memcache client fully supports IPv6 addresses using standard bracket notation in URIs.
import { Memcache } from 'memcache';
// IPv6 loopback
const client = new Memcache('[::1]:11211');
// Multiple IPv6 nodes
const client = new Memcache({
nodes: [
'[::1]:11211',
'[2001:db8::1]:11211',
'memcache://[2001:db8::2]:11212',
],
});
await client.connect();
When auto discovery returns IPv6 node addresses, the client automatically brackets them for correct URI handling:
const client = new Memcache({
nodes: [],
autoDiscover: {
enabled: true,
configEndpoint: '[2001:db8::1]:11211',
},
});
await client.connect();
// Discovered IPv6 nodes are added as [host]:port automatically
Node IDs for IPv6 addresses use bracket notation to avoid ambiguity:
const client = new Memcache({
nodes: ['[::1]:11211', '[2001:db8::1]:11212'],
});
console.log(client.nodeIds);
// ['[::1]:11211', '[2001:db8::1]:11212']
The client can connect to TLS-enabled memcached servers (memcached ships TLS
since 1.5.13 via -Z; the official Docker image supports it since 1.5.21).
Connection readiness waits for the completed TLS handshake (secureConnect),
so pipelined commands are never written into an unfinished handshake.
Enable TLS for every node with the client-level tls option:
import { Memcache } from 'memcache';
// TLS with Node's default trust store (publicly-trusted server certs)
const client = new Memcache({
nodes: ['my-cache.example.com:11211'],
tls: true,
});
await client.set('mykey', 'Hello over TLS!');
Or per node with the memcaches:// URI scheme (enables TLS for that node
even when the client-level option is unset):
const client = new Memcache('memcaches://my-cache.example.com:11211');
The tls option accepts:
true / {} — connect using TLS with Node's default trust storetls.ConnectionOptions object — passed through to tls.connect() (CA,
client certificates, servername, minVersion, …)false / undefined (default) — plain TCPCertificate verification is always on (standard Node behavior). To connect to a server with a self-signed cert, pass its CA — do not disable verification.
The node's host, port (or Unix socket path), and keep-alive settings always
win over any host / port / path fields in a tls options object.
You can also enable TLS when creating individual nodes:
import { createNode } from 'memcache';
import { readFileSync } from 'node:fs';
const node = createNode('memcached-internal', 11211, {
tls: { ca: readFileSync('/etc/ssl/private-ca.pem') },
});
await node.connect();
await node.command('version');
node.tlsEnabled — true when TLS is configured for the nodenode.tls — the TLS option the node was constructed withnode.uri — memcaches://host:port when TLS is enabled, so passing it
back into addNode() or the constructor keeps TLS on even without a
client-level tls optionThe client's connect event fires after the TLS handshake completes.
ElastiCache Serverless (Memcached) requires TLS and only speaks the text
protocol — both are this client's defaults, so the only configuration needed
is tls: true (the server presents a publicly-trusted ACM certificate):
const client = new Memcache({
nodes: ['my-cache-xxxxxx.serverless.use1.cache.amazonaws.com:11211'],
tls: true,
});
Pass any tls.connect() options — private CAs, client certificates, servername
overrides — as an object:
import { readFileSync } from 'node:fs';
const client = new Memcache({
nodes: ['memcached-internal:11211'],
tls: {
ca: readFileSync('/etc/ssl/private-ca.pem'),
// cert, key, servername, ... are passed through to tls.connect()
},
});
Auto Discovery uses the same client-level tls (and sasl) options as data
nodes, including the configuration-endpoint connection. Set tls: true (or a
CA options object) when the cluster requires in-transit encryption:
const client = new Memcache({
nodes: [],
tls: true,
autoDiscover: {
enabled: true,
configEndpoint: 'my-cluster.cfg.use1.cache.amazonaws.com:11211',
},
});
A memcaches:// configuration endpoint also enables TLS for discovery. When
discovery returns a DNS hostname plus an IP, the client connects to the IP
(stable node IDs) and sets TLS SNI/servername to the hostname so certificate
verification matches ElastiCache node certs.
TLS and SASL compose: the TCP handshake completes, then SASL PLAIN runs on the encrypted socket. Use both for ElastiCache clusters that require in-transit encryption and AUTH. SASL-enabled servers still require the binary protocol after authentication (see SASL Authentication).
const client = new Memcache({
nodes: ['my-cluster.use1.cache.amazonaws.com:11211'],
tls: true,
sasl: { username: 'user', password: 'token' },
});
await client.connect();
const node = client.nodes[0];
await node.binarySet('mykey', 'hello');
To run memcached with TLS:
Build or use an image with TLS — memcached 1.5.13+ (--enable-tls);
the official Docker image supports it since 1.5.21
Provide a certificate chain and key
Start memcached with -Z:
memcached -Z \
-o ssl_chain_cert=/path/to/server_crt.pem \
-o ssl_key=/path/to/server_key.pem \
-o ssl_session_cache
ElastiCache Serverless is ASCII-only; a local stand-in is:
memcached -Z -B ascii -U 0 \
-o ssl_chain_cert=/path/to/server_crt.pem \
-o ssl_key=/path/to/server_key.pem
For more details, see the memcached TLS documentation.
Tables below are auto-generated by
pnpm benchmark:readme. Do not edit between the<!-- BENCHMARK:* -->markers.
Set, Get and Delete compares this client with other Node.js memcached clients on single-key and multi-key tasks run one at a time in random order, and the next section compares them under load and on multi-gets. The other tables show how this client behaves under load; in each one, every row does the same total work in a different shape.
All the tables come from one run of pnpm benchmark:readme, with Node.js 22 on Linux, against the benchmark containers' IPs (see Running the benchmarks). The absolute numbers depend on the machine; the comparisons within each table are what carry over.
Each library runs 1,000 tasks that set, get and delete one key, and 1,000 that set, get and delete 10 keys. The tasks of all 3 libraries go into one queue in random order and run one at a time. The queue runs 5 times, shuffled each time, after an untimed warm-up of 100 tasks of each kind per library. Every result is checked.
Total time per library, the median of the 5 runs (lower is better). 🥇 marks the fastest library in each row, and the percentages compare the others with it. The text protocol has no multi-set or multi-delete, so for 10 keys every library sends its 10 sets, and then its 10 deletes, at once. memjs has no multi-get either, so it does the same with its gets. memcached pools up to 10 connections; the other clients use one.
| Tasks | memcache (v1.11.0) | memjs (v1.3.2) | memcached (v2.2.2) |
|---|---|---|---|
| 1,000 × set, get, delete 1 key | 🥇 290 ms | 322 ms (+11%) | 333 ms (+15%) |
| 1,000 × set, get, delete 10 keys | 🥇 424 ms | 566 ms (+33%) | 789 ms (+86%) |
| All 2,000 tasks | 🥇 713 ms | 893 ms (+25%) | 1.12 s (+57%) |
Each cell is the median of 3 rounds, with the clients taking turns. 🥇 marks the fastest client in each row, and the percentages compare the other clients with it.
Requests per second, 500 requests per run (higher is better). memcached pools up to 10 connections; the other clients use one.
| Workload | memcache (v1.11.0) | memjs (v1.3.2) | memcached (v2.2.2) |
|---|---|---|---|
| gets, 1 in flight | 🥇 12.3K | 11.8K (-3.5%) | 10.5K (-14%) |
| gets, 10 in flight | 🥇 86.8K | 65.0K (-25%) | 44.6K (-49%) |
| gets, 100 in flight | 🥇 285.6K | 104.0K (-64%) | 59.7K (-79%) |
| gets, 500 in flight | 🥇 298.1K | 109.9K (-63%) | 60.0K (-80%) |
| sets, 1 in flight | 🥇 13.2K | 11.8K (-11%) | 10.7K (-19%) |
| sets, 10 in flight | 🥇 106.8K | 64.9K (-39%) | 35.6K (-67%) |
| sets, 100 in flight | 🥇 328.9K | 92.1K (-72%) | 42.9K (-87%) |
| sets, 500 in flight | 🥇 272.1K | 93.7K (-66%) | 46.3K (-83%) |
Time to fetch 10,000 keys in batches (lower is better). memjs has no multi-get, so it sends one get per key, all at once.
| Batches | memcache (v1.11.0) | memjs (v1.3.2) | memcached (v2.2.2) |
|---|---|---|---|
| 100 × 100 keys | 🥇 28 ms | 93 ms (+230%) | 68 ms (+141%) |
| 10 × 1,000 keys | 🥇 18 ms | 97 ms (+443%) | 132 ms (+642%) |
| 1 × 10,000 keys | 🥇 21 ms | 146 ms (+606%) | 2.63 s (+12649%) |
| name | summary | ops/sec | time/op | margin | samples |
|---|---|---|---|---|---|
| 500 sets, 100 in flight | 🥇 | 725 | 1ms | ±1.27% | 697 |
| 500 gets, 500 in flight | -16% | 606 | 2ms | ±1.71% | 571 |
| 500 sets, 500 in flight | -19% | 588 | 2ms | ±1.74% | 558 |
| 500 gets, 100 in flight | -24% | 549 | 2ms | ±1.50% | 526 |
| 500 sets, 10 in flight | -70% | 216 | 5ms | ±2.38% | 209 |
| 500 gets, 10 in flight | -75% | 182 | 6ms | ±1.97% | 179 |
| 500 sets, 1 in flight | -96% | 27 | 37ms | ±1.68% | 64 |
| 500 gets, 1 in flight | -96% | 26 | 39ms | ±1.91% | 64 |
| name | summary | ops/sec | time/op | margin | samples |
|---|---|---|---|---|---|
| 10 × gets() of 1,000 keys | 🥇 | 56 | 18ms | ±1.77% | 166 |
| 1 × gets() of 10,000 keys | -14% | 48 | 21ms | ±2.02% | 143 |
| 100 × gets() of 100 keys | -30% | 39 | 26ms | ±2.39% | 116 |
| name | summary | ops/sec | time/op | margin | samples |
|---|---|---|---|---|---|
| TCP: 4 × 1 MB sets | 🥇 | 157 | 7ms | ±2.15% | 154 |
| TCP: 1 × 4 MB sets | -1.6% | 155 | 7ms | ±1.68% | 153 |
| TCP: 16 × 256 KB sets | -4.2% | 151 | 7ms | ±1.84% | 149 |
| TLS: 4 × 1 MB sets | -23% | 121 | 8ms | ±2.74% | 118 |
| TLS: 1 × 4 MB sets | -24% | 120 | 8ms | ±1.50% | 120 |
| TCP: 1 × 4 MB gets | -29% | 112 | 9ms | ±2.23% | 110 |
| TCP: 16 × 256 KB gets | -30% | 110 | 10ms | ±4.03% | 104 |
| TLS: 16 × 256 KB sets | -34% | 104 | 10ms | ±3.18% | 102 |
| TCP: 4 × 1 MB gets | -35% | 102 | 10ms | ±2.67% | 100 |
| TLS: 4 × 1 MB gets | -40% | 94 | 11ms | ±4.72% | 90 |
| TLS: 1 × 4 MB gets | -40% | 94 | 11ms | ±5.67% | 87 |
| TLS: 16 × 256 KB gets | -54% | 73 | 14ms | ±3.92% | 72 |
| name | summary | ops/sec | time/op | margin | samples |
|---|---|---|---|---|---|
| 6 × 10,000 concurrent gets | 🥇 | 4 | 268ms | ±6.48% | 19 |
| 2 × 30,000 concurrent gets | -8.3% | 4 | 292ms | ±7.15% | 18 |
| 1 × 60,000 concurrent gets | -8.4% | 4 | 293ms | ±7.67% | 18 |
| concurrent first requests | sockets opened |
|---|---|
| 50 | 1 |
Each table has its own script: pnpm benchmark:set-get, benchmark:compare, benchmark:concurrency, benchmark:multi-get, benchmark:large-values, benchmark:bursts and benchmark:cold-start. pnpm benchmark runs them all, and pnpm benchmark:readme runs them and updates the tables above; pass section ids, such as pnpm benchmark:readme compare, to update only those tables. They run against dedicated memcached containers that the test services don't start:
pnpm benchmark:services:start
pnpm benchmark
pnpm benchmark:services:stop
To target other servers, set MEMCACHE_BENCH_HOST and MEMCACHE_BENCH_PORT, plus MEMCACHE_BENCH_TLS_HOST and MEMCACHE_BENCH_TLS_PORT for the TLS measurements. TLS trusts the test CA by default. For a server with its own certificate, set MEMCACHE_BENCH_TLS_CA to its CA bundle, and MEMCACHE_BENCH_TLS_SERVERNAME if the certificate's name differs from the host. Set MEMCACHE_BENCH_SKIP_TLS=1 to leave TLS out.
On Linux, published Docker ports go through docker-proxy, which adds per-packet overhead. For numbers closer to a real network, use the containers' IPs with port 11211:
MEMCACHE_BENCH_HOST=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' memcached-server-bench) \
MEMCACHE_BENCH_PORT=11211 \
MEMCACHE_BENCH_TLS_HOST=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' memcached-server-bench-tls) \
MEMCACHE_BENCH_TLS_PORT=11211 \
pnpm benchmark
Please read our Contributing Guidelines and also our Code of Conduct.
Add maxPendingCommands, fix connection and timeout behavior, and speed up commands.
add `maxPendingCommands` to fail requests fast under overload (#162)
```javascript
const client = new Memcache({
nodes: ['localhost:11211'],
maxPendingCommands: 1000, // default 0: no limit
});
```
While a node has that many requests waiting for a response or for its connection to open, a new request to it fails at once instead of waiting: `set()` resolves `false` and `get()` resolves `undefined` on an open connection; while the connection is being opened, single-key commands reject. Refused requests are not retried, and `quit()` still goes out. `MemcacheNode` gains `connectForRequest()`, which the client's commands use to wait for a connection.
The same benchmark files run against 1.11.0 and this branch in one session, taking turns (time per operation, so lower is better):
| Benchmark | 1.11.0 | 1.12.0 | Speedup |
|---|---|---|---|
| 500 gets, 100 in flight | 5.8 ms | 1.9 ms | 3.1× |
| 500 sets, 100 in flight | 5.0 ms | 1.6 ms | 3.2× |
| 500 gets, 10 in flight | 7.6 ms | 5.4 ms | 1.4× |
| 500 gets, 1 in flight | 41 ms | 40 ms | unchanged (one round trip at a time) |
| `gets()` of 10,000 keys, one batch | 1.69 s | 22 ms | 77× |
| `gets()` of 10,000 keys, 10 batches | 228 ms | 19 ms | 12× |
| 60,000 gets in one burst | 6.7 s | 296 ms | 23× |
| get of a 4 MB value, TLS | 105 ms | 10 ms | 10.6× |
| get of a 4 MB value, TCP | 31 ms | 8.5 ms | 3.6× |
| 4 sets of 1 MB values, TCP | 8.5 ms | 6.2 ms | 1.4× |
| 1,000 tasks setting, getting and deleting 10 keys, one at a time | 519 ms | 412 ms | 1.26× |
In the README's comparison with memjs and memcached, 1.12.0 is now the fastest client in every row. In the same session, 1.11.0 trailed memjs on gets with 100 or more in flight, on sets with 500, and on multi-gets of 1,000 or more keys per batch.
Full diff: https://github.com/jaredwray/memcache/compare/v1.11.0...v1.12.0
TLS Auto Discovery and TLS+SASL composition, plus pnpm 12 and dependency maintenance.
bring TLS to SASL-level support (`769ac99`, #134)
```javascript
const client = new Memcache({
nodes: [],
tls: true,
autoDiscover: {
enabled: true,
configEndpoint: 'my-cluster.cfg.use1.cache.amazonaws.com:11211',
},
});
```
```javascript
const client = new Memcache({
nodes: ['my-cluster.use1.cache.amazonaws.com:11211'],
tls: true,
sasl: { username: 'user', password: 'token' },
});
await client.connect();
const node = client.nodes[0];
node.tlsEnabled; // true
await node.binarySet('mykey', 'hello');
```
Full diff: https://github.com/jaredwray/memcache/compare/v1.10.0...v1.11.0
Adds TLS connections (`tls` / `memcaches://`), publishes memcachejs.org, and hardens CI/publish.
add TLS support (`7a822b9`, #115)
```javascript
import { Memcache } from 'memcache';
const client = new Memcache({
nodes: ['my-cache.example.com:11211'],
tls: true, // or a tls.ConnectionOptions object, e.g. { ca }
});
```
```javascript
// Per-node TLS without a client-level tls option
const client = new Memcache('memcaches://my-cache.example.com:11211');
```
generate memcachejs.org site with Docula (`1f0507e`, #104)
Full diff: https://github.com/jaredwray/memcache/compare/v1.9.0...v1.10.0