Nodejs Memcache Client

• Getting Started
  • Installation
  • Basic Usage
  • Custom Connection
• API
  • Constructor
  • Properties
  • Connection Management
  • Node Management
  • Data Storage Operations
  • String Modification Operations
  • Deletion & Expiration
  • Numeric Operations
  • Server Management & Statistics
  • Validation
  • Helper Functions
• Hooks and Events
  • Events
  • Available Events
  • Hooks
  • Available Hooks
    • get(key)
    • set(key, value, exptime?, flags?)
    • gets(keys[])
    • add(key, value, exptime?, flags?)
    • replace(key, value, exptime?, flags?)
    • append(key, value)
    • prepend(key, value)
    • delete(key)
    • incr(key, value?)
    • decr(key, value?)
    • touch(key, exptime)
  • Hook Examples
• Contributing
• License and Copyright

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:

• A string representing a single node URI (uses default settings)
• A MemcacheOptions object for custom configuration

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
  • Examples: ["localhost:11211", "memcache://192.168.1.100:11212"]
• timeout?: number - Operation timeout in milliseconds (default: 5000)
• 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)

Returns the list of all MemcacheNode instances in the cluster.

Returns the list of node IDs (e.g., ["localhost:11211", "127.0.0.1:11212"]).

Get or set the hash provider used for consistent hashing distribution.

Get or set the timeout for operations in milliseconds (default: 5000).

Get or set the keepAlive setting. Updates all existing nodes. Requires reconnect() to apply changes.

Get or set the keep alive delay in milliseconds. Updates all existing nodes. Requires reconnect() to apply changes.

Connect to all Memcache servers or a specific node.

Disconnect all connections.

Reconnect all nodes by disconnecting and connecting them again.

Quit all connections gracefully.

Check if any node is connected to a Memcache server.

Get an array of all MemcacheNode instances.

Get a specific node by its ID (e.g., "localhost:11211").

Add a new node to the cluster. Throws error if node already exists.

Remove a node from the cluster.

Get the nodes for a given key using consistent hashing. Automatically connects to nodes if not already connected.

Parse a URI string into host and port. Supports formats:

• Simple: "localhost:11211" or "localhost"
• Protocol: "memcache://localhost:11211", "tcp://localhost:11211"
• IPv6: "[::1]:11211" or "memcache://[2001:db8::1]:11212"
• Unix socket: "/var/run/memcached.sock" or "unix:///var/run/memcached.sock"

Get a value from the Memcache server. Returns the first successful result from replica nodes.

Get multiple values from the Memcache server. Returns a Map with keys to values.

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 a value (only if key doesn't exist). Returns true only if all replica nodes succeed.

Replace a value (only if key exists). Returns true only if all replica nodes succeed.

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 a value to an existing key. Returns true only if all replica nodes succeed.

Prepend a value to an existing key. Returns true only if all replica nodes succeed.

Delete a value from the Memcache server. Returns true only if all replica nodes succeed.

Update expiration time without retrieving value. Returns true only if all replica nodes succeed.

Increment a value. Returns the new value or undefined on failure.

• value - Amount to increment (default: 1)

Decrement a value. Returns the new value or undefined on failure.

• value - Amount to decrement (default: 1)

Flush all values from all Memcache servers. Returns true if all nodes successfully flushed.

• delay - Optional delay in seconds before flushing

Get statistics from all Memcache servers. Returns a Map of node IDs to their stats.

Get the Memcache server version from all nodes. Returns a Map of node IDs to version strings.

Validates a Memcache key according to protocol requirements. Throws error if:

• Key is empty
• Key exceeds 250 characters
• Key contains spaces, newlines, or null characters

Factory 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', () => {
  console.log('Connection timeout');
});

// 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 established
• close - Emitted when connection is closed
• error - Emitted when an error occurs
• timeout - Emitted when a connection timeout occurs
• hit - Emitted when a key is found in cache (includes key and value)
• miss - Emitted when a key is not found in cache
• quit - Emitted when quit command is sent
• warn - Emitted for warning messages
• info - Emitted for informational messages

Hooks 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`);
});

Please read our Contributing Guidelines and also our Code of Conduct.

MIT & Copyright (c) Jared Wray