@valkey/valkey-glide 2.0.1 → 2.1.0-rc2

package/build-ts/BaseClient.js

@@ -403,9 +403,6 @@ class BaseClient {
             this.completePubSubFuturesSafe();
         }
     }
-    /**
-     * @internal
-     */
     constructor(socket, options) {
         // if logger has been initialized by the external-user on info level this log will be shown
         _1.Logger.log("info", "Client lifetime", `construct client`);
@@ -1794,6 +1791,449 @@ class BaseClient {
     async hrandfieldWithValues(key, count, options) {
         return this.createWritePromise((0, _1.createHRandField)(key, count, true), options);
     }
+    /**
+     * Sets hash fields with expiration times and optional conditional changes.
+     *
+     * @param key - The key of the hash.
+     * @param fieldsAndValues - A map or array of field-value pairs to set.
+     * @param options - Optional parameters including field conditional changes and expiry settings.
+     *                  See {@link HSetExOptions}.
+     * @returns A number of fields that were set.
+     *
+     * @example
+     * ```typescript
+     * // Set fields with 60 second expiration, only if none exist
+     * const result = await client.hsetex(
+     *     "myHash",
+     *     { field1: "value1", field2: "value2" },
+     *     {
+     *         fieldConditionalChange: HashFieldConditionalChange.ONLY_IF_NONE_EXIST,
+     *         expiry: { type: TimeUnit.Seconds, count: 60 }
+     *     }
+     * );
+     * console.log(result); // 2 - both fields were set with 60s expiration
+     *
+     * // Set fields and keep existing TTL
+     * const keepTtlResult = await client.hsetex(
+     *     "myHash",
+     *     { field3: "value3" },
+     *     { expiry: "KEEPTTL" }
+     * );
+     * console.log(keepTtlResult); // 1 - field was set, existing TTL preserved
+     *
+     * // Set fields with millisecond precision expiration
+     * const msResult = await client.hsetex(
+     *     "myHash",
+     *     { field4: "value4" },
+     *     { expiry: { type: TimeUnit.Milliseconds, count: 5000 } }
+     * );
+     * console.log(msResult); // 1 - field expires in 5000ms
+     *
+     * // Set fields with Unix timestamp expiration
+     * const timestampResult = await client.hsetex(
+     *     "myHash",
+     *     { field5: "value5" },
+     *     { expiry: { type: TimeUnit.UnixSeconds, count: Math.floor(Date.now() / 1000) + 3600 } }
+     * );
+     * console.log(timestampResult); // 1 - field expires in 1 hour
+     *
+     * // Only update existing fields and keep their TTL
+     * const updateResult = await client.hsetex(
+     *     "myHash",
+     *     { field1: "newValue1" },
+     *     {
+     *         fieldConditionalChange: HashFieldConditionalChange.ONLY_IF_ALL_EXIST,
+     *         expiry: "KEEPTTL"
+     *     }
+     * );
+     * console.log(updateResult); // 0 or 1 depending on whether field1 exists
+     * ```
+     *
+     * @since Valkey 9.0.0
+     * @see {@link https://valkey.io/commands/hsetex/|valkey.io}
+     */
+    async hsetex(key, fieldsAndValues, options) {
+        return this.createWritePromise((0, _1.createHSetEx)(key, (0, _1.convertFieldsAndValuesToHashDataType)(fieldsAndValues), options));
+    }
+    /**
+     * Gets hash fields and optionally sets their expiration.
+     *
+     * @param key - The key of the hash.
+     * @param fields - The fields in the hash stored at `key` to retrieve from the database.
+     * @param options - Optional arguments for the HGETEX command. See {@link HGetExOptions} and see {@link DecoderOption}.
+     * @returns An array of values associated with the given fields,
+     *          in the same order as they are requested. For every field that does not exist
+     *          in the hash, a null value is returned. If `key` does not exist, returns an
+     *          array of null values.
+     *
+     * @example
+     * ```typescript
+     * // Get fields without setting expiration
+     * const values = await client.hgetex("myHash", ["field1", "field2"]);
+     * console.log(values); // ["value1", "value2"] or [null, null] if fields don't exist
+     *
+     * // Get fields and set 30 second expiration
+     * const valuesWithExpiry = await client.hgetex(
+     *     "myHash",
+     *     ["field1", "field2"],
+     *     { expiry: { type: TimeUnit.Seconds, count: 30 } }
+     * );
+     * console.log(valuesWithExpiry); // ["value1", "value2"] - fields now expire in 30s
+     *
+     * // Get fields and remove expiration (make persistent)
+     * const persistValues = await client.hgetex(
+     *     "myHash",
+     *     ["field1", "field2"],
+     *     { expiry: "PERSIST" }
+     * );
+     * console.log(persistValues); // ["value1", "value2"] - fields are now persistent
+     *
+     * // Get fields and set millisecond precision expiration
+     * const msValues = await client.hgetex(
+     *     "myHash",
+     *     ["field3", "field4"],
+     *     { expiry: { type: TimeUnit.Milliseconds, count: 2500 } }
+     * );
+     * console.log(msValues); // ["value3", "value4"] - fields expire in 2500ms
+     *
+     * // Get fields and set Unix timestamp expiration
+     * const timestampValues = await client.hgetex(
+     *     "myHash",
+     *     ["field5"],
+     *     { expiry: { type: TimeUnit.UnixMilliseconds, count: Date.now() + 60000 } }
+     * );
+     * console.log(timestampValues); // ["value5"] - field expires in 1 minute
+     * ```
+     *
+     * @since Valkey 9.0.0
+     * @see {@link https://valkey.io/commands/hgetex/|valkey.io}
+     */
+    async hgetex(key, fields, options) {
+        return this.createWritePromise((0, _1.createHGetEx)(key, fields, options), options);
+    }
+    /**
+     * Sets expiration time for hash fields in seconds. Creates the hash if it doesn't exist.
+     *
+     * @see {@link https://valkey.io/commands/hexpire/|valkey.io} for details.
+     *
+     * @param key - The key of the hash.
+     * @param seconds - The expiration time in seconds.
+     * @param fields - The fields to set expiration for.
+     * @param options - Optional parameters for the command.
+     * @returns An array of numbers indicating the result for each field:
+     *          - `1` if expiration was set successfully
+     *          - `0` if the specified condition (NX, XX, GT, LT) was not met
+     *          - `-2` if the field does not exist or the key does not exist
+     *          - `2` when called with 0 seconds (field deleted)
+     *
+     * @example
+     * ```typescript
+     * // Set expiration for hash fields
+     * const result = await client.hexpire("my_hash", 60, ["field1", "field2"]);
+     * console.log(result); // [1, 1] - expiration set for both fields
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Set expiration only if fields don't have expiration
+     * const result = await client.hexpire("my_hash", 120, ["field1", "field2"], {
+     *     condition: HashExpirationCondition.ONLY_IF_NO_EXPIRY
+     * });
+     * console.log(result); // [1, 0] - expiration set for field1, condition not met for field2
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Set expiration with greater than condition
+     * const result = await client.hexpire("my_hash", 300, ["field1"], {
+     *     condition: HashExpirationCondition.ONLY_IF_GREATER_THAN_CURRENT
+     * });
+     * console.log(result); // [1] - expiration set because 300 > current TTL
+     * ```
+     */
+    async hexpire(key, seconds, fields, options) {
+        return this.createWritePromise((0, _1.createHExpire)(key, seconds, fields, options));
+    }
+    /**
+     * Removes the expiration time associated with each specified field, causing them to persist.
+     *
+     * @see {@link https://valkey.io/commands/hpersist/|valkey.io} for details.
+     *
+     * @param key - The key of the hash.
+     * @param fields - The fields in the hash to remove expiration from.
+     * @returns An array of numbers indicating the result for each field:
+     *     - `1` if the field's expiration was removed successfully.
+     *     - `-1` if the field exists but has no associated expiration.
+     *     - `-2` if the field does not exist or the key does not exist.
+     *
+     * @example
+     * ```typescript
+     * // Remove expiration from hash fields
+     * const result = await client.hpersist("my_hash", ["field1", "field2"]);
+     * console.log(result); // [1, -1] - expiration removed from field1, field2 had no expiration
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Remove expiration from a single field
+     * const result = await client.hpersist("my_hash", ["field1"]);
+     * console.log(result); // [1] - expiration removed from field1
+     * ```
+     */
+    async hpersist(key, fields) {
+        return this.createWritePromise((0, _1.createHPersist)(key, fields));
+    }
+    /**
+     * Sets expiration time for hash fields in milliseconds. Creates the hash if it doesn't exist.
+     *
+     * @see {@link https://valkey.io/commands/hpexpire/|valkey.io} for details.
+     *
+     * @param key - The key of the hash.
+     * @param milliseconds - The expiration time in milliseconds.
+     * @param fields - The fields to set expiration for.
+     * @param options - Optional arguments for the HPEXPIRE command. See {@link HPExpireOptions}.
+     * @returns An array of numbers indicating the result for each field:
+     *          - `1` if expiration was set successfully
+     *          - `0` if the specified condition (NX, XX, GT, LT) was not met
+     *          - `-2` if the field does not exist or the key does not exist
+     *          - `2` when called with 0 milliseconds (field deleted)
+     *
+     * @example
+     * ```typescript
+     * // Set expiration for hash fields in milliseconds
+     * const result = await client.hpexpire("my_hash", 60000, ["field1", "field2"]);
+     * console.log(result); // [1, 1] - expiration set for both fields
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Set expiration only if fields don't have expiration
+     * const result = await client.hpexpire("my_hash", 120000, ["field1", "field2"], {
+     *     condition: HashExpirationCondition.ONLY_IF_NO_EXPIRY
+     * });
+     * console.log(result); // [1, 0] - expiration set for field1, condition not met for field2
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Set expiration with greater than condition
+     * const result = await client.hpexpire("my_hash", 300000, ["field1"], {
+     *     condition: HashExpirationCondition.ONLY_IF_GREATER_THAN_CURRENT
+     * });
+     * console.log(result); // [1] - expiration set because 300000 ms > current TTL
+     * ```
+     */
+    async hpexpire(key, milliseconds, fields, options) {
+        return this.createWritePromise((0, _1.createHPExpire)(key, milliseconds, fields, options));
+    }
+    /**
+     * Sets expiration time for hash fields using an absolute Unix timestamp in seconds. Creates the hash if it doesn't exist.
+     *
+     * @see {@link https://valkey.io/commands/hexpireat/|valkey.io} for details.
+     *
+     * @param key - The key of the hash.
+     * @param unixTimestampSeconds - The expiration time as a Unix timestamp in seconds.
+     * @param fields - The fields to set expiration for.
+     * @param options - Optional arguments for the HEXPIREAT command. See {@link HExpireOptions}.
+     * @returns An array of numbers indicating the result for each field:
+     *          - `1` if expiration was set successfully
+     *          - `0` if the specified condition (NX, XX, GT, LT) was not met
+     *          - `-2` if the field does not exist or the key does not exist
+     *          - `2` when called with 0 seconds (field deleted)
+     *
+     * @example
+     * ```typescript
+     * // Set expiration for hash fields using Unix timestamp
+     * const futureTimestamp = Math.floor(Date.now() / 1000) + 3600; // 1 hour from now
+     * const result = await client.hexpireat("my_hash", futureTimestamp, ["field1", "field2"]);
+     * console.log(result); // [1, 1] - expiration set for both fields
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Set expiration only if fields don't have expiration
+     * const futureTimestamp = Math.floor(Date.now() / 1000) + 7200; // 2 hours from now
+     * const result = await client.hexpireat("my_hash", futureTimestamp, ["field1", "field2"], {
+     *     condition: HashExpirationCondition.ONLY_IF_NO_EXPIRY
+     * });
+     * console.log(result); // [1, 0] - expiration set for field1, condition not met for field2
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Set expiration with greater than condition
+     * const futureTimestamp = Math.floor(Date.now() / 1000) + 10800; // 3 hours from now
+     * const result = await client.hexpireat("my_hash", futureTimestamp, ["field1"], {
+     *     condition: HashExpirationCondition.ONLY_IF_GREATER_THAN_CURRENT
+     * });
+     * console.log(result); // [1] - expiration set because timestamp > current expiration
+     * ```
+     */
+    async hexpireat(key, unixTimestampSeconds, fields, options) {
+        return this.createWritePromise((0, _1.createHExpireAt)(key, unixTimestampSeconds, fields, options));
+    }
+    /**
+     * Sets expiration time for hash fields using an absolute Unix timestamp in milliseconds. Creates the hash if it doesn't exist.
+     *
+     * @see {@link https://valkey.io/commands/hpexpireat/|valkey.io} for details.
+     *
+     * @param key - The key of the hash.
+     * @param unixTimestampMilliseconds - The expiration time as a Unix timestamp in milliseconds.
+     * @param fields - The fields to set expiration for.
+     * @param options - Optional arguments for the HPEXPIREAT command. See {@link HExpireOptions}.
+     * @returns An array of numbers indicating the result for each field:
+     *          - `1` if expiration was set successfully
+     *          - `0` if the specified condition (NX, XX, GT, LT) was not met
+     *          - `-2` if the field does not exist or the key does not exist
+     *          - `2` when called with 0 milliseconds (field deleted)
+     *
+     * @example
+     * ```typescript
+     * // Set expiration for hash fields using Unix timestamp in milliseconds
+     * const futureTimestamp = Date.now() + 3600000; // 1 hour from now
+     * const result = await client.hpexpireat("my_hash", futureTimestamp, ["field1", "field2"]);
+     * console.log(result); // [1, 1] - expiration set for both fields
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Set expiration only if fields don't have expiration
+     * const futureTimestamp = Date.now() + 7200000; // 2 hours from now
+     * const result = await client.hpexpireat("my_hash", futureTimestamp, ["field1", "field2"], {
+     *     condition: HashExpirationCondition.ONLY_IF_NO_EXPIRY
+     * });
+     * console.log(result); // [1, 0] - expiration set for field1, condition not met for field2
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Set expiration with greater than condition
+     * const futureTimestamp = Date.now() + 10800000; // 3 hours from now
+     * const result = await client.hpexpireat("my_hash", futureTimestamp, ["field1"], {
+     *     condition: HashExpirationCondition.ONLY_IF_GREATER_THAN_CURRENT
+     * });
+     * console.log(result); // [1] - expiration set because timestamp > current expiration
+     * ```
+     */
+    async hpexpireat(key, unixTimestampMilliseconds, fields, options) {
+        return this.createWritePromise((0, _1.createHPExpireAt)(key, unixTimestampMilliseconds, fields, options));
+    }
+    /**
+     * Returns the remaining time to live of hash fields that have a timeout, in seconds.
+     *
+     * @see {@link https://valkey.io/commands/httl/|valkey.io} for details.
+     *
+     * @param key - The key of the hash.
+     * @param fields - The fields in the hash stored at `key` to retrieve the TTL for.
+     * @returns An array of TTL values in seconds for the specified fields.
+     *     - For fields with a timeout, returns the remaining time in seconds.
+     *     - For fields that exist but have no associated expire, returns -1.
+     *     - For fields that do not exist, returns -2.
+     *
+     * @example
+     * ```typescript
+     * // Get TTL for hash fields
+     * const result = await client.httl("my_hash", ["field1", "field2", "field3"]);
+     * console.log(result); // [120, -1, -2] - field1 expires in 120 seconds, field2 has no expiration, field3 doesn't exist
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Get TTL for a single field
+     * const result = await client.httl("my_hash", ["field1"]);
+     * console.log(result); // [60] - field1 expires in 60 seconds
+     * ```
+     */
+    async httl(key, fields) {
+        return this.createWritePromise((0, _1.createHTtl)(key, fields));
+    }
+    /**
+     * Returns the absolute Unix timestamp (in seconds) at which hash fields will expire.
+     *
+     * @see {@link https://valkey.io/commands/hexpiretime/|valkey.io} for details.
+     *
+     * @param key - The key of the hash.
+     * @param fields - The list of fields to get the expiration timestamp for.
+     * @returns An array of expiration timestamps in seconds for the specified fields:
+     *   - For fields with a timeout, returns the absolute Unix timestamp in seconds.
+     *   - For fields without a timeout, returns -1.
+     *   - For fields that do not exist, returns -2.
+     *
+     * @example
+     * ```typescript
+     * // Get expiration timestamps for hash fields
+     * const result = await client.hexpiretime("my_hash", ["field1", "field2", "field3"]);
+     * console.log(result); // [1672531200, -1, -2] - field1 expires at timestamp 1672531200, field2 has no expiration, field3 doesn't exist
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Get expiration timestamp for a single field
+     * const result = await client.hexpiretime("my_hash", ["field1"]);
+     * console.log(result); // [1672531200] - field1 expires at timestamp 1672531200
+     * ```
+     */
+    async hexpiretime(key, fields) {
+        return this.createWritePromise((0, _1.createHExpireTime)(key, fields));
+    }
+    /**
+     * Returns the absolute Unix timestamp (in milliseconds) at which hash fields will expire.
+     *
+     * @see {@link https://valkey.io/commands/hpexpiretime/|valkey.io} for details.
+     *
+     * @param key - The key of the hash.
+     * @param fields - The list of fields to get the expiration timestamp for.
+     * @returns An array of expiration timestamps in milliseconds for the specified fields:
+     *   - For fields with a timeout, returns the absolute Unix timestamp in milliseconds.
+     *   - For fields without a timeout, returns -1.
+     *   - For fields that do not exist, returns -2.
+     *
+     * @example
+     * ```typescript
+     * // Get expiration timestamps for hash fields in milliseconds
+     * const result = await client.hpexpiretime("my_hash", ["field1", "field2", "field3"]);
+     * console.log(result); // [1672531200000, -1, -2] - field1 expires at timestamp 1672531200000, field2 has no expiration, field3 doesn't exist
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Get expiration timestamp for a single field in milliseconds
+     * const result = await client.hpexpiretime("my_hash", ["field1"]);
+     * console.log(result); // [1672531200000] - field1 expires at timestamp 1672531200000
+     * ```
+     */
+    async hpexpiretime(key, fields) {
+        return this.createWritePromise((0, _1.createHPExpireTime)(key, fields));
+    }
+    /**
+     * Returns the remaining time to live of hash fields that have a timeout, in milliseconds.
+     *
+     * @see {@link https://valkey.io/commands/hpttl/|valkey.io} for details.
+     *
+     * @param key - The key of the hash.
+     * @param fields - The list of fields to get the TTL for.
+     * @returns An array of TTL values in milliseconds for the specified fields:
+     *   - For fields with a timeout, returns the remaining TTL in milliseconds.
+     *   - For fields without a timeout, returns -1.
+     *   - For fields that do not exist, returns -2.
+     *
+     * @example
+     * ```typescript
+     * // Get TTL for hash fields in milliseconds
+     * const result = await client.hpttl("my_hash", ["field1", "field2", "field3"]);
+     * console.log(result); // [120000, -1, -2] - field1 expires in 120000 ms, field2 has no expiration, field3 doesn't exist
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Get TTL for a single field in milliseconds
+     * const result = await client.hpttl("my_hash", ["field1"]);
+     * console.log(result); // [60000] - field1 expires in 60000 ms
+     * ```
+     */
+    async hpttl(key, fields) {
+        return this.createWritePromise((0, _1.createHPTtl)(key, fields));
+    }
     /** Inserts all the specified values at the head of the list stored at `key`.
      * `elements` are inserted one after the other to the head of the list, from the leftmost element to the rightmost element.
      * If `key` does not exist, it is created as empty list before performing the push operations.
@@ -6429,6 +6869,12 @@ class BaseClient {
             }
             : undefined;
         const protocol = options.protocol;
+        // Validate that clientAz is set when using AZ affinity strategies
+        if ((options.readFrom === "AZAffinity" ||
+            options.readFrom === "AZAffinityReplicasAndPrimary") &&
+            !options.clientAz) {
+            throw new _1.ConfigurationError(`clientAz must be set when readFrom is set to ${options.readFrom}`);
+        }
         return {
             protocol,
             clientName: options.clientName,
@@ -6440,6 +6886,7 @@ class BaseClient {
             clusterModeEnabled: false,
             readFrom,
             authenticationInfo,
+            databaseId: options.databaseId,
             inflightRequestsLimit: options.inflightRequestsLimit,
             clientAz: options.clientAz ?? null,
             connectionRetryStrategy: options.connectionBackoff,