logo

codecov tests npm npm license

Memcache

Nodejs Memcache Client

Table of Contents

Getting Started

Installation

npm install memcache

or with pnpm:

pnpm add memcache

Basic Usage

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

API

Constructor

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

Options

Properties

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: HashProvider

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

timeout: number

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

keepAlive: boolean

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

keepAliveDelay: number

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

retries: number

Get or set the number of retry attempts for failed commands (default: 0).

retryDelay: number

Get or set the base delay in milliseconds between retry attempts (default: 100).

retryBackoff: RetryBackoffFunction

Get or set the backoff function for calculating retry delays.

retryOnlyIdempotent: boolean

Get or set whether retries are restricted to idempotent commands only (default: true).

maxKeySize: number

Get or set the maximum allowed key size in characters (default: 250). Memcache protocol max is 250.

maxValueSize: number

Get 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: number

Get 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: boolean

Get 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: Hashery

Get 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).

Connection Management

connect(nodeId?: string): Promise

Connect to all Memcache servers or a specific node.

disconnect(): Promise

Disconnect all connections.

reconnect(): Promise

Reconnect all nodes by disconnecting and connecting them again.

quit(): Promise

Quit all connections gracefully.

isConnected(): boolean

Check if any node is connected to a Memcache server.

Node Management

getNodes(): MemcacheNode[]

Get an array of all MemcacheNode instances.

getNode(id: string): MemcacheNode | undefined

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

addNode(uri: string | MemcacheNode, weight?: number): Promise

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

removeNode(uri: string): Promise

Remove a node from the cluster.

getNodesByKey(key: string): Promise

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

parseUri(uri: string): { host: string; port: number; secure?: boolean }

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

Data Storage Operations

get(key: string): Promise

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

gets(keys: string[]): Promise>

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

set(key: string, value: string, exptime?: number, flags?: number): Promise

Set a value in the Memcache server. Returns true only if all replica nodes succeed.

add(key: string, value: string, exptime?: number, flags?: number): Promise

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

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

Check-And-Set: Store a value only if it hasn't been modified since last fetch. Returns true only if all replica nodes succeed.

String Modification Operations

append(key: string, value: string): Promise

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

prepend(key: string, value: string): Promise

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

Deletion & Expiration

delete(key: string): Promise

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

touch(key: string, exptime: number): Promise

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

Numeric Operations

incr(key: string, value?: number): Promise

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

decr(key: string, value?: number): Promise

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

Server Management & Statistics

flush(delay?: number): Promise

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

stats(type?: string): Promise>

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

version(): Promise>

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

Validation

validateKey(key: string): void

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

resolveKey(key: string): string

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

Helper Functions

createNode(host: string, port: number, options?: MemcacheNodeOptions): MemcacheNode

Factory function to create a new MemcacheNode instance.

import { createNode } from 'memcache';

const node = createNode('localhost', 11211, {
  timeout: 5000,
  keepAlive: true,
  weight: 1
});

Hooks and Events

The Memcache client extends Hookified to provide powerful hooks and events for monitoring and customizing behavior.

Events

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

Available Events

Hooks

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.
});

Available Hooks

All operations support before and after hooks with specific parameters:

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

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

Distribution Algorithms

Memcache supports pluggable distribution algorithms to determine how keys are distributed across nodes. You can configure the algorithm using the hash option.

KetamaHash (Default)

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

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:

Weighted Nodes with ModulaHash

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

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:

Choosing an Algorithm

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:

Retry Configuration

The Memcache client supports automatic retry of failed commands with configurable backoff strategies.

Basic Retry Setup

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;

Backoff Strategies

The client includes two built-in backoff functions:

Fixed Delay (Default)

import { Memcache, defaultRetryBackoff } from 'memcache';

const client = new Memcache({
  retries: 3,
  retryDelay: 100,
  retryBackoff: defaultRetryBackoff  // 100ms, 100ms, 100ms
});

Exponential Backoff

import { Memcache, exponentialRetryBackoff } from 'memcache';

const client = new Memcache({
  retries: 3,
  retryDelay: 100,
  retryBackoff: exponentialRetryBackoff  // 100ms, 200ms, 400ms
});

Custom Backoff Function

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:

Idempotent Safety

Important: 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.

Why This Matters

If a network timeout occurs after the server applies a mutation but before the client receives the response, retrying would apply the mutation twice:

Safe Usage Patterns

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

Behavior Summary

retryOnlyIdempotent idempotent flag Retries enabled?
true (default) false (default) No
true (default) true Yes
false (any) Yes

Methods Without Retry Support

The following methods do not use the retry mechanism and have their own error handling:

To 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 });

SASL Authentication

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.

Enabling SASL 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

SASL Options

The sasl option accepts an object with the following properties:

Currently, only the PLAIN mechanism is supported.

Binary Protocol Methods

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

Per-Node SASL Configuration

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

Authentication Events

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 Properties

Server Configuration

To use SASL authentication, your memcached server must be configured with SASL support:

  1. Build memcached with SASL support - Ensure memcached was compiled with --enable-sasl

  2. Create SASL users - Use saslpasswd2 to create users:

    saslpasswd2 -a memcached -c username

  3. Configure SASL mechanism - Create /etc/sasl2/memcached.conf:

    mech_list: plain

  4. Start memcached with SASL - Use the -S flag:

    memcached -S -m 64 -p 11211

For more details, see the memcached SASL documentation.

Auto Discovery

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.

Enabling Auto Discovery

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

Auto Discovery Options

The autoDiscover option accepts an object with the following properties:

Auto Discovery Events

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

Legacy Command Support

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

IPv6 Support

The Memcache client fully supports IPv6 addresses using standard bracket notation in URIs.

Connecting to IPv6 Nodes

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

IPv6 in Auto Discovery

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

IPv6 Node IDs

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']

TLS Support

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.

Connecting with TLS

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

AWS ElastiCache Serverless

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

Custom certificate authorities

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

Notes:

Benchmarks

These are provided to show a simple benchmark against current libraries. This is not robust but it is something we update regularly to make sure we are keeping performant.

name summary ops/sec time/op margin samples
memcache set/get (v1.4.0) 🥇 3K 350µs ±0.19% 10K
memcached set/get (v2.2.2) -2.9% 3K 361µs ±0.16% 10K
memjs set/get (v1.3.2) -12% 3K 398µs ±0.17% 10K

Contributing

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

License and Copyright

MIT & Copyright (c) Jared Wray

Contributors

jaredwray claude cursoragent marceloboeira

Changelog

v1.10.0 August 19, 2026

memcache@1.10.0 — 2026-08-19

Adds TLS connections (`tls` / `memcaches://`), publishes memcachejs.org, and hardens CI/publish.

Features

  • 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)

Bug Fixes

  • emit `memcaches://` from `MemcacheNode.uri` when TLS is enabled so the URI round-trips through `parseUri()` / `addNode()` (`246dd3d`, #122)

Documentation

  • add Cursor Cloud dev environment setup notes to AGENTS.md (`fddc21e`, #103)

Internal

  • scaffold security docs (`b8203e5`, #105)
  • add CODEOWNERS (`a61167b`, #106)
  • bootstrap Aikido Safe Chain (`0fbd4e0`, #107)
  • set pnpm 7-day cooldown (`3121f16`, #108)
  • block pnpm lifecycle scripts (`367c832`, #109)
  • block exotic pnpm subdeps (`56d201b`, #110)
  • freeze CI installs behind Socket Firewall (`8b4058b`, #111)
  • pin GitHub Actions to SHAs (`0351c0f`, #113)
  • lint workflows with zizmor (`d74fefc`, #116)
  • stage npm releases from CI (`5cd58cf`, #117)
  • gate staged npm publish on Aikido scan-release (`27379f4`, #118)
  • record repository lockdown (`e87b6f9`, #119)
  • enable pnpm `trustPolicy: no-downgrade` (`1238008`, #120)
  • remove writr override (`5d86e40`, #123)
  • upgrade `@biomejs/biome` to 2.5.8 (`73045c9`, #124)
  • upgrade TypeScript build tooling — tsx 4.23.12, tsdown 0.22.14, @types/node 24.13.3 (`e6bb669`, #125)
  • upgrade pnpm to 11.21.0 (`a7067cb`, #126)
  • upgrade tinybench to 6.1.3 (`2a24f95`, #127)
  • upgrade wrangler to 4.121.0 (`a69a878`, #128)
  • upgrade `hashery` runtime dependency to 3.0.1 (`2da196b`, #129)
  • upgrade `hookified` runtime dependency to 3.0.2 (`1a4969a`, #130)
  • upgrade memcached test-service image to 1.6.45 (`5885484`, #131)

Contributors

  • @jaredwray (23)
  • @marceloboeira (1)

Full List of Changes

  • docs: add Cursor Cloud dev environment setup notes to AGENTS.md by @jaredwray in #103
  • feat: generate memcachejs.org site with Docula by @jaredwray in #104
  • memcache - chore: defense - scaffold security docs by @jaredwray in #105
  • memcache - chore: defense - add CODEOWNERS by @jaredwray in #106
  • memcache - chore: defense - bootstrap Aikido Safe Chain by @jaredwray in #107
  • memcache - chore: defense - set pnpm 7-day cooldown by @jaredwray in #108
  • memcache - chore: defense - block pnpm lifecycle scripts by @jaredwray in #109
  • memcache - chore: defense - block exotic pnpm subdeps by @jaredwray in #110
  • memcache - chore: defense - freeze CI installs behind sfw by @jaredwray in #111
  • memcache - chore: defense - pin GitHub Actions to SHAs by @jaredwray in #113
  • memcache - chore: defense - lint workflows with zizmor by @jaredwray in #116
  • memcache - chore: defense - stage npm releases from CI by @jaredwray in #117
  • memcache - chore: defense - gate staged npm publish on Aikido scan-release by @jaredwray in #118
  • memcache - chore: defense - record repository lockdown by @jaredwray in #119
  • memcache - chore: defense - enable pnpm trustPolicy no-downgrade by @jaredwray in #120
  • feat: add TLS support by @marceloboeira in #115
  • fix: emit memcaches:// from MemcacheNode.uri when TLS is enabled by @jaredwray in #122
  • root - chore: remove writr override by @jaredwray in #123
  • root - chore: upgrade code quality dependencies by @jaredwray in #124
  • root - chore: upgrade TypeScript and build tooling by @jaredwray in #125
  • root - chore: upgrade package manager by @jaredwray in #126
  • root - chore: upgrade tinybench by @jaredwray in #127
  • root - chore: upgrade wrangler by @jaredwray in #128
  • root - chore: upgrade hashery by @jaredwray in #129
  • root - chore: upgrade hookified by @jaredwray in #130
  • root - chore: upgrade Docker memcached service image by @jaredwray in #131

Full diff: https://github.com/jaredwray/memcache/compare/v1.9.0...v1.10.0

v1.9.0 July 08, 2026

memcache@1.9.0 — 2026-07-08

Maintenance release: dependency and CI upgrades. Minimum supported Node is now 22.19.

Internal

  • pin the `memcached` test-service image to `1.6.44` for reproducible test runs (e3d6b4c, #101)
  • upgrade `hashery` runtime dependency to v3 — no API or hash-output changes (109dd19, #100)
  • upgrade `hookified` runtime dependency to 3.0.1 (f598fe9, #99)
  • raise minimum Node to 22.19 (`engines.node` `>=22.19.0`) (8eabc21, #98)
  • upgrade `docula` docs tooling to 2.1.0 (477160a, #97)
  • upgrade all GitHub Actions to their latest majors — `actions/checkout` v7, `pnpm/action-setup` v6 (7ecba81, #96)
  • upgrade TypeScript build tooling — tsx 4.23.0, tsdown 0.22.3, @types/node 24.13.2 (0c789ef, #95)
  • upgrade code quality dependencies — biome 2.5.2, vitest 4.1.10, faker 10.5.0 (b713578, #94)
  • consolidate build and test into a single CI job (d2a2770, #93)

Contributors

  • @jaredwray (9)

Full List of Changes

  • ci: consolidate build and test into a single job by @jaredwray in #93
  • root - chore: upgrade code quality dependencies by @jaredwray in #94
  • root - chore: upgrade TypeScript and build tooling by @jaredwray in #95
  • root - chore: upgrade GitHub Actions (breaking) by @jaredwray in #96
  • root - chore: upgrade docula by @jaredwray in #97
  • root - chore: raise Node engine floor to >=22.19 by @jaredwray in #98
  • root - chore: upgrade hookified by @jaredwray in #99
  • root - chore: upgrade hashery (breaking) by @jaredwray in #100
  • root - chore: pin memcached test-service image by @jaredwray in #101

Full diff: https://github.com/jaredwray/memcache/compare/v1.8.0...v1.9.0

v1.8.0 June 08, 2026

memcache@1.8.0 — 2026-06-08

Maintenance release: dependency, build, and CI upgrades. Minimum supported Node is now 22.

Internal

  • raise minimum Node to 22 and adopt pnpm 11 via corepack; CI matrix now Node 22/24/26 (c3f68e2, #90)
  • upgrade hookified runtime dependency to v3 — no API changes (f660f54, #89)
  • upgrade all GitHub Actions to their latest majors (67d8b27, #88)
  • upgrade docula docs tooling to v2 (f6e881b, #87)
  • upgrade TypeScript build tooling — tsx, tsdown (109cf2d, #86)
  • upgrade code quality dependencies — biome, vitest, tinybench (7644273, #85)

Contributors

  • @jaredwray (6)

Full List of Changes

  • root - chore: upgrade code quality dependencies by @jaredwray in #85
  • root - chore: upgrade TypeScript and build tooling by @jaredwray in #86
  • root - chore: upgrade docula (breaking) by @jaredwray in #87
  • root - chore: upgrade GitHub Actions (breaking) by @jaredwray in #88
  • root - chore: upgrade hookified (breaking) by @jaredwray in #89
  • root - chore: adopt pnpm 11 with corepack by @jaredwray in #90

Full diff: https://github.com/jaredwray/memcache/compare/v1.7.0...v1.8.0

Full Changelog →