Merge branch 'release-1.2' into fix_pypi

Signed-off-by: avifenesh <[email protected]>

.github/workflows/pypi-cd.yml

@@ -179,7 +179,7 @@ jobs:
               if: startsWith(matrix.build.NAMED_OS, 'darwin')
               uses: PyO3/maturin-action@v1
               with:
-                  maturin-version: latest                 
+                  maturin-version: "0.14.14" # Due to a bug in later versions
                   working-directory: ./python
                   target: ${{ matrix.build.TARGET }}
                   args: --release --strip --out wheels -i  ${{ github.event_name != 'pull_request' && 'python3.9 python3.10 python3.11 python3.12 python3.13' || 'python3.13' }}

node/src/BaseClient.ts

@@ -506,6 +506,67 @@ export type ReadFrom =
 
 /**
  * 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 {
     /**

node/src/GlideClient.ts

@@ -99,6 +99,43 @@ export namespace GlideClientConfiguration {
     }
 }
 
+/**
+ * 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.
@@ -154,7 +191,53 @@ export class GlideClient extends BaseClient {
         this.configurePubsub(options, configuration);
         return configuration;
     }
-
+    /**
+     * 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.
+     */
     public static async createClient(
         options: GlideClientConfiguration,
     ): Promise<GlideClient> {
@@ -164,7 +247,9 @@ export class GlideClient extends BaseClient {
                 new GlideClient(socket, options),
         );
     }
-
+    /**
+     * @internal
+     */
     static async __createClient(
         options: BaseClientConfiguration,
         connectedSocket: net.Socket,