@valkey/valkey-glide 1.2.0-rc9 → 1.2.1-rc0

package/build-ts/index.js

@@ -45,9 +45,6 @@ function loadNativeBinding() {
             break;
         case "darwin":
             switch (process_1.arch) {
-                case "x64":
-                    nativeBinding = require("@valkey/valkey-glide-darwin-x64");
-                    break;
                 case "arm64":
                     nativeBinding = require("@valkey/valkey-glide-darwin-arm64");
                     break;
@@ -65,10 +62,11 @@ function loadNativeBinding() {
 }
 function initialize() {
     const nativeBinding = loadNativeBinding();
-    const { AggregationType, BaseScanOptions, ZScanOptions, HScanOptions, BitEncoding, BitFieldGet, BitFieldIncrBy, BitFieldOffset, BitFieldOverflow, BitFieldSet, BitFieldSubCommands, BitOffset, BitOffsetMultiplier, BitOffsetOptions, BitOverflowControl, BitmapIndexType, BitwiseOperation, ConditionalChange, Decoder, DecoderOption, GeoAddOptions, CoordOrigin, MemberOrigin, SearchOrigin, GeoBoxShape, GeoCircleShape, GeoSearchShape, GeoSearchResultOptions, GeoSearchStoreResultOptions, SortOrder, GeoUnit, GeospatialData, GlideClient, GlideClusterClient, GlideClientConfiguration, GlideJson, GlideFt, TextField, TagField, NumericField, VectorField, VectorFieldAttributesFlat, VectorFieldAttributesHnsw, FtCreateOptions, FtSearchOptions, FtInfoReturnType, FtAggregateOptions, FtAggregateLimit, FtAggregateFilter, FtAggregateGroupBy, FtAggregateReducer, FtAggregateSortBy, FtAggregateSortProperty, FtAggregateApply, FtAggregateReturnType, FtSearchReturnType, FtProfileOtions, GlideRecord, GlideString, JsonGetOptions, JsonArrPopOptions, SortedSetDataType, StreamEntryDataType, HashDataType, FunctionListOptions, FunctionListResponse, FunctionStatsSingleResponse, FunctionStatsFullResponse, FunctionRestorePolicy, SlotIdTypes, SlotKeyTypes, TimeUnit, RouteByAddress, RouteOption, Routes, RestoreOptions, SingleNodeRoute, PeriodicChecksManualInterval, PeriodicChecks, Logger, Limit, LolwutOptions, LPosOptions, ListDirection, ExpireOptions, FlushMode, InfoOptions, InsertPosition, SetOptions, ZAddOptions, InfBoundary, KeyWeight, Boundary, UpdateOptions, ProtocolVersion, RangeByIndex, RangeByScore, RangeByLex, ReadFrom, ServerCredentials, SortClusterOptions, SortOptions, SortedSetRange, StreamGroupOptions, StreamTrimOptions, StreamAddOptions, StreamReadGroupOptions, StreamReadOptions, StreamClaimOptions, StreamPendingOptions, ClosingError, ConfigurationError, ExecAbortError, ValkeyError, GlideReturnType, StreamEntries, ReturnTypeXinfoStream, RequestError, TimeoutError, ConnectionError, ClusterTransaction, Transaction, PubSubMsg, ScoreFilter, SignedEncoding, UnsignedEncoding, UpdateByScore, createLeakedArray, createLeakedAttribute, createLeakedBigint, createLeakedDouble, createLeakedMap, createLeakedString, parseInfoResponse, Script, ObjectType, ClusterScanCursor, BaseClientConfiguration, GlideClusterClientConfiguration, LevelOptions, ReturnTypeRecord, ReturnTypeMap, ClusterResponse, ReturnTypeAttribute, ReturnTypeJson, UniversalReturnTypeJson, } = nativeBinding;
+    const { AggregationType, BaseScanOptions, ScanOptions, ZScanOptions, HScanOptions, BitEncoding, BitFieldGet, BitFieldIncrBy, BitFieldOffset, BitFieldOverflow, BitFieldSet, BitFieldSubCommands, BitOffset, BitOffsetMultiplier, BitOffsetOptions, BitOverflowControl, BitmapIndexType, BitwiseOperation, ConditionalChange, Decoder, DecoderOption, GeoAddOptions, CoordOrigin, MemberOrigin, SearchOrigin, GeoBoxShape, GeoCircleShape, GeoSearchShape, GeoSearchResultOptions, GeoSearchStoreResultOptions, SortOrder, GeoUnit, GeospatialData, GlideClient, GlideClusterClient, GlideClientConfiguration, GlideJson, GlideFt, Field, TextField, TagField, NumericField, VectorField, VectorFieldAttributesFlat, VectorFieldAttributesHnsw, FtCreateOptions, FtSearchOptions, FtInfoReturnType, FtAggregateOptions, FtAggregateLimit, FtAggregateFilter, FtAggregateGroupBy, FtAggregateReducer, FtAggregateSortBy, FtAggregateSortProperty, FtAggregateApply, FtAggregateReturnType, FtSearchReturnType, GlideRecord, GlideString, JsonGetOptions, JsonArrPopOptions, SortedSetDataType, StreamEntryDataType, HashDataType, FunctionListOptions, FunctionListResponse, FunctionStatsSingleResponse, FunctionStatsFullResponse, FunctionRestorePolicy, SlotIdTypes, SlotKeyTypes, TimeUnit, RouteByAddress, RouteOption, Routes, RestoreOptions, SingleNodeRoute, PeriodicChecksManualInterval, PeriodicChecks, Logger, Limit, LolwutOptions, LPosOptions, ListDirection, ExpireOptions, FlushMode, InfoOptions, InsertPosition, SetOptions, ZAddOptions, InfBoundary, KeyWeight, Boundary, ProtocolVersion, RangeByIndex, RangeByScore, RangeByLex, ReadFrom, ServerCredentials, SortOptions, StreamGroupOptions, StreamTrimOptions, StreamAddOptions, StreamReadGroupOptions, StreamReadOptions, StreamClaimOptions, StreamPendingOptions, ClosingError, ConfigurationError, ExecAbortError, ValkeyError, GlideReturnType, StreamEntries, ReturnTypeXinfoStream, RequestError, TimeoutError, ConnectionError, ClusterTransaction, Transaction, PubSubMsg, ScoreFilter, SignedEncoding, UnsignedEncoding, UpdateByScore, createLeakedArray, createLeakedAttribute, createLeakedBigint, createLeakedDouble, createLeakedMap, createLeakedString, Script, ObjectType, ClusterScanCursor, AdvancedGlideClientConfiguration, AdvancedGlideClusterClientConfiguration, BaseClientConfiguration, GlideClusterClientConfiguration, LevelOptions, ReturnTypeRecord, ReturnTypeMap, ClusterResponse, ReturnTypeAttribute, ReturnTypeJson, UniversalReturnTypeJson, } = nativeBinding;
     module.exports = {
         AggregationType,
         BaseScanOptions,
+        ScanOptions,
         HScanOptions,
         ZScanOptions,
         BitEncoding,
@@ -89,6 +87,7 @@ function initialize() {
         DecoderOption,
         GeoAddOptions,
         GlideFt,
+        Field,
         TextField,
         TagField,
         NumericField,
@@ -108,7 +107,6 @@ function initialize() {
         FtAggregateApply,
         FtAggregateReturnType,
         FtSearchReturnType,
-        FtProfileOtions,
         GlideRecord,
         GlideJson,
         GlideString,
@@ -131,6 +129,8 @@ function initialize() {
         GlideClient,
         GlideClusterClient,
         GlideClientConfiguration,
+        AdvancedGlideClientConfiguration,
+        AdvancedGlideClusterClientConfiguration,
         FunctionListOptions,
         FunctionListResponse,
         FunctionStatsSingleResponse,
@@ -162,16 +162,13 @@ function initialize() {
         InfBoundary,
         KeyWeight,
         Boundary,
-        UpdateOptions,
         ProtocolVersion,
         RangeByIndex,
         RangeByScore,
         RangeByLex,
         ReadFrom,
         ServerCredentials,
-        SortClusterOptions,
         SortOptions,
-        SortedSetRange,
         StreamGroupOptions,
         StreamTrimOptions,
         StreamAddOptions,
@@ -200,7 +197,6 @@ function initialize() {
         createLeakedDouble,
         createLeakedMap,
         createLeakedString,
-        parseInfoResponse,
         Script,
         ObjectType,
         ClusterScanCursor,

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

@@ -142,6 +142,67 @@ export type ReadFrom =
  | "AZAffinity";
 /**
  * Configuration settings for creating a client. Shared settings for standalone and cluster clients.
+ *
+ * @remarks
+ * The `BaseClientConfiguration` interface defines the foundational configuration options used when creating a client to connect to a Valkey server or cluster. It includes connection details, authentication, communication protocols, and various settings that influence the client's behavior and interaction with the server.
+ *
+ * ### Connection Details
+ *
+ * - **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.
+ *
+ * ### Security Settings
+ *
+ * - **TLS**: Enable secure communication using `useTLS`.
+ * - **Authentication**: Provide `credentials` to authenticate with the server.
+ *
+ * ### Communication Settings
+ *
+ * - **Request Timeout**: Set `requestTimeout` to specify how long the client should wait for a request to complete.
+ * - **Protocol Version**: Choose the serialization protocol using `protocol`.
+ *
+ * ### Client Identification
+ *
+ * - **Client Name**: Set `clientName` to identify the client connection.
+ *
+ * ### Read Strategy
+ *
+ * - Use `readFrom` to specify the client's read strategy (e.g., primary, preferReplica, AZAffinity).
+ *
+ * ### Availability Zone
+ *
+ * - Use `clientAz` to specify the client's availability zone, which can influence read operations when using `readFrom: 'AZAffinity'`.
+ *
+ * ### Decoder Settings
+ *
+ * - **Default Decoder**: Set `defaultDecoder` to specify how responses are decoded by default.
+ *
+ * ### Concurrency Control
+ *
+ * - **Inflight Requests Limit**: Control the number of concurrent requests using `inflightRequestsLimit`.
+ *
+ * @example
+ * ```typescript
+ * const config: BaseClientConfiguration = {
+ *   addresses: [
+ *     { host: 'redis-node-1.example.com', port: 6379 },
+ *     { host: 'redis-node-2.example.com' }, // Defaults to port 6379
+ *   ],
+ *   useTLS: true,
+ *   credentials: {
+ *     username: 'myUser',
+ *     password: 'myPassword',
+ *   },
+ *   requestTimeout: 5000, // 5 seconds
+ *   protocol: ProtocolVersion.RESP3,
+ *   clientName: 'myValkeyClient',
+ *   readFrom: ReadFrom.AZAffinity,
+ *   clientAz: 'us-east-1a',
+ *   defaultDecoder: Decoder.String,
+ *   inflightRequestsLimit: 1000,
+ * };
+ * ```
  */
 export interface BaseClientConfiguration {
     /**
@@ -181,7 +242,7 @@ export interface BaseClientConfiguration {
      * 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.
      * If the specified timeout is exceeded for a pending request, it will result in a timeout error.
-     * If not set, a default value will be used.
+     * If not explicitly set, a default value of 250 milliseconds will be used.
      * Value must be an integer.
      */
     requestTimeout?: number;
@@ -224,6 +285,32 @@ export interface BaseClientConfiguration {
      */
     clientAz?: string;
 }
+/**
+ * Represents advanced configuration settings for a client, including connection-related options.
+ *
+ * @remarks
+ * The `AdvancedBaseClientConfiguration` interface defines advanced configuration settings for managing the client's connection behavior.
+ *
+ * ### Connection Timeout
+ *
+ * - **Connection Timeout**: The `connectionTimeout` property specifies the duration (in milliseconds) the client should wait for a connection to be established.
+ *
+ * @example
+ * ```typescript
+ * const config: AdvancedBaseClientConfiguration = {
+ *   connectionTimeout: 5000, // 5 seconds
+ * };
+ * ```
+ */
+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.
+     * **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.
+     */
+    connectionTimeout?: number;
+}
 /**
  * Enum of Valkey data types
  * `STRING`
@@ -5174,6 +5261,10 @@ export declare class BaseClient {
      * @internal
      */
     protected createClientRequest(options: BaseClientConfiguration): connection_request.IConnectionRequest;
+    /**
+     * @internal
+     */
+    protected configureAdvancedConfigurationBase(options: AdvancedBaseClientConfiguration, request: connection_request.IConnectionRequest): void;
     /**
      * @internal
      */
@@ -5216,5 +5307,11 @@ export declare class BaseClient {
      * ```
      */
     updateConnectionPassword(password: string | null, immediateAuth?: boolean): Promise<GlideString>;
+    /**
+     * Return a statistics
+     *
+     * @return Return an object that contains the statistics collected internally by GLIDE core
+     */
+    getStatistics(): object;
 }
 export {};

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

@@ -1679,6 +1679,18 @@ export interface BaseScanOptions {
 export interface ScanOptions extends BaseScanOptions {
     type?: ObjectType;
 }
+/**
+ * Options for the SCAN command.
+ * `match`: The match filter is applied to the result of the command and will only include keys that match the pattern specified.
+ * `count`: `COUNT` is a just a hint for the command for how many elements to fetch from the server, the default is 10.
+ * `type`: The type of the object to scan.
+ * Types are the data types of Valkey: `string`, `list`, `set`, `zset`, `hash`, `stream`.
+ * `allowNonCoveredSlots`: If true, the scan will keep scanning even if slots are not covered by the cluster.
+ * By default, the scan will stop if slots are not covered by the cluster.
+ */
+export interface ClusterScanOptions extends ScanOptions {
+    allowNonCoveredSlots?: boolean;
+}
 /**
  * Options specific to the ZSCAN command, extending from the base scan options.
  */

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

@@ -2,7 +2,7 @@
  * Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
  */
 import * as net from "net";
-import { BaseClient, BaseClientConfiguration, DecoderOption, GlideReturnType, GlideString, PubSubMsg } from "./BaseClient";
+import { AdvancedBaseClientConfiguration, BaseClient, BaseClientConfiguration, DecoderOption, GlideReturnType, GlideString, PubSubMsg } from "./BaseClient";
 import { FlushMode, FunctionListOptions, FunctionListResponse, FunctionRestorePolicy, FunctionStatsFullResponse, InfoOptions, LolwutOptions, ScanOptions } from "./Commands";
 import { connection_request } from "./ProtobufMessage";
 import { Transaction } from "./Transaction";
@@ -36,6 +36,43 @@ export declare namespace GlideClientConfiguration {
         context?: any;
     }
 }
+/**
+ * Configuration options for creating a {@link GlideClient | GlideClient}.
+ *
+ * Extends `BaseClientConfiguration` with properties specific to `GlideClient`, such as database selection,
+ * reconnection strategies, and Pub/Sub subscription settings.
+ *
+ * @remarks
+ * This configuration allows you to tailor the client's behavior when connecting to a standalone Valkey Glide server.
+ *
+ * - **Database Selection**: Use `databaseId` to specify which logical database to connect to.
+ * - **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).
+ * - **Pub/Sub Subscriptions**: Predefine Pub/Sub channels and patterns to subscribe to upon connection establishment.
+ *
+ * @example
+ * ```typescript
+ * const config: GlideClientConfiguration = {
+ *   databaseId: 1,
+ *   connectionBackoff: {
+ *     numberOfRetries: 10, // Maximum retries before delay becomes constant
+ *     factor: 500,        // Base delay in milliseconds
+ *     exponentBase: 2,    // Delay doubles with each retry (2^N)
+ *   },
+ *   pubsubSubscriptions: {
+ *     channelsAndPatterns: {
+ *       [GlideClientConfiguration.PubSubChannelModes.Pattern]: new Set(['news.*']),
+ *     },
+ *     callback: (msg) => {
+ *       console.log(`Received message on ${msg.channel}:`, msg.payload);
+ *     },
+ *   },
+ * };
+ * ```
+ */
 export type GlideClientConfiguration = BaseClientConfiguration & {
     /**
      * index of the logical database to connect to.
@@ -71,7 +108,23 @@ export type GlideClientConfiguration = BaseClientConfiguration & {
      * Will be applied via SUBSCRIBE/PSUBSCRIBE commands during connection establishment.
      */
     pubsubSubscriptions?: GlideClientConfiguration.PubSubSubscriptions;
+    /**
+     * Advanced configuration settings for the client.
+     */
+    advancedConfiguration?: AdvancedGlideClientConfiguration;
 };
+/**
+ * Represents advanced configuration settings for creating a {@link GlideClient | GlideClient} used in {@link GlideClientConfiguration | GlideClientConfiguration}.
+ *
+ *
+ * @example
+ * ```typescript
+ * const config: AdvancedGlideClientConfiguration = {
+ *   connectionTimeout: 500, // Set the connection timeout to 500ms
+ * };
+ * ```
+ */
+export type AdvancedGlideClientConfiguration = AdvancedBaseClientConfiguration & {};
 /**
  * Client used for connection to standalone servers.
  *
@@ -82,7 +135,57 @@ export declare class GlideClient extends BaseClient {
      * @internal
      */
     protected createClientRequest(options: GlideClientConfiguration): connection_request.IConnectionRequest;
+    /**
+     * Creates a new `GlideClient` instance and establishes a connection to a standalone Valkey Glide server.
+     *
+     * @param options - The configuration options for the client, including server addresses, authentication credentials, TLS settings, database selection, reconnection strategy, and Pub/Sub subscriptions.
+     * @returns A promise that resolves to a connected `GlideClient` instance.
+     *
+     * @remarks
+     * Use this static method to create and connect a `GlideClient` to a standalone Valkey Glide server. The client will automatically handle connection establishment, including any authentication and TLS configurations.
+     *
+     * @example
+     * ```typescript
+     * // Connecting to a Standalone Server
+     * import { GlideClient, GlideClientConfiguration } from '@valkey/valkey-glide';
+     *
+     * const client = await GlideClient.createClient({
+     *   addresses: [
+     *     { host: 'primary.example.com', port: 6379 },
+     *     { host: 'replica1.example.com', port: 6379 },
+     *   ],
+     *   databaseId: 1,
+     *   credentials: {
+     *     username: 'user1',
+     *     password: 'passwordA',
+     *   },
+     *   useTLS: true,
+     *   connectionBackoff: {
+     *     numberOfRetries: 5,
+     *     factor: 1000,
+     *     exponentBase: 2,
+     *   },
+     *   pubsubSubscriptions: {
+     *     channelsAndPatterns: {
+     *       [GlideClientConfiguration.PubSubChannelModes.Exact]: new Set(['updates']),
+     *     },
+     *     callback: (msg) => {
+     *       console.log(`Received message: ${msg.payload}`);
+     *     },
+     *   },
+     * });
+     * ```
+     *
+     * @remarks
+     * - **Authentication**: If `credentials` are provided, the client will attempt to authenticate using the specified username and password.
+     * - **TLS**: If `useTLS` is set to `true`, the client will establish a secure connection using TLS.
+     * - **Reconnection Strategy**: The `connectionBackoff` settings define how the client will attempt to reconnect in case of disconnections.
+     * - **Pub/Sub Subscriptions**: Any channels or patterns specified in `pubsubSubscriptions` will be subscribed to upon connection.
+     */
     static createClient(options: GlideClientConfiguration): Promise<GlideClient>;
+    /**
+     * @internal
+     */
     static __createClient(options: BaseClientConfiguration, connectedSocket: net.Socket): Promise<GlideClient>;
     /**
      * Execute a transaction by processing the queued commands.