@valkey/valkey-glide 1.3.5-rc9 → 2.0.0-rc7

package/README.md

@@ -27,23 +27,30 @@ Refer to the [Supported Engine Versions table](https://github.com/valkey-io/valk
 
 The release of Valkey GLIDE was tested on the following platforms:
 
-Linux:
+### Linux GNU
 
-- Ubuntu 22.04.5 (x86_64/amd64 and arm64/aarch64)
-- Amazon Linux 2023 (AL2023) (x86_64/amd64 and arm64/aarch64)
+Linux with **glibc 2.17** or higher.
 
-macOS:
+### MacOS (Darwin)
 
-- macOS 14.7 (Apple silicon/aarch_64)
-- macOS 13.7 (x86_64/amd64)
+MacOS Apple Silicon/aarch_64 and x86_64/amd64.
 
-Alpine:
+- Full tests are running on MacOS 15.0 arm64/aarch64
+- Minimal tests are running on: MacOS 13.5 x86*64/amd64*(We do not recommend using MacOS Intel for production, It is supported for development purposes)\_
+
+### Alpine
+
+All alpine versions that are using _musl libc_ 1.2.3 (All Alpine non deprecated alpine versions) or higher should be supported.
+Tests are running on:
 
 - node:alpine (x86_64/amd64 and arm64/aarch64)
 
 ## NodeJS supported version
 
 Node.js 16 or higher.
+**For npm users on linux it is recommended to use npm >=11 since it support optional download base on libc, yarn users should not be concerned**
+
+- Note: The library is dependent on the [protobufjs library](https://protobufjs.github.io/protobuf.js/#installation), which add a size to the package. The package is using the protobufjs/minimal version, hence, if size matter, bundlers should be able to strip the unused code. It should reduce the size of the dependency from 19kb gzipped to 6.5kb gzipped.
 
 ### Building & Testing
 
@@ -75,6 +82,8 @@ const client = await GlideClient.createClient({
     addresses: addresses,
     // if the server uses TLS, you'll need to enable it. Otherwise, the connection attempt will time out silently.
     // useTLS: true,
+    // It is recommended to set a timeout for your specific use case
+    requestTimeout: 500, // 500ms timeout
     clientName: "test_standalone_client",
 });
 // The empty array signifies that there are no additional arguments.
@@ -102,6 +111,8 @@ const client = await GlideClusterClient.createClient({
     addresses: addresses,
     // if the cluster nodes use TLS, you'll need to enable it. Otherwise the connection attempt will time out silently.
     // useTLS: true,
+    // It is recommended to set a timeout for your specific use case
+    requestTimeout: 500, // 500ms timeout
     clientName: "test_cluster_client",
 });
 // The empty array signifies that there are no additional arguments.

package/build-ts/BaseClient.d.ts

@@ -1,15 +1,9 @@
 import { Buffer, Writer } from "protobufjs/minimal";
-import { command_request, connection_request, response } from "../build-ts/ProtobufMessage";
-import { AggregationType, BaseScanOptions, BatchOptions, BitFieldGet, // eslint-disable-line @typescript-eslint/no-unused-vars
+import { AggregationType, BaseScanOptions, BitFieldGet, // eslint-disable-line @typescript-eslint/no-unused-vars
 BitFieldSubCommands, // eslint-disable-line @typescript-eslint/no-unused-vars
-BitOffsetOptions, BitwiseOperation, Boundary, ClusterBatchOptions, // 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, RequestError, ValkeyError } from "./Errors";
-import { GlideClientConfiguration } from "./GlideClient";
-import { GlideClusterClientConfiguration, Routes } from "./GlideClusterClient";
-import { Script } from "./native";
+BitOffsetOptions, BitwiseOperation, Boundary, ConnectionError, ExpireOptions, GeoAddOptions, // eslint-disable-line @typescript-eslint/no-unused-vars
+GeoSearchResultOptions, GeoSearchShape, GeoSearchStoreResultOptions, GeoUnit, GeospatialData, GlideClientConfiguration, GlideClusterClientConfiguration, HScanOptions, InsertPosition, KeyWeight, LPosOptions, ListDirection, RangeByIndex, RangeByLex, RangeByScore, RequestError, RestoreOptions, Routes, ScoreFilter, Script, SearchOrigin, SetOptions, SortOptions, StreamAddOptions, StreamClaimOptions, StreamGroupOptions, StreamPendingOptions, StreamReadGroupOptions, StreamReadOptions, StreamTrimOptions, TimeUnit, ValkeyError, ZAddOptions, ZScanOptions } from ".";
+import { command_request, connection_request, response } from "../build-ts/ProtobufMessage";
 type PromiseFunction = (value?: any) => void;
 type ErrorFunction = (error: ValkeyError) => void;
 export type ReturnTypeRecord = {
@@ -150,10 +144,13 @@ export type ReadFrom =
  * - **Addresses**: Use the `addresses` property to specify the hostnames and ports of the server(s) to connect to.
  *   - **Cluster Mode**: In cluster mode, the client will discover other nodes based on the provided addresses.
  *   - **Standalone Mode**: In standalone mode, only the provided nodes will be used.
+ * - **Lazy Connect**: Set `lazyConnect` to `true` to defer connection establishment until the first command is sent.
  *
  * ### Security Settings
  *
  * - **TLS**: Enable secure communication using `useTLS`.
+ *      Should match the TLS configuration of the server/cluster, otherwise the connection attempt will fail.
+ *      For advanced tls configuration, , see {@link AdvancedBaseClientConfiguration}.
  * - **Authentication**: Provide `credentials` to authenticate with the server.
  *
  * ### Communication Settings
@@ -181,6 +178,14 @@ export type ReadFrom =
  *
  * - **Inflight Requests Limit**: Control the number of concurrent requests using `inflightRequestsLimit`.
  *
+ * ### Reconnection Strategy
+ * - **Reconnection Strategy**: Customize how the client should attempt reconnections using `connectionBackoff`.
+ *   - `numberOfRetries`: The maximum number of retry attempts with increasing delays.
+ *     - After this limit is reached, the retry interval becomes constant.
+ *   - `factor`: A multiplier applied to the base delay between retries (e.g., `500` means a 500ms base delay).
+ *   - `exponentBase`: The exponential growth factor for delays (e.g., `2` means the delay doubles with each retry).
+ *  - `jitterPercent`: An optional percentage of jitter to add to the delay (e.g., `30` means the final delay will vary randomly between 70% and 130% of the calculated delay).
+ *
  * @example
  * ```typescript
  * const config: BaseClientConfiguration = {
@@ -200,6 +205,13 @@ export type ReadFrom =
  *   clientAz: 'us-east-1a',
  *   defaultDecoder: Decoder.String,
  *   inflightRequestsLimit: 1000,
+ *   connectionBackoff: {
+ *     numberOfRetries: 10, // Maximum retries before delay becomes constant
+ *     factor: 500,        // Base delay in milliseconds
+ *     exponentBase: 2,    // Delay doubles with each retry (2^N)
+ *     jitterPercent: 20,   // Optional jitter percentage
+ *   },
+ *   lazyConnect: true,
  * };
  * ```
  */
@@ -239,7 +251,7 @@ export interface BaseClientConfiguration {
     credentials?: ServerCredentials;
     /**
      * The duration in milliseconds that the client should wait for a request to complete.
-     * This duration encompasses sending the request, awaiting for a response from the server, and any required reconnections or retries.
+     * This duration encompasses sending the request, awaiting for a response from the server, and any required reconnection or retries.
      * If the specified timeout is exceeded for a pending request, it will result in a timeout error.
      * If not explicitly set, a default value of 250 milliseconds will be used.
      * Value must be an integer.
@@ -285,6 +297,71 @@ export interface BaseClientConfiguration {
      * ```
      */
     clientAz?: string;
+    /**
+     * Strategy used to determine how and when to reconnect, in case of connection failures.
+     * The time between attempts grows exponentially, following the formula rand(0 ... factor * (exponentBase ^ N)), where N is the number of failed attempts,
+     * and rand(...) applies a jitter of up to `jitterPercent`% to introduce randomness and reduce retry storms.
+     * The client will attempt to reconnect indefinitely. Once the maximum value is reached, that will remain the time between retry attempts until a
+     * reconnect attempt is successful.
+     * If not set, a default backoff strategy will be used.
+     */
+    connectionBackoff?: {
+        /**
+         * Number of retry attempts that the client should perform when disconnected from the server, where the time between retries increases.
+         * Once the retries have reached the maximum value, the time between retries will remain constant until a reconnect attempt is succesful.
+         * Value must be an integer.
+         */
+        numberOfRetries: number;
+        /**
+         * The multiplier that will be applied to the waiting time between each retry.
+         * Value must be an integer.
+         */
+        factor: number;
+        /**
+         * The exponent base configured for the strategy.
+         * Value must be an integer.
+         */
+        exponentBase: number;
+        /** The Jitter percent on the calculated duration.
+         * If not set, a default value will be used.
+         * Value is optional, and must be an integer.
+         */
+        jitterPercent?: number;
+    };
+    /**
+     * Enables lazy connection mode, where physical connections to the server(s) are deferred
+     * until the first command is sent. This can reduce startup latency and allow for client
+     * creation in disconnected environments.
+     *
+     * - **Default**: `false` – connections are established immediately during client creation.
+     *
+     * @remarks
+     * When `lazyConnect` is set to `true`, the client will not attempt to connect to the specified
+     * nodes during initialization. Instead, connections will be established only when a command is
+     * actually executed.
+     *
+     * Note that the first command executed with lazy connections may experience additional latency
+     * as it needs to establish the connection first. During this initial connection, the standard
+     * request timeout does not apply yet - instead, the connection establishment is governed by
+     * `AdvancedBaseClientConfiguration::connectionTimeout`. The request timeout (`requestTimeout`)
+     * only begins counting after the connection has been successfully established. This behavior
+     * can effectively increase the total time needed for the first command to complete.
+     *
+     * This setting applies to both standalone and cluster modes. Note that if an operation is
+     * attempted and connection fails (e.g., unreachable nodes), errors will surface at that point.
+     *
+     * @example
+     * ```typescript
+     * const client = await GlideClient.createClient({
+     *   addresses: [{ host: "localhost", port: 6379 }],
+     *   lazyConnect: true
+     * });
+     *
+     * // No connection is made yet
+     * await client.ping(); // Now the client connects and sends the command
+     * ```
+     */
+    lazyConnect?: boolean;
 }
 /**
  * Represents advanced configuration settings for a client, including connection-related options.
@@ -296,6 +373,10 @@ export interface BaseClientConfiguration {
  *
  * - **Connection Timeout**: The `connectionTimeout` property specifies the duration (in milliseconds) the client should wait for a connection to be established.
  *
+ * ### TLS config
+ *
+ * - **TLS Configuration**: The `tlsAdvancedConfiguration` property allows for advanced TLS settings, such as enabling insecure mode.
+ *
  * @example
  * ```typescript
  * const config: AdvancedBaseClientConfiguration = {
@@ -306,11 +387,33 @@ export interface BaseClientConfiguration {
 export interface AdvancedBaseClientConfiguration {
     /**
      * The duration in milliseconds to wait for a TCP/TLS connection to complete.
-     * This applies both during initial client creation and any reconnections that may occur during request processing.
+     * This applies both during initial client creation and any reconnection that may occur during request processing.
      * **Note**: A high connection timeout may lead to prolonged blocking of the entire command pipeline.
-     * If not explicitly set, a default value of 250 milliseconds will be used.
+     * If not explicitly set, a default value of 2000 milliseconds will be used.
      */
     connectionTimeout?: number;
+    /**
+     * The advanced TLS configuration settings. This allows for more granular control of TLS behavior,
+     * such as enabling an insecure mode that bypasses certificate validation.
+     */
+    tlsAdvancedConfiguration?: {
+        /**
+         * Whether to bypass TLS certificate verification.
+         *
+         * - When set to `true`, the client skips certificate validation.
+         *   This is useful when connecting to servers or clusters using self-signed certificates,
+         *   or when DNS entries (e.g., CNAMEs) don't match certificate hostnames.
+         *
+         * - This setting is typically used in development or testing environments.
+         *   **It is strongly discouraged in production**, as it introduces security risks such as man-in-the-middle attacks.
+         *
+         * - Only valid if TLS is already enabled in the base client configuration.
+         *   Enabling it without TLS will result in a `ConfigurationError`.
+         *
+         * - Default: false (verification is enforced).
+         */
+        insecure?: boolean;
+    };
 }
 /**
  * Enum of Valkey data types
@@ -334,7 +437,6 @@ export interface PubSubMsg {
     channel: GlideString;
     pattern?: GlideString | null;
 }
-export type WritePromiseOptions = BaseOptions | (BaseOptions & (ClusterBatchOptions | BatchOptions));
 /**
  * Base client interface for GLIDE
  */
@@ -355,6 +457,7 @@ export declare class BaseClient {
     protected configurePubsub(options: GlideClusterClientConfiguration | GlideClientConfiguration, configuration: connection_request.IConnectionRequest): void;
     private handleReadData;
     protected toProtobufRoute(route: Routes | undefined): command_request.Routes | undefined;
+    private dropCommandSpan;
     processResponse(message: response.Response): void;
     processPush(response: response.Response): void;
     protected getCallbackIndex(): number;
@@ -1531,7 +1634,7 @@ export declare class BaseClient {
      * @param start - The starting point of the range.
      * @param end - The end of the range.
      * @returns always "OK".
-     * If `start` exceeds the end of the list, or if `start` is greater than `end`, the result will be an empty list (which causes key to be removed).
+     * If `start` exceeds the end of the list, or if `start` is greater than `end`, the list is emptied and the key is removed.
      * If `end` exceeds the actual end of the list, it will be treated like the last element of the list.
      * If `key` does not exist the command will be ignored.
      *
@@ -1544,12 +1647,12 @@ export declare class BaseClient {
      */
     ltrim(key: GlideString, start: number, end: number): Promise<"OK">;
     /** Removes the first `count` occurrences of elements equal to `element` from the list stored at `key`.
-     * If `count` is positive : Removes elements equal to `element` moving from head to tail.
-     * If `count` is negative : Removes elements equal to `element` moving from tail to head.
-     * If `count` is 0 or `count` is greater than the occurrences of elements equal to `element`: Removes all elements equal to `element`.
      *
      * @param key - The key of the list.
      * @param count - The count of the occurrences of elements equal to `element` to remove.
+     * If `count` is positive : Removes elements equal to `element` moving from head to tail.
+     * If `count` is negative : Removes elements equal to `element` moving from tail to head.
+     * If `count` is 0 or `count` is greater than the occurrences of elements equal to `element`: Removes all elements equal to `element`.
      * @param element - The element to remove from the list.
      * @returns the number of the removed elements.
      * If `key` does not exist, 0 is returned.
@@ -4219,16 +4322,16 @@ export declare class BaseClient {
      * @param key - The key of the HyperLogLog data structure to add elements into.
      * @param elements - An array of members to add to the HyperLogLog stored at `key`.
      * @returns - If the HyperLogLog is newly created, or if the HyperLogLog approximated cardinality is
-     *     altered, then returns `1`. Otherwise, returns `0`.
+     *     altered, then returns `true`. Otherwise, returns `false`.
      * @example
      * ```typescript
      * const result = await client.pfadd("hll_1", ["a", "b", "c"]);
-     * console.log(result); // Output: 1 - Indicates that a data structure was created or modified
+     * console.log(result); // Output: true - Indicates that a data structure was created or modified
      * const result = await client.pfadd("hll_2", []);
-     * console.log(result); // Output: 1 - Indicates that a new empty data structure was created
+     * console.log(result); // Output: true - Indicates that a new empty data structure was created
      * ```
      */
-    pfadd(key: GlideString, elements: GlideString[]): Promise<number>;
+    pfadd(key: GlideString, elements: GlideString[]): Promise<boolean>;
     /** Estimates the cardinality of the data stored in a HyperLogLog structure for a single key or
      * calculates the combined cardinality of multiple keys by merging their HyperLogLogs temporarily.
      *