@valkey/valkey-glide 1.3.4 → 1.3.5-rc2

package/build-ts/{src/GlideClusterClient.d.ts → GlideClusterClient.d.ts}

@@ -1,12 +1,10 @@
 /**
  * Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
  */
-import { ClusterScanCursor, Script } from "glide-rs";
-import * as net from "net";
 import { AdvancedBaseClientConfiguration, BaseClient, BaseClientConfiguration, DecoderOption, GlideReturnType, GlideString, PubSubMsg } from "./BaseClient";
-import { ClusterScanOptions, FlushMode, FunctionListOptions, FunctionListResponse, FunctionRestorePolicy, FunctionStatsSingleResponse, InfoOptions, LolwutOptions } from "./Commands";
-import { command_request, connection_request } from "./ProtobufMessage";
-import { ClusterTransaction } from "./Transaction";
+import { ClusterBatch } from "./Batch";
+import { ClusterBatchOptions, ClusterScanOptions, FlushMode, FunctionListOptions, FunctionListResponse, FunctionRestorePolicy, FunctionStatsSingleResponse, InfoOptions, LolwutOptions } from "./Commands";
+import { ClusterScanCursor, Script } from "./native";
 /** An extension to command option types with {@link Routes}. */
 export interface RouteOption {
     /**
@@ -385,25 +383,24 @@ export type SingleNodeRoute =
  | SlotKeyTypes | RouteByAddress;
 /**
  * Client used for connection to cluster servers.
+ * Use {@link createClient} to request a client.
  *
- * @see For full documentation refer to {@link https://github.com/valkey-io/valkey-glide/wiki/NodeJS-wrapper#cluster|Valkey Glide Wiki}.
+ * @see For full documentation refer to {@link https://github.com/valkey-io/valkey-glide/wiki/NodeJS-wrapper#cluster | Valkey Glide Wiki}.
  */
 export declare class GlideClusterClient extends BaseClient {
     /**
-     * @internal
-     */
-    protected createClientRequest(options: GlideClusterClientConfiguration): connection_request.IConnectionRequest;
-    /**
-     * Creates a new `GlideClusterClient` instance and establishes connections to a Valkey GLIDE Cluster.
+     * Creates a new `GlideClusterClient` instance and establishes connections to a Valkey Cluster.
      *
      * @param options - The configuration options for the client, including cluster addresses, authentication credentials, TLS settings, periodic checks, and Pub/Sub subscriptions.
      * @returns A promise that resolves to a connected `GlideClusterClient` instance.
      *
      * @remarks
-     * Use this static method to create and connect a `GlideClusterClient` to a Valkey GLIDE Cluster. The client will automatically handle connection establishment, including cluster topology discovery and handling of authentication and TLS configurations.
+     * Use this static method to create and connect a `GlideClusterClient` to a Valkey Cluster.
+     * The client will automatically handle connection establishment, including cluster topology discovery and handling of authentication and TLS configurations.
      *
-     * ### Example - Connecting to a Cluster
+     * @example
      * ```typescript
+     * // Connecting to a Cluster
      * import { GlideClusterClient, GlideClusterClientConfiguration } from '@valkey/valkey-glide';
      *
      * const client = await GlideClusterClient.createClient({
@@ -439,18 +436,6 @@ export declare class GlideClusterClient extends BaseClient {
      * - **Pub/Sub Subscriptions**: Any channels or patterns specified in `pubsubSubscriptions` will be subscribed to upon connection.
      */
     static createClient(options: GlideClusterClientConfiguration): Promise<GlideClusterClient>;
-    /**
-     * @internal
-     */
-    static __createClient(options: BaseClientConfiguration, connectedSocket: net.Socket): Promise<GlideClusterClient>;
-    /**
-     * @internal
-     */
-    protected scanOptionsToProto(cursor: string, options?: ClusterScanOptions): command_request.ClusterScan;
-    /**
-     * @internal
-     */
-    protected createClusterScanPromise(cursor: ClusterScanCursor, options?: ClusterScanOptions & DecoderOption): Promise<[ClusterScanCursor, GlideString[]]>;
     /**
      * Incrementally iterates over the keys in the Cluster.
      *
@@ -533,25 +518,67 @@ export declare class GlideClusterClient extends BaseClient {
      */
     customCommand(args: GlideString[], options?: RouteOption & DecoderOption): Promise<ClusterResponse<GlideReturnType>>;
     /**
-     * Execute a transaction by processing the queued commands.
+     * Executes a batch by processing the queued commands.
+     *
+     * **Routing Behavior:**
+     *
+     * - If a `route` is specified in {@link ClusterBatchOptions}, the entire batch is sent to the specified node.
+     * - If no `route` is specified:
+     *   - **Atomic batches (Transactions):** Routed to the slot owner of the first key in the batch. If no key is found, the request is sent to a random node.
+     *   - **Non-atomic batches (Pipelines):** Each command is routed to the node owning the corresponding key's slot. If no key is present, routing follows the command's request policy. Multi-node commands are automatically split and dispatched to the appropriate nodes.
+     *
+     * **Behavior Notes:**
+     *
+     * - **Atomic Batches (Transactions):** All key-based commands must map to the same hash slot. If keys span different slots, the transaction will fail. If the transaction fails due to a `WATCH` command, `exec` will return `null`.
      *
      * @see {@link https://github.com/valkey-io/valkey-glide/wiki/NodeJS-wrapper#transaction|Valkey Glide Wiki} for details on Valkey Transactions.
      *
-     * @param transaction - A {@link ClusterTransaction} object containing a list of commands to be executed.
-     *
-     *  @param options - (Optional) Additional parameters:
-     * - (Optional) `route`: If `route` is not provided, the transaction will be routed to the slot owner of the first key found in the transaction.
-     *     If no key is found, the command will be sent to a random node.
-     *     If `route` is provided, the client will route the command to the nodes defined by `route`.
-     * - (Optional) `decoder`: See {@link DecoderOption}.
-     * @returns A list of results corresponding to the execution of each command in the transaction.
-     *     If a command returns a value, it will be included in the list. If a command doesn't return a value,
-     *     the list entry will be `null`.
-     *     If the transaction failed due to a `WATCH` command, `exec` will return `null`.
+     * **Retry and Redirection:**
+     *
+     * - If a redirection error occurs:
+     *   - **Atomic batches (Transactions):** The entire transaction will be redirected.
+     *   - **Non-atomic batches (Pipelines):** Only commands that encountered redirection errors will be retried.
+     * - Retries for failures will be handled according to the configured {@link BatchRetryStrategy}.
+     *
+     * @param batch - A {@link ClusterBatch} containing the commands to execute.
+     * @param raiseOnError - Determines how errors are handled within the batch response.
+     *   - If `true`, the first encountered error in the batch will be raised as an exception of type {@link RequestError}
+     *     after all retries and reconnections have been exhausted.
+     *   - If `false`, errors will be included as part of the batch response, allowing the caller to process both successful and failed commands together.
+     *     In this case, error details will be provided as instances of {@link RequestError} in the response list.
+     * @param options - (Optional) {@link ClusterBatchOptions} and {@link DecoderOption} specifying execution and decoding behavior.
+     * @returns A Promise resolving to an array of results, where each entry corresponds to a command’s execution result.
+     *   - If the transaction fails due to a `WATCH` command, the promise resolves to `null`.
+     *
+     * @see {@link https://valkey.io/docs/topics/transactions/|Valkey Transactions (Atomic Batches)}
+     * @see {@link https://valkey.io/docs/topics/pipelining/|Valkey Pipelines (Non-Atomic Batches)}
+     * @example
+     * ```typescript
+     * // Atomic batch (transaction): all keys must share the same hash slot
+     * const atomicBatch = new ClusterBatch(true)
+     *   .set('key', '1')
+     *   .incr('key')
+     *   .get('key');
+     *
+     * const atomicOptions = {timeout: 1000};
+     * const atomicResult = await clusterClient.exec(atomicBatch, false, atomicOptions);
+     * console.log('Atomic Batch Result:', atomicResult);
+     * // Output: ['OK', 2, '2']
+     *
+     * // Non-atomic batch (pipeline): keys may span different hash slots
+     * const nonAtomicBatch = new ClusterBatch(false)
+     *   .set('key1', 'value1')
+     *   .set('key2', 'value2')
+     *   .get('key1')
+     *   .get('key2');
+     *
+     * const pipelineOptions = { retryStrategy: { retryServerError: true, retryConnectionError: false } };
+     * const nonAtomicResult = await clusterClient.exec(nonAtomicBatch, false, pipelineOptions);
+     * console.log(nonAtomicResult);
+     * // Output: ['OK', 'OK', 'value1', 'value2']
+     * ```
      */
-    exec(transaction: ClusterTransaction, options?: {
-        route?: SingleNodeRoute;
-    } & DecoderOption): Promise<GlideReturnType[] | null>;
+    exec(batch: ClusterBatch, raiseOnError: boolean, options?: ClusterBatchOptions & DecoderOption): Promise<GlideReturnType[] | null>;
     /**
      * Pings the server.
      *
@@ -589,6 +616,8 @@ export declare class GlideClusterClient extends BaseClient {
      *
      * The command will be routed to all primary nodes, unless `route` is provided.
      *
+     * Starting from server version 7, command supports multiple section arguments.
+     *
      * @see {@link https://valkey.io/commands/info/|valkey.io} for details.
      *
      * @param options - (Optional) Additional parameters:
@@ -596,8 +625,15 @@ export declare class GlideClusterClient extends BaseClient {
      *     When no parameter is provided, {@link InfoOptions.Default|Default} is assumed.
      * - (Optional) `route`: see {@link RouteOption}.
      * @returns A string containing the information for the sections requested.
-     * When specifying a route other than a single node,
+     *     When specifying a route other than a single node,
      *     it returns a dictionary where each address is the key and its corresponding node response is the value.
+     *
+     * @example
+     * ```typescript
+     * // Example usage of the info method with retrieving total_net_input_bytes from the result
+     * const result = await client.info(new Section[] { Section.STATS });
+     * console.log(someClusterParsingFunction(result, "total_net_input_bytes")); // Output: 1
+     * ```
      */
     info(options?: {
         sections?: InfoOptions[];
@@ -969,7 +1005,7 @@ export declare class GlideClusterClient extends BaseClient {
      * Returns information about the function that's currently running and information about the
      * available execution engines.
      *
-     * The command will be routed to all primary nodes, unless `route` is provided.
+     * The command will be routed to all nodes, unless `route` is provided.
      *
      * @see {@link https://valkey.io/commands/function-stats/|valkey.io} for details.
      * @remarks Since Valkey version 7.0.0.