@valkey/valkey-glide 1.1.0 → 1.2.0-rc7

package/README.md

@@ -14,12 +14,16 @@ The release of Valkey GLIDE was tested on the following platforms:
 
 Linux:
 
--   Ubuntu 22.04.1 (x86_64)
+-   Ubuntu 22.04.1 (x86_64 and aarch64)
 -   Amazon Linux 2023 (AL2023) (x86_64)
 
 macOS:
 
--   macOS 12.7 (Apple silicon/aarch_64 and Intel/x86_64)
+-   macOS 14.7 (Apple silicon/aarch_64)
+
+Alpine:
+
+-   node:alpine (default on aarch64 and x86_64)
 
 ## NodeJS supported version
 
@@ -92,9 +96,9 @@ client.close();
 
 ### Supported platforms
 
-Currentlly the package is supported on:
+Currently, the package is tested on:
 
 | Operation systems | C lib                | Architecture      |
 | ----------------- | -------------------- | ----------------- |
 | `Linux`           | `glibc`, `musl libc` | `x86_64`, `arm64` |
-| `macOS`           | `Darwin`             | `x86_64`, `arm64` |
+| `macOS`           | `Darwin`             | `arm64`           |

package/build-ts/index.d.ts

@@ -8,4 +8,7 @@ export * from "./src/Errors";
 export * from "./src/GlideClient";
 export * from "./src/GlideClusterClient";
 export * from "./src/Logger";
+export * from "./src/server-modules/GlideJson";
+export * from "./src/server-modules/GlideFt";
+export * from "./src/server-modules/GlideFtOptions";
 export * from "./src/Transaction";

package/build-ts/index.js

@@ -65,7 +65,7 @@ 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, GlideRecord, GlideString, 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, } = nativeBinding;
+    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;
     module.exports = {
         AggregationType,
         BaseScanOptions,
@@ -88,8 +88,32 @@ function initialize() {
         Decoder,
         DecoderOption,
         GeoAddOptions,
+        GlideFt,
+        TextField,
+        TagField,
+        NumericField,
+        VectorField,
+        VectorFieldAttributesFlat,
+        VectorFieldAttributesHnsw,
+        FtCreateOptions,
+        FtSearchOptions,
+        FtInfoReturnType,
+        FtAggregateOptions,
+        FtAggregateLimit,
+        FtAggregateFilter,
+        FtAggregateGroupBy,
+        FtAggregateReducer,
+        FtAggregateSortBy,
+        FtAggregateSortProperty,
+        FtAggregateApply,
+        FtAggregateReturnType,
+        FtSearchReturnType,
+        FtProfileOtions,
         GlideRecord,
+        GlideJson,
         GlideString,
+        JsonGetOptions,
+        JsonArrPopOptions,
         SortedSetDataType,
         StreamEntryDataType,
         HashDataType,
@@ -187,6 +211,8 @@ function initialize() {
         ReturnTypeMap,
         ClusterResponse,
         ReturnTypeAttribute,
+        ReturnTypeJson,
+        UniversalReturnTypeJson,
     };
     globalObject = Object.assign(global, nativeBinding);
 }

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

@@ -136,7 +136,10 @@ export type ReadFrom =
 "primary"
 /** Spread the requests between all replicas in a round robin manner.
     If no replica is available, route the requests to the primary.*/
- | "preferReplica";
+ | "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";
 /**
  * Configuration settings for creating a client. Shared settings for standalone and cluster clients.
  */
@@ -201,6 +204,25 @@ export interface BaseClientConfiguration {
      * If not set, 'Decoder.String' will be used.
      */
     defaultDecoder?: Decoder;
+    /**
+     * The maximum number of concurrent requests allowed to be in-flight (sent but not yet completed).
+     * This limit is used to control the memory usage and prevent the client from overwhelming the
+     * server or getting stuck in case of a queue backlog. If not set, a default value of 1000 will be
+     * used.
+     */
+    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.
+     *
+     * @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
+     * ```
+     */
+    clientAz?: string;
 }
 /**
  * Enum of Valkey data types
@@ -245,6 +267,8 @@ export declare class BaseClient {
     protected defaultDecoder: Decoder;
     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;
@@ -259,8 +283,8 @@ export declare class BaseClient {
     /**
      * @internal
      */
-    protected createWritePromise<T>(command: command_request.Command | command_request.Command[] | command_request.ScriptInvocation | command_request.ClusterScan, options?: WritePromiseOptions): Promise<T>;
-    protected writeOrBufferCommandRequest(callbackIdx: number, command: command_request.Command | command_request.Command[] | command_request.ScriptInvocation | command_request.ClusterScan, route?: command_request.Routes): void;
+    protected createWritePromise<T>(command: command_request.Command | command_request.Command[] | command_request.ScriptInvocation | command_request.ClusterScan | command_request.UpdateConnectionPassword, options?: WritePromiseOptions): Promise<T>;
+    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;
     /**
      * @internal
@@ -401,6 +425,14 @@ export declare class BaseClient {
      *
      * @see {@link https://valkey.io/commands/del/|valkey.io} for details.
      *
+     * @remarks In cluster mode, if keys in `keys` map to different hash slots,
+     * the command will be split across these slots and executed separately for each.
+     * This means the command is atomic only at the slot level. If one or more slot-specific
+     * requests fail, the entire call will return the first encountered error, even
+     * though some requests may have succeeded while others did not.
+     * If this behavior impacts your application logic, consider splitting the
+     * request into sub-requests per slot to ensure atomicity.
+     *
      * @param keys - The keys we wanted to remove.
      * @returns The number of keys that were removed.
      *
@@ -482,7 +514,14 @@ export declare class BaseClient {
     /** Retrieve the values of multiple keys.
      *
      * @see {@link https://valkey.io/commands/mget/|valkey.io} for details.
-     * @remarks When in cluster mode, the command may route to multiple nodes when `keys` map to different hash slots.
+     *
+     * @remarks In cluster mode, if keys in `keys` map to different hash slots,
+     * the command will be split across these slots and executed separately for each.
+     * This means the command is atomic only at the slot level. If one or more slot-specific
+     * requests fail, the entire call will return the first encountered error, even
+     * though some requests may have succeeded while others did not.
+     * If this behavior impacts your application logic, consider splitting the
+     * request into sub-requests per slot to ensure atomicity.
      *
      * @param keys - A list of keys to retrieve values for.
      * @param options - (Optional) See {@link DecoderOption}.
@@ -502,10 +541,18 @@ export declare class BaseClient {
     /** Set multiple keys to multiple values in a single operation.
      *
      * @see {@link https://valkey.io/commands/mset/|valkey.io} for details.
-     * @remarks When in cluster mode, the command may route to multiple nodes when keys in `keyValueMap` map to different hash slots.
+     *
+     * @remarks In cluster mode, if keys in `keyValueMap` map to different hash slots,
+     * the command will be split across these slots and executed separately for each.
+     * This means the command is atomic only at the slot level. If one or more slot-specific
+     * requests fail, the entire call will return the first encountered error, even
+     * though some requests may have succeeded while others did not.
+     * If this behavior impacts your application logic, consider splitting the
+     * request into sub-requests per slot to ensure atomicity.
      *
      * @param keysAndValues - A list of key-value pairs to set.
-     * @returns always "OK".
+     *
+     * @returns A simple "OK" response.
      *
      * @example
      * ```typescript
@@ -1086,7 +1133,7 @@ export declare class BaseClient {
      *
      * @param key - The key of the set.
      * @param cursor - The cursor that points to the next iteration of results. A value of `"0"` indicates the start of the search.
-     * @param options - (Optional) The {@link HScanOptions}.
+     * @param options - (Optional) See {@link HScanOptions} and {@link DecoderOption}.
      * @returns An array of the `cursor` and the subset of the hash held by `key`.
      * The first element is always the `cursor` for the next iteration of results. `"0"` will be the `cursor`
      * returned on the last iteration of the hash. The second element is always an array of the subset of the
@@ -1963,6 +2010,14 @@ export declare class BaseClient {
     /**
      * Returns the number of keys in `keys` that exist in the database.
      *
+     * @remarks In cluster mode, if keys in `keys` map to different hash slots,
+     * the command will be split across these slots and executed separately for each.
+     * This means the command is atomic only at the slot level. If one or more slot-specific
+     * requests fail, the entire call will return the first encountered error, even
+     * though some requests may have succeeded while others did not.
+     * If this behavior impacts your application logic, consider splitting the
+     * request into sub-requests per slot to ensure atomicity.
+     *
      * @see {@link https://valkey.io/commands/exists/|valkey.io} for details.
      *
      * @param keys - The keys list to check.
@@ -1982,6 +2037,14 @@ export declare class BaseClient {
      * This command, similar to {@link del}, removes specified keys and ignores non-existent ones.
      * However, this command does not block the server, while {@link https://valkey.io/commands/del|`DEL`} does.
      *
+     * @remarks In cluster mode, if keys in `keys` map to different hash slots,
+     * the command will be split across these slots and executed separately for each.
+     * This means the command is atomic only at the slot level. If one or more slot-specific
+     * requests fail, the entire call will return the first encountered error, even
+     * though some requests may have succeeded while others did not.
+     * If this behavior impacts your application logic, consider splitting the
+     * request into sub-requests per slot to ensure atomicity.
+     *
      * @see {@link https://valkey.io/commands/unlink/|valkey.io} for details.
      *
      * @param keys - The keys we wanted to unlink.
@@ -3599,7 +3662,6 @@ export declare class BaseClient {
      *     attributes of a consumer group for the stream at `key`.
      * @example
      * ```typescript
-     *     <pre>{@code
      * const result = await client.xinfoGroups("my_stream");
      * console.log(result); // Output:
      * // [
@@ -3911,13 +3973,11 @@ export declare class BaseClient {
      *
      * @example
      * ```typescript
-     *  <pre>{@code
      * const entryId = await client.xadd("mystream", ["myfield", "mydata"]);
      * // read messages from streamId
      * const readResult = await client.xreadgroup(["myfield", "mydata"], "mygroup", "my0consumer");
      * // acknowledge messages on stream
      * console.log(await client.xack("mystream", "mygroup", [entryId])); // Output: 1
-     * </pre>
      * ```
      */
     xack(key: GlideString, group: GlideString, ids: string[]): Promise<number>;
@@ -4780,7 +4840,14 @@ export declare class BaseClient {
      * Updates the last access time of the specified keys.
      *
      * @see {@link https://valkey.io/commands/touch/|valkey.io} for more details.
-     * @remarks When in cluster mode, the command may route to multiple nodes when `keys` map to different hash slots.
+     *
+     * @remarks In cluster mode, if keys in `keys` map to different hash slots,
+     * the command will be split across these slots and executed separately for each.
+     * This means the command is atomic only at the slot level. If one or more slot-specific
+     * requests fail, the entire call will return the first encountered error, even
+     * though some requests may have succeeded while others did not.
+     * If this behavior impacts your application logic, consider splitting the
+     * request into sub-requests per slot to ensure atomicity.
      *
      * @param keys - The keys to update the last access time of.
      * @returns The number of keys that were updated. A key is ignored if it doesn't exist.
@@ -4800,7 +4867,14 @@ export declare class BaseClient {
      * transaction. Executing a transaction will automatically flush all previously watched keys.
      *
      * @see {@link https://valkey.io/commands/watch/|valkey.io} and {@link https://valkey.io/topics/transactions/#cas|Valkey Glide Wiki} for more details.
-     * @remarks When in cluster mode, the command may route to multiple nodes when `keys` map to different hash slots.
+     *
+     * @remarks In cluster mode, if keys in `keys` map to different hash slots,
+     * the command will be split across these slots and executed separately for each.
+     * This means the command is atomic only at the slot level. If one or more slot-specific
+     * requests fail, the entire call will return the first encountered error, even
+     * though some requests may have succeeded while others did not.
+     * If this behavior impacts your application logic, consider splitting the
+     * request into sub-requests per slot to ensure atomicity.
      *
      * @param keys - The keys to watch.
      * @returns A simple `"OK"` response.
@@ -5122,5 +5196,25 @@ export declare class BaseClient {
      * @internal
      */
     protected static createClientInternal<TConnection extends BaseClient>(options: BaseClientConfiguration, constructor: (socket: net.Socket, options?: BaseClientConfiguration) => TConnection): Promise<TConnection>;
+    /**
+     * Update the current connection with a new password.
+     *
+     * This method is useful in scenarios where the server password has changed or when utilizing short-lived passwords for enhanced security.
+     * It allows the client to update its password to reconnect upon disconnection without the need to recreate the client instance.
+     * This ensures that the internal reconnection mechanism can handle reconnection seamlessly, preventing the loss of in-flight commands.
+     *
+     * This method updates the client's internal password configuration and does not perform password rotation on the server side.
+     *
+     * @param password - `String | null`. The new password to update the current password, or `null` to remove the current password.
+     * @param immidiateAuth - A `boolean` flag. If `true`, the client will authenticate immediately with the new password against all connections, Using `AUTH` command.
+     *                 If password supplied is an empty string, the client will not perform auth and instead a warning will be returned.
+     *                 The default is `false`.
+     *
+     * @example
+     * ```typescript
+     * await client.updateConnectionPassword("newPassword", true) // "OK"
+     * ```
+     */
+    updateConnectionPassword(password: string | null, immediateAuth?: boolean): Promise<GlideString>;
 }
 export {};

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

@@ -1,8 +1,7 @@
 /**
  * Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
  */
-import { ClusterScanCursor } from "glide-rs";
-import { Script } from "index";
+import { ClusterScanCursor, Script } from "glide-rs";
 import * as net from "net";
 import { BaseClient, BaseClientConfiguration, DecoderOption, GlideReturnType, GlideString, PubSubMsg } from "./BaseClient";
 import { FlushMode, FunctionListOptions, FunctionListResponse, FunctionRestorePolicy, FunctionStatsSingleResponse, InfoOptions, LolwutOptions, ScanOptions } from "./Commands";

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

@@ -1,7 +1,7 @@
 /**
  * Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
  */
-export type LevelOptions = "error" | "warn" | "info" | "debug" | "trace";
+export type LevelOptions = "error" | "warn" | "info" | "debug" | "trace" | "off";
 export declare class Logger {
     private static _instance;
     private static logger_level;
@@ -19,12 +19,14 @@ export declare class Logger {
      * Initialize a logger if it wasn't initialized before - this method is meant to be used when there is no intention to replace an existing logger.
      * The logger will filter all logs with a level lower than the given level,
      * If given a fileName argument, will write the logs to files postfixed with fileName. If fileName isn't provided, the logs will be written to the console.
+     * To turn off the logger, provide the level "off".
      */
     static init(level?: LevelOptions, fileName?: string): void;
     /**
      * configure the logger.
      * the level argument is the level of the logs you want the system to provide (error logs, warn logs, etc.)
      * the filename argument is optional - if provided the target of the logs will be the file mentioned, else will be the console
+     * To turn off the logger, provide the level "off".
      */
     static setLoggerConfig(level: LevelOptions, fileName?: string): void;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@valkey/valkey-glide",
     "types": "build-ts/index.d.ts",
-    "version": "1.1.0",
+    "version": "1.2.0-rc7",
     "description": "General Language Independent Driver for the Enterprise (GLIDE) for Valkey",
     "main": "build-ts/index.js",
     "module": "build-ts/index.js",
@@ -40,12 +40,12 @@
         "typescript": "^4.9.4"
     },
     "optionalDependencies": {
-        "@valkey/valkey-glide-darwin-arm64": "1.1.0",
-        "@valkey/valkey-glide-darwin-x64": "1.1.0",
-        "@valkey/valkey-glide-linux-arm64": "1.1.0",
-        "@valkey/valkey-glide-linux-x64": "1.1.0",
-        "@valkey/valkey-glide-linux-musl-arm64": "1.1.0",
-        "@valkey/valkey-glide-linux-musl-x64": "1.1.0"
+        "@valkey/valkey-glide-darwin-arm64": "1.2.0-rc7",
+        "@valkey/valkey-glide-darwin-x64": "1.2.0-rc7",
+        "@valkey/valkey-glide-linux-arm64": "1.2.0-rc7",
+        "@valkey/valkey-glide-linux-x64": "1.2.0-rc7",
+        "@valkey/valkey-glide-linux-musl-arm64": "1.2.0-rc7",
+        "@valkey/valkey-glide-linux-musl-x64": "1.2.0-rc7"
     },
     "eslintConfig": {
         "extends": [