memcache 1.2.0 → 1.4.0

package/dist/index.js

@@ -1,412 +1,362 @@
 // src/index.ts
+import { Hookified as Hookified3 } from "hookified";
+
+// src/auto-discovery.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 {
+// src/node.ts
+import { createConnection } from "net";
+import { Hookified } from "hookified";
+
+// src/binary-protocol.ts
+var REQUEST_MAGIC = 128;
+var OPCODE_SASL_AUTH = 33;
+var OPCODE_GET = 0;
+var OPCODE_SET = 1;
+var OPCODE_ADD = 2;
+var OPCODE_REPLACE = 3;
+var OPCODE_DELETE = 4;
+var OPCODE_INCREMENT = 5;
+var OPCODE_DECREMENT = 6;
+var OPCODE_QUIT = 7;
+var OPCODE_FLUSH = 8;
+var OPCODE_VERSION = 11;
+var OPCODE_APPEND = 14;
+var OPCODE_PREPEND = 15;
+var OPCODE_STAT = 16;
+var OPCODE_TOUCH = 28;
+var STATUS_SUCCESS = 0;
+var STATUS_KEY_NOT_FOUND = 1;
+var STATUS_AUTH_ERROR = 32;
+var HEADER_SIZE = 24;
+function serializeHeader(header) {
+  const buf = Buffer.alloc(HEADER_SIZE);
+  buf.writeUInt8(header.magic ?? REQUEST_MAGIC, 0);
+  buf.writeUInt8(header.opcode ?? 0, 1);
+  buf.writeUInt16BE(header.keyLength ?? 0, 2);
+  buf.writeUInt8(header.extrasLength ?? 0, 4);
+  buf.writeUInt8(header.dataType ?? 0, 5);
+  buf.writeUInt16BE(header.status ?? 0, 6);
+  buf.writeUInt32BE(header.totalBodyLength ?? 0, 8);
+  buf.writeUInt32BE(header.opaque ?? 0, 12);
+  if (header.cas) {
+    header.cas.copy(buf, 16);
+  }
+  return buf;
+}
+function deserializeHeader(buf) {
+  return {
+    magic: buf.readUInt8(0),
+    opcode: buf.readUInt8(1),
+    keyLength: buf.readUInt16BE(2),
+    extrasLength: buf.readUInt8(4),
+    dataType: buf.readUInt8(5),
+    status: buf.readUInt16BE(6),
+    totalBodyLength: buf.readUInt32BE(8),
+    opaque: buf.readUInt32BE(12),
+    cas: buf.subarray(16, 24)
+  };
+}
+function buildSaslPlainRequest(username, password) {
+  const mechanism = "PLAIN";
+  const authData = `\0${username}\0${password}`;
+  const keyBuf = Buffer.from(mechanism, "utf8");
+  const valueBuf = Buffer.from(authData, "utf8");
+  const header = serializeHeader({
+    magic: REQUEST_MAGIC,
+    opcode: OPCODE_SASL_AUTH,
+    keyLength: keyBuf.length,
+    totalBodyLength: keyBuf.length + valueBuf.length
+  });
+  return Buffer.concat([header, keyBuf, valueBuf]);
+}
+function buildGetRequest(key) {
+  const keyBuf = Buffer.from(key, "utf8");
+  const header = serializeHeader({
+    magic: REQUEST_MAGIC,
+    opcode: OPCODE_GET,
+    keyLength: keyBuf.length,
+    totalBodyLength: keyBuf.length
+  });
+  return Buffer.concat([header, keyBuf]);
+}
+function buildSetRequest(key, value, flags = 0, exptime = 0) {
+  const keyBuf = Buffer.from(key, "utf8");
+  const valueBuf = Buffer.isBuffer(value) ? value : Buffer.from(value, "utf8");
+  const extras = Buffer.alloc(8);
+  extras.writeUInt32BE(flags, 0);
+  extras.writeUInt32BE(exptime, 4);
+  const header = serializeHeader({
+    magic: REQUEST_MAGIC,
+    opcode: OPCODE_SET,
+    keyLength: keyBuf.length,
+    extrasLength: 8,
+    totalBodyLength: 8 + keyBuf.length + valueBuf.length
+  });
+  return Buffer.concat([header, extras, keyBuf, valueBuf]);
+}
+function buildAddRequest(key, value, flags = 0, exptime = 0) {
+  const keyBuf = Buffer.from(key, "utf8");
+  const valueBuf = Buffer.isBuffer(value) ? value : Buffer.from(value, "utf8");
+  const extras = Buffer.alloc(8);
+  extras.writeUInt32BE(flags, 0);
+  extras.writeUInt32BE(exptime, 4);
+  const header = serializeHeader({
+    magic: REQUEST_MAGIC,
+    opcode: OPCODE_ADD,
+    keyLength: keyBuf.length,
+    extrasLength: 8,
+    totalBodyLength: 8 + keyBuf.length + valueBuf.length
+  });
+  return Buffer.concat([header, extras, keyBuf, valueBuf]);
+}
+function buildReplaceRequest(key, value, flags = 0, exptime = 0) {
+  const keyBuf = Buffer.from(key, "utf8");
+  const valueBuf = Buffer.isBuffer(value) ? value : Buffer.from(value, "utf8");
+  const extras = Buffer.alloc(8);
+  extras.writeUInt32BE(flags, 0);
+  extras.writeUInt32BE(exptime, 4);
+  const header = serializeHeader({
+    magic: REQUEST_MAGIC,
+    opcode: OPCODE_REPLACE,
+    keyLength: keyBuf.length,
+    extrasLength: 8,
+    totalBodyLength: 8 + keyBuf.length + valueBuf.length
+  });
+  return Buffer.concat([header, extras, keyBuf, valueBuf]);
+}
+function buildDeleteRequest(key) {
+  const keyBuf = Buffer.from(key, "utf8");
+  const header = serializeHeader({
+    magic: REQUEST_MAGIC,
+    opcode: OPCODE_DELETE,
+    keyLength: keyBuf.length,
+    totalBodyLength: keyBuf.length
+  });
+  return Buffer.concat([header, keyBuf]);
+}
+function buildIncrementRequest(key, delta = 1, initial = 0, exptime = 0) {
+  const keyBuf = Buffer.from(key, "utf8");
+  const extras = Buffer.alloc(20);
+  extras.writeUInt32BE(Math.floor(delta / 4294967296), 0);
+  extras.writeUInt32BE(delta >>> 0, 4);
+  extras.writeUInt32BE(Math.floor(initial / 4294967296), 8);
+  extras.writeUInt32BE(initial >>> 0, 12);
+  extras.writeUInt32BE(exptime, 16);
+  const header = serializeHeader({
+    magic: REQUEST_MAGIC,
+    opcode: OPCODE_INCREMENT,
+    keyLength: keyBuf.length,
+    extrasLength: 20,
+    totalBodyLength: 20 + keyBuf.length
+  });
+  return Buffer.concat([header, extras, keyBuf]);
+}
+function buildDecrementRequest(key, delta = 1, initial = 0, exptime = 0) {
+  const keyBuf = Buffer.from(key, "utf8");
+  const extras = Buffer.alloc(20);
+  extras.writeUInt32BE(Math.floor(delta / 4294967296), 0);
+  extras.writeUInt32BE(delta >>> 0, 4);
+  extras.writeUInt32BE(Math.floor(initial / 4294967296), 8);
+  extras.writeUInt32BE(initial >>> 0, 12);
+  extras.writeUInt32BE(exptime, 16);
+  const header = serializeHeader({
+    magic: REQUEST_MAGIC,
+    opcode: OPCODE_DECREMENT,
+    keyLength: keyBuf.length,
+    extrasLength: 20,
+    totalBodyLength: 20 + keyBuf.length
+  });
+  return Buffer.concat([header, extras, keyBuf]);
+}
+function buildAppendRequest(key, value) {
+  const keyBuf = Buffer.from(key, "utf8");
+  const valueBuf = Buffer.isBuffer(value) ? value : Buffer.from(value, "utf8");
+  const header = serializeHeader({
+    magic: REQUEST_MAGIC,
+    opcode: OPCODE_APPEND,
+    keyLength: keyBuf.length,
+    totalBodyLength: keyBuf.length + valueBuf.length
+  });
+  return Buffer.concat([header, keyBuf, valueBuf]);
+}
+function buildPrependRequest(key, value) {
+  const keyBuf = Buffer.from(key, "utf8");
+  const valueBuf = Buffer.isBuffer(value) ? value : Buffer.from(value, "utf8");
+  const header = serializeHeader({
+    magic: REQUEST_MAGIC,
+    opcode: OPCODE_PREPEND,
+    keyLength: keyBuf.length,
+    totalBodyLength: keyBuf.length + valueBuf.length
+  });
+  return Buffer.concat([header, keyBuf, valueBuf]);
+}
+function buildTouchRequest(key, exptime) {
+  const keyBuf = Buffer.from(key, "utf8");
+  const extras = Buffer.alloc(4);
+  extras.writeUInt32BE(exptime, 0);
+  const header = serializeHeader({
+    magic: REQUEST_MAGIC,
+    opcode: OPCODE_TOUCH,
+    keyLength: keyBuf.length,
+    extrasLength: 4,
+    totalBodyLength: 4 + keyBuf.length
+  });
+  return Buffer.concat([header, extras, keyBuf]);
+}
+function buildFlushRequest(exptime = 0) {
+  const extras = Buffer.alloc(4);
+  extras.writeUInt32BE(exptime, 0);
+  const header = serializeHeader({
+    magic: REQUEST_MAGIC,
+    opcode: OPCODE_FLUSH,
+    extrasLength: 4,
+    totalBodyLength: 4
+  });
+  return Buffer.concat([header, extras]);
+}
+function buildVersionRequest() {
+  return serializeHeader({
+    magic: REQUEST_MAGIC,
+    opcode: OPCODE_VERSION
+  });
+}
+function buildStatRequest(key) {
+  if (key) {
+    const keyBuf = Buffer.from(key, "utf8");
+    const header = serializeHeader({
+      magic: REQUEST_MAGIC,
+      opcode: OPCODE_STAT,
+      keyLength: keyBuf.length,
+      totalBodyLength: keyBuf.length
+    });
+    return Buffer.concat([header, keyBuf]);
+  }
+  return serializeHeader({
+    magic: REQUEST_MAGIC,
+    opcode: OPCODE_STAT
+  });
+}
+function buildQuitRequest() {
+  return serializeHeader({
+    magic: REQUEST_MAGIC,
+    opcode: OPCODE_QUIT
+  });
+}
+function parseGetResponse(buf) {
+  const header = deserializeHeader(buf);
+  if (header.status !== STATUS_SUCCESS) {
+    return { header, value: void 0, key: void 0 };
+  }
+  const extrasEnd = HEADER_SIZE + header.extrasLength;
+  const keyEnd = extrasEnd + header.keyLength;
+  const valueEnd = HEADER_SIZE + header.totalBodyLength;
+  const key = header.keyLength > 0 ? buf.subarray(extrasEnd, keyEnd).toString("utf8") : void 0;
+  const value = valueEnd > keyEnd ? buf.subarray(keyEnd, valueEnd) : void 0;
+  return { header, value, key };
+}
+function parseIncrDecrResponse(buf) {
+  const header = deserializeHeader(buf);
+  if (header.status !== STATUS_SUCCESS || header.totalBodyLength < 8) {
+    return { header, value: void 0 };
+  }
+  const high = buf.readUInt32BE(HEADER_SIZE);
+  const low = buf.readUInt32BE(HEADER_SIZE + 4);
+  const value = high * 4294967296 + low;
+  return { header, value };
+}
+
+// src/node.ts
+var MemcacheNode = class extends Hookified {
+  _host;
+  _port;
+  _socket = void 0;
+  _timeout;
+  _keepAlive;
+  _keepAliveDelay;
+  _weight;
+  _connected = false;
+  _commandQueue = [];
+  _buffer = "";
+  _currentCommand = void 0;
+  _multilineData = [];
+  _pendingValueBytes = 0;
+  _sasl;
+  _authenticated = false;
+  _binaryBuffer = Buffer.alloc(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;
+    this._sasl = options?.sasl;
+  }
   /**
-   * 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%.
+   * Get the host of this node
    */
-  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();
+  get host() {
+    return this._host;
+  }
   /**
-   * Gets the sorted array of [hash, node key] tuples representing virtual nodes on the ring.
-   * @returns The hash clock array
+   * Get the port of this node
    */
-  get clock() {
-    return this._clock;
+  get port() {
+    return this._port;
   }
   /**
-   * Gets the map of node keys to actual node objects.
-   * @returns The nodes map
+   * Get the unique identifier for this node (host:port format)
    */
-  get nodes() {
-    return this._nodes;
+  get id() {
+    if (this._port === 0) {
+      return this._host;
+    }
+    const host = this._host.includes(":") ? `[${this._host}]` : this._host;
+    return `${host}:${this._port}`;
   }
   /**
-   * 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 }
-   * ]);
-   * ```
+   * Get the full uri like memcache://localhost:11211
    */
-  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);
-      }
-    }
+  get uri() {
+    return `memcache://${this.id}`;
   }
   /**
-   * 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
-   * ```
+   * Get the socket connection
    */
-  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));
-    }
+  get socket() {
+    return this._socket;
   }
   /**
-   * 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
-   * ```
+   * Get the weight of this node (used for consistent hashing distribution)
    */
-  removeNode(node) {
-    const key = keyFor(node);
-    if (this._nodes.delete(key)) {
-      this._clock = this._clock.filter(([, n]) => n !== key);
-    }
+  get weight() {
+    return this._weight;
   }
   /**
-   * 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'));
-   * ```
+   * Set the weight of this node (used for consistent hashing distribution)
    */
-  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);
+  set weight(value) {
+    this._weight = value;
   }
   /**
-   * 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
+   * Get the keepAlive setting for this node
    */
-  getIndexForInput(input) {
-    const hash = this.hashFn(
-      typeof input === "string" ? Buffer.from(input) : input
-    );
-    return binarySearchRing(this._clock, hash);
+  get keepAlive() {
+    return this._keepAlive;
   }
   /**
-   * 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']
-   * ```
+   * Set the keepAlive setting for this node
    */
-  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));
+  set keepAlive(value) {
+    this._keepAlive = value;
   }
   /**
-   * 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)
+   * Get the keepAliveDelay setting for this node
    */
-  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;
+  get keepAliveDelay() {
+    return this._keepAliveDelay;
   }
   /**
    * Set the keepAliveDelay setting for this node
@@ -420,6 +370,18 @@ var MemcacheNode = class extends Hookified {
   get commandQueue() {
     return this._commandQueue;
   }
+  /**
+   * Get whether SASL authentication is configured
+   */
+  get hasSaslCredentials() {
+    return !!this._sasl?.username && !!this._sasl?.password;
+  }
+  /**
+   * Get whether the node is authenticated (only relevant if SASL is configured)
+   */
+  get isAuthenticated() {
+    return this._authenticated;
+  }
   /**
    * Connect to the memcache server
    */
@@ -436,14 +398,31 @@ var MemcacheNode = class extends Hookified {
         keepAliveInitialDelay: this._keepAliveDelay
       });
       this._socket.setTimeout(this._timeout);
-      this._socket.setEncoding("utf8");
-      this._socket.on("connect", () => {
+      if (!this._sasl) {
+        this._socket.setEncoding("utf8");
+      }
+      this._socket.on("connect", async () => {
         this._connected = true;
-        this.emit("connect");
-        resolve();
+        if (this._sasl) {
+          try {
+            await this.performSaslAuth();
+            this.emit("connect");
+            resolve();
+          } catch (error) {
+            this._socket?.destroy();
+            this._connected = false;
+            this._authenticated = false;
+            reject(error);
+          }
+        } else {
+          this.emit("connect");
+          resolve();
+        }
       });
       this._socket.on("data", (data) => {
-        this.handleData(data);
+        if (typeof data === "string") {
+          this.handleData(data);
+        }
       });
       this._socket.on("error", (error) => {
         this.emit("error", error);
@@ -453,6 +432,7 @@ var MemcacheNode = class extends Hookified {
       });
       this._socket.on("close", () => {
         this._connected = false;
+        this._authenticated = false;
         this.emit("close");
         this.rejectPendingCommands(new Error("Connection closed"));
       });
@@ -486,47 +466,296 @@ var MemcacheNode = class extends Hookified {
       this._currentCommand = void 0;
       this._multilineData = [];
       this._pendingValueBytes = 0;
+      this._authenticated = false;
+      this._binaryBuffer = Buffer.alloc(0);
     }
     await this.connect();
   }
   /**
-   * Gracefully quit the connection (send quit command then disconnect)
+   * Perform SASL PLAIN authentication using the binary protocol
    */
-  async quit() {
-    if (this._connected && this._socket) {
-      try {
-        await this.command("quit");
-      } catch (error) {
-      }
-      await this.disconnect();
+  async performSaslAuth() {
+    if (!this._sasl || !this._socket) {
+      throw new Error("SASL credentials not configured");
     }
+    const socket = this._socket;
+    const sasl = this._sasl;
+    return new Promise((resolve, reject) => {
+      this._binaryBuffer = Buffer.alloc(0);
+      const authPacket = buildSaslPlainRequest(sasl.username, sasl.password);
+      const binaryHandler = (data) => {
+        this._binaryBuffer = Buffer.concat([this._binaryBuffer, data]);
+        if (this._binaryBuffer.length < HEADER_SIZE) {
+          return;
+        }
+        const header = deserializeHeader(this._binaryBuffer);
+        const totalLength = HEADER_SIZE + header.totalBodyLength;
+        if (this._binaryBuffer.length < totalLength) {
+          return;
+        }
+        socket.removeListener("data", binaryHandler);
+        if (header.status === STATUS_SUCCESS) {
+          this._authenticated = true;
+          this.emit("authenticated");
+          resolve();
+        } else if (header.status === STATUS_AUTH_ERROR) {
+          const body = this._binaryBuffer.subarray(HEADER_SIZE, totalLength);
+          reject(
+            new Error(
+              `SASL authentication failed: ${body.toString() || "Invalid credentials"}`
+            )
+          );
+        } else {
+          reject(
+            new Error(
+              `SASL authentication failed with status: 0x${header.status.toString(16)}`
+            )
+          );
+        }
+      };
+      socket.on("data", binaryHandler);
+      socket.write(authPacket);
+    });
   }
   /**
-   * Check if connected to the memcache server
+   * Send a binary protocol request and wait for response.
+   * Used internally for SASL-authenticated connections.
    */
-  isConnected() {
-    return this._connected;
+  async binaryRequest(packet) {
+    if (!this._socket) {
+      throw new Error("Not connected");
+    }
+    const socket = this._socket;
+    return new Promise((resolve) => {
+      let buffer = Buffer.alloc(0);
+      const dataHandler = (data) => {
+        buffer = Buffer.concat([buffer, data]);
+        if (buffer.length < HEADER_SIZE) {
+          return;
+        }
+        const header = deserializeHeader(buffer);
+        const totalLength = HEADER_SIZE + header.totalBodyLength;
+        if (buffer.length < totalLength) {
+          return;
+        }
+        socket.removeListener("data", dataHandler);
+        resolve(buffer.subarray(0, totalLength));
+      };
+      socket.on("data", dataHandler);
+      socket.write(packet);
+    });
   }
   /**
-   * 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
+   * Binary protocol GET operation
    */
-  async command(cmd, options) {
-    if (!this._connected || !this._socket) {
-      throw new Error(`Not connected to memcache server ${this.id}`);
+  async binaryGet(key) {
+    const response = await this.binaryRequest(buildGetRequest(key));
+    const { header, value } = parseGetResponse(response);
+    if (header.status === STATUS_KEY_NOT_FOUND) {
+      this.emit("miss", key);
+      return void 0;
     }
-    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
-`);
+    if (header.status !== STATUS_SUCCESS || !value) {
+      return void 0;
+    }
+    const result = value.toString("utf8");
+    this.emit("hit", key, result);
+    return result;
+  }
+  /**
+   * Binary protocol SET operation
+   */
+  async binarySet(key, value, exptime = 0, flags = 0) {
+    const response = await this.binaryRequest(
+      buildSetRequest(key, value, flags, exptime)
+    );
+    const header = deserializeHeader(response);
+    return header.status === STATUS_SUCCESS;
+  }
+  /**
+   * Binary protocol ADD operation
+   */
+  async binaryAdd(key, value, exptime = 0, flags = 0) {
+    const response = await this.binaryRequest(
+      buildAddRequest(key, value, flags, exptime)
+    );
+    const header = deserializeHeader(response);
+    return header.status === STATUS_SUCCESS;
+  }
+  /**
+   * Binary protocol REPLACE operation
+   */
+  async binaryReplace(key, value, exptime = 0, flags = 0) {
+    const response = await this.binaryRequest(
+      buildReplaceRequest(key, value, flags, exptime)
+    );
+    const header = deserializeHeader(response);
+    return header.status === STATUS_SUCCESS;
+  }
+  /**
+   * Binary protocol DELETE operation
+   */
+  async binaryDelete(key) {
+    const response = await this.binaryRequest(buildDeleteRequest(key));
+    const header = deserializeHeader(response);
+    return header.status === STATUS_SUCCESS || header.status === STATUS_KEY_NOT_FOUND;
+  }
+  /**
+   * Binary protocol INCREMENT operation
+   */
+  async binaryIncr(key, delta = 1, initial = 0, exptime = 0) {
+    const response = await this.binaryRequest(
+      buildIncrementRequest(key, delta, initial, exptime)
+    );
+    const { header, value } = parseIncrDecrResponse(response);
+    if (header.status !== STATUS_SUCCESS) {
+      return void 0;
+    }
+    return value;
+  }
+  /**
+   * Binary protocol DECREMENT operation
+   */
+  async binaryDecr(key, delta = 1, initial = 0, exptime = 0) {
+    const response = await this.binaryRequest(
+      buildDecrementRequest(key, delta, initial, exptime)
+    );
+    const { header, value } = parseIncrDecrResponse(response);
+    if (header.status !== STATUS_SUCCESS) {
+      return void 0;
+    }
+    return value;
+  }
+  /**
+   * Binary protocol APPEND operation
+   */
+  async binaryAppend(key, value) {
+    const response = await this.binaryRequest(buildAppendRequest(key, value));
+    const header = deserializeHeader(response);
+    return header.status === STATUS_SUCCESS;
+  }
+  /**
+   * Binary protocol PREPEND operation
+   */
+  async binaryPrepend(key, value) {
+    const response = await this.binaryRequest(buildPrependRequest(key, value));
+    const header = deserializeHeader(response);
+    return header.status === STATUS_SUCCESS;
+  }
+  /**
+   * Binary protocol TOUCH operation
+   */
+  async binaryTouch(key, exptime) {
+    const response = await this.binaryRequest(buildTouchRequest(key, exptime));
+    const header = deserializeHeader(response);
+    return header.status === STATUS_SUCCESS;
+  }
+  /**
+   * Binary protocol FLUSH operation
+   */
+  /* v8 ignore next -- @preserve */
+  async binaryFlush(exptime = 0) {
+    const response = await this.binaryRequest(buildFlushRequest(exptime));
+    const header = deserializeHeader(response);
+    return header.status === STATUS_SUCCESS;
+  }
+  /**
+   * Binary protocol VERSION operation
+   */
+  async binaryVersion() {
+    const response = await this.binaryRequest(buildVersionRequest());
+    const header = deserializeHeader(response);
+    if (header.status !== STATUS_SUCCESS) {
+      return void 0;
+    }
+    return response.subarray(HEADER_SIZE, HEADER_SIZE + header.totalBodyLength).toString("utf8");
+  }
+  /**
+   * Binary protocol STATS operation
+   */
+  async binaryStats() {
+    if (!this._socket) {
+      throw new Error("Not connected");
+    }
+    const socket = this._socket;
+    const stats = {};
+    return new Promise((resolve) => {
+      let buffer = Buffer.alloc(0);
+      const dataHandler = (data) => {
+        buffer = Buffer.concat([buffer, data]);
+        while (buffer.length >= HEADER_SIZE) {
+          const header = deserializeHeader(buffer);
+          const totalLength = HEADER_SIZE + header.totalBodyLength;
+          if (buffer.length < totalLength) {
+            return;
+          }
+          if (header.keyLength === 0 && header.totalBodyLength === 0) {
+            socket.removeListener("data", dataHandler);
+            resolve(stats);
+            return;
+          }
+          if (header.opcode === OPCODE_STAT && header.status === STATUS_SUCCESS) {
+            const keyStart = HEADER_SIZE;
+            const keyEnd = keyStart + header.keyLength;
+            const valueEnd = HEADER_SIZE + header.totalBodyLength;
+            const key = buffer.subarray(keyStart, keyEnd).toString("utf8");
+            const value = buffer.subarray(keyEnd, valueEnd).toString("utf8");
+            stats[key] = value;
+          }
+          buffer = buffer.subarray(totalLength);
+        }
+      };
+      socket.on("data", dataHandler);
+      socket.write(buildStatRequest());
+    });
+  }
+  /**
+   * Binary protocol QUIT operation
+   */
+  async binaryQuit() {
+    if (this._socket) {
+      this._socket.write(buildQuitRequest());
+    }
+  }
+  /**
+   * 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,
+        isConfig: options?.isConfig,
+        requestedKeys: options?.requestedKeys
+      });
+      this._socket.write(`${cmd}\r
+`);
     });
   }
   handleData(data) {
@@ -579,81 +808,769 @@ var MemcacheNode = class extends Hookified {
       }
       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;
-      }
+    if (this._currentCommand.isConfig) {
+      if (line.startsWith("CONFIG ")) {
+        const parts = line.split(" ");
+        const bytes = Number.parseInt(parts[3], 10);
+        this._pendingValueBytes = bytes;
+      } else if (line === "END") {
+        const result = this._multilineData.length > 0 ? this._multilineData : void 0;
+        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;
+      }
+      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/auto-discovery.ts
+var AutoDiscovery = class _AutoDiscovery extends Hookified2 {
+  _configEndpoint;
+  _pollingInterval;
+  _useLegacyCommand;
+  _configVersion = -1;
+  _pollingTimer;
+  _configNode;
+  _timeout;
+  _keepAlive;
+  _keepAliveDelay;
+  _sasl;
+  _isRunning = false;
+  _isPolling = false;
+  constructor(options) {
+    super();
+    this._configEndpoint = options.configEndpoint;
+    this._pollingInterval = options.pollingInterval;
+    this._useLegacyCommand = options.useLegacyCommand;
+    this._timeout = options.timeout;
+    this._keepAlive = options.keepAlive;
+    this._keepAliveDelay = options.keepAliveDelay;
+    this._sasl = options.sasl;
+  }
+  /** Current config version. -1 means no config has been fetched yet. */
+  get configVersion() {
+    return this._configVersion;
+  }
+  /** Whether auto discovery is currently running. */
+  get isRunning() {
+    return this._isRunning;
+  }
+  /** The configuration endpoint being used. */
+  get configEndpoint() {
+    return this._configEndpoint;
+  }
+  /**
+   * Start the auto discovery process.
+   * Performs an initial discovery, then starts the polling timer.
+   */
+  async start() {
+    if (this._isRunning) {
+      throw new Error("Auto discovery is already running");
+    }
+    this._isRunning = true;
+    let config;
+    try {
+      const configNode = await this.ensureConfigNode();
+      config = await this.fetchConfig(configNode);
+    } catch (error) {
+      this._isRunning = false;
+      throw error;
+    }
+    this._configVersion = config.version;
+    this.emit("autoDiscover", config);
+    this._pollingTimer = setInterval(() => {
+      void this.poll();
+    }, this._pollingInterval);
+    if (this._pollingTimer && typeof this._pollingTimer === "object" && "unref" in this._pollingTimer) {
+      this._pollingTimer.unref();
+    }
+    return config;
+  }
+  /**
+   * Stop the auto discovery process.
+   */
+  async stop() {
+    this._isRunning = false;
+    if (this._pollingTimer) {
+      clearInterval(this._pollingTimer);
+      this._pollingTimer = void 0;
+    }
+    if (this._configNode) {
+      await this._configNode.disconnect();
+      this._configNode = void 0;
+    }
+  }
+  /**
+   * Perform a single discovery cycle.
+   * Returns the ClusterConfig if the version has changed, or undefined if unchanged.
+   */
+  async discover() {
+    const configNode = await this.ensureConfigNode();
+    const config = await this.fetchConfig(configNode);
+    if (config.version === this._configVersion) {
+      return void 0;
+    }
+    this._configVersion = config.version;
+    return config;
+  }
+  /**
+   * Parse the raw response data from a config get cluster command.
+   * The raw data is the value content between the CONFIG/VALUE header and END.
+   * Format: "<version>\n<host1>|<ip1>|<port1> <host2>|<ip2>|<port2>\n"
+   */
+  static parseConfigResponse(rawData) {
+    if (!rawData || rawData.length === 0) {
+      throw new Error("Empty config response");
+    }
+    const data = rawData.join("");
+    const lines = data.split("\n").filter((line) => line.trim().length > 0);
+    if (lines.length < 2) {
+      throw new Error(
+        "Invalid config response: expected version and node list"
+      );
+    }
+    const version = Number.parseInt(lines[0].trim(), 10);
+    if (Number.isNaN(version)) {
+      throw new Error(`Invalid config version: ${lines[0]}`);
+    }
+    const nodeEntries = lines[1].trim().split(" ").filter((e) => e.length > 0);
+    const nodes = nodeEntries.map(
+      (entry) => _AutoDiscovery.parseNodeEntry(entry)
+    );
+    return { version, nodes };
+  }
+  /**
+   * Parse a single node entry in the format "hostname|ip|port".
+   */
+  static parseNodeEntry(entry) {
+    const parts = entry.split("|");
+    if (parts.length !== 3) {
+      throw new Error(`Invalid node entry format: ${entry}`);
+    }
+    const hostname = parts[0];
+    const ip = parts[1];
+    const port = Number.parseInt(parts[2], 10);
+    if (!hostname) {
+      throw new Error(`Invalid node entry: missing hostname in ${entry}`);
+    }
+    if (Number.isNaN(port) || port <= 0 || port > 65535) {
+      throw new Error(`Invalid port in node entry: ${entry}`);
+    }
+    return { hostname, ip, port };
+  }
+  /**
+   * Build a node ID from a DiscoveredNode.
+   * Prefers IP when available, falls back to hostname.
+   */
+  static nodeId(node) {
+    const host = node.ip || node.hostname;
+    const wrappedHost = host.includes(":") ? `[${host}]` : host;
+    return `${wrappedHost}:${node.port}`;
+  }
+  async ensureConfigNode() {
+    if (this._configNode?.isConnected()) {
+      return this._configNode;
+    }
+    const { host, port } = this.parseEndpoint(this._configEndpoint);
+    this._configNode = new MemcacheNode(host, port, {
+      timeout: this._timeout,
+      keepAlive: this._keepAlive,
+      keepAliveDelay: this._keepAliveDelay,
+      sasl: this._sasl
+    });
+    await this._configNode.connect();
+    return this._configNode;
+  }
+  async fetchConfig(node) {
+    if (!node.isConnected()) {
+      await node.connect();
+    }
+    if (this._useLegacyCommand) {
+      const result2 = await node.command("get AmazonElastiCache:cluster", {
+        isMultiline: true,
+        requestedKeys: ["AmazonElastiCache:cluster"]
+      });
+      if (!result2?.values || result2.values.length === 0) {
+        throw new Error("No config data received from legacy command");
+      }
+      return _AutoDiscovery.parseConfigResponse(result2.values);
+    }
+    const result = await node.command("config get cluster", {
+      isConfig: true
+    });
+    if (!result || result.length === 0) {
+      throw new Error("No config data received");
+    }
+    return _AutoDiscovery.parseConfigResponse(result);
+  }
+  async poll() {
+    if (this._isPolling) {
+      return;
+    }
+    this._isPolling = true;
+    try {
+      const config = await this.discover();
+      if (config) {
+        this.emit("autoDiscoverUpdate", config);
+      }
+    } catch (error) {
+      this.emit("autoDiscoverError", error);
+      try {
+        if (this._configNode && !this._configNode.isConnected()) {
+          await this._configNode.reconnect();
+        }
+      } catch {
+      }
+    } finally {
+      this._isPolling = false;
+    }
+  }
+  parseEndpoint(endpoint) {
+    if (endpoint.startsWith("[")) {
+      const bracketEnd = endpoint.indexOf("]");
+      if (bracketEnd === -1) {
+        throw new Error("Invalid IPv6 endpoint: missing closing bracket");
+      }
+      const host2 = endpoint.slice(1, bracketEnd);
+      const remainder = endpoint.slice(bracketEnd + 1);
+      if (remainder === "" || remainder === ":") {
+        return { host: host2, port: 11211 };
+      }
+      if (remainder.startsWith(":")) {
+        const port2 = Number.parseInt(remainder.slice(1), 10);
+        return { host: host2, port: Number.isNaN(port2) ? 11211 : port2 };
+      }
+      return { host: host2, port: 11211 };
+    }
+    const colonIndex = endpoint.lastIndexOf(":");
+    if (colonIndex === -1) {
+      return { host: endpoint, port: 11211 };
+    }
+    const host = endpoint.slice(0, colonIndex);
+    const port = Number.parseInt(endpoint.slice(colonIndex + 1), 10);
+    return { host, port: Number.isNaN(port) ? 11211 : port };
+  }
+};
+
+// 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 {
-      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;
+      lo = mid + 1;
     }
   }
-  rejectPendingCommands(error) {
-    if (this._currentCommand) {
-      this._currentCommand.reject(error);
-      this._currentCommand = void 0;
+  return lo;
+}
+
+// src/modula.ts
+import { createHash as createHash2 } from "crypto";
+var hashFunctionForBuiltin2 = (algorithm) => (value) => createHash2(algorithm).update(value).digest().readUInt32BE(0);
+var ModulaHash = class {
+  /** The name of this distribution strategy */
+  name = "modula";
+  /** The hash function used to compute key hashes */
+  hashFn;
+  /** Map of node IDs to MemcacheNode instances */
+  nodeMap;
+  /**
+   * Weighted list of node IDs for modulo distribution.
+   * Nodes with higher weights appear multiple times.
+   */
+  nodeList;
+  /**
+   * Creates a new ModulaHash 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 ModulaHash();
+   *
+   * // Use MD5 hashing
+   * const distribution = new ModulaHash('md5');
+   *
+   * // Use custom hash function
+   * const distribution = new ModulaHash((buf) => buf.readUInt32BE(0));
+   * ```
+   */
+  constructor(hashFn) {
+    this.hashFn = typeof hashFn === "string" ? hashFunctionForBuiltin2(hashFn) : hashFn ?? hashFunctionForBuiltin2("sha1");
+    this.nodeMap = /* @__PURE__ */ new Map();
+    this.nodeList = [];
+  }
+  /**
+   * 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.
+   * Weight determines how many times the node appears in the distribution list.
+   *
+   * @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);
+    const weight = node.weight || 1;
+    for (let i = 0; i < weight; i++) {
+      this.nodeList.push(node.id);
     }
-    while (this._commandQueue.length > 0) {
-      const cmd = this._commandQueue.shift();
-      if (cmd) {
-        cmd.reject(error);
-      }
+  }
+  /**
+   * 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.nodeList = this.nodeList.filter((nodeId) => nodeId !== 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 modulo hashing.
+   * Uses `hash(key) % nodeCount` to determine the target node.
+   *
+   * @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) {
+    if (this.nodeList.length === 0) {
+      return [];
     }
+    const hash = this.hashFn(Buffer.from(key));
+    const index = hash % this.nodeList.length;
+    const nodeId = this.nodeList[index];
+    const node = this.nodeMap.get(nodeId);
+    return node ? [node] : [];
   }
 };
-function createNode(host, port, options) {
-  return new MemcacheNode(host, port, options);
-}
 
-// src/index.ts
+// src/types.ts
 var MemcacheEvents = /* @__PURE__ */ ((MemcacheEvents2) => {
   MemcacheEvents2["CONNECT"] = "connect";
   MemcacheEvents2["QUIT"] = "quit";
@@ -664,26 +1581,52 @@ var MemcacheEvents = /* @__PURE__ */ ((MemcacheEvents2) => {
   MemcacheEvents2["INFO"] = "info";
   MemcacheEvents2["TIMEOUT"] = "timeout";
   MemcacheEvents2["CLOSE"] = "close";
+  MemcacheEvents2["AUTO_DISCOVER"] = "autoDiscover";
+  MemcacheEvents2["AUTO_DISCOVER_ERROR"] = "autoDiscoverError";
+  MemcacheEvents2["AUTO_DISCOVER_UPDATE"] = "autoDiscoverUpdate";
   return MemcacheEvents2;
 })(MemcacheEvents || {});
-var Memcache = class extends Hookified2 {
+
+// src/index.ts
+var defaultRetryBackoff = (_attempt, baseDelay) => baseDelay;
+var exponentialRetryBackoff = (attempt, baseDelay) => baseDelay * 2 ** attempt;
+var Memcache = class extends Hookified3 {
   _nodes = [];
   _timeout;
   _keepAlive;
   _keepAliveDelay;
   _hash;
+  _retries;
+  _retryDelay;
+  _retryBackoff;
+  _retryOnlyIdempotent;
+  _sasl;
+  _autoDiscovery;
+  _autoDiscoverOptions;
   constructor(options) {
     super();
-    this._hash = new KetamaHash();
     if (typeof options === "string") {
+      this._hash = new KetamaHash();
       this._timeout = 5e3;
       this._keepAlive = true;
       this._keepAliveDelay = 1e3;
+      this._retries = 0;
+      this._retryDelay = 100;
+      this._retryBackoff = defaultRetryBackoff;
+      this._retryOnlyIdempotent = true;
+      this._sasl = void 0;
       this.addNode(options);
     } else {
+      this._hash = options?.hash ?? new KetamaHash();
       this._timeout = options?.timeout || 5e3;
       this._keepAlive = options?.keepAlive !== false;
       this._keepAliveDelay = options?.keepAliveDelay || 1e3;
+      this._retries = options?.retries ?? 0;
+      this._retryDelay = options?.retryDelay ?? 100;
+      this._retryBackoff = options?.retryBackoff ?? defaultRetryBackoff;
+      this._retryOnlyIdempotent = options?.retryOnlyIdempotent ?? true;
+      this._sasl = options?.sasl;
+      this._autoDiscoverOptions = options?.autoDiscover;
       const nodeUris = options?.nodes || ["localhost:11211"];
       for (const nodeUri of nodeUris) {
         this.addNode(nodeUri);
@@ -788,6 +1731,74 @@ var Memcache = class extends Hookified2 {
     this._keepAliveDelay = value;
     this.updateNodes();
   }
+  /**
+   * Get the number of retry attempts for failed commands.
+   * @returns {number}
+   * @default 0
+   */
+  get retries() {
+    return this._retries;
+  }
+  /**
+   * Set the number of retry attempts for failed commands.
+   * Set to 0 to disable retries.
+   * @param {number} value
+   * @default 0
+   */
+  set retries(value) {
+    this._retries = Math.max(0, Math.floor(value));
+  }
+  /**
+   * Get the base delay in milliseconds between retry attempts.
+   * @returns {number}
+   * @default 100
+   */
+  get retryDelay() {
+    return this._retryDelay;
+  }
+  /**
+   * Set the base delay in milliseconds between retry attempts.
+   * @param {number} value
+   * @default 100
+   */
+  set retryDelay(value) {
+    this._retryDelay = Math.max(0, value);
+  }
+  /**
+   * Get the backoff function for retry delays.
+   * @returns {RetryBackoffFunction}
+   * @default defaultRetryBackoff
+   */
+  get retryBackoff() {
+    return this._retryBackoff;
+  }
+  /**
+   * Set the backoff function for retry delays.
+   * @param {RetryBackoffFunction} value
+   * @default defaultRetryBackoff
+   */
+  set retryBackoff(value) {
+    this._retryBackoff = value;
+  }
+  /**
+   * Get whether retries are restricted to idempotent commands only.
+   * @returns {boolean}
+   * @default true
+   */
+  get retryOnlyIdempotent() {
+    return this._retryOnlyIdempotent;
+  }
+  /**
+   * Set whether retries are restricted to idempotent commands only.
+   * When true (default), retries only occur for commands explicitly marked
+   * as idempotent via ExecuteOptions. This prevents accidental double-execution
+   * of non-idempotent operations like incr, decr, append, etc.
+   * @param {boolean} value
+   * @default true
+   */
+  set retryOnlyIdempotent(value) {
+    this._retryOnlyIdempotent = value;
+  }
   /**
    * Get an array of all MemcacheNode instances
    * @returns {MemcacheNode[]}
@@ -821,7 +1832,8 @@ var Memcache = class extends Hookified2 {
         timeout: this._timeout,
         keepAlive: this._keepAlive,
         keepAliveDelay: this._keepAliveDelay,
-        weight
+        weight,
+        sasl: this._sasl
       });
     } else {
       node = uri;
@@ -930,6 +1942,9 @@ var Memcache = class extends Hookified2 {
       return;
     }
     await Promise.all(this._nodes.map((node) => node.connect()));
+    if (this._autoDiscoverOptions?.enabled && !this._autoDiscovery) {
+      await this.startAutoDiscovery();
+    }
   }
   /**
    * Get a value from the Memcache server.
@@ -1289,6 +2304,10 @@ ${valueStr}`;
    * @returns {Promise<void>}
    */
   async quit() {
+    if (this._autoDiscovery) {
+      await this._autoDiscovery.stop();
+      this._autoDiscovery = void 0;
+    }
     await Promise.all(
       this._nodes.map(async (node) => {
         if (node.isConnected()) {
@@ -1302,6 +2321,10 @@ ${valueStr}`;
    * @returns {Promise<void>}
    */
   async disconnect() {
+    if (this._autoDiscovery) {
+      await this._autoDiscovery.stop();
+      this._autoDiscovery = void 0;
+    }
     await Promise.all(this._nodes.map((node) => node.disconnect()));
   }
   /**
@@ -1339,19 +2362,27 @@ ${valueStr}`;
     return nodes;
   }
   /**
-   * Execute a command on the specified nodes.
+   * Execute a command on the specified nodes with retry support.
    * @param {string} command - The memcache command string to execute
    * @param {MemcacheNode[]} nodes - Array of MemcacheNode instances to execute on
-   * @param {ExecuteOptions} options - Optional execution options
+   * @param {ExecuteOptions} options - Optional execution options including retry overrides
    * @returns {Promise<unknown[]>} Promise resolving to array of results from each node
    */
   async execute(command, nodes, options) {
+    const configuredRetries = options?.retries ?? this._retries;
+    const retryDelay = options?.retryDelay ?? this._retryDelay;
+    const retryBackoff = options?.retryBackoff ?? this._retryBackoff;
+    const isIdempotent = options?.idempotent === true;
+    const maxRetries = this._retryOnlyIdempotent && !isIdempotent ? 0 : configuredRetries;
     const promises = nodes.map(async (node) => {
-      try {
-        return await node.command(command, options?.commandOptions);
-      } catch {
-        return void 0;
-      }
+      return this.executeWithRetry(
+        node,
+        command,
+        options?.commandOptions,
+        maxRetries,
+        retryDelay,
+        retryBackoff
+      );
     });
     return Promise.all(promises);
   }
@@ -1382,6 +2413,46 @@ ${valueStr}`;
     }
   }
   // Private methods
+  /**
+   * Sleep utility for retry delays.
+   * @param {number} ms - Milliseconds to sleep
+   * @returns {Promise<void>}
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  /**
+   * Execute a command on a single node with retry logic.
+   * @param {MemcacheNode} node - The node to execute on
+   * @param {string} command - The command string
+   * @param {CommandOptions} commandOptions - Optional command options
+   * @param {number} maxRetries - Maximum number of retry attempts
+   * @param {number} retryDelay - Base delay between retries in milliseconds
+   * @param {RetryBackoffFunction} retryBackoff - Function to calculate backoff delay
+   * @returns {Promise<unknown>} Result or undefined on failure
+   */
+  async executeWithRetry(node, command, commandOptions, maxRetries, retryDelay, retryBackoff) {
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        return await node.command(command, commandOptions);
+      } catch {
+        if (attempt >= maxRetries) {
+          break;
+        }
+        const delay = retryBackoff(attempt, retryDelay);
+        if (delay > 0) {
+          await this.sleep(delay);
+        }
+        if (!node.isConnected()) {
+          try {
+            await node.connect();
+          } catch {
+          }
+        }
+      }
+    }
+    return void 0;
+  }
   /**
    * Update all nodes with current keepAlive settings
    */
@@ -1408,12 +2479,92 @@ ${valueStr}`;
     );
     node.on("miss", (key) => this.emit("miss" /* MISS */, key));
   }
+  async startAutoDiscovery() {
+    const options = this._autoDiscoverOptions;
+    if (!options) {
+      return;
+    }
+    const configEndpoint = options.configEndpoint || (this._nodes.length > 0 ? this._nodes[0].id : "localhost:11211");
+    this._autoDiscovery = new AutoDiscovery({
+      configEndpoint,
+      pollingInterval: options.pollingInterval ?? 6e4,
+      useLegacyCommand: options.useLegacyCommand ?? false,
+      timeout: this._timeout,
+      keepAlive: this._keepAlive,
+      keepAliveDelay: this._keepAliveDelay,
+      sasl: this._sasl
+    });
+    this._autoDiscovery.on("autoDiscover", (config) => {
+      this.emit("autoDiscover" /* AUTO_DISCOVER */, config);
+    });
+    this._autoDiscovery.on("autoDiscoverError", (error) => {
+      this.emit("autoDiscoverError" /* AUTO_DISCOVER_ERROR */, error);
+    });
+    this._autoDiscovery.on(
+      "autoDiscoverUpdate",
+      /* v8 ignore next -- @preserve */
+      async (config) => {
+        this.emit("autoDiscoverUpdate" /* AUTO_DISCOVER_UPDATE */, config);
+        try {
+          await this.applyClusterConfig(config);
+        } catch (error) {
+          this.emit("autoDiscoverError" /* AUTO_DISCOVER_ERROR */, error);
+        }
+      }
+    );
+    try {
+      const initialConfig = await this._autoDiscovery.start();
+      await this.applyClusterConfig(initialConfig);
+    } catch (error) {
+      this.emit("autoDiscoverError" /* AUTO_DISCOVER_ERROR */, error);
+    }
+  }
+  async applyClusterConfig(config) {
+    if (config.nodes.length === 0) {
+      this.emit(
+        "autoDiscoverError" /* AUTO_DISCOVER_ERROR */,
+        new Error("Discovery returned zero nodes; keeping current topology")
+      );
+      return;
+    }
+    const discoveredNodeIds = new Set(
+      config.nodes.map((n) => AutoDiscovery.nodeId(n))
+    );
+    const currentNodeIds = new Set(this.nodeIds);
+    for (const node of config.nodes) {
+      const id = AutoDiscovery.nodeId(node);
+      if (!currentNodeIds.has(id)) {
+        try {
+          const host = node.ip || node.hostname;
+          const wrappedHost = host.includes(":") ? `[${host}]` : host;
+          await this.addNode(`${wrappedHost}:${node.port}`);
+        } catch (error) {
+          this.emit("error" /* ERROR */, id, error);
+        }
+      }
+    }
+    for (const nodeId of currentNodeIds) {
+      if (!discoveredNodeIds.has(nodeId)) {
+        try {
+          await this.removeNode(nodeId);
+        } catch (error) {
+          this.emit("error" /* ERROR */, nodeId, error);
+        }
+      }
+    }
+  }
 };
 var index_default = Memcache;
 export {
+  AutoDiscovery,
   Memcache,
   MemcacheEvents,
+  MemcacheNode,
+  ModulaHash,
   createNode,
-  index_default as default
+  index_default as default,
+  defaultRetryBackoff,
+  exponentialRetryBackoff
 };
 /* v8 ignore next -- @preserve */
+/* v8 ignore next 3 -- @preserve */