memcache 1.3.0 → 1.5.0

package/README.md

@@ -1,4 +1,4 @@
-[<img src="https://jaredwray.com/images/memcache.svg" alt="Memcache Logo" align="center">](https://memcachejs.org)
+[<img src="https://jaredwray.com/images/memcache.svg" width="80%" height="80%" align="center" alt="Memcache Logo" align="center">](https://memcachejs.org)
 
 [![codecov](https://codecov.io/gh/jaredwray/memcache/graph/badge.svg?token=4DUANNWiIE)](https://codecov.io/gh/jaredwray/memcache)
 [![tests](https://github.com/jaredwray/memcache/actions/workflows/tests.yaml/badge.svg)](https://github.com/jaredwray/memcache/actions/workflows/tests.yaml)
@@ -14,7 +14,6 @@ Nodejs Memcache Client
 - [Getting Started](#getting-started)
   - [Installation](#installation)
   - [Basic Usage](#basic-usage)
-  - [Custom Connection](#custom-connection)
 - [API](#api)
   - [Constructor](#constructor)
   - [Properties](#properties)
@@ -47,6 +46,7 @@ Nodejs Memcache Client
 - [Distribution Algorithms](#distribution-algorithms)
   - [KetamaHash (Default)](#ketamahash-default)
   - [ModulaHash](#modulahash)
+  - [BroadcastHash](#broadcasthash)
   - [Choosing an Algorithm](#choosing-an-algorithm)
 - [Retry Configuration](#retry-configuration)
   - [Basic Retry Setup](#basic-retry-setup)
@@ -59,6 +59,13 @@ Nodejs Memcache Client
   - [Per-Node SASL Configuration](#per-node-sasl-configuration)
   - [Authentication Events](#authentication-events)
   - [Server Configuration](#server-configuration)
+- [Auto Discovery](#auto-discovery)
+  - [Enabling Auto Discovery](#enabling-auto-discovery)
+  - [Auto Discovery Options](#auto-discovery-options)
+  - [Auto Discovery Events](#auto-discovery-events)
+  - [Legacy Command Support](#legacy-command-support)
+- [IPv6 Support](#ipv6-support)
+- [Benchmarks](#benchmarks)
 - [Contributing](#contributing)
 - [License and Copyright](#license-and-copyright)
 
@@ -198,6 +205,7 @@ const client = new Memcache({
 - `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)
+- `autoDiscover?: AutoDiscoverOptions` - AWS ElastiCache Auto Discovery configuration (see [Auto Discovery](#auto-discovery))
 
 ## Properties
 
@@ -404,6 +412,9 @@ client.on('miss', (key) => {
 - `quit` - Emitted when quit command is sent
 - `warn` - Emitted for warning messages
 - `info` - Emitted for informational messages
+- `autoDiscover` - Emitted on initial auto discovery with the cluster config
+- `autoDiscoverUpdate` - Emitted when auto discovery detects a topology change
+- `autoDiscoverError` - Emitted when auto discovery encounters an error
 
 ## Hooks
 
@@ -573,15 +584,39 @@ const client = new Memcache({
 // 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.
+
+```javascript
+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:**
+- Every operation targets all nodes
+- No key partitioning — all nodes hold the same data
+- Reads return the first successful result from any node
+- Writes succeed only if all nodes succeed
+- Best for replication, broadcast invalidation, or small clusters where all nodes should be in sync
+
 ## Choosing an Algorithm
 
-| Feature | KetamaHash | ModulaHash |
-|---------|------------|------------|
-| Key redistribution on node change | Minimal (~1/n keys) | All keys may move |
-| Complexity | Higher (virtual nodes) | Lower (simple modulo) |
-| Performance | Slightly slower | Faster |
-| Best for | Dynamic scaling | Fixed clusters |
-| Weighted nodes | Yes | Yes |
+| 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:**
 - Your cluster size may change dynamically
@@ -593,6 +628,11 @@ const client = new Memcache({
 - You prefer simplicity over minimal redistribution
 - You're in a testing or development environment
 
+**Use BroadcastHash when:**
+- You want all nodes to hold the same data
+- You need broadcast cache invalidation across all nodes
+- You're running a small cluster where replication is more important than partitioning
+
 # Retry Configuration
 
 The Memcache client supports automatic retry of failed commands with configurable backoff strategies.
@@ -877,6 +917,158 @@ To use SASL authentication, your memcached server must be configured with SASL s
 
 For more details, see the [memcached SASL documentation](https://github.com/memcached/memcached/wiki/SASLHowto).
 
+# 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
+
+```javascript
+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:
+
+```javascript
+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:
+
+- `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 used
+- `useLegacyCommand?: boolean` - Use the legacy `get AmazonElastiCache:cluster` command instead of `config get cluster` (default: false)
+
+## Auto Discovery Events
+
+The client emits events during the auto discovery lifecycle:
+
+```javascript
+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:
+
+```javascript
+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
+
+```javascript
+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:
+
+```javascript
+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:
+
+```javascript
+const client = new Memcache({
+  nodes: ['[::1]:11211', '[2001:db8::1]:11212'],
+});
+
+console.log(client.nodeIds);
+// ['[::1]:11211', '[2001:db8::1]:11212']
+```
+
+# 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](./CONTRIBUTING.md) and also our [Code of Conduct](./CODE_OF_CONDUCT.md).