@valkey/valkey-glide-darwin-arm64 1.2.1 → 1.3.0-rc2

package/build-ts/src/BaseClient.d.ts

@@ -2,16 +2,16 @@
  * Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
  */
 import { Script } from "glide-rs";
-import { Buffer } from "protobufjs";
+import { Buffer, Writer } from "protobufjs";
 import { AggregationType, BaseScanOptions, BitFieldGet, // eslint-disable-line @typescript-eslint/no-unused-vars
 BitFieldSubCommands, // eslint-disable-line @typescript-eslint/no-unused-vars
-BitOffsetOptions, BitmapIndexType, BitwiseOperation, Boundary, // eslint-disable-line @typescript-eslint/no-unused-vars
+BitOffsetOptions, BitwiseOperation, Boundary, // eslint-disable-line @typescript-eslint/no-unused-vars
 ExpireOptions, GeoAddOptions, // eslint-disable-line @typescript-eslint/no-unused-vars
 GeoSearchResultOptions, GeoSearchShape, GeoSearchStoreResultOptions, GeoUnit, GeospatialData, HScanOptions, InsertPosition, KeyWeight, LPosOptions, ListDirection, // 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 { ConnectionError, ValkeyError } from "./Errors";
 import { GlideClientConfiguration } from "./GlideClient";
-import { GlideClusterClientConfiguration } from "./GlideClusterClient";
+import { GlideClusterClientConfiguration, Routes } from "./GlideClusterClient";
 import { command_request, connection_request, response } from "./ProtobufMessage";
 type PromiseFunction = (value?: any) => void;
 type ErrorFunction = (error: ValkeyError) => void;
@@ -115,7 +115,10 @@ export type ReadFrom =
  | "preferReplica"
 /** Spread the requests between replicas in the same client's Aviliablity zone in a round robin manner.
     If no replica is available, route the requests to the primary.*/
- | "AZAffinity";
+ | "AZAffinity"
+/** Spread the read requests among all nodes within the client's Availability Zone (AZ) in a round robin manner,
+     prioritizing local replicas, then the local primary, and falling back to any replica or the primary if needed.*/
+ | "AZAffinityReplicasAndPrimary";
 /**
  * Configuration settings for creating a client. Shared settings for standalone and cluster clients.
  *
@@ -144,11 +147,11 @@ export type ReadFrom =
  *
  * ### Read Strategy
  *
- * - Use `readFrom` to specify the client's read strategy (e.g., primary, preferReplica, AZAffinity).
+ * - Use `readFrom` to specify the client's read strategy (e.g., primary, preferReplica, AZAffinity, AZAffinityReplicasAndPrimary).
  *
  * ### Availability Zone
  *
- * - Use `clientAz` to specify the client's availability zone, which can influence read operations when using `readFrom: 'AZAffinity'`.
+ * - Use `clientAz` to specify the client's availability zone, which can influence read operations when using `readFrom: 'AZAffinity'or `readFrom: 'AZAffinityReplicasAndPrimary'`.
  *
  * ### Decoder Settings
  *
@@ -223,12 +226,12 @@ export interface BaseClientConfiguration {
      */
     requestTimeout?: number;
     /**
-     * Represents the client's read from strategy.
+     * The client's read from strategy.
      * If not set, `Primary` will be used.
      */
     readFrom?: ReadFrom;
     /**
-     * Choose the serialization protocol to be used with the server.
+     * Serialization protocol to be used.
      * If not set, `RESP3` will be used.
      */
     protocol?: ProtocolVersion;
@@ -250,13 +253,15 @@ export interface BaseClientConfiguration {
     inflightRequestsLimit?: number;
     /**
      * Availability Zone of the client.
-     * If ReadFrom strategy is AZAffinity, this setting ensures that readonly commands are directed to replicas within the specified AZ if exits.
+     * If ReadFrom strategy is AZAffinity or AZAffinityReplicasAndPrimary, this setting ensures that readonly commands are directed to nodes within the specified AZ if they exist.
      *
      * @example
      * ```typescript
      * // Example configuration for setting client availability zone and read strategy
      * configuration.clientAz = 'us-east-1a'; // Sets the client's availability zone
      * configuration.readFrom = 'AZAffinity'; // Directs read operations to nodes within the same AZ
+     * Or
+     * configuration.readFrom = 'AZAffinityReplicasAndPrimary'; // Directs read operations to any node (primary or replica) within the same AZ
      * ```
      */
     clientAz?: string;
@@ -311,10 +316,7 @@ export interface PubSubMsg {
 }
 export declare class BaseClient {
     private socket;
-    protected readonly promiseCallbackFunctions: [
-        PromiseFunction,
-        ErrorFunction
-    ][];
+    protected readonly promiseCallbackFunctions: [PromiseFunction, ErrorFunction, Decoder | undefined][] | [PromiseFunction, ErrorFunction][];
     private readonly availableCallbackSlots;
     private requestWriter;
     private writeInProgress;
@@ -325,16 +327,22 @@ export declare class BaseClient {
     private readonly pubsubFutures;
     private pendingPushNotification;
     private readonly inflightRequestsLimit;
-    private readonly clientAz;
     private config;
     protected configurePubsub(options: GlideClusterClientConfiguration | GlideClientConfiguration, configuration: connection_request.IConnectionRequest): void;
     private handleReadData;
+    protected toProtobufRoute(route: Routes | undefined): command_request.Routes | undefined;
     processResponse(message: response.Response): void;
     processPush(response: response.Response): void;
     protected getCallbackIndex(): number;
     private writeBufferedRequestsToSocket;
-    protected writeOrBufferCommandRequest(callbackIdx: number, command: command_request.Command | command_request.Command[] | command_request.ScriptInvocation | command_request.ClusterScan | command_request.UpdateConnectionPassword, route?: command_request.Routes): void;
-    private writeOrBufferRequest;
+    protected ensureClientIsOpen(): void;
+    protected createUpdateConnectionPasswordPromise(command: command_request.UpdateConnectionPassword): Promise<GlideString>;
+    protected createScriptInvocationPromise<T = GlideString>(command: command_request.ScriptInvocation, options?: {
+        keys?: GlideString[];
+        args?: GlideString[];
+    } & DecoderOption): Promise<T>;
+    protected writeOrBufferCommandRequest(callbackIdx: number, command: command_request.Command | command_request.Command[], route?: command_request.Routes): void;
+    protected writeOrBufferRequest<TRequest>(message: TRequest, encodeDelimited: (message: TRequest, writer: Writer) => void): void;
     cancelPubSubFuturesWithExceptionSafe(exception: ConnectionError): void;
     isPubsubConfigured(config: GlideClientConfiguration | GlideClusterClientConfiguration): boolean;
     getPubsubCallbackAndContext(config: GlideClientConfiguration | GlideClusterClientConfiguration): [((msg: PubSubMsg, context: any) => void) | null | undefined, any];
@@ -442,7 +450,8 @@ export declare class BaseClient {
      * @param value - The value to store with the given key.
      * @param options - (Optional) See {@link SetOptions} and {@link DecoderOption}.
      * @returns - If the value is successfully set, return OK.
-     * If value isn't set because of `onlyIfExists` or `onlyIfDoesNotExist` conditions, return null.
+     * If `conditional` in `options` is not set, the value will be set regardless of prior value existence.
+     * If value isn't set because of `onlyIfExists` or `onlyIfDoesNotExist` or `onlyIfEqual` conditions, return `null`.
      * If `returnOldValue` is set, return the old value as a string.
      *
      * @example
@@ -462,6 +471,13 @@ export declare class BaseClient {
      * // Example usage of get method to retrieve the value of a key
      * const result4 = await client.get("key");
      * console.log(result4); // Output: 'new_value' - Value wasn't modified back to being "value" because of "NX" flag.
+     *
+     * // Example usage of set method with conditional option IFEQ
+     * await client.set("key", "value we will compare to");
+     * const result5 = await client.set("key", "new_value", {conditionalSet: "onlyIfEqual", comparisonValue: "value we will compare to"});
+     * console.log(result5); // Output: 'OK' - Set "new_value" to "key" only if comparisonValue is equal to the current value of "key".
+     * const result6 = await client.set("key", "another_new_value", {conditionalSet: "onlyIfEqual", comparisonValue: "value we will compare to"});
+     * console.log(result6); // Output: `null` - Value wasn't set because the comparisonValue is not equal to the current value of "key". Value of "key" remains "new_value".
      * ```
      */
     set(key: GlideString, value: GlideString, options?: SetOptions & DecoderOption): Promise<"OK" | GlideString | null>;
@@ -787,11 +803,12 @@ export declare class BaseClient {
      * The offset can also be a negative number indicating an offset starting at the end of the list, with `-1` being
      * the last byte of the list, `-2` being the penultimate, and so on.
      *
-     * @see {@link https://valkey.io/commands/bitpos/|valkey.io} for more details.
+     * @see {@link https://valkey.io/commands/bitpos/|valkey.io} for details.
      *
      * @param key - The key of the string.
      * @param bit - The bit value to match. Must be `0` or `1`.
-     * @param start - (Optional) The starting offset. If not supplied, the search will start at the beginning of the string.
+     * @param options - (Optional) The {@link BitOffsetOptions}.
+     *
      * @returns The position of the first occurrence of `bit` in the binary value of the string held at `key`.
      *      If `start` was provided, the search begins at the offset indicated by `start`.
      *
@@ -801,45 +818,18 @@ export declare class BaseClient {
      * const result1 = await client.bitpos("key1", 1);
      * console.log(result1); // Output: 1 - The first occurrence of bit value 1 in the string stored at "key1" is at the second position.
      *
-     * const result2 = await client.bitpos("key1", 1, -1);
+     * const result2 = await client.bitpos("key1", 1, { start: -1 });
      * console.log(result2); // Output: 10 - The first occurrence of bit value 1, starting at the last byte in the string stored at "key1", is at the eleventh position.
-     * ```
-     */
-    bitpos(key: GlideString, bit: number, start?: number): Promise<number>;
-    /**
-     * Returns the position of the first bit matching the given `bit` value. The offsets are zero-based indexes, with
-     * `0` being the first element of the list, `1` being the next, and so on. These offsets can also be negative
-     * numbers indicating offsets starting at the end of the list, with `-1` being the last element of the list, `-2`
-     * being the penultimate, and so on.
-     *
-     * If you are using Valkey 7.0.0 or above, the optional `indexType` can also be provided to specify whether the
-     * `start` and `end` offsets specify BIT or BYTE offsets. If `indexType` is not provided, BYTE offsets
-     * are assumed. If BIT is specified, `start=0` and `end=2` means to look at the first three bits. If BYTE is
-     * specified, `start=0` and `end=2` means to look at the first three bytes.
      *
-     * @see {@link https://valkey.io/commands/bitpos/|valkey.io} for more details.
-     *
-     * @param key - The key of the string.
-     * @param bit - The bit value to match. Must be `0` or `1`.
-     * @param start - The starting offset.
-     * @param end - The ending offset.
-     * @param indexType - (Optional) The index offset type. This option can only be specified if you are using Valkey
-     *      version 7.0.0 or above. Could be either {@link BitmapIndexType.BYTE} or {@link BitmapIndexType.BIT}. If no
-     *      index type is provided, the indexes will be assumed to be byte indexes.
-     * @returns The position of the first occurrence from the `start` to the `end` offsets of the `bit` in the binary
-     *      value of the string held at `key`.
-     *
-     * @example
-     * ```typescript
      * await client.set("key1", "A12");  // "A12" has binary value 01000001 00110001 00110010
-     * const result1 = await client.bitposInterval("key1", 1, 1, -1);
-     * console.log(result1); // Output: 10 - The first occurrence of bit value 1 in the second byte to the last byte of the string stored at "key1" is at the eleventh position.
+     * const result3 = await client.bitpos("key1", 1, { start: 1, end: -1 });
+     * console.log(result3); // Output: 10 - The first occurrence of bit value 1 in the second byte to the last byte of the string stored at "key1" is at the eleventh position.
      *
-     * const result2 = await client.bitposInterval("key1", 1, 2, 9, BitmapIndexType.BIT);
-     * console.log(result2); // Output: 7 - The first occurrence of bit value 1 in the third to tenth bits of the string stored at "key1" is at the eighth position.
+     * const result4 = await client.bitpos("key1", 1, { start: 2, end: 9, indexType: BitmapIndexType.BIT });
+     * console.log(result4); // Output: 7 - The first occurrence of bit value 1 in the third to tenth bits of the string stored at "key1" is at the eighth position.
      * ```
      */
-    bitposInterval(key: GlideString, bit: number, start: number, end: number, indexType?: BitmapIndexType): Promise<number>;
+    bitpos(key: GlideString, bit: number, options?: BitOffsetOptions): Promise<number>;
     /**
      * Reads or modifies the array of bits representing the string that is held at `key` based on the specified
      * `subcommands`.
@@ -2787,7 +2777,6 @@ export declare class BaseClient {
      * @param key - The key of the sorted set.
      * @param rangeQuery - The range query object representing the type of range query to perform.
      * - For range queries by index (rank), use {@link RangeByIndex}.
-     * - For range queries by lexicographical order, use {@link RangeByLex}.
      * - For range queries by score, use {@link RangeByScore}.
      * @param options - (Optional) Additional parameters:
      * - (Optional) `reverse`: if `true`, reverses the sorted set, with index `0` as the element with the highest score.
@@ -2818,7 +2807,7 @@ export declare class BaseClient {
      * // [{ element: 'member7', score: 1.5 }, { element: 'member4', score: -2.0 }]
      * ```
      */
-    zrangeWithScores(key: GlideString, rangeQuery: RangeByScore | RangeByLex | RangeByIndex, options?: {
+    zrangeWithScores(key: GlideString, rangeQuery: RangeByScore | RangeByIndex, options?: {
         reverse?: boolean;
     } & DecoderOption): Promise<SortedSetDataType>;
     /**
@@ -4390,7 +4379,7 @@ export declare class BaseClient {
      * @see {@link https://valkey.io/commands/bitcount/|valkey.io} for more details.
      *
      * @param key - The key for the string to count the set bits of.
-     * @param options - The offset options.
+     * @param options - The offset options - see {@link BitOffsetOptions}.
      * @returns If `options` is provided, returns the number of set bits in the string interval specified by `options`.
      *     If `options` is not provided, returns the number of set bits in the string stored at `key`.
      *     Otherwise, if `key` is missing, returns `0` as it is treated as an empty string.