memcache 1.1.0 → 1.3.0

package/dist/index.js

@@ -322,9 +322,390 @@ function binarySearchRing(ring, hash) {
   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);
+    }
+  }
+  /**
+   * 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] : [];
+  }
+};
+
 // 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;
@@ -339,6 +720,9 @@ var MemcacheNode = class extends Hookified {
   _currentCommand = void 0;
   _multilineData = [];
   _pendingValueBytes = 0;
+  _sasl;
+  _authenticated = false;
+  _binaryBuffer = Buffer.alloc(0);
   constructor(host, port, options) {
     super();
     this._host = host;
@@ -347,6 +731,7 @@ var MemcacheNode = class extends Hookified {
     this._keepAlive = options?.keepAlive !== false;
     this._keepAliveDelay = options?.keepAliveDelay || 1e3;
     this._weight = options?.weight || 1;
+    this._sasl = options?.sasl;
   }
   /**
    * Get the host of this node
@@ -420,6 +805,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 +833,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 +867,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,9 +901,257 @@ 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();
   }
+  /**
+   * Perform SASL PLAIN authentication using the binary protocol
+   */
+  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);
+    });
+  }
+  /**
+   * Send a binary protocol request and wait for response.
+   * Used internally for SASL-authenticated connections.
+   */
+  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);
+    });
+  }
+  /**
+   * Binary protocol GET operation
+   */
+  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;
+    }
+    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)
    */
@@ -653,7 +1316,7 @@ 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";
@@ -666,24 +1329,44 @@ var MemcacheEvents = /* @__PURE__ */ ((MemcacheEvents2) => {
   MemcacheEvents2["CLOSE"] = "close";
   return MemcacheEvents2;
 })(MemcacheEvents || {});
+
+// src/index.ts
+var defaultRetryBackoff = (_attempt, baseDelay) => baseDelay;
+var exponentialRetryBackoff = (attempt, baseDelay) => baseDelay * 2 ** attempt;
 var Memcache = class extends Hookified2 {
   _nodes = [];
   _timeout;
   _keepAlive;
   _keepAliveDelay;
   _hash;
+  _retries;
+  _retryDelay;
+  _retryBackoff;
+  _retryOnlyIdempotent;
+  _sasl;
   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;
       const nodeUris = options?.nodes || ["localhost:11211"];
       for (const nodeUri of nodeUris) {
         this.addNode(nodeUri);
@@ -788,6 +1471,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 +1572,8 @@ var Memcache = class extends Hookified2 {
         timeout: this._timeout,
         keepAlive: this._keepAlive,
         keepAliveDelay: this._keepAliveDelay,
-        weight
+        weight,
+        sasl: this._sasl
       });
     } else {
       node = uri;
@@ -1036,16 +1788,8 @@ var Memcache = class extends Hookified2 {
     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);
+    const results = await this.execute(command, nodes);
+    const success = results.every((result) => result === "STORED");
     await this.afterHook("cas", {
       key,
       value,
@@ -1074,16 +1818,8 @@ ${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);
+    const results = await this.execute(command, nodes);
+    const success = results.every((result) => result === "STORED");
     await this.afterHook("set", { key, value, exptime, flags, success });
     return success;
   }
@@ -1105,16 +1841,8 @@ ${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);
+    const results = await this.execute(command, nodes);
+    const success = results.every((result) => result === "STORED");
     await this.afterHook("add", { key, value, exptime, flags, success });
     return success;
   }
@@ -1136,16 +1864,8 @@ ${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);
+    const results = await this.execute(command, nodes);
+    const success = results.every((result) => result === "STORED");
     await this.afterHook("replace", { key, value, exptime, flags, success });
     return success;
   }
@@ -1165,16 +1885,8 @@ ${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);
+    const results = await this.execute(command, nodes);
+    const success = results.every((result) => result === "STORED");
     await this.afterHook("append", { key, value, success });
     return success;
   }
@@ -1194,16 +1906,8 @@ ${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);
+    const results = await this.execute(command, nodes);
+    const success = results.every((result) => result === "STORED");
     await this.afterHook("prepend", { key, value, success });
     return success;
   }
@@ -1218,16 +1922,8 @@ ${valueStr}`;
     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);
+    const results = await this.execute(`delete ${key}`, nodes);
+    const success = results.every((result) => result === "DELETED");
     await this.afterHook("delete", { key, success });
     return success;
   }
@@ -1243,16 +1939,8 @@ ${valueStr}`;
     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);
+    const results = await this.execute(`incr ${key} ${value}`, nodes);
+    const newValue = results.find((v) => typeof v === "number");
     await this.afterHook("incr", { key, value, newValue });
     return newValue;
   }
@@ -1268,16 +1956,8 @@ ${valueStr}`;
     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);
+    const results = await this.execute(`decr ${key} ${value}`, nodes);
+    const newValue = results.find((v) => typeof v === "number");
     await this.afterHook("decr", { key, value, newValue });
     return newValue;
   }
@@ -1293,16 +1973,8 @@ ${valueStr}`;
     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);
+    const results = await this.execute(`touch ${key} ${exptime}`, nodes);
+    const success = results.every((result) => result === "TOUCHED");
     await this.afterHook("touch", { key, exptime, success });
     return success;
   }
@@ -1418,6 +2090,31 @@ ${valueStr}`;
     }
     return 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 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) => {
+      return this.executeWithRetry(
+        node,
+        command,
+        options?.commandOptions,
+        maxRetries,
+        retryDelay,
+        retryBackoff
+      );
+    });
+    return Promise.all(promises);
+  }
   /**
    * Validates a Memcache key according to protocol requirements.
    * @param {string} key - The key to validate
@@ -1445,6 +2142,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
    */
@@ -1476,7 +2213,12 @@ var index_default = Memcache;
 export {
   Memcache,
   MemcacheEvents,
+  MemcacheNode,
+  ModulaHash,
   createNode,
-  index_default as default
+  index_default as default,
+  defaultRetryBackoff,
+  exponentialRetryBackoff
 };
 /* v8 ignore next -- @preserve */
+/* v8 ignore next 3 -- @preserve */