memcache 1.3.0 → 1.5.0

package/dist/index.d.cts

@@ -1,139 +1,6 @@
 import { Hookified } from 'hookified';
 import { Socket } from 'node:net';
 
-/**
- * SASL authentication credentials for connecting to a secured memcache server.
- */
-interface SASLCredentials {
-    /**
-     * Username for SASL authentication
-     */
-    username: string;
-    /**
-     * Password for SASL authentication
-     */
-    password: string;
-    /**
-     * SASL mechanism to use (default: 'PLAIN')
-     * Currently only 'PLAIN' is supported.
-     */
-    mechanism?: "PLAIN";
-}
-declare enum MemcacheEvents {
-    CONNECT = "connect",
-    QUIT = "quit",
-    HIT = "hit",
-    MISS = "miss",
-    ERROR = "error",
-    WARN = "warn",
-    INFO = "info",
-    TIMEOUT = "timeout",
-    CLOSE = "close"
-}
-/**
- * Function to calculate delay between retry attempts.
- * @param attempt - The current attempt number (0-indexed)
- * @param baseDelay - The base delay in milliseconds
- * @returns The delay in milliseconds before the next retry
- */
-type RetryBackoffFunction = (attempt: number, baseDelay: number) => number;
-interface HashProvider {
-    name: string;
-    nodes: Array<MemcacheNode>;
-    addNode: (node: MemcacheNode) => void;
-    removeNode: (id: string) => void;
-    getNode: (id: string) => MemcacheNode | undefined;
-    getNodesByKey: (key: string) => Array<MemcacheNode>;
-}
-interface MemcacheOptions {
-    /**
-     * Array of node URIs or MemcacheNode instances to add to the consistent hashing ring.
-     * Examples: ["localhost:11211", "memcache://192.168.1.100:11212", "server3:11213"]
-     * Can also pass MemcacheNode instances directly: [createNode("localhost", 11211), createNode("server2", 11211)]
-     */
-    nodes?: (string | MemcacheNode)[];
-    /**
-     * The timeout for Memcache operations.
-     * @default 5000
-     */
-    timeout?: number;
-    /**
-     * Whether to keep the connection alive.
-     * @default true
-     */
-    keepAlive?: boolean;
-    /**
-     * The delay before the connection is kept alive.
-     * @default 1000
-     */
-    keepAliveDelay?: number;
-    /**
-     * The hash provider used to determine the distribution on each item is placed based
-     * on the number of nodes and hashing. By default it uses KetamaHash as the provider
-     */
-    hash?: HashProvider;
-    /**
-     * The number of retry attempts for failed commands.
-     * Set to 0 to disable retries.
-     * @default 0
-     */
-    retries?: number;
-    /**
-     * The base delay in milliseconds between retry attempts.
-     * @default 100
-     */
-    retryDelay?: number;
-    /**
-     * Function to calculate backoff delay between retries.
-     * Receives (attempt, baseDelay) and returns delay in ms.
-     * @default defaultRetryBackoff (fixed delay)
-     */
-    retryBackoff?: RetryBackoffFunction;
-    /**
-     * When true, retries are only performed for commands marked as idempotent.
-     * This prevents accidental double-execution of non-idempotent operations
-     * (like incr, decr, append) if the server applies the command but the
-     * client doesn't receive the response before a timeout/disconnect.
-     * @default true
-     */
-    retryOnlyIdempotent?: boolean;
-    /**
-     * SASL authentication credentials for all nodes.
-     * When provided, nodes will authenticate using SASL PLAIN mechanism
-     * before accepting commands.
-     */
-    sasl?: SASLCredentials;
-}
-interface MemcacheStats {
-    [key: string]: string;
-}
-interface ExecuteOptions {
-    /** Command options passed to node.command() */
-    commandOptions?: CommandOptions;
-    /**
-     * Override the number of retries for this specific execution.
-     * If undefined, uses the instance-level retries setting.
-     */
-    retries?: number;
-    /**
-     * Override the retry delay for this specific execution.
-     * If undefined, uses the instance-level retryDelay setting.
-     */
-    retryDelay?: number;
-    /**
-     * Override the backoff function for this specific execution.
-     * If undefined, uses the instance-level retryBackoff setting.
-     */
-    retryBackoff?: RetryBackoffFunction;
-    /**
-     * Mark this command as idempotent, allowing retries even when
-     * retryOnlyIdempotent is true. Set this for read operations (get, gets)
-     * or operations that are safe to repeat (set with same value).
-     * @default false
-     */
-    idempotent?: boolean;
-}
-
 interface MemcacheNodeOptions {
     timeout?: number;
     keepAlive?: boolean;
@@ -145,6 +12,7 @@ interface MemcacheNodeOptions {
 interface CommandOptions {
     isMultiline?: boolean;
     isStats?: boolean;
+    isConfig?: boolean;
     requestedKeys?: string[];
 }
 type CommandQueueItem = {
@@ -153,6 +21,7 @@ type CommandQueueItem = {
     reject: (reason?: any) => void;
     isMultiline?: boolean;
     isStats?: boolean;
+    isConfig?: boolean;
     requestedKeys?: string[];
     foundKeys?: string[];
 };
@@ -348,6 +217,324 @@ declare class MemcacheNode extends Hookified {
  */
 declare function createNode(host: string, port: number, options?: MemcacheNodeOptions): MemcacheNode;
 
+/**
+ * SASL authentication credentials for connecting to a secured memcache server.
+ */
+interface SASLCredentials {
+    /**
+     * Username for SASL authentication
+     */
+    username: string;
+    /**
+     * Password for SASL authentication
+     */
+    password: string;
+    /**
+     * SASL mechanism to use (default: 'PLAIN')
+     * Currently only 'PLAIN' is supported.
+     */
+    mechanism?: "PLAIN";
+}
+declare enum MemcacheEvents {
+    CONNECT = "connect",
+    QUIT = "quit",
+    HIT = "hit",
+    MISS = "miss",
+    ERROR = "error",
+    WARN = "warn",
+    INFO = "info",
+    TIMEOUT = "timeout",
+    CLOSE = "close",
+    AUTO_DISCOVER = "autoDiscover",
+    AUTO_DISCOVER_ERROR = "autoDiscoverError",
+    AUTO_DISCOVER_UPDATE = "autoDiscoverUpdate"
+}
+/**
+ * Function to calculate delay between retry attempts.
+ * @param attempt - The current attempt number (0-indexed)
+ * @param baseDelay - The base delay in milliseconds
+ * @returns The delay in milliseconds before the next retry
+ */
+type RetryBackoffFunction = (attempt: number, baseDelay: number) => number;
+interface HashProvider {
+    name: string;
+    nodes: Array<MemcacheNode>;
+    addNode: (node: MemcacheNode) => void;
+    removeNode: (id: string) => void;
+    getNode: (id: string) => MemcacheNode | undefined;
+    getNodesByKey: (key: string) => Array<MemcacheNode>;
+}
+interface MemcacheOptions {
+    /**
+     * Array of node URIs or MemcacheNode instances to add to the consistent hashing ring.
+     * Examples: ["localhost:11211", "memcache://192.168.1.100:11212", "server3:11213"]
+     * Can also pass MemcacheNode instances directly: [createNode("localhost", 11211), createNode("server2", 11211)]
+     */
+    nodes?: (string | MemcacheNode)[];
+    /**
+     * The timeout for Memcache operations.
+     * @default 5000
+     */
+    timeout?: number;
+    /**
+     * Whether to keep the connection alive.
+     * @default true
+     */
+    keepAlive?: boolean;
+    /**
+     * The delay before the connection is kept alive.
+     * @default 1000
+     */
+    keepAliveDelay?: number;
+    /**
+     * The hash provider used to determine the distribution on each item is placed based
+     * on the number of nodes and hashing. By default it uses KetamaHash as the provider
+     */
+    hash?: HashProvider;
+    /**
+     * The number of retry attempts for failed commands.
+     * Set to 0 to disable retries.
+     * @default 0
+     */
+    retries?: number;
+    /**
+     * The base delay in milliseconds between retry attempts.
+     * @default 100
+     */
+    retryDelay?: number;
+    /**
+     * Function to calculate backoff delay between retries.
+     * Receives (attempt, baseDelay) and returns delay in ms.
+     * @default defaultRetryBackoff (fixed delay)
+     */
+    retryBackoff?: RetryBackoffFunction;
+    /**
+     * When true, retries are only performed for commands marked as idempotent.
+     * This prevents accidental double-execution of non-idempotent operations
+     * (like incr, decr, append) if the server applies the command but the
+     * client doesn't receive the response before a timeout/disconnect.
+     * @default true
+     */
+    retryOnlyIdempotent?: boolean;
+    /**
+     * SASL authentication credentials for all nodes.
+     * When provided, nodes will authenticate using SASL PLAIN mechanism
+     * before accepting commands.
+     */
+    sasl?: SASLCredentials;
+    /**
+     * AWS ElastiCache Auto Discovery configuration.
+     * When enabled, the client will periodically poll the configuration endpoint
+     * to detect cluster topology changes and automatically update the node list.
+     */
+    autoDiscover?: AutoDiscoverOptions;
+}
+interface MemcacheStats {
+    [key: string]: string;
+}
+/**
+ * Configuration for AWS ElastiCache Auto Discovery.
+ * When enabled, the client connects to a configuration endpoint and periodically
+ * polls for cluster topology changes, automatically adding/removing nodes.
+ */
+interface AutoDiscoverOptions {
+    /**
+     * Enable auto discovery of cluster nodes.
+     */
+    enabled: boolean;
+    /**
+     * How often to poll for topology changes, in milliseconds.
+     * @default 60000
+     */
+    pollingInterval?: number;
+    /**
+     * The configuration endpoint to use for discovery.
+     * This is typically the .cfg endpoint from ElastiCache.
+     * If not specified, the first node in the nodes array will be used.
+     */
+    configEndpoint?: string;
+    /**
+     * Use the legacy `get AmazonElastiCache:cluster` command
+     * instead of `config get cluster` (for engine versions < 1.4.14).
+     * @default false
+     */
+    useLegacyCommand?: boolean;
+}
+/**
+ * Represents a discovered node from the ElastiCache cluster configuration.
+ */
+interface DiscoveredNode {
+    /** The hostname of the node */
+    hostname: string;
+    /** The IP address of the node (may be empty string) */
+    ip: string;
+    /** The port number of the node */
+    port: number;
+}
+/**
+ * Represents the parsed result of an ElastiCache cluster config response.
+ */
+interface ClusterConfig {
+    /** The config version number (increments on topology changes) */
+    version: number;
+    /** The list of discovered nodes */
+    nodes: DiscoveredNode[];
+}
+interface ExecuteOptions {
+    /** Command options passed to node.command() */
+    commandOptions?: CommandOptions;
+    /**
+     * Override the number of retries for this specific execution.
+     * If undefined, uses the instance-level retries setting.
+     */
+    retries?: number;
+    /**
+     * Override the retry delay for this specific execution.
+     * If undefined, uses the instance-level retryDelay setting.
+     */
+    retryDelay?: number;
+    /**
+     * Override the backoff function for this specific execution.
+     * If undefined, uses the instance-level retryBackoff setting.
+     */
+    retryBackoff?: RetryBackoffFunction;
+    /**
+     * Mark this command as idempotent, allowing retries even when
+     * retryOnlyIdempotent is true. Set this for read operations (get, gets)
+     * or operations that are safe to repeat (set with same value).
+     * @default false
+     */
+    idempotent?: boolean;
+}
+
+interface AutoDiscoveryOptions {
+    configEndpoint: string;
+    pollingInterval: number;
+    useLegacyCommand: boolean;
+    timeout: number;
+    keepAlive: boolean;
+    keepAliveDelay: number;
+    sasl?: SASLCredentials;
+}
+/**
+ * Handles AWS ElastiCache Auto Discovery for memcache clusters.
+ * Connects to a configuration endpoint, periodically polls for cluster
+ * topology changes, and emits events when nodes are added or removed.
+ */
+declare class AutoDiscovery extends Hookified {
+    private _configEndpoint;
+    private _pollingInterval;
+    private _useLegacyCommand;
+    private _configVersion;
+    private _pollingTimer;
+    private _configNode;
+    private _timeout;
+    private _keepAlive;
+    private _keepAliveDelay;
+    private _sasl;
+    private _isRunning;
+    private _isPolling;
+    constructor(options: AutoDiscoveryOptions);
+    /** Current config version. -1 means no config has been fetched yet. */
+    get configVersion(): number;
+    /** Whether auto discovery is currently running. */
+    get isRunning(): boolean;
+    /** The configuration endpoint being used. */
+    get configEndpoint(): string;
+    /**
+     * Start the auto discovery process.
+     * Performs an initial discovery, then starts the polling timer.
+     */
+    start(): Promise<ClusterConfig>;
+    /**
+     * Stop the auto discovery process.
+     */
+    stop(): Promise<void>;
+    /**
+     * Perform a single discovery cycle.
+     * Returns the ClusterConfig if the version has changed, or undefined if unchanged.
+     */
+    discover(): Promise<ClusterConfig | undefined>;
+    /**
+     * 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: string[]): ClusterConfig;
+    /**
+     * Parse a single node entry in the format "hostname|ip|port".
+     */
+    static parseNodeEntry(entry: string): DiscoveredNode;
+    /**
+     * Build a node ID from a DiscoveredNode.
+     * Prefers IP when available, falls back to hostname.
+     */
+    static nodeId(node: DiscoveredNode): string;
+    private ensureConfigNode;
+    private fetchConfig;
+    private poll;
+    private parseEndpoint;
+}
+
+/**
+ * A distribution hash implementation that sends every key to all nodes.
+ * Unlike KetamaHash or ModulaHash, this does not partition keys — every
+ * operation targets every node in the cluster.
+ *
+ * This is useful for replication scenarios where all nodes should hold
+ * the same data, or for broadcast operations like flush/delete.
+ *
+ * @example
+ * ```typescript
+ * const client = new Memcache({
+ *   nodes: ['server1:11211', 'server2:11211'],
+ *   hash: new BroadcastHash(),
+ * });
+ * // Every set/get/delete will hit all nodes
+ * ```
+ */
+declare class BroadcastHash implements HashProvider {
+    /** The name of this distribution strategy */
+    readonly name = "broadcast";
+    /** Map of node IDs to MemcacheNode instances */
+    private nodeMap;
+    /** Cached array of nodes, rebuilt only on add/remove */
+    private nodeCache;
+    constructor();
+    /**
+     * Gets all nodes in the distribution.
+     * @returns Array of all MemcacheNode instances
+     */
+    get nodes(): Array<MemcacheNode>;
+    /**
+     * Adds a node to the distribution.
+     * @param node - The MemcacheNode to add
+     */
+    addNode(node: MemcacheNode): void;
+    /**
+     * Removes a node from the distribution by its ID.
+     * @param id - The node ID (e.g., "localhost:11211")
+     */
+    removeNode(id: string): void;
+    /**
+     * Gets a specific node by its ID.
+     * @param id - The node ID (e.g., "localhost:11211")
+     * @returns The MemcacheNode if found, undefined otherwise
+     */
+    getNode(id: string): MemcacheNode | undefined;
+    /**
+     * Returns all nodes regardless of key. Every operation is broadcast
+     * to every node in the cluster.
+     * @param _key - The cache key (ignored — all nodes are always returned)
+     * @returns Array of all MemcacheNode instances
+     */
+    getNodesByKey(_key: string): Array<MemcacheNode>;
+    /**
+     * Rebuilds the cached node array from the map.
+     */
+    private rebuildCache;
+}
+
 /**
  * Function that returns an unsigned 32-bit hash of the input.
  */
@@ -482,6 +669,8 @@ declare class Memcache extends Hookified {
     private _retryBackoff;
     private _retryOnlyIdempotent;
     private _sasl;
+    private _autoDiscovery;
+    private _autoDiscoverOptions;
     constructor(options?: string | MemcacheOptions);
     /**
      * Get the list of nodes
@@ -862,6 +1051,8 @@ declare class Memcache extends Hookified {
      * Forward events from a MemcacheNode to the Memcache instance
      */
     private forwardNodeEvents;
+    private startAutoDiscovery;
+    private applyClusterConfig;
 }
 
-export { type ExecuteOptions, type HashProvider, Memcache, MemcacheEvents, MemcacheNode, type MemcacheOptions, type MemcacheStats, ModulaHash, type RetryBackoffFunction, type SASLCredentials, createNode, Memcache as default, defaultRetryBackoff, exponentialRetryBackoff };
+export { type AutoDiscoverOptions, AutoDiscovery, BroadcastHash, type ClusterConfig, type DiscoveredNode, type ExecuteOptions, type HashProvider, Memcache, MemcacheEvents, MemcacheNode, type MemcacheOptions, type MemcacheStats, ModulaHash, type RetryBackoffFunction, type SASLCredentials, createNode, Memcache as default, defaultRetryBackoff, exponentialRetryBackoff };