memcache 0.2.0 → 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,501 @@
+import { Hookified } from 'hookified';
+import { Socket } from 'node:net';
+
+interface MemcacheNodeOptions {
+    timeout?: number;
+    keepAlive?: boolean;
+    keepAliveDelay?: number;
+    weight?: number;
+}
+interface CommandOptions {
+    isMultiline?: boolean;
+    isStats?: boolean;
+    requestedKeys?: string[];
+}
+type CommandQueueItem = {
+    command: string;
+    resolve: (value: any) => void;
+    reject: (reason?: any) => void;
+    isMultiline?: boolean;
+    isStats?: boolean;
+    requestedKeys?: string[];
+    foundKeys?: string[];
+};
+/**
+ * MemcacheNode represents a single memcache server connection.
+ * It handles the socket connection, command queue, and protocol parsing for one node.
+ */
+declare class MemcacheNode extends Hookified {
+    private _host;
+    private _port;
+    private _socket;
+    private _timeout;
+    private _keepAlive;
+    private _keepAliveDelay;
+    private _weight;
+    private _connected;
+    private _commandQueue;
+    private _buffer;
+    private _currentCommand;
+    private _multilineData;
+    private _pendingValueBytes;
+    constructor(host: string, port: number, options?: MemcacheNodeOptions);
+    /**
+     * Get the host of this node
+     */
+    get host(): string;
+    /**
+     * Get the port of this node
+     */
+    get port(): number;
+    /**
+     * Get the unique identifier for this node (host:port format)
+     */
+    get id(): string;
+    /**
+     * Get the full uri like memcache://localhost:11211
+     */
+    get uri(): string;
+    /**
+     * Get the socket connection
+     */
+    get socket(): Socket | undefined;
+    /**
+     * Get the weight of this node (used for consistent hashing distribution)
+     */
+    get weight(): number;
+    /**
+     * Set the weight of this node (used for consistent hashing distribution)
+     */
+    set weight(value: number);
+    /**
+     * Get the keepAlive setting for this node
+     */
+    get keepAlive(): boolean;
+    /**
+     * Set the keepAlive setting for this node
+     */
+    set keepAlive(value: boolean);
+    /**
+     * Get the keepAliveDelay setting for this node
+     */
+    get keepAliveDelay(): number;
+    /**
+     * Set the keepAliveDelay setting for this node
+     */
+    set keepAliveDelay(value: number);
+    /**
+     * Get the command queue
+     */
+    get commandQueue(): CommandQueueItem[];
+    /**
+     * Connect to the memcache server
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the memcache server
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Reconnect to the memcache server by disconnecting and connecting again
+     */
+    reconnect(): Promise<void>;
+    /**
+     * Gracefully quit the connection (send quit command then disconnect)
+     */
+    quit(): Promise<void>;
+    /**
+     * Check if connected to the memcache server
+     */
+    isConnected(): boolean;
+    /**
+     * 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
+     */
+    command(cmd: string, options?: CommandOptions): Promise<any>;
+    private handleData;
+    private processLine;
+    private rejectPendingCommands;
+}
+/**
+ * Factory function to create a new MemcacheNode instance.
+ * @param host - The hostname or IP address of the memcache server
+ * @param port - The port number of the memcache server
+ * @param options - Optional configuration for the node
+ * @returns A new MemcacheNode instance
+ *
+ * @example
+ * ```typescript
+ * const node = createNode('localhost', 11211, {
+ *   timeout: 5000,
+ *   keepAlive: true,
+ *   weight: 1
+ * });
+ * await node.connect();
+ * ```
+ */
+declare function createNode(host: string, port: number, options?: MemcacheNodeOptions): MemcacheNode;
+
+declare enum MemcacheEvents {
+    CONNECT = "connect",
+    QUIT = "quit",
+    HIT = "hit",
+    MISS = "miss",
+    ERROR = "error",
+    WARN = "warn",
+    INFO = "info",
+    TIMEOUT = "timeout",
+    CLOSE = "close"
+}
+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;
+}
+interface MemcacheStats {
+    [key: string]: string;
+}
+declare class Memcache extends Hookified {
+    private _nodes;
+    private _timeout;
+    private _keepAlive;
+    private _keepAliveDelay;
+    private _hash;
+    constructor(options?: MemcacheOptions);
+    /**
+     * Get the list of nodes
+     * @returns {MemcacheNode[]} Array of MemcacheNode
+     */
+    get nodes(): MemcacheNode[];
+    /**
+     * Get the list of node IDs (e.g., ["localhost:11211", "127.0.0.1:11212"])
+     * @returns {string[]} Array of node ID strings
+     */
+    get nodeIds(): string[];
+    /**
+     * Get the hash provider used for consistent hashing distribution.
+     * @returns {HashProvider} The current hash provider instance
+     * @default KetamaHash
+     *
+     * @example
+     * ```typescript
+     * const client = new Memcache();
+     * const hashProvider = client.hash;
+     * console.log(hashProvider.name); // "ketama"
+     * ```
+     */
+    get hash(): HashProvider;
+    /**
+     * Set the hash provider used for consistent hashing distribution.
+     * This allows you to customize the hashing strategy for distributing keys across nodes.
+     * @param {HashProvider} hash - The hash provider instance to use
+     *
+     * @example
+     * ```typescript
+     * const client = new Memcache();
+     * const customHashProvider = new KetamaHash();
+     * client.hash = customHashProvider;
+     * ```
+     */
+    set hash(hash: HashProvider);
+    /**
+     * Get the timeout for Memcache operations.
+     * @returns {number}
+     * @default 5000
+     */
+    get timeout(): number;
+    /**
+     * Set the timeout for Memcache operations.
+     * @param {number} value
+     * @default 5000
+     */
+    set timeout(value: number);
+    /**
+     * Get the keepAlive setting for the Memcache connection.
+     * @returns {boolean}
+     * @default true
+     */
+    get keepAlive(): boolean;
+    /**
+     * Set the keepAlive setting for the Memcache connection.
+     * Updates all existing nodes with the new value.
+     * Note: To apply the new value, you need to call reconnect() on the nodes.
+     * @param {boolean} value
+     * @default true
+     */
+    set keepAlive(value: boolean);
+    /**
+     * Get the delay before the connection is kept alive.
+     * @returns {number}
+     * @default 1000
+     */
+    get keepAliveDelay(): number;
+    /**
+     * Set the delay before the connection is kept alive.
+     * Updates all existing nodes with the new value.
+     * Note: To apply the new value, you need to call reconnect() on the nodes.
+     * @param {number} value
+     * @default 1000
+     */
+    set keepAliveDelay(value: number);
+    /**
+     * Get an array of all MemcacheNode instances
+     * @returns {MemcacheNode[]}
+     */
+    getNodes(): MemcacheNode[];
+    /**
+     * Get a specific node by its ID
+     * @param {string} id - The node ID (e.g., "localhost:11211")
+     * @returns {MemcacheNode | undefined}
+     */
+    getNode(id: string): MemcacheNode | undefined;
+    /**
+     * Add a new node to the cluster
+     * @param {string | MemcacheNode} uri - Node URI (e.g., "localhost:11212") or a MemcacheNode instance
+     * @param {number} weight - Optional weight for consistent hashing (only used for string URIs)
+     */
+    addNode(uri: string | MemcacheNode, weight?: number): Promise<void>;
+    /**
+     * Remove a node from the cluster
+     * @param {string} uri - Node URI (e.g., "localhost:11212")
+     */
+    removeNode(uri: string): Promise<void>;
+    /**
+     * Parse a URI string into host and port.
+     * Supports multiple formats:
+     * - Simple: "localhost:11211" or "localhost"
+     * - Protocol: "memcache://localhost:11211", "memcached://localhost:11211", "tcp://localhost:11211"
+     * - IPv6: "[::1]:11211" or "memcache://[2001:db8::1]:11212"
+     * - Unix socket: "/var/run/memcached.sock" or "unix:///var/run/memcached.sock"
+     *
+     * @param {string} uri - URI string
+     * @returns {{ host: string; port: number }} Object containing host and port (port is 0 for Unix sockets)
+     * @throws {Error} If URI format is invalid
+     */
+    parseUri(uri: string): {
+        host: string;
+        port: number;
+    };
+    /**
+     * Connect to all Memcache servers or a specific node.
+     * @param {string} nodeId - Optional node ID to connect to (e.g., "localhost:11211")
+     * @returns {Promise<void>}
+     */
+    connect(nodeId?: string): Promise<void>;
+    /**
+     * Get a value from the Memcache server.
+     * When multiple nodes are returned by the hash provider (for replication),
+     * queries all nodes and returns the first successful result.
+     * @param {string} key
+     * @returns {Promise<string | undefined>}
+     */
+    get(key: string): Promise<string | undefined>;
+    /**
+     * Get multiple values from the Memcache server.
+     * When multiple nodes are returned by the hash provider (for replication),
+     * queries all replica nodes and returns the first successful result for each key.
+     * @param keys {string[]}
+     * @returns {Promise<Map<string, string>>}
+     */
+    gets(keys: string[]): Promise<Map<string, string>>;
+    /**
+     * Check-And-Set: Store a value only if it hasn't been modified since last fetch.
+     * When multiple nodes are returned by the hash provider (for replication),
+     * executes on all nodes and returns true only if all succeed.
+     * @param key {string}
+     * @param value {string}
+     * @param casToken {string}
+     * @param exptime {number}
+     * @param flags {number}
+     * @returns {Promise<boolean>}
+     */
+    cas(key: string, value: string, casToken: string, exptime?: number, flags?: number): Promise<boolean>;
+    /**
+     * Set a value in the Memcache server.
+     * When multiple nodes are returned by the hash provider (for replication),
+     * executes on all nodes and returns true only if all succeed.
+     * @param key {string}
+     * @param value {string}
+     * @param exptime {number}
+     * @param flags {number}
+     * @returns {Promise<boolean>}
+     */
+    set(key: string, value: string, exptime?: number, flags?: number): Promise<boolean>;
+    /**
+     * Add a value to the Memcache server (only if key doesn't exist).
+     * When multiple nodes are returned by the hash provider (for replication),
+     * executes on all nodes and returns true only if all succeed.
+     * @param key {string}
+     * @param value {string}
+     * @param exptime {number}
+     * @param flags {number}
+     * @returns {Promise<boolean>}
+     */
+    add(key: string, value: string, exptime?: number, flags?: number): Promise<boolean>;
+    /**
+     * Replace a value in the Memcache server (only if key exists).
+     * When multiple nodes are returned by the hash provider (for replication),
+     * executes on all nodes and returns true only if all succeed.
+     * @param key {string}
+     * @param value {string}
+     * @param exptime {number}
+     * @param flags {number}
+     * @returns {Promise<boolean>}
+     */
+    replace(key: string, value: string, exptime?: number, flags?: number): Promise<boolean>;
+    /**
+     * Append a value to an existing key in the Memcache server.
+     * When multiple nodes are returned by the hash provider (for replication),
+     * executes on all nodes and returns true only if all succeed.
+     * @param key {string}
+     * @param value {string}
+     * @returns {Promise<boolean>}
+     */
+    append(key: string, value: string): Promise<boolean>;
+    /**
+     * Prepend a value to an existing key in the Memcache server.
+     * When multiple nodes are returned by the hash provider (for replication),
+     * executes on all nodes and returns true only if all succeed.
+     * @param key {string}
+     * @param value {string}
+     * @returns {Promise<boolean>}
+     */
+    prepend(key: string, value: string): Promise<boolean>;
+    /**
+     * Delete a value from the Memcache server.
+     * When multiple nodes are returned by the hash provider (for replication),
+     * executes on all nodes and returns true only if all succeed.
+     * @param key {string}
+     * @returns {Promise<boolean>}
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Increment a value in the Memcache server.
+     * When multiple nodes are returned by the hash provider (for replication),
+     * executes on all nodes and returns the first successful result.
+     * @param key {string}
+     * @param value {number}
+     * @returns {Promise<number | undefined>}
+     */
+    incr(key: string, value?: number): Promise<number | undefined>;
+    /**
+     * Decrement a value in the Memcache server.
+     * When multiple nodes are returned by the hash provider (for replication),
+     * executes on all nodes and returns the first successful result.
+     * @param key {string}
+     * @param value {number}
+     * @returns {Promise<number | undefined>}
+     */
+    decr(key: string, value?: number): Promise<number | undefined>;
+    /**
+     * Touch a value in the Memcache server (update expiration time).
+     * When multiple nodes are returned by the hash provider (for replication),
+     * executes on all nodes and returns true only if all succeed.
+     * @param key {string}
+     * @param exptime {number}
+     * @returns {Promise<boolean>}
+     */
+    touch(key: string, exptime: number): Promise<boolean>;
+    /**
+     * Flush all values from all Memcache servers.
+     * @param delay {number}
+     * @returns {Promise<boolean>}
+     */
+    flush(delay?: number): Promise<boolean>;
+    /**
+     * Get statistics from all Memcache servers.
+     * @param type {string}
+     * @returns {Promise<Map<string, MemcacheStats>>}
+     */
+    stats(type?: string): Promise<Map<string, MemcacheStats>>;
+    /**
+     * Get the Memcache server version from all nodes.
+     * @returns {Promise<Map<string, string>>} Map of node IDs to version strings
+     */
+    version(): Promise<Map<string, string>>;
+    /**
+     * Quit all connections gracefully.
+     * @returns {Promise<void>}
+     */
+    quit(): Promise<void>;
+    /**
+     * Disconnect all connections.
+     * @returns {Promise<void>}
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Reconnect all nodes by disconnecting and connecting them again.
+     * @returns {Promise<void>}
+     */
+    reconnect(): Promise<void>;
+    /**
+     * Check if any node is connected to a Memcache server.
+     * @returns {boolean}
+     */
+    isConnected(): boolean;
+    /**
+     * Get the nodes for a given key using consistent hashing, with lazy connection.
+     * This method will automatically connect to the nodes if they're not already connected.
+     * Returns an array to support replication strategies.
+     * @param {string} key - The cache key
+     * @returns {Promise<Array<MemcacheNode>>} The nodes responsible for this key
+     * @throws {Error} If no nodes are available for the key
+     */
+    getNodesByKey(key: string): Promise<Array<MemcacheNode>>;
+    /**
+     * Validates a Memcache key according to protocol requirements.
+     * @param {string} key - The key to validate
+     * @throws {Error} If the key is empty, exceeds 250 characters, or contains invalid characters
+     *
+     * @example
+     * ```typescript
+     * client.validateKey("valid-key"); // OK
+     * client.validateKey(""); // Throws: Key cannot be empty
+     * client.validateKey("a".repeat(251)); // Throws: Key length cannot exceed 250 characters
+     * client.validateKey("key with spaces"); // Throws: Key cannot contain spaces, newlines, or null characters
+     * ```
+     */
+    validateKey(key: string): void;
+    /**
+     * Update all nodes with current keepAlive settings
+     */
+    private updateNodes;
+    /**
+     * Forward events from a MemcacheNode to the Memcache instance
+     */
+    private forwardNodeEvents;
+}
+
+export { type HashProvider, Memcache, MemcacheEvents, type MemcacheOptions, type MemcacheStats, createNode, Memcache as default };