@valkey/valkey-glide 1.3.4 → 1.3.5-rc2

package/build-ts/{src/Transaction.d.ts → Batch.d.ts}

@@ -1,8 +1,8 @@
 /**
  * Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
  */
-import { // eslint-disable-line @typescript-eslint/no-unused-vars
-GlideRecord, GlideString, HashDataType, Score, ElementAndScore } from "./BaseClient";
+import { ElementAndScore, GlideRecord, GlideString, HashDataType, // eslint-disable-line @typescript-eslint/no-unused-vars
+Score } from "./BaseClient";
 import { AggregationType, BaseScanOptions, BitFieldGet, // eslint-disable-line @typescript-eslint/no-unused-vars
 BitFieldSubCommands, // eslint-disable-line @typescript-eslint/no-unused-vars
 BitOffsetOptions, BitwiseOperation, Boundary, // eslint-disable-line @typescript-eslint/no-unused-vars
@@ -11,49 +11,41 @@ FunctionRestorePolicy, // eslint-disable-line @typescript-eslint/no-unused-vars
 GeoAddOptions, // eslint-disable-line @typescript-eslint/no-unused-vars
 GeoSearchResultOptions, GeoSearchShape, GeoSearchStoreResultOptions, GeoUnit, GeospatialData, HScanOptions, InfoOptions, InsertPosition, KeyWeight, LPosOptions, ListDirection, LolwutOptions, // eslint-disable-line @typescript-eslint/no-unused-vars
 RangeByIndex, RangeByLex, RangeByScore, RestoreOptions, ScoreFilter, SearchOrigin, SetOptions, SortOptions, StreamAddOptions, StreamClaimOptions, StreamGroupOptions, StreamPendingOptions, StreamReadGroupOptions, StreamReadOptions, StreamTrimOptions, TimeUnit, ZAddOptions, ZScanOptions } from "./Commands";
-import { command_request } from "./ProtobufMessage";
+import { command_request } from "../build-ts/ProtobufMessage";
 /**
- * Base class encompassing shared commands for both standalone and cluster mode implementations in a transaction.
- * Transactions allow the execution of a group of commands in a single step.
+ * Base class encompassing shared commands for both standalone and cluster mode implementations in a Batch.
+ * Batches allow the execution of a group of commands in a single step.
  *
- * Command Response:
+ * ### Batch Response:
  *  An array of command responses is returned by the client exec command, in the order they were given.
- *  Each element in the array represents a command given to the transaction.
+ *  Each element in the array represents a command given to the batch.
  *  The response for each command depends on the executed Valkey command.
  *  Specific response types are documented alongside each method.
  *
- * @example
- * ```typescript
- * const transaction = new BaseTransaction()
- *    .set("key", "value")
- *    .get("key");
- * const result = await client.exec(transaction);
- * console.log(result); // Output: ['OK', 'value']
- * ```
+ * @param isAtomic - Indicates whether the batch is atomic or non-atomic. If `true`, the batch will be executed as an atomic transaction.
+ * If `false`, the batch will be executed as a non-atomic pipeline.
  */
-export declare class BaseTransaction<T extends BaseTransaction<T>> {
-    /**
-     * @internal
-     */
-    readonly commands: command_request.Command[];
+export declare class BaseBatch<T extends BaseBatch<T>> {
+    readonly isAtomic: boolean;
     /**
-     * Array of command indexes indicating commands that need to be converted into a `Set` within the transaction.
-     * @internal
+     * @param isAtomic - Determines whether the batch is atomic or non-atomic. If `true`, the
+     *     batch will be executed as an atomic `transaction`. If `false`, the batch will be
+     *     executed as a non-atomic `pipeline`.
      */
-    readonly setCommandsIndexes: number[];
+    constructor(isAtomic: boolean);
     /**
-     * Adds a command to the transaction and returns the transaction instance.
+     * Adds a command to the batch and returns the batch instance.
      * @param command - The command to add.
      * @param shouldConvertToSet - Indicates if the command should be converted to a `Set`.
-     * @returns The updated transaction instance.
+     * @returns The updated batch instance.
      */
     protected addAndReturn(command: command_request.Command, shouldConvertToSet?: boolean): T;
-    /** Get the value associated with the given key, or null if no such value exists.
+    /** Get the value associated with the given `key`, or `null` if no such `key` exists.
      * @see {@link https://valkey.io/commands/get/|valkey.io} for details.
      *
-     * @param key - The key to retrieve from the database.
+     * @param key - The `key` to retrieve from the database.
      *
-     * Command Response - If `key` exists, returns the value of `key`. Otherwise, return null.
+     * Command Response - If `key` exists, returns the value of `key`. Otherwise, return `null`.
      */
     get(key: GlideString): T;
     /**
@@ -126,6 +118,8 @@ export declare class BaseTransaction<T extends BaseTransaction<T>> {
     /**
      * Gets information and statistics about the server.
      *
+     * Starting from server version 7, command supports multiple section arguments.
+     *
      * @see {@link https://valkey.io/commands/info/|valkey.io} for details.
      *
      * @param sections - (Optional) A list of {@link InfoOptions} values specifying which sections of information to retrieve.
@@ -148,7 +142,7 @@ export declare class BaseTransaction<T extends BaseTransaction<T>> {
      * Serialize the value stored at `key` in a Valkey-specific format and return it to the user.
      *
      * @see {@link https://valkey.io/commands/dump/|valkey.io} for details.
-     * @remarks To execute a transaction with a `dump` command, the `exec` command requires `Decoder.Bytes` to handle the response.
+     * @remarks To execute a batch with a `dump` command, the `exec` command requires `Decoder.Bytes` to handle the response.
      *
      * @param key - The `key` to serialize.
      *
@@ -171,7 +165,7 @@ export declare class BaseTransaction<T extends BaseTransaction<T>> {
      */
     restore(key: GlideString, ttl: number, value: Buffer, options?: RestoreOptions): T;
     /**
-     * Gets the name of the connection on which the transaction is being executed.
+     * Gets the name of the connection on which the batch is being executed.
      *
      * @see {@link https://valkey.io/commands/client-getname/|valkey.io} for details.
      *
@@ -183,7 +177,7 @@ export declare class BaseTransaction<T extends BaseTransaction<T>> {
      *
      * @see {@link https://valkey.io/commands/select/|valkey.io} for details.
      *
-     * Command Response - "OK" when the configuration was rewritten properly. Otherwise, the transaction fails with an error.
+     * Command Response - "OK" when the configuration was rewritten properly. Otherwise, the command fails with an error.
      */
     configRewrite(): T;
     /**
@@ -390,7 +384,7 @@ export declare class BaseTransaction<T extends BaseTransaction<T>> {
      *
      * @param parameters - A map consisting of configuration parameters and their respective values to set.
      *
-     * Command Response - "OK" when the configuration was set properly. Otherwise, the transaction fails with an error.
+     * Command Response - "OK" when the configuration was set properly. Otherwise, the command fails with an error.
      */
     configSet(parameters: Record<string, GlideString>): T;
     /** Retrieve the value associated with `field` in the hash stored at `key`.
@@ -565,8 +559,8 @@ export declare class BaseTransaction<T extends BaseTransaction<T>> {
      *
      * @param key - The key of the hash.
      * @param count - The number of field names to return.
-     *
-     *     If `count` is positive, returns unique elements. If negative, allows for duplicates.
+     *     If `count` is positive, returns unique elements.
+     *     If negative, allows for duplicates.
      *
      * Command Response - An `array` of random field names from the hash stored at `key`,
      *     or an `empty array` when the key does not exist.
@@ -581,8 +575,8 @@ export declare class BaseTransaction<T extends BaseTransaction<T>> {
      *
      * @param key - The key of the hash.
      * @param count - The number of field names to return.
-     *
-     *     If `count` is positive, returns unique elements. If negative, allows for duplicates.
+     *     If `count` is positive, returns unique elements.
+     *     If negative, allows for duplicates.
      *
      * Command Response - A 2D `array` of `[fieldName, value]` `arrays`, where `fieldName` is a random
      *     field name from the hash and `value` is the associated value of the field name.
@@ -1740,6 +1734,7 @@ export declare class BaseTransaction<T extends BaseTransaction<T>> {
     linsert(key: GlideString, position: InsertPosition, pivot: GlideString, element: GlideString): T;
     /**
      * Adds an entry to the specified stream stored at `key`. If the `key` doesn't exist, the stream is created.
+     *
      * @see {@link https://valkey.io/commands/xadd/|valkey.io} for details.
      *
      * @param key - The key of the stream.
@@ -1968,7 +1963,7 @@ export declare class BaseTransaction<T extends BaseTransaction<T>> {
      * @param start - Filters the claimed entries to those that have an ID equal or greater than the
      *     specified value.
      * @param options - (Optional) Additional parameters:
-     * - (Optional) `count`: the number of claimed entries.
+     * - (Optional) `count`: the number of claimed entries. Default value is 100.
      *
      * Command Response - An `array` containing the following elements:
      *   - A stream ID to be used as the start argument for the next call to `XAUTOCLAIM`. This ID is
@@ -1997,7 +1992,7 @@ export declare class BaseTransaction<T extends BaseTransaction<T>> {
      * @param start - Filters the claimed entries to those that have an ID equal or greater than the
      *     specified value.
      * @param options - (Optional) Additional parameters:
-     * - (Optional) `count`: limits the number of claimed entries to the specified value.
+     * - (Optional) `count`: limits the number of claimed entries to the specified value. Default value is 100.
      *
      * Command Response - An `array` containing the following elements:
      *   - A stream ID to be used as the start argument for the next call to `XAUTOCLAIM`. This ID is
@@ -2020,7 +2015,8 @@ export declare class BaseTransaction<T extends BaseTransaction<T>> {
      * @param key - The key of the stream.
      * @param groupName - The newly created consumer group name.
      * @param id - Stream entry ID that specifies the last delivered entry in the stream from the new
-     *     group’s perspective. The special ID `"$"` can be used to specify the last entry in the stream.
+     *     group's perspective. The special ID `"$"` can be used to specify the last entry in the stream.
+     * @param options - The group options {@link StreamGroupOptions}
      *
      * Command Response - `"OK"`.
      */
@@ -2031,7 +2027,7 @@ export declare class BaseTransaction<T extends BaseTransaction<T>> {
      * @see {@link https://valkey.io/commands/xgroup-destroy/|valkey.io} for details.
      *
      * @param key - The key of the stream.
-     * @param groupname - The newly created consumer group name.
+     * @param groupname - The consumer group name to delete.
      *
      * Command Response - `true` if the consumer group is destroyed. Otherwise, `false`.
      */
@@ -2335,7 +2331,7 @@ export declare class BaseTransaction<T extends BaseTransaction<T>> {
      *
      * @see {@link https://valkey.io/commands/function-dump/|valkey.io} for details.
      * @remarks Since Valkey version 7.0.0.
-     * @remarks To execute a transaction with a `functionDump` command, the `exec` command requires `Decoder.Bytes` to handle the response.
+     * @remarks To execute a batch with a `functionDump` command, the `exec` command requires `Decoder.Bytes` to handle the response.
      *
      * Command Response - The serialized payload of all loaded libraries.
      */
@@ -2712,6 +2708,7 @@ export declare class BaseTransaction<T extends BaseTransaction<T>> {
      * @param count - (Optional) The maximum number of popped elements.
      *
      * Command Response - A `Record` which stores the key name where elements were popped out and the array of popped elements.
+     *     If no member could be popped, returns `null`.
      */
     lmpop(keys: GlideString[], direction: ListDirection, count?: number): T;
     /**
@@ -2826,26 +2823,47 @@ export declare class BaseTransaction<T extends BaseTransaction<T>> {
     sortStore(key: GlideString, destination: GlideString, options?: SortOptions): T;
 }
 /**
- * Extends BaseTransaction class for Valkey standalone commands.
- * Transactions allow the execution of a group of commands in a single step.
+ * Batch implementation for standalone {@link GlideClient}.
+ * Batches allow the execution of a group of commands in a single step.
  *
- * Command Response:
- *  An array of command responses is returned by the GlideClient.exec command, in the order they were given.
- *  Each element in the array represents a command given to the transaction.
+ * ### Batch Response:
+ *  An array of command responses is returned by the client {@link GlideClient.exec | exec} command, in the order they were given.
+ *  Each element in the array represents a command given to the batch.
  *  The response for each command depends on the executed Valkey command.
  *  Specific response types are documented alongside each method.
  *
+ * @param isAtomic - Indicates whether the batch is atomic or non-atomic. If `true`, the batch will be executed as an atomic transaction.
+ * If `false`, the batch will be executed as a non-atomic pipeline.
+ *
+ * @see {@link https://valkey.io/docs/topics/transactions/ | Valkey Transactions (Atomic Batches)}
+ * @see {@link https://valkey.io/topics/pipelining | Valkey Pipelines (Non-Atomic Batches)}
+ * @remarks Standalone Batches are executed on the primary node.
+ *
+ * @example
+ * ```typescript
+ * // Example of Atomic Batch (Transaction)
+ * const transaction = new Batch(true) // Atomic (Transactional)
+ *     .set("key", "value")
+ *     .get("key");
+ * const result = await client.exec(transaction, true);
+ * // result contains: OK and "value"
+ * console.log(result); // ["OK", "value"]
+ * ```
+ *
  * @example
  * ```typescript
- * const transaction = new Transaction()
- *    .set("key", "value")
- *    .select(1)  /// Standalone command
- *    .get("key");
- * const result = await GlideClient.exec(transaction);
- * console.log(result); // Output: ['OK', 'OK', null]
+ * // Example of Non-Atomic Batch (Pipeline)
+ * const pipeline = new Batch(false) // Non-Atomic (Pipeline)
+ *     .set("key1", "value1")
+ *     .set("key2", "value2")
+ *     .get("key1")
+ *     .get("key2");
+ * const result = await client.exec(pipeline, true);
+ * // result contains: OK, OK, "value1", "value2"
+ * console.log(result); // ["OK", "OK", "value1", "value2"]
  * ```
  */
-export declare class Transaction extends BaseTransaction<Transaction> {
+export declare class Batch extends BaseBatch<Batch> {
     /**
      * Change the currently selected database.
      *
@@ -2855,7 +2873,7 @@ export declare class Transaction extends BaseTransaction<Transaction> {
      *
      * Command Response - A simple `"OK"` response.
      */
-    select(index: number): Transaction;
+    select(index: number): Batch;
     /**
      * Copies the value stored at the `source` to the `destination` key. If `destinationDB` is specified,
      * the value will be copied to the database specified, otherwise the current database will be used.
@@ -2877,7 +2895,7 @@ export declare class Transaction extends BaseTransaction<Transaction> {
     copy(source: GlideString, destination: GlideString, options?: {
         destinationDB?: number;
         replace?: boolean;
-    }): Transaction;
+    }): Batch;
     /**
      * Move `key` from the currently selected database to the database specified by `dbIndex`.
      *
@@ -2889,7 +2907,7 @@ export declare class Transaction extends BaseTransaction<Transaction> {
      * Command Response - `true` if `key` was moved, or `false` if the `key` already exists in the destination
      *     database or does not exist in the source database.
      */
-    move(key: GlideString, dbIndex: number): Transaction;
+    move(key: GlideString, dbIndex: number): Batch;
     /** Publish a message on pubsub channel.
      *
      * @see {@link https://valkey.io/commands/publish/|valkey.io} for more details.
@@ -2900,20 +2918,47 @@ export declare class Transaction extends BaseTransaction<Transaction> {
      * Command Response -  Number of subscriptions in primary node that received the message.
      * Note that this value does not include subscriptions that configured on replicas.
      */
-    publish(message: GlideString, channel: GlideString): Transaction;
+    publish(message: GlideString, channel: GlideString): Batch;
 }
 /**
- * Extends BaseTransaction class for cluster mode commands.
- * Transactions allow the execution of a group of commands in a single step.
+ * Batch implementation for standalone {@link GlideClusterClient | GlideClusterClient}.
+ * Batches allow the execution of a group of commands in a single step.
  *
- * Command Response:
- *  An array of command responses is returned by the GlideClusterClient.exec command, in the order they were given.
- *  Each element in the array represents a command given to the transaction.
+ * ### Batch Response:
+ *  An array of command responses is returned by the client {@link GlideClusterClient.exec | exec} command, in the order they were given.
+ *  Each element in the array represents a command given to the batch.
  *  The response for each command depends on the executed Valkey command.
  *  Specific response types are documented alongside each method.
  *
+ * @param isAtomic - Indicates whether the batch is atomic or non-atomic. If `true`, the batch will be executed as an atomic transaction.
+ * If `false`, the batch will be executed as a non-atomic pipeline.
+ *
+ * @see {@link https://valkey.io/docs/topics/transactions/ | Valkey Transactions (Atomic Batches)}
+ * @see {@link https://valkey.io/topics/pipelining | Valkey Pipelines (Non-Atomic Batches)}
+ *
+ * @example
+ * ```typescript
+ * // Example of Atomic Batch (Transaction) in a Cluster
+ * const transaction = new ClusterBatch(true) // Atomic (Transactional)
+ *     .set("key", "value")
+ *     .get("key");
+ * const result = await client.exec(transaction, true);
+ * console.log(result); // ["OK", "value"]
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Example of Non-Atomic Batch (Pipeline) in a Cluster
+ * const pipeline = new ClusterBatch(false) // Non-Atomic (Pipeline)
+ *     .set("key1", "value1")
+ *     .set("key2", "value2")
+ *     .get("key1")
+ *     .get("key2");
+ * const result = await client.exec(pipeline, true);
+ * console.log(result); // ["OK", "OK", "value1", "value2"]
+ * ```
  */
-export declare class ClusterTransaction extends BaseTransaction<ClusterTransaction> {
+export declare class ClusterBatch extends BaseBatch<ClusterBatch> {
     /**
      * Copies the value stored at the `source` to the `destination` key. When `replace` is true,
      * removes the `destination` key first if it already exists, otherwise performs no action.
@@ -2930,7 +2975,7 @@ export declare class ClusterTransaction extends BaseTransaction<ClusterTransacti
      */
     copy(source: GlideString, destination: GlideString, options?: {
         replace?: boolean;
-    }): ClusterTransaction;
+    }): ClusterBatch;
     /** Publish a message on pubsub channel.
      * This command aggregates PUBLISH and SPUBLISH commands functionalities.
      * The mode is selected using the 'sharded' parameter.
@@ -2944,7 +2989,7 @@ export declare class ClusterTransaction extends BaseTransaction<ClusterTransacti
      *
      * Command Response -  Number of subscriptions in primary node that received the message.
      */
-    publish(message: GlideString, channel: GlideString, sharded?: boolean): ClusterTransaction;
+    publish(message: GlideString, channel: GlideString, sharded?: boolean): ClusterBatch;
     /**
      * Lists the currently active shard channels.
      * The command is routed to all nodes, and aggregates the response to a single array.
@@ -2957,7 +3002,7 @@ export declare class ClusterTransaction extends BaseTransaction<ClusterTransacti
      * Command Response - A list of currently active shard channels matching the given pattern.
      *          If no pattern is specified, all active shard channels are returned.
      */
-    pubsubShardChannels(pattern?: GlideString): ClusterTransaction;
+    pubsubShardChannels(pattern?: GlideString): ClusterBatch;
     /**
      * Returns the number of subscribers (exclusive of clients subscribed to patterns) for the specified shard channels.
      *
@@ -2968,5 +3013,17 @@ export declare class ClusterTransaction extends BaseTransaction<ClusterTransacti
      *
      * Command Response - A list of the shard channel names and their numbers of subscribers.
      */
-    pubsubShardNumSub(channels: GlideString[]): ClusterTransaction;
+    pubsubShardNumSub(channels: GlideString[]): ClusterBatch;
+}
+/**
+ * @deprecated This class is deprecated and should no longer be used. Use {@link ClusterBatch} instead.
+ */
+export declare class ClusterTransaction extends ClusterBatch {
+    constructor();
+}
+/**
+ * @deprecated This class is deprecated and should no longer be used. Use {@link Batch} instead.
+ */
+export declare class Transaction extends Batch {
+    constructor();
 }