memcache 1.4.0 → 1.5.0

package/README.md

@@ -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)
@@ -65,6 +65,7 @@ Nodejs Memcache Client
   - [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)
 
@@ -583,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
@@ -603,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.

package/dist/index.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AutoDiscovery: () => AutoDiscovery,
+  BroadcastHash: () => BroadcastHash,
   Memcache: () => Memcache,
   MemcacheEvents: () => MemcacheEvents,
   MemcacheNode: () => MemcacheNode,
@@ -317,7 +318,7 @@ var MemcacheNode = class extends import_hookified.Hookified {
   _authenticated = false;
   _binaryBuffer = Buffer.alloc(0);
   constructor(host, port, options) {
-    super();
+    super({ throwOnEmptyListeners: false });
     this._host = host;
     this._port = port;
     this._timeout = options?.timeout || 5e3;
@@ -946,7 +947,7 @@ var AutoDiscovery = class _AutoDiscovery extends import_hookified2.Hookified {
   _isRunning = false;
   _isPolling = false;
   constructor(options) {
-    super();
+    super({ throwOnEmptyListeners: false });
     this._configEndpoint = options.configEndpoint;
     this._pollingInterval = options.pollingInterval;
     this._useLegacyCommand = options.useLegacyCommand;
@@ -1160,6 +1161,67 @@ var AutoDiscovery = class _AutoDiscovery extends import_hookified2.Hookified {
   }
 };
 
+// src/broadcast.ts
+var BroadcastHash = class {
+  /** The name of this distribution strategy */
+  name = "broadcast";
+  /** Map of node IDs to MemcacheNode instances */
+  nodeMap;
+  /** Cached array of nodes, rebuilt only on add/remove */
+  nodeCache;
+  constructor() {
+    this.nodeMap = /* @__PURE__ */ new Map();
+    this.nodeCache = [];
+  }
+  /**
+   * Gets all nodes in the distribution.
+   * @returns Array of all MemcacheNode instances
+   */
+  get nodes() {
+    return [...this.nodeCache];
+  }
+  /**
+   * Adds a node to the distribution.
+   * @param node - The MemcacheNode to add
+   */
+  addNode(node) {
+    this.nodeMap.set(node.id, node);
+    this.rebuildCache();
+  }
+  /**
+   * Removes a node from the distribution by its ID.
+   * @param id - The node ID (e.g., "localhost:11211")
+   */
+  removeNode(id) {
+    if (this.nodeMap.delete(id)) {
+      this.rebuildCache();
+    }
+  }
+  /**
+   * Gets a specific node by its ID.
+   * @param id - The node ID (e.g., "localhost:11211")
+   * @returns The MemcacheNode if found, undefined otherwise
+   */
+  getNode(id) {
+    return this.nodeMap.get(id);
+  }
+  /**
+   * Returns all nodes regardless of key. Every operation is broadcast
+   * to every node in the cluster.
+   * @param _key - The cache key (ignored — all nodes are always returned)
+   * @returns Array of all MemcacheNode instances
+   */
+  getNodesByKey(_key) {
+    return [...this.nodeCache];
+  }
+  /**
+   * Rebuilds the cached node array from the map.
+   */
+  rebuildCache() {
+    this.nodeCache = [...this.nodeMap.values()];
+  }
+};
+
 // src/ketama.ts
 var import_node_crypto = require("crypto");
 var hashFunctionForBuiltin = (algorithm) => (value) => (0, import_node_crypto.createHash)(algorithm).update(value).digest().readInt32BE();
@@ -1636,7 +1698,7 @@ var Memcache = class extends import_hookified3.Hookified {
   _autoDiscovery;
   _autoDiscoverOptions;
   constructor(options) {
-    super();
+    super({ throwOnEmptyListeners: false });
     if (typeof options === "string") {
       this._hash = new KetamaHash();
       this._timeout = 5e3;
@@ -2590,6 +2652,7 @@ var index_default = Memcache;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AutoDiscovery,
+  BroadcastHash,
   Memcache,
   MemcacheEvents,
   MemcacheNode,

package/dist/index.d.cts

@@ -476,6 +476,65 @@ declare class AutoDiscovery extends Hookified {
     private parseEndpoint;
 }
 
+/**
+ * A distribution hash implementation that sends every key to all nodes.
+ * Unlike KetamaHash or ModulaHash, this does not partition keys — every
+ * operation targets every node in the cluster.
+ *
+ * This is useful for replication scenarios where all nodes should hold
+ * the same data, or for broadcast operations like flush/delete.
+ *
+ * @example
+ * ```typescript
+ * const client = new Memcache({
+ *   nodes: ['server1:11211', 'server2:11211'],
+ *   hash: new BroadcastHash(),
+ * });
+ * // Every set/get/delete will hit all nodes
+ * ```
+ */
+declare class BroadcastHash implements HashProvider {
+    /** The name of this distribution strategy */
+    readonly name = "broadcast";
+    /** Map of node IDs to MemcacheNode instances */
+    private nodeMap;
+    /** Cached array of nodes, rebuilt only on add/remove */
+    private nodeCache;
+    constructor();
+    /**
+     * Gets all nodes in the distribution.
+     * @returns Array of all MemcacheNode instances
+     */
+    get nodes(): Array<MemcacheNode>;
+    /**
+     * Adds a node to the distribution.
+     * @param node - The MemcacheNode to add
+     */
+    addNode(node: MemcacheNode): void;
+    /**
+     * Removes a node from the distribution by its ID.
+     * @param id - The node ID (e.g., "localhost:11211")
+     */
+    removeNode(id: string): void;
+    /**
+     * Gets a specific node by its ID.
+     * @param id - The node ID (e.g., "localhost:11211")
+     * @returns The MemcacheNode if found, undefined otherwise
+     */
+    getNode(id: string): MemcacheNode | undefined;
+    /**
+     * Returns all nodes regardless of key. Every operation is broadcast
+     * to every node in the cluster.
+     * @param _key - The cache key (ignored — all nodes are always returned)
+     * @returns Array of all MemcacheNode instances
+     */
+    getNodesByKey(_key: string): Array<MemcacheNode>;
+    /**
+     * Rebuilds the cached node array from the map.
+     */
+    private rebuildCache;
+}
+
 /**
  * Function that returns an unsigned 32-bit hash of the input.
  */
@@ -996,4 +1055,4 @@ declare class Memcache extends Hookified {
     private applyClusterConfig;
 }
 
-export { type AutoDiscoverOptions, AutoDiscovery, type ClusterConfig, type DiscoveredNode, type ExecuteOptions, type HashProvider, Memcache, MemcacheEvents, MemcacheNode, type MemcacheOptions, type MemcacheStats, ModulaHash, type RetryBackoffFunction, type SASLCredentials, createNode, Memcache as default, defaultRetryBackoff, exponentialRetryBackoff };
+export { type AutoDiscoverOptions, AutoDiscovery, BroadcastHash, type ClusterConfig, type DiscoveredNode, type ExecuteOptions, type HashProvider, Memcache, MemcacheEvents, MemcacheNode, type MemcacheOptions, type MemcacheStats, ModulaHash, type RetryBackoffFunction, type SASLCredentials, createNode, Memcache as default, defaultRetryBackoff, exponentialRetryBackoff };

package/dist/index.d.ts

@@ -476,6 +476,65 @@ declare class AutoDiscovery extends Hookified {
     private parseEndpoint;
 }
 
+/**
+ * A distribution hash implementation that sends every key to all nodes.
+ * Unlike KetamaHash or ModulaHash, this does not partition keys — every
+ * operation targets every node in the cluster.
+ *
+ * This is useful for replication scenarios where all nodes should hold
+ * the same data, or for broadcast operations like flush/delete.
+ *
+ * @example
+ * ```typescript
+ * const client = new Memcache({
+ *   nodes: ['server1:11211', 'server2:11211'],
+ *   hash: new BroadcastHash(),
+ * });
+ * // Every set/get/delete will hit all nodes
+ * ```
+ */
+declare class BroadcastHash implements HashProvider {
+    /** The name of this distribution strategy */
+    readonly name = "broadcast";
+    /** Map of node IDs to MemcacheNode instances */
+    private nodeMap;
+    /** Cached array of nodes, rebuilt only on add/remove */
+    private nodeCache;
+    constructor();
+    /**
+     * Gets all nodes in the distribution.
+     * @returns Array of all MemcacheNode instances
+     */
+    get nodes(): Array<MemcacheNode>;
+    /**
+     * Adds a node to the distribution.
+     * @param node - The MemcacheNode to add
+     */
+    addNode(node: MemcacheNode): void;
+    /**
+     * Removes a node from the distribution by its ID.
+     * @param id - The node ID (e.g., "localhost:11211")
+     */
+    removeNode(id: string): void;
+    /**
+     * Gets a specific node by its ID.
+     * @param id - The node ID (e.g., "localhost:11211")
+     * @returns The MemcacheNode if found, undefined otherwise
+     */
+    getNode(id: string): MemcacheNode | undefined;
+    /**
+     * Returns all nodes regardless of key. Every operation is broadcast
+     * to every node in the cluster.
+     * @param _key - The cache key (ignored — all nodes are always returned)
+     * @returns Array of all MemcacheNode instances
+     */
+    getNodesByKey(_key: string): Array<MemcacheNode>;
+    /**
+     * Rebuilds the cached node array from the map.
+     */
+    private rebuildCache;
+}
+
 /**
  * Function that returns an unsigned 32-bit hash of the input.
  */
@@ -996,4 +1055,4 @@ declare class Memcache extends Hookified {
     private applyClusterConfig;
 }
 
-export { type AutoDiscoverOptions, AutoDiscovery, type ClusterConfig, type DiscoveredNode, type ExecuteOptions, type HashProvider, Memcache, MemcacheEvents, MemcacheNode, type MemcacheOptions, type MemcacheStats, ModulaHash, type RetryBackoffFunction, type SASLCredentials, createNode, Memcache as default, defaultRetryBackoff, exponentialRetryBackoff };
+export { type AutoDiscoverOptions, AutoDiscovery, BroadcastHash, type ClusterConfig, type DiscoveredNode, type ExecuteOptions, type HashProvider, Memcache, MemcacheEvents, MemcacheNode, type MemcacheOptions, type MemcacheStats, ModulaHash, type RetryBackoffFunction, type SASLCredentials, createNode, Memcache as default, defaultRetryBackoff, exponentialRetryBackoff };

package/dist/index.js

@@ -285,7 +285,7 @@ var MemcacheNode = class extends Hookified {
   _authenticated = false;
   _binaryBuffer = Buffer.alloc(0);
   constructor(host, port, options) {
-    super();
+    super({ throwOnEmptyListeners: false });
     this._host = host;
     this._port = port;
     this._timeout = options?.timeout || 5e3;
@@ -914,7 +914,7 @@ var AutoDiscovery = class _AutoDiscovery extends Hookified2 {
   _isRunning = false;
   _isPolling = false;
   constructor(options) {
-    super();
+    super({ throwOnEmptyListeners: false });
     this._configEndpoint = options.configEndpoint;
     this._pollingInterval = options.pollingInterval;
     this._useLegacyCommand = options.useLegacyCommand;
@@ -1128,6 +1128,67 @@ var AutoDiscovery = class _AutoDiscovery extends Hookified2 {
   }
 };
 
+// src/broadcast.ts
+var BroadcastHash = class {
+  /** The name of this distribution strategy */
+  name = "broadcast";
+  /** Map of node IDs to MemcacheNode instances */
+  nodeMap;
+  /** Cached array of nodes, rebuilt only on add/remove */
+  nodeCache;
+  constructor() {
+    this.nodeMap = /* @__PURE__ */ new Map();
+    this.nodeCache = [];
+  }
+  /**
+   * Gets all nodes in the distribution.
+   * @returns Array of all MemcacheNode instances
+   */
+  get nodes() {
+    return [...this.nodeCache];
+  }
+  /**
+   * Adds a node to the distribution.
+   * @param node - The MemcacheNode to add
+   */
+  addNode(node) {
+    this.nodeMap.set(node.id, node);
+    this.rebuildCache();
+  }
+  /**
+   * Removes a node from the distribution by its ID.
+   * @param id - The node ID (e.g., "localhost:11211")
+   */
+  removeNode(id) {
+    if (this.nodeMap.delete(id)) {
+      this.rebuildCache();
+    }
+  }
+  /**
+   * Gets a specific node by its ID.
+   * @param id - The node ID (e.g., "localhost:11211")
+   * @returns The MemcacheNode if found, undefined otherwise
+   */
+  getNode(id) {
+    return this.nodeMap.get(id);
+  }
+  /**
+   * Returns all nodes regardless of key. Every operation is broadcast
+   * to every node in the cluster.
+   * @param _key - The cache key (ignored — all nodes are always returned)
+   * @returns Array of all MemcacheNode instances
+   */
+  getNodesByKey(_key) {
+    return [...this.nodeCache];
+  }
+  /**
+   * Rebuilds the cached node array from the map.
+   */
+  rebuildCache() {
+    this.nodeCache = [...this.nodeMap.values()];
+  }
+};
+
 // src/ketama.ts
 import { createHash } from "crypto";
 var hashFunctionForBuiltin = (algorithm) => (value) => createHash(algorithm).update(value).digest().readInt32BE();
@@ -1604,7 +1665,7 @@ var Memcache = class extends Hookified3 {
   _autoDiscovery;
   _autoDiscoverOptions;
   constructor(options) {
-    super();
+    super({ throwOnEmptyListeners: false });
     if (typeof options === "string") {
       this._hash = new KetamaHash();
       this._timeout = 5e3;
@@ -2557,6 +2618,7 @@ ${valueStr}`;
 var index_default = Memcache;
 export {
   AutoDiscovery,
+  BroadcastHash,
   Memcache,
   MemcacheEvents,
   MemcacheNode,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memcache",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Nodejs Memcache Client",
   "main": "dist/index.js",
   "type": "module",
@@ -46,24 +46,24 @@
   },
   "homepage": "https://github.com/jaredwray/memcache#readme",
   "devDependencies": {
-    "@biomejs/biome": "^2.3.15",
+    "@biomejs/biome": "^2.4.7",
     "@faker-js/faker": "^10.3.0",
     "@monstermann/tinybench-pretty-printer": "^0.3.0",
     "@types/memcached": "^2.2.10",
     "@types/memjs": "^1.3.3",
-    "@types/node": "^25.2.3",
-    "@vitest/coverage-v8": "^4.0.18",
+    "@types/node": "^25.5.0",
+    "@vitest/coverage-v8": "^4.1.0",
     "memcached": "^2.2.2",
     "memjs": "^1.3.2",
-    "rimraf": "^6.1.2",
+    "rimraf": "^6.1.3",
     "tinybench": "^6.0.0",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.0"
   },
   "dependencies": {
-    "hookified": "^1.15.1"
+    "hookified": "^2.1.0"
   },
   "files": [
     "dist",