@valkey/valkey-glide 2.4.2 → 2.5.0-rc2

package/build-ts/GlideClusterClient.js

@@ -41,6 +41,21 @@ var GlideClusterClientConfiguration;
         PubSubChannelModes[PubSubChannelModes["Sharded"] = 2] = "Sharded";
     })(PubSubChannelModes = GlideClusterClientConfiguration.PubSubChannelModes || (GlideClusterClientConfiguration.PubSubChannelModes = {}));
 })(GlideClusterClientConfiguration || (exports.GlideClusterClientConfiguration = GlideClusterClientConfiguration = {}));
+/**
+ * @internal
+ * Determines whether a command response is from a single node based on routing.
+ *
+ * @param isRoutedToSingleNodeByDefault - Whether the command defaults to a single node.
+ * @param route - The route option provided by the caller.
+ * @returns `true` if the response is from a single node.
+ */
+function isSingleNodeRoute(isRoutedToSingleNodeByDefault, route) {
+    return (
+    // route not given and command is routed by default to a random node
+    (!route && isRoutedToSingleNodeByDefault) ||
+        // or route is given and it is a single node route
+        (Boolean(route) && route !== "allPrimaries" && route !== "allNodes"));
+}
 /**
  * @internal
  * Convert {@link ClusterGlideRecord} to {@link ClusterResponse}.
@@ -51,15 +66,30 @@ var GlideClusterClientConfiguration;
  * @returns Converted value.
  */
 function convertClusterGlideRecord(res, isRoutedToSingleNodeByDefault, route) {
-    const isSingleNodeResponse = 
-    // route not given and command is routed by default to a random node
-    (!route && isRoutedToSingleNodeByDefault) ||
-        // or route is given and it is a single node route
-        (Boolean(route) && route !== "allPrimaries" && route !== "allNodes");
-    return isSingleNodeResponse
+    return isSingleNodeRoute(isRoutedToSingleNodeByDefault, route)
         ? res
         : (0, BaseClient_1.convertGlideRecordToRecord)(res);
 }
+/**
+ * Converts a cluster response by applying a transform function to each node's raw value.
+ * Handles both single-node and multi-node routing automatically.
+ *
+ * @param res - Raw response from Glide core.
+ * @param isSingleNode - Whether the response is from a single node.
+ * @param transform - A function that transforms the raw value into the desired type.
+ * @returns Transformed single value or a record mapping node addresses to transformed values.
+ */
+function convertAndParseClusterResponse(res, isSingleNode, transform) {
+    if (isSingleNode) {
+        return transform(res);
+    }
+    const record = (0, BaseClient_1.convertGlideRecordToRecord)(res);
+    const result = {};
+    for (const [node, raw] of Object.entries(record)) {
+        result[node] = transform(raw);
+    }
+    return result;
+}
 /**
  * Client used for connection to cluster servers.
  * Use {@link createClient} to request a client.
@@ -527,6 +557,43 @@ class GlideClusterClient extends BaseClient_1.BaseClient {
     async clientId(options) {
         return this.createWritePromise((0, Commands_1.createClientId)(), options).then((res) => convertClusterGlideRecord(res, true, options?.route));
     }
+    /**
+     * Returns information about the current client connection's use
+     * of the server assisted client side caching feature.
+     *
+     * The command will be routed to a random node, unless `route` is provided.
+     *
+     * @see {@link https://valkey.io/commands/client-trackinginfo/|valkey.io} for details.
+     *
+     * @param options - (Optional) See {@link RouteOption}.
+     * @returns A {@link ClusterResponse} containing tracking info(s) for the client.
+     *
+     * @example
+     * ```typescript
+     * const info = await client.clientTrackingInfo();
+     * console.log(info.flags); // Set { "off" }
+     * console.log(info.redirect); // -1
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const info = await client.clientTrackingInfo({ route: "allNodes" });
+     * // info is Record<string, ClientTrackingInfo>
+     * ```
+     */
+    async clientTrackingInfo(options) {
+        return this.createWritePromise((0, Commands_1.createClientTrackingInfo)(), options).then((res) => {
+            if (isSingleNodeRoute(true, options?.route)) {
+                return (0, Commands_1.parseClientTrackingInfoResponse)((0, BaseClient_1.convertGlideRecordToRecord)(res));
+            }
+            const record = (0, BaseClient_1.convertGlideRecordToRecord)(res);
+            const result = {};
+            for (const [node, entry] of Object.entries(record)) {
+                result[node] = (0, Commands_1.parseClientTrackingInfoResponse)(entry);
+            }
+            return result;
+        });
+    }
     /**
      * Reads the configuration parameters of the running server.
      * Starting from server version 7, command supports multiple parameters.
@@ -1096,6 +1163,178 @@ class GlideClusterClient extends BaseClient_1.BaseClient {
     async lastsave(options) {
         return this.createWritePromise((0, Commands_1.createLastSave)(), options).then((res) => convertClusterGlideRecord(res, true, options?.route));
     }
+    /**
+     * Returns the latency spike time series for the specified event.
+     *
+     * The command will be routed to all primary nodes, unless `route` is provided.
+     *
+     * @see {@link https://valkey.io/commands/latency-history/|valkey.io} for details.
+     *
+     * @param event - The name of the latency event (e.g., `"command"`).
+     * @param options - (Optional) See {@link RouteOption}.
+     * @returns A {@link ClusterResponse} containing array(s) of {@link LatencyEntry} for the event.
+     *
+     * @example
+     * ```typescript
+     * const history = await client.latencyHistory("command");
+     * // history is Record<string, LatencyEntry[]> (multi-node) or LatencyEntry[] (single-node)
+     * ```
+     */
+    async latencyHistory(event, options) {
+        return this.createWritePromise((0, Commands_1.createLatencyHistory)(event), options).then((res) => convertAndParseClusterResponse(res, isSingleNodeRoute(false, options?.route), (raw) => (0, Commands_1.parseLatencyHistoryResponse)(raw)));
+    }
+    /**
+     * Reports the latest latency events logged by the server.
+     *
+     * The command will be routed to all primary nodes, unless `route` is provided.
+     *
+     * @see {@link https://valkey.io/commands/latency-latest/|valkey.io} for details.
+     *
+     * @param options - (Optional) See {@link RouteOption}.
+     * @returns A {@link ClusterResponse} containing array(s) of {@link LatencyEventInfo} for the latest latency events.
+     *
+     * @example
+     * ```typescript
+     * const latest = await client.latencyLatest();
+     * // latest is Record<string, LatencyEventInfo[]> (multi-node) or LatencyEventInfo[] (single-node)
+     * ```
+     */
+    async latencyLatest(options) {
+        return this.createWritePromise((0, Commands_1.createLatencyLatest)(), options).then((res) => convertAndParseClusterResponse(res, isSingleNodeRoute(false, options?.route), (raw) => (0, Commands_1.parseLatencyLatestResponse)(raw)));
+    }
+    /**
+     * Resets the latency spike time series for all or specified events.
+     * If no events are provided, resets the latency spike time series for all events.
+     *
+     * The command will be routed to all primary nodes, unless `route` is provided.
+     *
+     * @see {@link https://valkey.io/commands/latency-reset/|valkey.io} for details.
+     *
+     * @param events - The event names to reset. If not provided, resets all events.
+     * @param options - (Optional) See {@link RouteOption}.
+     * @returns The total number of event time series that were reset across all nodes.
+     *
+     * @example
+     * ```typescript
+     * await client.latencyReset(); // Resets all events
+     * await client.latencyReset(["command"], { route: "allNodes" });
+     * ```
+     */
+    async latencyReset(events, options) {
+        return this.createWritePromise((0, Commands_1.createLatencyReset)(events), options);
+    }
+    /**
+     * Synchronously saves the dataset to disk.
+     *
+     * The command will be routed to all primary nodes, unless `route` is provided.
+     *
+     * @see {@link https://valkey.io/commands/save/|valkey.io} for more details.
+     *
+     * @param options - (Optional) See {@link RouteOption}.
+     * @returns `"OK"`
+     *
+     * @example
+     * ```typescript
+     * const result = await client.save();
+     * console.log(result); // "OK"
+     * ```
+     */
+    async save(options) {
+        return this.createWritePromise((0, Commands_1.createSave)(), {
+            decoder: BaseClient_1.Decoder.String,
+            ...options,
+        });
+    }
+    /**
+     * Asynchronously saves the dataset to disk in the background.
+     *
+     * The command will be routed to all primary nodes, unless `route` is provided.
+     *
+     * @see {@link https://valkey.io/commands/bgsave/|valkey.io} for more details.
+     *
+     * @param options - (Optional) See {@link RouteOption}.
+     * @returns A non-empty status string.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.bgsave();
+     * console.log(result); // "Background saving started"
+     * ```
+     */
+    async bgsave(options) {
+        return this.createWritePromise((0, Commands_1.createBgSave)(), {
+            decoder: BaseClient_1.Decoder.String,
+            ...options,
+        }).then((res) => convertClusterGlideRecord(res, false, options?.route));
+    }
+    /**
+     * Schedules a background save of the database.
+     *
+     * The command will be routed to all primary nodes, unless `route` is provided.
+     *
+     * @see {@link https://valkey.io/commands/bgsave/|valkey.io} for more details.
+     *
+     * @param options - (Optional) See {@link RouteOption}.
+     * @returns A non-empty status string.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.bgsaveSchedule();
+     * console.log(result); // "Background saving scheduled"
+     * ```
+     */
+    async bgsaveSchedule(options) {
+        return this.createWritePromise((0, Commands_1.createBgSave)(["SCHEDULE"]), {
+            decoder: BaseClient_1.Decoder.String,
+            ...options,
+        }).then((res) => convertClusterGlideRecord(res, false, options?.route));
+    }
+    /**
+     * Aborts all in-progress and scheduled background saves.
+     *
+     * The command will be routed to all primary nodes, unless `route` is provided.
+     *
+     * @see {@link https://valkey.io/commands/bgsave/|valkey.io} for more details.
+     *
+     * @since Valkey 8.1
+     *
+     * @param options - (Optional) See {@link RouteOption}.
+     * @returns A non-empty status string.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.bgsaveCancel();
+     * console.log(result); // "Background saving cancelled"
+     * ```
+     */
+    async bgsaveCancel(options) {
+        return this.createWritePromise((0, Commands_1.createBgSave)(["CANCEL"]), {
+            decoder: BaseClient_1.Decoder.String,
+            ...options,
+        }).then((res) => convertClusterGlideRecord(res, false, options?.route));
+    }
+    /**
+     * Initiates a background rewrite of the append-only file (AOF).
+     *
+     * The command will be routed to all primary nodes, unless `route` is provided.
+     *
+     * @see {@link https://valkey.io/commands/bgrewriteaof/|valkey.io} for more details.
+     *
+     * @param options - (Optional) See {@link RouteOption}.
+     * @returns A non-empty status string.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.bgrewriteaof();
+     * console.log(result); // "Background append only file rewriting started"
+     * ```
+     */
+    async bgrewriteaof(options) {
+        return this.createWritePromise((0, Commands_1.createBgRewriteAof)(), {
+            decoder: BaseClient_1.Decoder.String,
+            ...options,
+        }).then((res) => convertClusterGlideRecord(res, false, options?.route));
+    }
     /**
      * Returns a random existing key name.
      *
@@ -1138,6 +1377,59 @@ class GlideClusterClient extends BaseClient_1.BaseClient {
             ...options,
         });
     }
+    /**
+     * Suspends all clients for the specified timeout.
+     *
+     * The command will be routed to all primary nodes, unless `route` is provided.
+     *
+     * @see {@link https://valkey.io/commands/client-pause/|valkey.io} for details.
+     *
+     * @param timeout - The time in milliseconds to pause clients.
+     * @param mode - (Optional) The pause mode to use.
+     *   + If not provided, all commands are paused.
+     * @param options - (Optional) See {@link RouteOption} and {@link DecoderOption}.
+     * @returns `"OK"` response on success.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.clientPause(1000);
+     * console.log(result); // Output: 'OK'
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const result = await client.clientPause(1000, ClientPauseMode.WRITE);
+     * console.log(result); // Output: 'OK'
+     * ```
+     */
+    async clientPause(timeout, mode, options) {
+        return this.createWritePromise((0, Commands_1.createClientPause)(timeout, mode), {
+            route: "allPrimaries",
+            ...options,
+        });
+    }
+    /**
+     * Resumes processing commands on all clients.
+     *
+     * The command will be routed to all primary nodes, unless `route` is provided.
+     *
+     * @see {@link https://valkey.io/commands/client-unpause/|valkey.io} for details.
+     *
+     * @param options - (Optional) See {@link RouteOption} and {@link DecoderOption}.
+     * @returns `"OK"` response on success.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.clientUnpause();
+     * console.log(result); // Output: 'OK'
+     * ```
+     */
+    async clientUnpause(options) {
+        return this.createWritePromise((0, Commands_1.createClientUnpause)(), {
+            route: "allPrimaries",
+            ...options,
+        });
+    }
     /**
      * Invokes a Lua script with arguments.
      * This method simplifies the process of invoking scripts on a Valkey server by using an object that represents a Lua script.
@@ -1357,5 +1649,87 @@ class GlideClusterClient extends BaseClient_1.BaseClient {
         const response = await this.createWritePromise((0, Commands_1.createGetSubscriptions)());
         return this.parseGetSubscriptionsResponse(response);
     }
+    // TODO #6166: move to shared base once server management refactor lands
+    /**
+     * Returns a report about memory problems detected by the server.
+     *
+     * The command will be routed to all primary nodes, unless `route` is provided.
+     *
+     * @see {@link https://valkey.io/commands/memory-doctor/|valkey.io} for details.
+     *
+     * @param options - (Optional) See {@link RouteOption} to specify the route to override the default.
+     * @returns A {@link ClusterResponse} containing the memory diagnostic report string(s).
+     *
+     * @example
+     * ```typescript
+     * const report = await client.memoryDoctor();
+     * // report is Record<string, string> (multi-node) or string (single-node)
+     * ```
+     */
+    async memoryDoctor(options) {
+        return this.createWritePromise((0, Commands_1.createMemoryDoctor)(), { decoder: BaseClient_1.Decoder.String, ...options }).then((res) => convertClusterGlideRecord(res, false, options?.route));
+    }
+    /**
+     * Returns the internal statistics of the memory allocator.
+     *
+     * The command will be routed to all primary nodes, unless `route` is provided.
+     *
+     * @see {@link https://valkey.io/commands/memory-malloc-stats/|valkey.io} for details.
+     *
+     * @param options - (Optional) See {@link RouteOption} to specify the route to override the default.
+     * @returns A {@link ClusterResponse} containing the memory allocator statistics string(s).
+     *
+     * @example
+     * ```typescript
+     * const stats = await client.memoryMallocStats();
+     * // stats is Record<string, string> (multi-node) or string (single-node)
+     * ```
+     */
+    async memoryMallocStats(options) {
+        return this.createWritePromise((0, Commands_1.createMemoryMallocStats)(), { decoder: BaseClient_1.Decoder.String, ...options }).then((res) => convertClusterGlideRecord(res, false, options?.route));
+    }
+    /**
+     * Asks the server to reclaim memory from the allocator back to the operating system.
+     *
+     * The command will be routed to all primary nodes, unless `route` is provided.
+     *
+     * @see {@link https://valkey.io/commands/memory-purge/|valkey.io} for details.
+     *
+     * @param options - (Optional) See {@link RouteOption} to specify the route to override the default.
+     * @returns `"OK"`.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.memoryPurge();
+     * console.log(result); // Output: 'OK'
+     * ```
+     */
+    async memoryPurge(options) {
+        return this.createWritePromise((0, Commands_1.createMemoryPurge)(), {
+            decoder: BaseClient_1.Decoder.String,
+            ...options,
+        });
+    }
+    /**
+     * Returns detailed memory consumption statistics of the server.
+     *
+     * The command will be routed to all primary nodes, unless `route` is provided.
+     *
+     * @see {@link https://valkey.io/commands/memory-stats/|valkey.io} for details.
+     *
+     * @param options - (Optional) See {@link RouteOption} to specify the route to override the default.
+     * @returns A {@link ClusterResponse} containing {@link MemoryStats} object(s).
+     *
+     * @example
+     * ```typescript
+     * const stats = await client.memoryStats();
+     * // stats is Record<string, MemoryStats> (multi-node) or MemoryStats (single-node)
+     * ```
+     */
+    async memoryStats(options) {
+        return this.createWritePromise((0, Commands_1.createMemoryStats)(), options).then((res) => convertAndParseClusterResponse(res, isSingleNodeRoute(false, options?.route), (raw) => (0, Commands_1.parseMemoryStatsResponse)((0, BaseClient_1.isGlideRecord)(raw)
+            ? (0, BaseClient_1.convertGlideRecordToRecord)(raw)
+            : raw)));
+    }
 }
 exports.GlideClusterClient = GlideClusterClient;

package/build-ts/GlideMonitorClient.d.ts

@@ -0,0 +1,36 @@
+import { BaseClientConfiguration } from "./BaseClient.js";
+export interface MonitorLine {
+    timestamp: number;
+    db: number;
+    clientAddr: string;
+    command: string;
+    args: string[];
+}
+export declare class GlideMonitorClient {
+    private handleId;
+    private closed;
+    private readonly queue;
+    private waiters;
+    private constructor();
+    /**
+     * Creates a GlideMonitorClient that streams server-side commands.
+     * @param options - Connection configuration.
+     * @param callback - Optional callback invoked for each monitor line.
+     *   If omitted, use {@link getNextMessage} or {@link tryGetNextMessage} to poll.
+     */
+    static create(options: BaseClientConfiguration, callback?: (line: MonitorLine) => void): Promise<GlideMonitorClient>;
+    /**
+     * Returns the next monitor line, waiting until one arrives.
+     * Only usable when no callback was provided to {@link create}.
+     * Rejects if the client is already closed.
+     */
+    getNextMessage(): Promise<MonitorLine>;
+    /**
+     * Returns the next monitor line immediately, or `undefined` if none is queued.
+     * Only usable when no callback was provided to {@link create}.
+     */
+    tryGetNextMessage(): MonitorLine | undefined;
+    /** Stops monitoring. Idempotent — safe to call multiple times. */
+    close(): Promise<void>;
+    private static buildConnectionRequest;
+}

package/build-ts/GlideMonitorClient.js

@@ -0,0 +1,103 @@
+"use strict";
+// Copyright Valkey GLIDE Project Contributors - SPDX-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GlideMonitorClient = void 0;
+const native_1 = require("../build-ts/native");
+const ProtobufMessage_1 = require("../build-ts/ProtobufMessage");
+class GlideMonitorClient {
+    handleId = null;
+    closed = false;
+    queue = [];
+    waiters = [];
+    // eslint-disable-next-line @typescript-eslint/no-empty-function
+    constructor() { }
+    /**
+     * Creates a GlideMonitorClient that streams server-side commands.
+     * @param options - Connection configuration.
+     * @param callback - Optional callback invoked for each monitor line.
+     *   If omitted, use {@link getNextMessage} or {@link tryGetNextMessage} to poll.
+     */
+    static async create(options, callback) {
+        const client = new GlideMonitorClient();
+        const request = GlideMonitorClient.buildConnectionRequest(options);
+        const bytes = ProtobufMessage_1.connection_request.ConnectionRequest.encode(request).finish();
+        client.handleId = await (0, native_1.createMonitorClient)(Buffer.from(bytes), (timestamp, db, clientAddr, command, args) => {
+            const line = {
+                timestamp,
+                db,
+                clientAddr,
+                command,
+                args,
+            };
+            if (callback) {
+                callback(line);
+            }
+            else {
+                const waiter = client.waiters.shift();
+                if (waiter) {
+                    waiter.resolve(line);
+                }
+                else {
+                    client.queue.push(line);
+                }
+            }
+        });
+        return client;
+    }
+    /**
+     * Returns the next monitor line, waiting until one arrives.
+     * Only usable when no callback was provided to {@link create}.
+     * Rejects if the client is already closed.
+     */
+    getNextMessage() {
+        if (this.closed) {
+            return Promise.reject(new Error("Monitor is closed"));
+        }
+        if (this.queue.length > 0) {
+            return Promise.resolve(this.queue.shift());
+        }
+        return new Promise((resolve, reject) => this.waiters.push({ resolve, reject }));
+    }
+    /**
+     * Returns the next monitor line immediately, or `undefined` if none is queued.
+     * Only usable when no callback was provided to {@link create}.
+     */
+    tryGetNextMessage() {
+        return this.queue.shift();
+    }
+    /** Stops monitoring. Idempotent — safe to call multiple times. */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        // Reject any pending getNextMessage() waiters so callers don't hang.
+        for (const { reject } of this.waiters.splice(0)) {
+            reject(new Error("Monitor is closed"));
+        }
+        if (this.handleId !== null) {
+            const id = this.handleId;
+            this.handleId = null;
+            await (0, native_1.closeMonitorClient)(id);
+        }
+    }
+    static buildConnectionRequest(options) {
+        return ProtobufMessage_1.connection_request.ConnectionRequest.create({
+            addresses: options.addresses?.map((a) => ({
+                host: a.host,
+                port: a.port,
+            })),
+            tlsMode: options.useTLS
+                ? ProtobufMessage_1.connection_request.TlsMode.SecureTls
+                : ProtobufMessage_1.connection_request.TlsMode.NoTls,
+            authenticationInfo: options.credentials != null && "password" in options.credentials
+                ? ProtobufMessage_1.connection_request.AuthenticationInfo.create({
+                    username: options.credentials.username ?? "",
+                    password: options.credentials.password,
+                })
+                : undefined,
+            databaseId: options.databaseId ?? 0,
+            clientName: options.clientName,
+        });
+    }
+}
+exports.GlideMonitorClient = GlideMonitorClient;