memcache 0.2.0 → 1.0.0

package/dist/index.js

@@ -0,0 +1,1475 @@
+// src/index.ts
+import { Hookified as Hookified2 } from "hookified";
+
+// src/ketama.ts
+import { createHash } from "crypto";
+var hashFunctionForBuiltin = (algorithm) => (value) => createHash(algorithm).update(value).digest().readInt32BE();
+var keyFor = (node) => typeof node === "string" ? node : node.key;
+var HashRing = class _HashRing {
+  /**
+   * Base weight of each node in the hash ring. Having a base weight of 1 is
+   * not very desirable, since then, due to the ketama-style "clock", it's
+   * possible to end up with a clock that's very skewed when dealing with a
+   * small number of nodes. Setting to 50 nodes seems to give a better
+   * distribution, so that load is spread roughly evenly to +/- 5%.
+   */
+  static baseWeight = 50;
+  /** The hash function used to compute node positions on the ring */
+  hashFn;
+  /** The sorted array of [hash, node key] tuples representing virtual nodes on the ring */
+  _clock = [];
+  /** Map of node keys to actual node objects */
+  _nodes = /* @__PURE__ */ new Map();
+  /**
+   * Gets the sorted array of [hash, node key] tuples representing virtual nodes on the ring.
+   * @returns The hash clock array
+   */
+  get clock() {
+    return this._clock;
+  }
+  /**
+   * Gets the map of node keys to actual node objects.
+   * @returns The nodes map
+   */
+  get nodes() {
+    return this._nodes;
+  }
+  /**
+   * Creates a new HashRing instance.
+   *
+   * @param initialNodes - Array of nodes to add to the ring, optionally with weights
+   * @param hashFn - Hash function to use (string algorithm name or custom function, defaults to "sha1")
+   *
+   * @example
+   * ```typescript
+   * // Simple ring with default SHA-1 hashing
+   * const ring = new HashRing(['node1', 'node2']);
+   *
+   * // Ring with custom hash function
+   * const customRing = new HashRing(['node1', 'node2'], 'md5');
+   *
+   * // Ring with weighted nodes
+   * const weightedRing = new HashRing([
+   *   { node: 'heavy-server', weight: 3 },
+   *   { node: 'light-server', weight: 1 }
+   * ]);
+   * ```
+   */
+  constructor(initialNodes = [], hashFn = "sha1") {
+    this.hashFn = typeof hashFn === "string" ? hashFunctionForBuiltin(hashFn) : hashFn;
+    for (const node of initialNodes) {
+      if (typeof node === "object" && "weight" in node && "node" in node) {
+        this.addNode(node.node, node.weight);
+      } else {
+        this.addNode(node);
+      }
+    }
+  }
+  /**
+   * Add a new node to the ring. If the node already exists in the ring, it
+   * will be updated. For example, you can use this to update the node's weight.
+   *
+   * @param node - The node to add to the ring
+   * @param weight - The relative weight of this node (default: 1). Higher weights mean more keys will be assigned to this node. A weight of 0 removes the node.
+   * @throws {RangeError} If weight is negative
+   *
+   * @example
+   * ```typescript
+   * const ring = new HashRing();
+   * ring.addNode('server1'); // Add with default weight of 1
+   * ring.addNode('server2', 2); // Add with weight of 2 (will handle ~2x more keys)
+   * ring.addNode('server1', 3); // Update server1's weight to 3
+   * ring.addNode('server2', 0); // Remove server2
+   * ```
+   */
+  addNode(node, weight = 1) {
+    if (weight === 0) {
+      this.removeNode(node);
+    } else if (weight < 0) {
+      throw new RangeError("Cannot add a node to the hashring with weight < 0");
+    } else {
+      this.removeNode(node);
+      const key = keyFor(node);
+      this._nodes.set(key, node);
+      this.addNodeToClock(key, Math.round(weight * _HashRing.baseWeight));
+    }
+  }
+  /**
+   * Removes the node from the ring. No-op if the node does not exist.
+   *
+   * @param node - The node to remove from the ring
+   *
+   * @example
+   * ```typescript
+   * const ring = new HashRing(['server1', 'server2']);
+   * ring.removeNode('server1'); // Removes server1 from the ring
+   * ring.removeNode('nonexistent'); // Safe to call with non-existent node
+   * ```
+   */
+  removeNode(node) {
+    const key = keyFor(node);
+    if (this._nodes.delete(key)) {
+      this._clock = this._clock.filter(([, n]) => n !== key);
+    }
+  }
+  /**
+   * Gets the node which should handle the given input key. Returns undefined if
+   * the hashring has no nodes.
+   *
+   * Uses consistent hashing to ensure the same input always maps to the same node,
+   * and minimizes redistribution when nodes are added or removed.
+   *
+   * @param input - The key to find the responsible node for (string or Buffer)
+   * @returns The node responsible for this key, or undefined if ring is empty
+   *
+   * @example
+   * ```typescript
+   * const ring = new HashRing(['server1', 'server2', 'server3']);
+   * const node = ring.getNode('user:123'); // Returns e.g., 'server2'
+   * const sameNode = ring.getNode('user:123'); // Always returns 'server2'
+   *
+   * // Also accepts Buffer input
+   * const bufferNode = ring.getNode(Buffer.from('user:123'));
+   * ```
+   */
+  getNode(input) {
+    if (this._clock.length === 0) {
+      return void 0;
+    }
+    const index = this.getIndexForInput(input);
+    const key = index === this._clock.length ? this._clock[0][1] : this._clock[index][1];
+    return this._nodes.get(key);
+  }
+  /**
+   * Finds the index in the clock for the given input by hashing it and performing binary search.
+   *
+   * @param input - The input to find the clock position for
+   * @returns The index in the clock array
+   */
+  getIndexForInput(input) {
+    const hash = this.hashFn(
+      typeof input === "string" ? Buffer.from(input) : input
+    );
+    return binarySearchRing(this._clock, hash);
+  }
+  /**
+   * Gets multiple replica nodes that should handle the given input. Useful for
+   * implementing replication strategies where you want to store data on multiple nodes.
+   *
+   * The returned array will contain unique nodes in the order they appear on the ring
+   * starting from the primary node. If there are fewer nodes than replicas requested,
+   * all nodes are returned.
+   *
+   * @param input - The key to find replica nodes for (string or Buffer)
+   * @param replicas - The number of replica nodes to return
+   * @returns Array of nodes that should handle this key (length ≤ replicas)
+   *
+   * @example
+   * ```typescript
+   * const ring = new HashRing(['server1', 'server2', 'server3', 'server4']);
+   *
+   * // Get 3 replicas for a key
+   * const replicas = ring.getNodes('user:123', 3);
+   * // Returns e.g., ['server2', 'server4', 'server1']
+   *
+   * // If requesting more replicas than nodes, returns all nodes
+   * const allNodes = ring.getNodes('user:123', 10);
+   * // Returns ['server1', 'server2', 'server3', 'server4']
+   * ```
+   */
+  getNodes(input, replicas) {
+    if (this._clock.length === 0) {
+      return [];
+    }
+    if (replicas >= this._nodes.size) {
+      return [...this._nodes.values()];
+    }
+    const chosen = /* @__PURE__ */ new Set();
+    for (let i = this.getIndexForInput(input); chosen.size < replicas; i++) {
+      chosen.add(this._clock[i % this._clock.length][1]);
+    }
+    return [...chosen].map((c) => this._nodes.get(c));
+  }
+  /**
+   * Adds virtual nodes to the clock for the given node key.
+   * Creates multiple positions on the ring for better distribution.
+   *
+   * @param key - The node key to add to the clock
+   * @param weight - The number of virtual nodes to create (weight * baseWeight)
+   */
+  addNodeToClock(key, weight) {
+    for (let i = weight; i > 0; i--) {
+      const hash = this.hashFn(Buffer.from(`${key}\0${i}`));
+      this._clock.push([hash, key]);
+    }
+    this._clock.sort((a, b) => a[0] - b[0]);
+  }
+};
+var KetamaHash = class {
+  /** The name of this distribution strategy */
+  name = "ketama";
+  /** Internal hash ring for consistent hashing */
+  hashRing;
+  /** Map of node IDs to MemcacheNode instances */
+  nodeMap;
+  /**
+   * Creates a new KetamaDistributionHash instance.
+   *
+   * @param hashFn - Hash function to use (string algorithm name or custom function, defaults to "sha1")
+   *
+   * @example
+   * ```typescript
+   * // Use default SHA-1 hashing
+   * const distribution = new KetamaDistributionHash();
+   *
+   * // Use MD5 hashing
+   * const distribution = new KetamaDistributionHash('md5');
+   * ```
+   */
+  constructor(hashFn) {
+    this.hashRing = new HashRing([], hashFn);
+    this.nodeMap = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Gets all nodes in the distribution.
+   * @returns Array of all MemcacheNode instances
+   */
+  get nodes() {
+    return Array.from(this.nodeMap.values());
+  }
+  /**
+   * Adds a node to the distribution with its weight for consistent hashing.
+   *
+   * @param node - The MemcacheNode to add
+   *
+   * @example
+   * ```typescript
+   * const node = new MemcacheNode('localhost', 11211, { weight: 2 });
+   * distribution.addNode(node);
+   * ```
+   */
+  addNode(node) {
+    this.nodeMap.set(node.id, node);
+    this.hashRing.addNode(node.id, node.weight);
+  }
+  /**
+   * Removes a node from the distribution by its ID.
+   *
+   * @param id - The node ID (e.g., "localhost:11211")
+   *
+   * @example
+   * ```typescript
+   * distribution.removeNode('localhost:11211');
+   * ```
+   */
+  removeNode(id) {
+    this.nodeMap.delete(id);
+    this.hashRing.removeNode(id);
+  }
+  /**
+   * Gets a specific node by its ID.
+   *
+   * @param id - The node ID (e.g., "localhost:11211")
+   * @returns The MemcacheNode if found, undefined otherwise
+   *
+   * @example
+   * ```typescript
+   * const node = distribution.getNode('localhost:11211');
+   * if (node) {
+   *   console.log(`Found node: ${node.uri}`);
+   * }
+   * ```
+   */
+  getNode(id) {
+    return this.nodeMap.get(id);
+  }
+  /**
+   * Gets the nodes responsible for a given key using consistent hashing.
+   * Currently returns a single node (the primary node for the key).
+   *
+   * @param key - The cache key to find the responsible node for
+   * @returns Array containing the responsible node(s), empty if no nodes available
+   *
+   * @example
+   * ```typescript
+   * const nodes = distribution.getNodesByKey('user:123');
+   * if (nodes.length > 0) {
+   *   console.log(`Key will be stored on: ${nodes[0].id}`);
+   * }
+   * ```
+   */
+  getNodesByKey(key) {
+    const nodeId = this.hashRing.getNode(key);
+    if (!nodeId) {
+      return [];
+    }
+    const node = this.nodeMap.get(nodeId);
+    return node ? [node] : [];
+  }
+};
+function binarySearchRing(ring, hash) {
+  let mid;
+  let lo = 0;
+  let hi = ring.length - 1;
+  while (lo <= hi) {
+    mid = Math.floor((lo + hi) / 2);
+    if (ring[mid][0] >= hash) {
+      hi = mid - 1;
+    } else {
+      lo = mid + 1;
+    }
+  }
+  return lo;
+}
+
+// src/node.ts
+import { createConnection } from "net";
+import { Hookified } from "hookified";
+var MemcacheNode = class extends Hookified {
+  _host;
+  _port;
+  _socket = void 0;
+  _timeout;
+  _keepAlive;
+  _keepAliveDelay;
+  _weight;
+  _connected = false;
+  _commandQueue = [];
+  _buffer = "";
+  _currentCommand = void 0;
+  _multilineData = [];
+  _pendingValueBytes = 0;
+  constructor(host, port, options) {
+    super();
+    this._host = host;
+    this._port = port;
+    this._timeout = options?.timeout || 5e3;
+    this._keepAlive = options?.keepAlive !== false;
+    this._keepAliveDelay = options?.keepAliveDelay || 1e3;
+    this._weight = options?.weight || 1;
+  }
+  /**
+   * Get the host of this node
+   */
+  get host() {
+    return this._host;
+  }
+  /**
+   * Get the port of this node
+   */
+  get port() {
+    return this._port;
+  }
+  /**
+   * Get the unique identifier for this node (host:port format)
+   */
+  get id() {
+    return this._port === 0 ? this._host : `${this._host}:${this._port}`;
+  }
+  /**
+   * Get the full uri like memcache://localhost:11211
+   */
+  get uri() {
+    return `memcache://${this.id}`;
+  }
+  /**
+   * Get the socket connection
+   */
+  get socket() {
+    return this._socket;
+  }
+  /**
+   * Get the weight of this node (used for consistent hashing distribution)
+   */
+  get weight() {
+    return this._weight;
+  }
+  /**
+   * Set the weight of this node (used for consistent hashing distribution)
+   */
+  set weight(value) {
+    this._weight = value;
+  }
+  /**
+   * Get the keepAlive setting for this node
+   */
+  get keepAlive() {
+    return this._keepAlive;
+  }
+  /**
+   * Set the keepAlive setting for this node
+   */
+  set keepAlive(value) {
+    this._keepAlive = value;
+  }
+  /**
+   * Get the keepAliveDelay setting for this node
+   */
+  get keepAliveDelay() {
+    return this._keepAliveDelay;
+  }
+  /**
+   * Set the keepAliveDelay setting for this node
+   */
+  set keepAliveDelay(value) {
+    this._keepAliveDelay = value;
+  }
+  /**
+   * Get the command queue
+   */
+  get commandQueue() {
+    return this._commandQueue;
+  }
+  /**
+   * Connect to the memcache server
+   */
+  async connect() {
+    return new Promise((resolve, reject) => {
+      if (this._connected) {
+        resolve();
+        return;
+      }
+      this._socket = createConnection({
+        host: this._host,
+        port: this._port,
+        keepAlive: this._keepAlive,
+        keepAliveInitialDelay: this._keepAliveDelay
+      });
+      this._socket.setTimeout(this._timeout);
+      this._socket.setEncoding("utf8");
+      this._socket.on("connect", () => {
+        this._connected = true;
+        this.emit("connect");
+        resolve();
+      });
+      this._socket.on("data", (data) => {
+        this.handleData(data);
+      });
+      this._socket.on("error", (error) => {
+        this.emit("error", error);
+        if (!this._connected) {
+          reject(error);
+        }
+      });
+      this._socket.on("close", () => {
+        this._connected = false;
+        this.emit("close");
+        this.rejectPendingCommands(new Error("Connection closed"));
+      });
+      this._socket.on("timeout", () => {
+        this.emit("timeout");
+        this._socket?.destroy();
+        reject(new Error("Connection timeout"));
+      });
+    });
+  }
+  /**
+   * Disconnect from the memcache server
+   */
+  async disconnect() {
+    if (this._socket) {
+      this._socket.destroy();
+      this._socket = void 0;
+      this._connected = false;
+    }
+  }
+  /**
+   * Reconnect to the memcache server by disconnecting and connecting again
+   */
+  async reconnect() {
+    if (this._connected || this._socket) {
+      await this.disconnect();
+      this.rejectPendingCommands(
+        new Error("Connection reset for reconnection")
+      );
+      this._buffer = "";
+      this._currentCommand = void 0;
+      this._multilineData = [];
+      this._pendingValueBytes = 0;
+    }
+    await this.connect();
+  }
+  /**
+   * Gracefully quit the connection (send quit command then disconnect)
+   */
+  async quit() {
+    if (this._connected && this._socket) {
+      try {
+        await this.command("quit");
+      } catch (error) {
+      }
+      await this.disconnect();
+    }
+  }
+  /**
+   * Check if connected to the memcache server
+   */
+  isConnected() {
+    return this._connected;
+  }
+  /**
+   * Send a generic command to the memcache server
+   * @param cmd The command string to send (without trailing \r\n)
+   * @param options Command options for response parsing
+   */
+  async command(cmd, options) {
+    if (!this._connected || !this._socket) {
+      throw new Error(`Not connected to memcache server ${this.id}`);
+    }
+    return new Promise((resolve, reject) => {
+      this._commandQueue.push({
+        command: cmd,
+        resolve,
+        reject,
+        isMultiline: options?.isMultiline,
+        isStats: options?.isStats,
+        requestedKeys: options?.requestedKeys
+      });
+      this._socket.write(`${cmd}\r
+`);
+    });
+  }
+  handleData(data) {
+    this._buffer += data;
+    while (true) {
+      if (this._pendingValueBytes > 0) {
+        if (this._buffer.length >= this._pendingValueBytes + 2) {
+          const value = this._buffer.substring(0, this._pendingValueBytes);
+          this._buffer = this._buffer.substring(this._pendingValueBytes + 2);
+          this._multilineData.push(value);
+          this._pendingValueBytes = 0;
+        } else {
+          break;
+        }
+      }
+      const lineEnd = this._buffer.indexOf("\r\n");
+      if (lineEnd === -1) break;
+      const line = this._buffer.substring(0, lineEnd);
+      this._buffer = this._buffer.substring(lineEnd + 2);
+      this.processLine(line);
+    }
+  }
+  processLine(line) {
+    if (!this._currentCommand) {
+      this._currentCommand = this._commandQueue.shift();
+      if (!this._currentCommand) return;
+    }
+    if (this._currentCommand.isStats) {
+      if (line === "END") {
+        const stats = {};
+        for (const statLine of this._multilineData) {
+          const [, key, value] = statLine.split(" ");
+          if (key && value) {
+            stats[key] = value;
+          }
+        }
+        this._currentCommand.resolve(stats);
+        this._multilineData = [];
+        this._currentCommand = void 0;
+        return;
+      }
+      if (line.startsWith("STAT ")) {
+        this._multilineData.push(line);
+        return;
+      }
+      if (line.startsWith("ERROR") || line.startsWith("CLIENT_ERROR") || line.startsWith("SERVER_ERROR")) {
+        this._currentCommand.reject(new Error(line));
+        this._currentCommand = void 0;
+        return;
+      }
+      return;
+    }
+    if (this._currentCommand.isMultiline) {
+      if (this._currentCommand.requestedKeys && !this._currentCommand.foundKeys) {
+        this._currentCommand.foundKeys = [];
+      }
+      if (line.startsWith("VALUE ")) {
+        const parts = line.split(" ");
+        const key = parts[1];
+        const bytes = parseInt(parts[3], 10);
+        if (this._currentCommand.requestedKeys) {
+          this._currentCommand.foundKeys?.push(key);
+        }
+        this._pendingValueBytes = bytes;
+      } else if (line === "END") {
+        let result;
+        if (this._currentCommand.requestedKeys && this._currentCommand.foundKeys) {
+          result = {
+            values: this._multilineData.length > 0 ? this._multilineData : void 0,
+            foundKeys: this._currentCommand.foundKeys
+          };
+        } else {
+          result = this._multilineData.length > 0 ? this._multilineData : void 0;
+        }
+        if (this._currentCommand.requestedKeys && this._currentCommand.foundKeys) {
+          const foundKeys = this._currentCommand.foundKeys;
+          for (let i = 0; i < foundKeys.length; i++) {
+            this.emit("hit", foundKeys[i], this._multilineData[i]);
+          }
+          const missedKeys = this._currentCommand.requestedKeys.filter(
+            (key) => !foundKeys.includes(key)
+          );
+          for (const key of missedKeys) {
+            this.emit("miss", key);
+          }
+        }
+        this._currentCommand.resolve(result);
+        this._multilineData = [];
+        this._currentCommand = void 0;
+      } else if (line.startsWith("ERROR") || line.startsWith("CLIENT_ERROR") || line.startsWith("SERVER_ERROR")) {
+        this._currentCommand.reject(new Error(line));
+        this._multilineData = [];
+        this._currentCommand = void 0;
+      }
+    } else {
+      if (line === "STORED" || line === "DELETED" || line === "OK" || line === "TOUCHED" || line === "EXISTS" || line === "NOT_FOUND") {
+        this._currentCommand.resolve(line);
+      } else if (line === "NOT_STORED") {
+        this._currentCommand.resolve(false);
+      } else if (line.startsWith("ERROR") || line.startsWith("CLIENT_ERROR") || line.startsWith("SERVER_ERROR")) {
+        this._currentCommand.reject(new Error(line));
+      } else if (/^\d+$/.test(line)) {
+        this._currentCommand.resolve(parseInt(line, 10));
+      } else {
+        this._currentCommand.resolve(line);
+      }
+      this._currentCommand = void 0;
+    }
+  }
+  rejectPendingCommands(error) {
+    if (this._currentCommand) {
+      this._currentCommand.reject(error);
+      this._currentCommand = void 0;
+    }
+    while (this._commandQueue.length > 0) {
+      const cmd = this._commandQueue.shift();
+      if (cmd) {
+        cmd.reject(error);
+      }
+    }
+  }
+};
+function createNode(host, port, options) {
+  return new MemcacheNode(host, port, options);
+}
+
+// src/index.ts
+var MemcacheEvents = /* @__PURE__ */ ((MemcacheEvents2) => {
+  MemcacheEvents2["CONNECT"] = "connect";
+  MemcacheEvents2["QUIT"] = "quit";
+  MemcacheEvents2["HIT"] = "hit";
+  MemcacheEvents2["MISS"] = "miss";
+  MemcacheEvents2["ERROR"] = "error";
+  MemcacheEvents2["WARN"] = "warn";
+  MemcacheEvents2["INFO"] = "info";
+  MemcacheEvents2["TIMEOUT"] = "timeout";
+  MemcacheEvents2["CLOSE"] = "close";
+  return MemcacheEvents2;
+})(MemcacheEvents || {});
+var Memcache = class extends Hookified2 {
+  _nodes = [];
+  _timeout;
+  _keepAlive;
+  _keepAliveDelay;
+  _hash;
+  constructor(options) {
+    super();
+    this._hash = new KetamaHash();
+    this._timeout = options?.timeout || 5e3;
+    this._keepAlive = options?.keepAlive !== false;
+    this._keepAliveDelay = options?.keepAliveDelay || 1e3;
+    const nodeUris = options?.nodes || ["localhost:11211"];
+    for (const nodeUri of nodeUris) {
+      this.addNode(nodeUri);
+    }
+  }
+  /**
+   * Get the list of nodes
+   * @returns {MemcacheNode[]} Array of MemcacheNode
+   */
+  get nodes() {
+    return this._nodes;
+  }
+  /**
+   * Get the list of node IDs (e.g., ["localhost:11211", "127.0.0.1:11212"])
+   * @returns {string[]} Array of node ID strings
+   */
+  get nodeIds() {
+    return this._nodes.map((node) => node.id);
+  }
+  /**
+   * Get the hash provider used for consistent hashing distribution.
+   * @returns {HashProvider} The current hash provider instance
+   * @default KetamaHash
+   *
+   * @example
+   * ```typescript
+   * const client = new Memcache();
+   * const hashProvider = client.hash;
+   * console.log(hashProvider.name); // "ketama"
+   * ```
+   */
+  get hash() {
+    return this._hash;
+  }
+  /**
+   * Set the hash provider used for consistent hashing distribution.
+   * This allows you to customize the hashing strategy for distributing keys across nodes.
+   * @param {HashProvider} hash - The hash provider instance to use
+   *
+   * @example
+   * ```typescript
+   * const client = new Memcache();
+   * const customHashProvider = new KetamaHash();
+   * client.hash = customHashProvider;
+   * ```
+   */
+  set hash(hash) {
+    this._hash = hash;
+  }
+  /**
+   * Get the timeout for Memcache operations.
+   * @returns {number}
+   * @default 5000
+   */
+  get timeout() {
+    return this._timeout;
+  }
+  /**
+   * Set the timeout for Memcache operations.
+   * @param {number} value
+   * @default 5000
+   */
+  set timeout(value) {
+    this._timeout = value;
+  }
+  /**
+   * Get the keepAlive setting for the Memcache connection.
+   * @returns {boolean}
+   * @default true
+   */
+  get keepAlive() {
+    return this._keepAlive;
+  }
+  /**
+   * Set the keepAlive setting for the Memcache connection.
+   * Updates all existing nodes with the new value.
+   * Note: To apply the new value, you need to call reconnect() on the nodes.
+   * @param {boolean} value
+   * @default true
+   */
+  set keepAlive(value) {
+    this._keepAlive = value;
+    this.updateNodes();
+  }
+  /**
+   * Get the delay before the connection is kept alive.
+   * @returns {number}
+   * @default 1000
+   */
+  get keepAliveDelay() {
+    return this._keepAliveDelay;
+  }
+  /**
+   * Set the delay before the connection is kept alive.
+   * Updates all existing nodes with the new value.
+   * Note: To apply the new value, you need to call reconnect() on the nodes.
+   * @param {number} value
+   * @default 1000
+   */
+  set keepAliveDelay(value) {
+    this._keepAliveDelay = value;
+    this.updateNodes();
+  }
+  /**
+   * Get an array of all MemcacheNode instances
+   * @returns {MemcacheNode[]}
+   */
+  getNodes() {
+    return [...this._nodes];
+  }
+  /**
+   * Get a specific node by its ID
+   * @param {string} id - The node ID (e.g., "localhost:11211")
+   * @returns {MemcacheNode | undefined}
+   */
+  getNode(id) {
+    return this._nodes.find((n) => n.id === id);
+  }
+  /**
+   * Add a new node to the cluster
+   * @param {string | MemcacheNode} uri - Node URI (e.g., "localhost:11212") or a MemcacheNode instance
+   * @param {number} weight - Optional weight for consistent hashing (only used for string URIs)
+   */
+  async addNode(uri, weight) {
+    let node;
+    let nodeKey;
+    if (typeof uri === "string") {
+      const { host, port } = this.parseUri(uri);
+      nodeKey = port === 0 ? host : `${host}:${port}`;
+      if (this._nodes.some((n) => n.id === nodeKey)) {
+        throw new Error(`Node ${nodeKey} already exists`);
+      }
+      node = new MemcacheNode(host, port, {
+        timeout: this._timeout,
+        keepAlive: this._keepAlive,
+        keepAliveDelay: this._keepAliveDelay,
+        weight
+      });
+    } else {
+      node = uri;
+      nodeKey = node.id;
+      if (this._nodes.some((n) => n.id === nodeKey)) {
+        throw new Error(`Node ${nodeKey} already exists`);
+      }
+    }
+    this.forwardNodeEvents(node);
+    this._nodes.push(node);
+    this._hash.addNode(node);
+  }
+  /**
+   * Remove a node from the cluster
+   * @param {string} uri - Node URI (e.g., "localhost:11212")
+   */
+  async removeNode(uri) {
+    const { host, port } = this.parseUri(uri);
+    const nodeKey = port === 0 ? host : `${host}:${port}`;
+    const node = this._nodes.find((n) => n.id === nodeKey);
+    if (!node) return;
+    await node.disconnect();
+    this._nodes = this._nodes.filter((n) => n.id !== nodeKey);
+    this._hash.removeNode(node.id);
+  }
+  /**
+   * Parse a URI string into host and port.
+   * Supports multiple formats:
+   * - Simple: "localhost:11211" or "localhost"
+   * - Protocol: "memcache://localhost:11211", "memcached://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"
+   *
+   * @param {string} uri - URI string
+   * @returns {{ host: string; port: number }} Object containing host and port (port is 0 for Unix sockets)
+   * @throws {Error} If URI format is invalid
+   */
+  parseUri(uri) {
+    if (uri.startsWith("unix://")) {
+      return { host: uri.slice(7), port: 0 };
+    }
+    if (uri.startsWith("/")) {
+      return { host: uri, port: 0 };
+    }
+    let cleanUri = uri;
+    if (uri.includes("://")) {
+      const protocolParts = uri.split("://");
+      const protocol = protocolParts[0];
+      if (!["memcache", "memcached", "tcp"].includes(protocol)) {
+        throw new Error(
+          `Invalid protocol '${protocol}'. Supported protocols: memcache://, memcached://, tcp://, unix://`
+        );
+      }
+      cleanUri = protocolParts[1];
+    }
+    if (cleanUri.startsWith("[")) {
+      const bracketEnd = cleanUri.indexOf("]");
+      if (bracketEnd === -1) {
+        throw new Error("Invalid IPv6 format: missing closing bracket");
+      }
+      const host2 = cleanUri.slice(1, bracketEnd);
+      if (!host2) {
+        throw new Error("Invalid URI format: host is required");
+      }
+      const remainder = cleanUri.slice(bracketEnd + 1);
+      if (remainder === "") {
+        return { host: host2, port: 11211 };
+      }
+      if (!remainder.startsWith(":")) {
+        throw new Error("Invalid IPv6 format: expected ':' after bracket");
+      }
+      const portStr = remainder.slice(1);
+      const port2 = Number.parseInt(portStr, 10);
+      if (Number.isNaN(port2) || port2 <= 0 || port2 > 65535) {
+        throw new Error("Invalid port number");
+      }
+      return { host: host2, port: port2 };
+    }
+    const parts = cleanUri.split(":");
+    if (parts.length === 0 || parts.length > 2) {
+      throw new Error("Invalid URI format");
+    }
+    const host = parts[0];
+    if (!host) {
+      throw new Error("Invalid URI format: host is required");
+    }
+    const port = parts.length === 2 ? Number.parseInt(parts[1], 10) : 11211;
+    if (Number.isNaN(port) || port < 0 || port > 65535) {
+      throw new Error("Invalid port number");
+    }
+    if (port === 0) {
+      throw new Error("Invalid port number");
+    }
+    return { host, port };
+  }
+  /**
+   * Connect to all Memcache servers or a specific node.
+   * @param {string} nodeId - Optional node ID to connect to (e.g., "localhost:11211")
+   * @returns {Promise<void>}
+   */
+  async connect(nodeId) {
+    if (nodeId) {
+      const node = this._nodes.find((n) => n.id === nodeId);
+      if (!node) throw new Error(`Node ${nodeId} not found`);
+      await node.connect();
+      return;
+    }
+    await Promise.all(this._nodes.map((node) => node.connect()));
+  }
+  /**
+   * Get a value from the Memcache server.
+   * When multiple nodes are returned by the hash provider (for replication),
+   * queries all nodes and returns the first successful result.
+   * @param {string} key
+   * @returns {Promise<string | undefined>}
+   */
+  async get(key) {
+    await this.beforeHook("get", { key });
+    this.validateKey(key);
+    const nodes = await this.getNodesByKey(key);
+    const promises = nodes.map(async (node) => {
+      try {
+        const result = await node.command(`get ${key}`, {
+          isMultiline: true,
+          requestedKeys: [key]
+        });
+        if (result?.values && result.values.length > 0) {
+          return result.values[0];
+        }
+        return void 0;
+      } catch {
+        return void 0;
+      }
+    });
+    const results = await Promise.all(promises);
+    const value = results.find((v) => v !== void 0);
+    await this.afterHook("get", { key, value });
+    return value;
+  }
+  /**
+   * Get multiple values from the Memcache server.
+   * When multiple nodes are returned by the hash provider (for replication),
+   * queries all replica nodes and returns the first successful result for each key.
+   * @param keys {string[]}
+   * @returns {Promise<Map<string, string>>}
+   */
+  async gets(keys) {
+    await this.beforeHook("gets", { keys });
+    for (const key of keys) {
+      this.validateKey(key);
+    }
+    const keysByNode = /* @__PURE__ */ new Map();
+    for (const key of keys) {
+      const nodes = this._hash.getNodesByKey(key);
+      if (nodes.length === 0) {
+        throw new Error(`No node available for key: ${key}`);
+      }
+      for (const node of nodes) {
+        if (!keysByNode.has(node)) {
+          keysByNode.set(node, []);
+        }
+        keysByNode.get(node).push(key);
+      }
+    }
+    const promises = Array.from(keysByNode.entries()).map(
+      async ([node, nodeKeys]) => {
+        try {
+          if (!node.isConnected()) await node.connect();
+          const keysStr = nodeKeys.join(" ");
+          const result = await node.command(`get ${keysStr}`, {
+            isMultiline: true,
+            requestedKeys: nodeKeys
+          });
+          return result;
+        } catch {
+          return void 0;
+        }
+      }
+    );
+    const results = await Promise.all(promises);
+    const map = /* @__PURE__ */ new Map();
+    for (const result of results) {
+      if (result?.foundKeys && result.values) {
+        for (let i = 0; i < result.foundKeys.length; i++) {
+          if (result.values[i] !== void 0) {
+            if (!map.has(result.foundKeys[i])) {
+              map.set(result.foundKeys[i], result.values[i]);
+            }
+          }
+        }
+      }
+    }
+    await this.afterHook("gets", { keys, values: map });
+    return map;
+  }
+  /**
+   * Check-And-Set: Store a value only if it hasn't been modified since last fetch.
+   * When multiple nodes are returned by the hash provider (for replication),
+   * executes on all nodes and returns true only if all succeed.
+   * @param key {string}
+   * @param value {string}
+   * @param casToken {string}
+   * @param exptime {number}
+   * @param flags {number}
+   * @returns {Promise<boolean>}
+   */
+  async cas(key, value, casToken, exptime = 0, flags = 0) {
+    await this.beforeHook("cas", { key, value, casToken, exptime, flags });
+    this.validateKey(key);
+    const valueStr = String(value);
+    const bytes = Buffer.byteLength(valueStr);
+    const command = `cas ${key} ${flags} ${exptime} ${bytes} ${casToken}\r
+${valueStr}`;
+    const nodes = await this.getNodesByKey(key);
+    const promises = nodes.map(async (node) => {
+      try {
+        const result = await node.command(command);
+        return result === "STORED";
+      } catch {
+        return false;
+      }
+    });
+    const results = await Promise.all(promises);
+    const success = results.every((result) => result === true);
+    await this.afterHook("cas", {
+      key,
+      value,
+      casToken,
+      exptime,
+      flags,
+      success
+    });
+    return success;
+  }
+  /**
+   * Set a value in the Memcache server.
+   * When multiple nodes are returned by the hash provider (for replication),
+   * executes on all nodes and returns true only if all succeed.
+   * @param key {string}
+   * @param value {string}
+   * @param exptime {number}
+   * @param flags {number}
+   * @returns {Promise<boolean>}
+   */
+  async set(key, value, exptime = 0, flags = 0) {
+    await this.beforeHook("set", { key, value, exptime, flags });
+    this.validateKey(key);
+    const valueStr = String(value);
+    const bytes = Buffer.byteLength(valueStr);
+    const command = `set ${key} ${flags} ${exptime} ${bytes}\r
+${valueStr}`;
+    const nodes = await this.getNodesByKey(key);
+    const promises = nodes.map(async (node) => {
+      try {
+        const result = await node.command(command);
+        return result === "STORED";
+      } catch {
+        return false;
+      }
+    });
+    const results = await Promise.all(promises);
+    const success = results.every((result) => result === true);
+    await this.afterHook("set", { key, value, exptime, flags, success });
+    return success;
+  }
+  /**
+   * Add a value to the Memcache server (only if key doesn't exist).
+   * When multiple nodes are returned by the hash provider (for replication),
+   * executes on all nodes and returns true only if all succeed.
+   * @param key {string}
+   * @param value {string}
+   * @param exptime {number}
+   * @param flags {number}
+   * @returns {Promise<boolean>}
+   */
+  async add(key, value, exptime = 0, flags = 0) {
+    await this.beforeHook("add", { key, value, exptime, flags });
+    this.validateKey(key);
+    const valueStr = String(value);
+    const bytes = Buffer.byteLength(valueStr);
+    const command = `add ${key} ${flags} ${exptime} ${bytes}\r
+${valueStr}`;
+    const nodes = await this.getNodesByKey(key);
+    const promises = nodes.map(async (node) => {
+      try {
+        const result = await node.command(command);
+        return result === "STORED";
+      } catch {
+        return false;
+      }
+    });
+    const results = await Promise.all(promises);
+    const success = results.every((result) => result === true);
+    await this.afterHook("add", { key, value, exptime, flags, success });
+    return success;
+  }
+  /**
+   * Replace a value in the Memcache server (only if key exists).
+   * When multiple nodes are returned by the hash provider (for replication),
+   * executes on all nodes and returns true only if all succeed.
+   * @param key {string}
+   * @param value {string}
+   * @param exptime {number}
+   * @param flags {number}
+   * @returns {Promise<boolean>}
+   */
+  async replace(key, value, exptime = 0, flags = 0) {
+    await this.beforeHook("replace", { key, value, exptime, flags });
+    this.validateKey(key);
+    const valueStr = String(value);
+    const bytes = Buffer.byteLength(valueStr);
+    const command = `replace ${key} ${flags} ${exptime} ${bytes}\r
+${valueStr}`;
+    const nodes = await this.getNodesByKey(key);
+    const promises = nodes.map(async (node) => {
+      try {
+        const result = await node.command(command);
+        return result === "STORED";
+      } catch {
+        return false;
+      }
+    });
+    const results = await Promise.all(promises);
+    const success = results.every((result) => result === true);
+    await this.afterHook("replace", { key, value, exptime, flags, success });
+    return success;
+  }
+  /**
+   * Append a value to an existing key in the Memcache server.
+   * When multiple nodes are returned by the hash provider (for replication),
+   * executes on all nodes and returns true only if all succeed.
+   * @param key {string}
+   * @param value {string}
+   * @returns {Promise<boolean>}
+   */
+  async append(key, value) {
+    await this.beforeHook("append", { key, value });
+    this.validateKey(key);
+    const valueStr = String(value);
+    const bytes = Buffer.byteLength(valueStr);
+    const command = `append ${key} 0 0 ${bytes}\r
+${valueStr}`;
+    const nodes = await this.getNodesByKey(key);
+    const promises = nodes.map(async (node) => {
+      try {
+        const result = await node.command(command);
+        return result === "STORED";
+      } catch {
+        return false;
+      }
+    });
+    const results = await Promise.all(promises);
+    const success = results.every((result) => result === true);
+    await this.afterHook("append", { key, value, success });
+    return success;
+  }
+  /**
+   * Prepend a value to an existing key in the Memcache server.
+   * When multiple nodes are returned by the hash provider (for replication),
+   * executes on all nodes and returns true only if all succeed.
+   * @param key {string}
+   * @param value {string}
+   * @returns {Promise<boolean>}
+   */
+  async prepend(key, value) {
+    await this.beforeHook("prepend", { key, value });
+    this.validateKey(key);
+    const valueStr = String(value);
+    const bytes = Buffer.byteLength(valueStr);
+    const command = `prepend ${key} 0 0 ${bytes}\r
+${valueStr}`;
+    const nodes = await this.getNodesByKey(key);
+    const promises = nodes.map(async (node) => {
+      try {
+        const result = await node.command(command);
+        return result === "STORED";
+      } catch {
+        return false;
+      }
+    });
+    const results = await Promise.all(promises);
+    const success = results.every((result) => result === true);
+    await this.afterHook("prepend", { key, value, success });
+    return success;
+  }
+  /**
+   * Delete a value from the Memcache server.
+   * When multiple nodes are returned by the hash provider (for replication),
+   * executes on all nodes and returns true only if all succeed.
+   * @param key {string}
+   * @returns {Promise<boolean>}
+   */
+  async delete(key) {
+    await this.beforeHook("delete", { key });
+    this.validateKey(key);
+    const nodes = await this.getNodesByKey(key);
+    const promises = nodes.map(async (node) => {
+      try {
+        const result = await node.command(`delete ${key}`);
+        return result === "DELETED";
+      } catch {
+        return false;
+      }
+    });
+    const results = await Promise.all(promises);
+    const success = results.every((result) => result === true);
+    await this.afterHook("delete", { key, success });
+    return success;
+  }
+  /**
+   * Increment a value in the Memcache server.
+   * When multiple nodes are returned by the hash provider (for replication),
+   * executes on all nodes and returns the first successful result.
+   * @param key {string}
+   * @param value {number}
+   * @returns {Promise<number | undefined>}
+   */
+  async incr(key, value = 1) {
+    await this.beforeHook("incr", { key, value });
+    this.validateKey(key);
+    const nodes = await this.getNodesByKey(key);
+    const promises = nodes.map(async (node) => {
+      try {
+        const result = await node.command(`incr ${key} ${value}`);
+        return typeof result === "number" ? result : void 0;
+      } catch {
+        return void 0;
+      }
+    });
+    const results = await Promise.all(promises);
+    const newValue = results.find((v) => v !== void 0);
+    await this.afterHook("incr", { key, value, newValue });
+    return newValue;
+  }
+  /**
+   * Decrement a value in the Memcache server.
+   * When multiple nodes are returned by the hash provider (for replication),
+   * executes on all nodes and returns the first successful result.
+   * @param key {string}
+   * @param value {number}
+   * @returns {Promise<number | undefined>}
+   */
+  async decr(key, value = 1) {
+    await this.beforeHook("decr", { key, value });
+    this.validateKey(key);
+    const nodes = await this.getNodesByKey(key);
+    const promises = nodes.map(async (node) => {
+      try {
+        const result = await node.command(`decr ${key} ${value}`);
+        return typeof result === "number" ? result : void 0;
+      } catch {
+        return void 0;
+      }
+    });
+    const results = await Promise.all(promises);
+    const newValue = results.find((v) => v !== void 0);
+    await this.afterHook("decr", { key, value, newValue });
+    return newValue;
+  }
+  /**
+   * Touch a value in the Memcache server (update expiration time).
+   * When multiple nodes are returned by the hash provider (for replication),
+   * executes on all nodes and returns true only if all succeed.
+   * @param key {string}
+   * @param exptime {number}
+   * @returns {Promise<boolean>}
+   */
+  async touch(key, exptime) {
+    await this.beforeHook("touch", { key, exptime });
+    this.validateKey(key);
+    const nodes = await this.getNodesByKey(key);
+    const promises = nodes.map(async (node) => {
+      try {
+        const result = await node.command(`touch ${key} ${exptime}`);
+        return result === "TOUCHED";
+      } catch {
+        return false;
+      }
+    });
+    const results = await Promise.all(promises);
+    const success = results.every((result) => result === true);
+    await this.afterHook("touch", { key, exptime, success });
+    return success;
+  }
+  /**
+   * Flush all values from all Memcache servers.
+   * @param delay {number}
+   * @returns {Promise<boolean>}
+   */
+  async flush(delay) {
+    let command = "flush_all";
+    if (delay !== void 0) {
+      command += ` ${delay}`;
+    }
+    const results = await Promise.all(
+      this._nodes.map(async (node) => {
+        if (!node.isConnected()) {
+          await node.connect();
+        }
+        return node.command(command);
+      })
+    );
+    return results.every((r) => r === "OK");
+  }
+  /**
+   * Get statistics from all Memcache servers.
+   * @param type {string}
+   * @returns {Promise<Map<string, MemcacheStats>>}
+   */
+  async stats(type) {
+    const command = type ? `stats ${type}` : "stats";
+    const results = /* @__PURE__ */ new Map();
+    await Promise.all(
+      /* v8 ignore next -- @preserve */
+      this._nodes.map(async (node) => {
+        if (!node.isConnected()) {
+          await node.connect();
+        }
+        const stats = await node.command(command, { isStats: true });
+        results.set(node.id, stats);
+      })
+    );
+    return results;
+  }
+  /**
+   * Get the Memcache server version from all nodes.
+   * @returns {Promise<Map<string, string>>} Map of node IDs to version strings
+   */
+  async version() {
+    const results = /* @__PURE__ */ new Map();
+    await Promise.all(
+      /* v8 ignore next -- @preserve */
+      this._nodes.map(async (node) => {
+        if (!node.isConnected()) {
+          await node.connect();
+        }
+        const version = await node.command("version");
+        results.set(node.id, version);
+      })
+    );
+    return results;
+  }
+  /**
+   * Quit all connections gracefully.
+   * @returns {Promise<void>}
+   */
+  async quit() {
+    await Promise.all(
+      this._nodes.map(async (node) => {
+        if (node.isConnected()) {
+          await node.quit();
+        }
+      })
+    );
+  }
+  /**
+   * Disconnect all connections.
+   * @returns {Promise<void>}
+   */
+  async disconnect() {
+    await Promise.all(this._nodes.map((node) => node.disconnect()));
+  }
+  /**
+   * Reconnect all nodes by disconnecting and connecting them again.
+   * @returns {Promise<void>}
+   */
+  async reconnect() {
+    await Promise.all(this._nodes.map((node) => node.reconnect()));
+  }
+  /**
+   * Check if any node is connected to a Memcache server.
+   * @returns {boolean}
+   */
+  isConnected() {
+    return this._nodes.some((node) => node.isConnected());
+  }
+  /**
+   * Get the nodes for a given key using consistent hashing, with lazy connection.
+   * This method will automatically connect to the nodes if they're not already connected.
+   * Returns an array to support replication strategies.
+   * @param {string} key - The cache key
+   * @returns {Promise<Array<MemcacheNode>>} The nodes responsible for this key
+   * @throws {Error} If no nodes are available for the key
+   */
+  async getNodesByKey(key) {
+    const nodes = this._hash.getNodesByKey(key);
+    if (nodes.length === 0) {
+      throw new Error(`No node available for key: ${key}`);
+    }
+    for (const node of nodes) {
+      if (!node.isConnected()) {
+        await node.connect();
+      }
+    }
+    return nodes;
+  }
+  /**
+   * Validates a Memcache key according to protocol requirements.
+   * @param {string} key - The key to validate
+   * @throws {Error} If the key is empty, exceeds 250 characters, or contains invalid characters
+   *
+   * @example
+   * ```typescript
+   * client.validateKey("valid-key"); // OK
+   * client.validateKey(""); // Throws: Key cannot be empty
+   * client.validateKey("a".repeat(251)); // Throws: Key length cannot exceed 250 characters
+   * client.validateKey("key with spaces"); // Throws: Key cannot contain spaces, newlines, or null characters
+   * ```
+   */
+  validateKey(key) {
+    if (!key || key.length === 0) {
+      throw new Error("Key cannot be empty");
+    }
+    if (key.length > 250) {
+      throw new Error("Key length cannot exceed 250 characters");
+    }
+    if (/[\s\r\n\0]/.test(key)) {
+      throw new Error(
+        "Key cannot contain spaces, newlines, or null characters"
+      );
+    }
+  }
+  // Private methods
+  /**
+   * Update all nodes with current keepAlive settings
+   */
+  updateNodes() {
+    for (const node of this._nodes) {
+      node.keepAlive = this._keepAlive;
+      node.keepAliveDelay = this._keepAliveDelay;
+    }
+  }
+  /**
+   * Forward events from a MemcacheNode to the Memcache instance
+   */
+  forwardNodeEvents(node) {
+    node.on("connect", () => this.emit("connect" /* CONNECT */, node.id));
+    node.on("close", () => this.emit("close" /* CLOSE */, node.id));
+    node.on(
+      "error",
+      (err) => this.emit("error" /* ERROR */, node.id, err)
+    );
+    node.on("timeout", () => this.emit("timeout" /* TIMEOUT */, node.id));
+    node.on(
+      "hit",
+      (key, value) => this.emit("hit" /* HIT */, key, value)
+    );
+    node.on("miss", (key) => this.emit("miss" /* MISS */, key));
+  }
+};
+var index_default = Memcache;
+export {
+  Memcache,
+  MemcacheEvents,
+  createNode,
+  index_default as default
+};
+/* v8 ignore next -- @preserve */