memcache 1.0.0 → 1.2.0

package/README.md

@@ -1,7 +1,7 @@
-[<img src="./site/logo_medium.png" alt="Memcache Logo" align="center">](https://memcachejs.org)
+[<img src="https://jaredwray.com/images/memcache.svg" alt="Memcache Logo" align="center">](https://memcachejs.org)
 
 [![codecov](https://codecov.io/gh/jaredwray/memcache/graph/badge.svg?token=4DUANNWiIE)](https://codecov.io/gh/jaredwray/memcache)
-[![tests](https://github.com/jaredwray/memcache/actions/workflows/tests.yml/badge.svg)](https://github.com/jaredwray/memcache/actions/workflows/tests.yml)
+[![tests](https://github.com/jaredwray/memcache/actions/workflows/tests.yaml/badge.svg)](https://github.com/jaredwray/memcache/actions/workflows/tests.yaml)
 [![npm](https://img.shields.io/npm/v/memcache)](https://www.npmjs.com/package/memcache)
 [![npm](https://img.shields.io/npm/dm/memcache)](https://www.npmjs.com/package/memcache)
 [![license](https://img.shields.io/github/license/jaredwray/memcache)](https://github.com/jaredwray/memcache/blob/main/LICENSE)
@@ -83,15 +83,93 @@ await client.delete('mykey');
 await client.quit();
 ```
 
+You can also just pass in the `uri` into the constructor
+
+```javascript
+// Single node as string
+const client = new Memcache('localhost:11211');
+
+// Single node with protocol
+const client = new Memcache('memcache://192.168.1.100:11211');
+
+// Multiple nodes with options
+const client = new Memcache({
+  nodes: ['localhost:11211', 'server2:11211'],
+  timeout: 10000
+});
+```
+
+You can specify multiple Memcache nodes by passing an array of connection strings:
+
+```javascript
+import { Memcache } from 'memcache';
+
+// Create a client with multiple nodes
+const client = new Memcache({
+  nodes: ['localhost:11211', '192.168.1.100:11211', 'memcache://192.168.1.101:11211']
+});
+
+// Set and get values (automatically distributed across nodes)
+await client.set('mykey', 'Hello, Memcache!');
+const value = await client.get('mykey');
+console.log(value); // ['Hello, Memcache!']
+
+// Close the connection
+await client.quit();
+```
+
+You can also pass an array of MemcacheNode instances for advanced configuration:
+
+```javascript
+import { Memcache, createNode } from 'memcache';
+
+// Create nodes with custom settings
+const node1 = createNode('localhost', 11211, { weight: 2 });
+const node2 = createNode('192.168.1.100', 11211, { weight: 1 });
+const node3 = createNode('192.168.1.101', 11211, { weight: 1 });
+
+// Create a client with MemcacheNode instances
+const client = new Memcache({
+  nodes: [node1, node2, node3],
+  timeout: 10000
+});
+
+// node1 will receive twice as much traffic due to higher weight
+await client.set('mykey', 'Hello, Memcache!');
+const value = await client.get('mykey');
+console.log(value); // ['Hello, Memcache!']
+
+// Close the connection
+await client.quit();
+```
+
 # API
 
 ## Constructor
 
 ```typescript
-new Memcache(options?: MemcacheOptions)
+new Memcache(options?: string | MemcacheOptions)
 ```
 
-Creates a new Memcache client instance.
+Creates a new Memcache client instance. You can pass either:
+- A **string** representing a single node URI (uses default settings)
+- A **MemcacheOptions** object for custom configuration
+
+**Examples:**
+
+```javascript
+// Single node as string
+const client = new Memcache('localhost:11211');
+
+// Single node with protocol
+const client = new Memcache('memcache://192.168.1.100:11211');
+
+// Multiple nodes with options
+const client = new Memcache({
+  nodes: ['localhost:11211', 'server2:11211'],
+  timeout: 10000
+});
+```
 
 ### Options
 

package/dist/index.cjs

@@ -702,12 +702,19 @@ var Memcache = class extends import_hookified2.Hookified {
   constructor(options) {
     super();
     this._hash = new KetamaHash();
-    this._timeout = options?.timeout || 5e3;
-    this._keepAlive = options?.keepAlive !== false;
-    this._keepAliveDelay = options?.keepAliveDelay || 1e3;
-    const nodeUris = options?.nodes || ["localhost:11211"];
-    for (const nodeUri of nodeUris) {
-      this.addNode(nodeUri);
+    if (typeof options === "string") {
+      this._timeout = 5e3;
+      this._keepAlive = true;
+      this._keepAliveDelay = 1e3;
+      this.addNode(options);
+    } else {
+      this._timeout = options?.timeout || 5e3;
+      this._keepAlive = options?.keepAlive !== false;
+      this._keepAliveDelay = options?.keepAliveDelay || 1e3;
+      const nodeUris = options?.nodes || ["localhost:11211"];
+      for (const nodeUri of nodeUris) {
+        this.addNode(nodeUri);
+      }
     }
   }
   /**
@@ -1056,16 +1063,8 @@ var Memcache = class extends import_hookified2.Hookified {
     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,
@@ -1094,16 +1093,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;
   }
@@ -1125,16 +1116,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;
   }
@@ -1156,16 +1139,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;
   }
@@ -1185,16 +1160,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;
   }
@@ -1214,16 +1181,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;
   }
@@ -1238,16 +1197,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;
   }
@@ -1263,16 +1214,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;
   }
@@ -1288,16 +1231,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;
   }
@@ -1313,16 +1248,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;
   }
@@ -1438,6 +1365,23 @@ ${valueStr}`;
     }
     return nodes;
   }
+  /**
+   * Execute a command on the specified nodes.
+   * @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
+   * @returns {Promise<unknown[]>} Promise resolving to array of results from each node
+   */
+  async execute(command, nodes, options) {
+    const promises = nodes.map(async (node) => {
+      try {
+        return await node.command(command, options?.commandOptions);
+      } catch {
+        return void 0;
+      }
+    });
+    return Promise.all(promises);
+  }
   /**
    * Validates a Memcache key according to protocol requirements.
    * @param {string} key - The key to validate

package/dist/index.d.cts

@@ -187,13 +187,17 @@ interface MemcacheOptions {
 interface MemcacheStats {
     [key: string]: string;
 }
+interface ExecuteOptions {
+    /** Command options passed to node.command() */
+    commandOptions?: CommandOptions;
+}
 declare class Memcache extends Hookified {
     private _nodes;
     private _timeout;
     private _keepAlive;
     private _keepAliveDelay;
     private _hash;
-    constructor(options?: MemcacheOptions);
+    constructor(options?: string | MemcacheOptions);
     /**
      * Get the list of nodes
      * @returns {MemcacheNode[]} Array of MemcacheNode
@@ -474,6 +478,14 @@ declare class Memcache extends Hookified {
      * @throws {Error} If no nodes are available for the key
      */
     getNodesByKey(key: string): Promise<Array<MemcacheNode>>;
+    /**
+     * Execute a command on the specified nodes.
+     * @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
+     * @returns {Promise<unknown[]>} Promise resolving to array of results from each node
+     */
+    execute(command: string, nodes: MemcacheNode[], options?: ExecuteOptions): Promise<unknown[]>;
     /**
      * Validates a Memcache key according to protocol requirements.
      * @param {string} key - The key to validate
@@ -498,4 +510,4 @@ declare class Memcache extends Hookified {
     private forwardNodeEvents;
 }
 
-export { type HashProvider, Memcache, MemcacheEvents, type MemcacheOptions, type MemcacheStats, createNode, Memcache as default };
+export { type ExecuteOptions, type HashProvider, Memcache, MemcacheEvents, type MemcacheOptions, type MemcacheStats, createNode, Memcache as default };

package/dist/index.d.ts

@@ -187,13 +187,17 @@ interface MemcacheOptions {
 interface MemcacheStats {
     [key: string]: string;
 }
+interface ExecuteOptions {
+    /** Command options passed to node.command() */
+    commandOptions?: CommandOptions;
+}
 declare class Memcache extends Hookified {
     private _nodes;
     private _timeout;
     private _keepAlive;
     private _keepAliveDelay;
     private _hash;
-    constructor(options?: MemcacheOptions);
+    constructor(options?: string | MemcacheOptions);
     /**
      * Get the list of nodes
      * @returns {MemcacheNode[]} Array of MemcacheNode
@@ -474,6 +478,14 @@ declare class Memcache extends Hookified {
      * @throws {Error} If no nodes are available for the key
      */
     getNodesByKey(key: string): Promise<Array<MemcacheNode>>;
+    /**
+     * Execute a command on the specified nodes.
+     * @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
+     * @returns {Promise<unknown[]>} Promise resolving to array of results from each node
+     */
+    execute(command: string, nodes: MemcacheNode[], options?: ExecuteOptions): Promise<unknown[]>;
     /**
      * Validates a Memcache key according to protocol requirements.
      * @param {string} key - The key to validate
@@ -498,4 +510,4 @@ declare class Memcache extends Hookified {
     private forwardNodeEvents;
 }
 
-export { type HashProvider, Memcache, MemcacheEvents, type MemcacheOptions, type MemcacheStats, createNode, Memcache as default };
+export { type ExecuteOptions, type HashProvider, Memcache, MemcacheEvents, type MemcacheOptions, type MemcacheStats, createNode, Memcache as default };

package/dist/index.js

@@ -675,12 +675,19 @@ var Memcache = class extends Hookified2 {
   constructor(options) {
     super();
     this._hash = new KetamaHash();
-    this._timeout = options?.timeout || 5e3;
-    this._keepAlive = options?.keepAlive !== false;
-    this._keepAliveDelay = options?.keepAliveDelay || 1e3;
-    const nodeUris = options?.nodes || ["localhost:11211"];
-    for (const nodeUri of nodeUris) {
-      this.addNode(nodeUri);
+    if (typeof options === "string") {
+      this._timeout = 5e3;
+      this._keepAlive = true;
+      this._keepAliveDelay = 1e3;
+      this.addNode(options);
+    } else {
+      this._timeout = options?.timeout || 5e3;
+      this._keepAlive = options?.keepAlive !== false;
+      this._keepAliveDelay = options?.keepAliveDelay || 1e3;
+      const nodeUris = options?.nodes || ["localhost:11211"];
+      for (const nodeUri of nodeUris) {
+        this.addNode(nodeUri);
+      }
     }
   }
   /**
@@ -1029,16 +1036,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,
@@ -1067,16 +1066,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;
   }
@@ -1098,16 +1089,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;
   }
@@ -1129,16 +1112,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;
   }
@@ -1158,16 +1133,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;
   }
@@ -1187,16 +1154,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;
   }
@@ -1211,16 +1170,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;
   }
@@ -1236,16 +1187,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;
   }
@@ -1261,16 +1204,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;
   }
@@ -1286,16 +1221,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;
   }
@@ -1411,6 +1338,23 @@ ${valueStr}`;
     }
     return nodes;
   }
+  /**
+   * Execute a command on the specified nodes.
+   * @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
+   * @returns {Promise<unknown[]>} Promise resolving to array of results from each node
+   */
+  async execute(command, nodes, options) {
+    const promises = nodes.map(async (node) => {
+      try {
+        return await node.command(command, options?.commandOptions);
+      } catch {
+        return void 0;
+      }
+    });
+    return Promise.all(promises);
+  }
   /**
    * Validates a Memcache key according to protocol requirements.
    * @param {string} key - The key to validate