@valkey/valkey-glide
Version:
General Language Independent Driver for the Enterprise (GLIDE) for Valkey
1,081 lines • 177 kB
JavaScript
"use strict";
/**
* Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
*/
Object.defineProperty(exports, "__esModule", { value: true });
exports.Transaction = exports.ClusterTransaction = exports.ClusterBatch = exports.Batch = exports.BaseBatch = void 0;
/**
* Note: 'eslint-disable-line @typescript-eslint/no-unused-vars' is used intentionally
* to suppress unused import errors for types referenced only in JSDoc.
*/
const _1 = require(".");
/**
* Base class encompassing shared commands for both standalone and cluster mode implementations in a Batch.
* Batches allow the execution of a group of commands in a single step.
*
* ### Batch Response:
* An array of command responses is returned by the client exec command, in the order they were given.
* Each element in the array represents a command given to the batch.
* The response for each command depends on the executed Valkey command.
* Specific response types are documented alongside each method.
*
* @param isAtomic - Indicates whether the batch is atomic or non-atomic. If `true`, the batch will be executed as an atomic transaction.
* If `false`, the batch will be executed as a non-atomic pipeline.
*/
class BaseBatch {
isAtomic;
/**
* @internal
*/
commands = [];
/**
* Array of command indexes indicating commands that need to be converted into a `Set` within the batch.
* @internal
*/
setCommandsIndexes = [];
/**
* @param isAtomic - Determines whether the batch is atomic or non-atomic. If `true`, the
* batch will be executed as an atomic `transaction`. If `false`, the batch will be
* executed as a non-atomic `pipeline`.
*/
constructor(isAtomic) {
this.isAtomic = isAtomic;
}
/**
* Adds a command to the batch and returns the batch instance.
* @param command - The command to add.
* @param shouldConvertToSet - Indicates if the command should be converted to a `Set`.
* @returns The updated batch instance.
*/
addAndReturn(command, shouldConvertToSet = false) {
if (shouldConvertToSet) {
// The command's index within the batch is saved for later conversion of its response to a Set type.
this.setCommandsIndexes.push(this.commands.length);
}
this.commands.push(command);
return this;
}
/** Get the value associated with the given `key`, or `null` if no such `key` exists.
* @see {@link https://valkey.io/commands/get/|valkey.io} for details.
*
* @param key - The `key` to retrieve from the database.
*
* Command Response - If `key` exists, returns the value of `key`. Otherwise, return `null`.
*/
get(key) {
return this.addAndReturn((0, _1.createGet)(key));
}
/**
* Get the value of `key` and optionally set its expiration. `GETEX` is similar to {@link get}.
*
* @see {@link https://valkey.io/commands/getex/|valkey.io} for more details.
* @remarks Since Valkey version 6.2.0.
*
* @param key - The key to retrieve from the database.
* @param options - (Optional) set expiriation to the given key.
* "persist" will retain the time to live associated with the key. Equivalent to `PERSIST` in the VALKEY API.
* Otherwise, a {@link TimeUnit} and duration of the expire time should be specified.
*
* Command Response - If `key` exists, returns the value of `key` as a `string`. Otherwise, return `null`.
*/
getex(key, options) {
return this.addAndReturn((0, _1.createGetEx)(key, options));
}
/**
* Gets a string value associated with the given `key`and deletes the key.
*
* @see {@link https://valkey.io/commands/getdel/|valkey.io} for details.
*
* @param key - The key to retrieve from the database.
*
* Command Response - If `key` exists, returns the `value` of `key`. Otherwise, return `null`.
*/
getdel(key) {
return this.addAndReturn((0, _1.createGetDel)(key));
}
/**
* Returns the substring of the string value stored at `key`, determined by the byte offsets
* `start` and `end` (both are inclusive). Negative offsets can be used in order to provide
* an offset starting from the end of the string. So `-1` means the last character, `-2` the
* penultimate and so forth. If `key` does not exist, an empty string is returned. If `start`
* or `end` are out of range, returns the substring within the valid range of the string.
*
* @see {@link https://valkey.io/commands/getrange/|valkey.io} for details.
*
* @param key - The key of the string.
* @param start - The starting byte offset.
* @param end - The ending byte offset.
*
* Command Response - substring extracted from the value stored at `key`.
*/
getrange(key, start, end) {
return this.addAndReturn((0, _1.createGetRange)(key, start, end));
}
/** Set the given key with the given value. Return value is dependent on the passed options.
* @see {@link https://valkey.io/commands/set/|valkey.io} for details.
*
* @param key - The key to store.
* @param value - The value to store with the given key.
* @param options - The set options.
*
* Command Response - If the value is successfully set, return OK.
* If `value` isn't set because of `onlyIfExists` or `onlyIfDoesNotExist` conditions, return null.
* If `returnOldValue` is set, return the old value as a string.
*/
set(key, value, options) {
return this.addAndReturn((0, _1.createSet)(key, value, options));
}
/**
* Pings the server.
*
* @see {@link https://valkey.io/commands/ping/|valkey.io} for details.
*
* @param message - (Optional) A message to include in the PING command.
* - If not provided, the server will respond with `"PONG"`.
* - If provided, the server will respond with a copy of the message.
*
* Command Response - `"PONG"` if `message` is not provided, otherwise return a copy of `message`.
*/
ping(message) {
return this.addAndReturn((0, _1.createPing)(message));
}
/**
* Copies the value stored at the `source` to the `destination` key. If `destinationDB` is specified,
* the value will be copied to the database specified, otherwise the current database will be used.
* When `replace` is true, removes the `destination` key first if it already exists, otherwise performs
* no action.
*
* @see {@link https://valkey.io/commands/copy/|valkey.io} for details.
* @remarks Since Valkey version 6.2.0. destinationDB parameter for cluster mode is supported since Valkey 9.0.0 and above
*
* @param source - The key to the source value.
* @param destination - The key where the value should be copied to.
* @param destinationDB - (Optional) The alternative logical database index for the destination key.
* If not provided, the current database will be used.
* @param replace - (Optional) If `true`, the `destination` key should be removed before copying the
* value to it. If not provided, no action will be performed if the key already exists.
*
* Command Response - `true` if `source` was copied, `false` if the `source` was not copied.
*/
copy(source, destination, options) {
return this.addAndReturn((0, _1.createCopy)(source, destination, options));
}
/**
* Gets information and statistics about the server.
*
* Starting from server version 7, command supports multiple section arguments.
*
* @see {@link https://valkey.io/commands/info/|valkey.io} for details.
*
* @param sections - (Optional) A list of {@link InfoOptions} values specifying which sections of information to retrieve.
* When no parameter is provided, {@link InfoOptions.Default|Default} is assumed.
*
* Command Response - A string containing the information for the sections requested.
*/
info(sections) {
return this.addAndReturn((0, _1.createInfo)(sections));
}
/**
* Removes the specified keys. A key is ignored if it does not exist.
*
* @see {@link https://valkey.io/commands/del/|valkey.io} for details.
*
* @param keys - A list of keys to be deleted from the database.
*
* Command Response - The number of keys that were removed.
*/
del(keys) {
return this.addAndReturn((0, _1.createDel)(keys));
}
/**
* Serialize the value stored at `key` in a Valkey-specific format and return it to the user.
*
* @see {@link https://valkey.io/commands/dump/|valkey.io} for details.
* @remarks To execute a batch with a `dump` command, the `exec` command requires `Decoder.Bytes` to handle the response.
*
* @param key - The `key` to serialize.
*
* Command Response - The serialized value of the data stored at `key`. If `key` does not exist, `null` will be returned.
*/
dump(key) {
return this.addAndReturn((0, _1.createDump)(key));
}
/**
* Create a `key` associated with a `value` that is obtained by deserializing the provided
* serialized `value` (obtained via {@link dump}).
*
* @see {@link https://valkey.io/commands/restore/|valkey.io} for details.
* @remarks `options.idletime` and `options.frequency` modifiers cannot be set at the same time.
*
* @param key - The `key` to create.
* @param ttl - The expiry time (in milliseconds). If `0`, the `key` will persist.
* @param value - The serialized value to deserialize and assign to `key`.
* @param options - (Optional) Restore options {@link RestoreOptions}.
*
* Command Response - Return "OK" if the `key` was successfully restored with a `value`.
*/
restore(key, ttl, value, options) {
return this.addAndReturn((0, _1.createRestore)(key, ttl, value, options));
}
/**
* Gets the name of the connection on which the batch is being executed.
*
* @see {@link https://valkey.io/commands/client-getname/|valkey.io} for details.
*
* Command Response - The name of the client connection as a string if a name is set, or null if no name is assigned.
*/
clientGetName() {
return this.addAndReturn((0, _1.createClientGetName)());
}
/**
* Rewrites the configuration file with the current configuration.
*
* @see {@link https://valkey.io/commands/select/|valkey.io} for details.
*
* Command Response - "OK" when the configuration was rewritten properly. Otherwise, the command fails with an error.
*/
configRewrite() {
return this.addAndReturn((0, _1.createConfigRewrite)());
}
/**
* Resets the statistics reported by Valkey using the `INFO` and `LATENCY HISTOGRAM` commands.
*
* @see {@link https://valkey.io/commands/config-resetstat/|valkey.io} for details.
*
* Command Response - always "OK".
*/
configResetStat() {
return this.addAndReturn((0, _1.createConfigResetStat)());
}
/** Retrieve the values of multiple keys.
* @see {@link https://valkey.io/commands/mget/|valkey.io} for details.
*
* @param keys - A list of keys to retrieve values for.
*
* Command Response - A list of values corresponding to the provided keys. If a key is not found,
* its corresponding value in the list will be null.
*/
mget(keys) {
return this.addAndReturn((0, _1.createMGet)(keys));
}
/** Set multiple keys to multiple values in a single atomic operation.
* @see {@link https://valkey.io/commands/mset/|valkey.io} for details.
*
* @param keysAndValues - A list of key-value pairs to set.
*
* Command Response - always "OK".
*/
mset(keysAndValues) {
return this.addAndReturn((0, _1.createMSet)((0, _1.convertGlideRecord)(keysAndValues)));
}
/**
* Sets multiple keys to values if the key does not exist. The operation is atomic, and if one or
* more keys already exist, the entire operation fails.
*
* @see {@link https://valkey.io/commands/msetnx/|valkey.io} for details.
*
* @param keysAndValues - A list of key-value pairs to set.
* Command Response - `true` if all keys were set. `false` if no key was set.
*/
msetnx(keysAndValues) {
return this.addAndReturn((0, _1.createMSetNX)((0, _1.convertGlideRecord)(keysAndValues)));
}
/**
* Move `key` from the currently selected database to the database specified by `dbIndex`.
*
* @remarks Move is available for cluster mode since Valkey 9.0.0 and above.
*
* @see {@link https://valkey.io/commands/move/|valkey.io} for details.
*
* @param key - The key to move.
* @param dbIndex - The index of the database to move `key` to.
*
* Command Response - `true` if `key` was moved, or `false` if the `key` already exists in the destination
* database or does not exist in the source database.
*/
move(key, dbIndex) {
return this.addAndReturn((0, _1.createMove)(key, dbIndex));
}
/** Increments the number stored at `key` by one. If `key` does not exist, it is set to 0 before performing the operation.
* @see {@link https://valkey.io/commands/incr/|valkey.io} for details.
*
* @param key - The key to increment its value.
*
* Command Response - the value of `key` after the increment.
*/
incr(key) {
return this.addAndReturn((0, _1.createIncr)(key));
}
/** Increments the number stored at `key` by `amount`. If `key` does not exist, it is set to 0 before performing the operation.
* @see {@link https://valkey.io/commands/incrby/|valkey.io} for details.
*
* @param key - The key to increment its value.
* @param amount - The amount to increment.
*
* Command Response - the value of `key` after the increment.
*/
incrBy(key, amount) {
return this.addAndReturn((0, _1.createIncrBy)(key, amount));
}
/** Increment the string representing a floating point number stored at `key` by `amount`.
* By using a negative amount value, the result is that the value stored at `key` is decremented.
* If `key` does not exist, it is set to 0 before performing the operation.
* @see {@link https://valkey.io/commands/incrbyfloat/|valkey.io} for details.
*
* @param key - The key to increment its value.
* @param amount - The amount to increment.
*
* Command Response - the value of `key` after the increment.
*
*/
incrByFloat(key, amount) {
return this.addAndReturn((0, _1.createIncrByFloat)(key, amount));
}
/**
* Returns the current connection ID.
*
* @see {@link https://valkey.io/commands/client-id/|valkey.io} for details.
*
* Command Response - The ID of the connection.
*/
clientId() {
return this.addAndReturn((0, _1.createClientId)());
}
/** Decrements the number stored at `key` by one. If `key` does not exist, it is set to 0 before performing the operation.
* @see {@link https://valkey.io/commands/decr/|valkey.io} for details.
*
* @param key - The key to decrement its value.
*
* Command Response - the value of `key` after the decrement.
*/
decr(key) {
return this.addAndReturn((0, _1.createDecr)(key));
}
/** Decrements the number stored at `key` by `amount`. If `key` does not exist, it is set to 0 before performing the operation.
* @see {@link https://valkey.io/commands/decrby/|valkey.io} for details.
*
* @param key - The key to decrement its value.
* @param amount - The amount to decrement.
*
* Command Response - the value of `key` after the decrement.
*/
decrBy(key, amount) {
return this.addAndReturn((0, _1.createDecrBy)(key, amount));
}
/**
* Perform a bitwise operation between multiple keys (containing string values) and store the result in the
* `destination`.
*
* @see {@link https://valkey.io/commands/bitop/|valkey.io} for details.
*
* @param operation - The bitwise operation to perform.
* @param destination - The key that will store the resulting string.
* @param keys - The list of keys to perform the bitwise operation on.
*
* Command Response - The size of the string stored in `destination`.
*/
bitop(operation, destination, keys) {
return this.addAndReturn((0, _1.createBitOp)(operation, destination, keys));
}
/**
* Returns the bit value at `offset` in the string value stored at `key`. `offset` must be greater than or equal
* to zero.
*
* @see {@link https://valkey.io/commands/getbit/|valkey.io} for details.
*
* @param key - The key of the string.
* @param offset - The index of the bit to return.
*
* Command Response - The bit at the given `offset` of the string. Returns `0` if the key is empty or if the
* `offset` exceeds the length of the string.
*/
getbit(key, offset) {
return this.addAndReturn((0, _1.createGetBit)(key, offset));
}
/**
* Sets or clears the bit at `offset` in the string value stored at `key`. The `offset` is a zero-based index, with
* `0` being the first element of the list, `1` being the next element, and so on. The `offset` must be less than
* `2^32` and greater than or equal to `0`. If a key is non-existent then the bit at `offset` is set to `value` and
* the preceding bits are set to `0`.
*
* @see {@link https://valkey.io/commands/setbit/|valkey.io} for details.
*
* @param key - The key of the string.
* @param offset - The index of the bit to be set.
* @param value - The bit value to set at `offset`. The value must be `0` or `1`.
*
* Command Response - The bit value that was previously stored at `offset`.
*/
setbit(key, offset, value) {
return this.addAndReturn((0, _1.createSetBit)(key, offset, value));
}
/**
* Returns the position of the first bit matching the given `bit` value. The optional starting offset
* `start` is a zero-based index, with `0` being the first byte of the list, `1` being the next byte and so on.
* The offset can also be a negative number indicating an offset starting at the end of the list, with `-1` being
* the last byte of the list, `-2` being the penultimate, and so on.
*
* @see {@link https://valkey.io/commands/bitpos/|valkey.io} for details.
*
* @param key - The key of the string.
* @param bit - The bit value to match. Must be `0` or `1`.
* @param options - (Optional) The {@link BitOffsetOptions}.
*
* Command Response - The position of the first occurrence of `bit` in the binary value of the string held at `key`.
* If `start` was provided, the search begins at the offset indicated by `start`.
*/
bitpos(key, bit, options) {
return this.addAndReturn((0, _1.createBitPos)(key, bit, options));
}
/**
* Reads or modifies the array of bits representing the string that is held at `key` based on the specified
* `subcommands`.
*
* @see {@link https://valkey.io/commands/bitfield/|valkey.io} for details.
*
* @param key - The key of the string.
* @param subcommands - The subcommands to be performed on the binary value of the string at `key`, which could be
* any of the following:
*
* - {@link BitFieldGet}
* - {@link BitFieldSet}
* - {@link BitFieldIncrBy}
* - {@link BitFieldOverflow}
*
* Command Response - An array of results from the executed subcommands:
*
* - {@link BitFieldGet} returns the value in {@link BitOffset} or {@link BitOffsetMultiplier}.
* - {@link BitFieldSet} returns the old value in {@link BitOffset} or {@link BitOffsetMultiplier}.
* - {@link BitFieldIncrBy} returns the new value in {@link BitOffset} or {@link BitOffsetMultiplier}.
* - {@link BitFieldOverflow} determines the behavior of the {@link BitFieldSet} and {@link BitFieldIncrBy}
* subcommands when an overflow or underflow occurs. {@link BitFieldOverflow} does not return a value and
* does not contribute a value to the array response.
*/
bitfield(key, subcommands) {
return this.addAndReturn((0, _1.createBitField)(key, subcommands));
}
/**
* Reads the array of bits representing the string that is held at `key` based on the specified `subcommands`.
*
* @see {@link https://valkey.io/commands/bitfield_ro/|valkey.io} for details.
* @remarks Since Valkey version 6.0.0.
*
* @param key - The key of the string.
* @param subcommands - The {@link BitFieldGet} subcommands to be performed.
*
* Command Response - An array of results from the {@link BitFieldGet} subcommands.
*
*/
bitfieldReadOnly(key, subcommands) {
return this.addAndReturn((0, _1.createBitField)(key, subcommands, true));
}
/**
* Reads the configuration parameters of the running server.
* Starting from server version 7, command supports multiple parameters.
*
* @see {@link https://valkey.io/commands/config-get/|valkey.io} for details.
*
* @param parameters - A list of configuration parameter names to retrieve values for.
*
* Command Response - A map of values corresponding to the configuration parameters.
*
*/
configGet(parameters) {
return this.addAndReturn((0, _1.createConfigGet)(parameters));
}
/**
* Sets configuration parameters to the specified values.
* Starting from server version 7, command supports multiple parameters.
*
* @see {@link https://valkey.io/commands/config-set/|valkey.io} for details.
*
* @param parameters - A map consisting of configuration parameters and their respective values to set.
*
* Command Response - "OK" when the configuration was set properly. Otherwise, the command fails with an error.
*/
configSet(parameters) {
return this.addAndReturn((0, _1.createConfigSet)(parameters));
}
/** Retrieve the value associated with `field` in the hash stored at `key`.
* @see {@link https://valkey.io/commands/hget/|valkey.io} for details.
*
* @param key - The key of the hash.
* @param field - The field in the hash stored at `key` to retrieve from the database.
*
* Command Response - the value associated with `field`, or null when `field` is not present in the hash or `key` does not exist.
*/
hget(key, field) {
return this.addAndReturn((0, _1.createHGet)(key, field));
}
/** Sets the specified fields to their respective values in the hash stored at `key`.
* @see {@link https://valkey.io/commands/hset/|valkey.io} for details.
*
* @param key - The key of the hash.
* @param fieldValueList - A list of field names and their values.
* to be set in the hash stored at the specified key.
*
* Command Response - The number of fields that were added.
*/
hset(key, fieldsAndValues) {
return this.addAndReturn((0, _1.createHSet)(key, (0, _1.convertFieldsAndValuesToHashDataType)(fieldsAndValues)));
}
/**
* Returns all field names in the hash stored at `key`.
*
* @see {@link https://valkey.io/commands/hkeys/|valkey.io} for details.
*
* @param key - The key of the hash.
*
* Command Response - A list of field names for the hash, or an empty list when the key does not exist.
*/
hkeys(key) {
return this.addAndReturn((0, _1.createHKeys)(key));
}
/** Sets `field` in the hash stored at `key` to `value`, only if `field` does not yet exist.
* If `key` does not exist, a new key holding a hash is created.
* If `field` already exists, this operation has no effect.
* @see {@link https://valkey.io/commands/hsetnx/|valkey.io} for details.
*
* @param key - The key of the hash.
* @param field - The field to set the value for.
* @param value - The value to set.
*
* Command Response - `true` if the field was set, `false` if the field already existed and was not set.
*/
hsetnx(key, field, value) {
return this.addAndReturn((0, _1.createHSetNX)(key, field, value));
}
/** Removes the specified fields from the hash stored at `key`.
* Specified fields that do not exist within this hash are ignored.
* @see {@link https://valkey.io/commands/hdel/|valkey.io} for details.
*
* @param key - The key of the hash.
* @param fields - The fields to remove from the hash stored at `key`.
*
* Command Response - the number of fields that were removed from the hash, not including specified but non existing fields.
* If `key` does not exist, it is treated as an empty hash and it returns 0.
*/
hdel(key, fields) {
return this.addAndReturn((0, _1.createHDel)(key, fields));
}
/** Returns the values associated with the specified fields in the hash stored at `key`.
* @see {@link https://valkey.io/commands/hmget/|valkey.io} for details.
*
* @param key - The key of the hash.
* @param fields - The fields in the hash stored at `key` to retrieve from the database.
*
* Command Response - a list 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, it is treated as an empty hash and it returns a list of null values.
*/
hmget(key, fields) {
return this.addAndReturn((0, _1.createHMGet)(key, fields));
}
/** Returns if `field` is an existing field in the hash stored at `key`.
* @see {@link https://valkey.io/commands/hexists/|valkey.io} for details.
*
* @param key - The key of the hash.
* @param field - The field to check in the hash stored at `key`.
*
* Command Response - `true` if the hash contains `field`. If the hash does not contain `field`, or if `key` does not exist,
* the command response will be `false`.
*/
hexists(key, field) {
return this.addAndReturn((0, _1.createHExists)(key, field));
}
/**
* Returns all fields and values of the hash stored at `key`.
*
* @see {@link https://valkey.io/commands/hgetall/|valkey.io} for details.
*
* @param key - The key of the hash.
*
* Command Response - A list of fields and their values stored in the hash.
* If `key` does not exist, it returns an empty list.
*/
hgetall(key) {
return this.addAndReturn((0, _1.createHGetAll)(key));
}
/** Increments the number stored at `field` in the hash stored at `key` by `increment`.
* By using a negative increment value, the value stored at `field` in the hash stored at `key` is decremented.
* If `field` or `key` does not exist, it is set to 0 before performing the operation.
* @see {@link https://valkey.io/commands/hincrby/|valkey.io} for details.
*
* @param key - The key of the hash.
* @param amount - The amount to increment.
* @param field - The field in the hash stored at `key` to increment its value.
*
* Command Response - the value of `field` in the hash stored at `key` after the increment.
*/
hincrBy(key, field, amount) {
return this.addAndReturn((0, _1.createHIncrBy)(key, field, amount));
}
/** Increment the string representing a floating point number stored at `field` in the hash stored at `key` by `increment`.
* By using a negative increment value, the value stored at `field` in the hash stored at `key` is decremented.
* If `field` or `key` does not exist, it is set to 0 before performing the operation.
* @see {@link https://valkey.io/commands/hincrbyfloat/|valkey.io} for details.
*
* @param key - The key of the hash.
* @param amount - The amount to increment.
* @param field - The field in the hash stored at `key` to increment its value.
*
* Command Response - the value of `field` in the hash stored at `key` after the increment.
*/
hincrByFloat(key, field, amount) {
return this.addAndReturn((0, _1.createHIncrByFloat)(key, field, amount));
}
/** Returns the number of fields contained in the hash stored at `key`.
* @see {@link https://valkey.io/commands/hlen/|valkey.io} for details.
*
* @param key - The key of the hash.
*
* Command Response - The number of fields in the hash, or 0 when the key does not exist.
*/
hlen(key) {
return this.addAndReturn((0, _1.createHLen)(key));
}
/** Returns all values in the hash stored at key.
* @see {@link https://valkey.io/commands/hvals/|valkey.io} for details.
*
* @param key - The key of the hash.
*
* Command Response - a list of values in the hash, or an empty list when the key does not exist.
*/
hvals(key) {
return this.addAndReturn((0, _1.createHVals)(key));
}
/**
* Returns the string length of the value associated with `field` in the hash stored at `key`.
*
* @see {@link https://valkey.io/commands/hstrlen/|valkey.io} for details.
*
* @param key - The key of the hash.
* @param field - The field in the hash.
*
* Command Response - The string length or `0` if `field` or `key` does not exist.
*/
hstrlen(key, field) {
return this.addAndReturn((0, _1.createHStrlen)(key, field));
}
/**
* Returns a random field name from the hash value stored at `key`.
*
* @see {@link https://valkey.io/commands/hrandfield/|valkey.io} for details.
* @remarks Since Valkey version 6.2.0.
*
* @param key - The key of the hash.
*
* Command Response - A random field name from the hash stored at `key`, or `null` when
* the key does not exist.
*/
hrandfield(key) {
return this.addAndReturn((0, _1.createHRandField)(key));
}
/**
* Iterates incrementally over a hash.
*
* @see {@link https://valkey.io/commands/hscan/|valkey.io} for more details.
*
* @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}.
*
* Command Response - 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
* hash held in `key`. The array in the second element is a flattened series of string pairs,
* where the value is at even indices and the value is at odd indices.
* If `options.noValues` is set to `true`, the second element will only contain the fields without the values.
*/
hscan(key, cursor, options) {
return this.addAndReturn((0, _1.createHScan)(key, cursor, options));
}
/**
* Retrieves up to `count` random field names from the hash value stored at `key`.
*
* @see {@link https://valkey.io/commands/hrandfield/|valkey.io} for details.
* @remarks Since Valkey version 6.2.0.
*
* @param key - The key of the hash.
* @param count - The number of field names to return.
* If `count` is positive, returns unique elements.
* If negative, allows for duplicates.
*
* Command Response - An `array` of random field names from the hash stored at `key`,
* or an `empty array` when the key does not exist.
*/
hrandfieldCount(key, count) {
return this.addAndReturn((0, _1.createHRandField)(key, count));
}
/**
* Retrieves up to `count` random field names along with their values from the hash
* value stored at `key`.
*
* @see {@link https://valkey.io/commands/hrandfield/|valkey.io} for details.
* @remarks Since Valkey version 6.2.0.
*
* @param key - The key of the hash.
* @param count - The number of field names to return.
* If `count` is positive, returns unique elements.
* If negative, allows for duplicates.
*
* Command Response - A 2D `array` of `[fieldName, value]` `arrays`, where `fieldName` is a random
* field name from the hash and `value` is the associated value of the field name.
* If the hash does not exist or is empty, the response will be an empty `array`.
*/
hrandfieldWithValues(key, count) {
return this.addAndReturn((0, _1.createHRandField)(key, count, true));
}
/**
* 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}.
*
* @example
* ```typescript
* // Set fields with 60 second expiration, only if none exist
* batch.hsetex(
* "myHash",
* { field1: "value1", field2: "value2" },
* {
* fieldConditionalChange: HashFieldConditionalChange.ONLY_IF_NONE_EXIST,
* expiry: { type: TimeUnit.Seconds, count: 60 }
* }
* );
*
* // Set fields and keep existing TTL
* batch.hsetex(
* "myHash",
* { field3: "value3" },
* { expiry: "KEEPTTL" }
* );
*
* // Set fields with Unix timestamp expiration
* batch.hsetex(
* "myHash",
* { field4: "value4" },
* { expiry: { type: TimeUnit.UnixSeconds, count: Math.floor(Date.now() / 1000) + 3600 } }
* );
* ```
*
* Command Response - The number of fields that were added to the hash.
*
* @since Valkey 9.0.0
* @see https://valkey.io/commands/hsetex/
*/
hsetex(key, fieldsAndValues, options) {
return this.addAndReturn((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}.
*
* @example
* ```typescript
* // Get fields without setting expiration
* batch.hgetex("myHash", ["field1", "field2"]);
*
* // Get fields and set 30 second expiration
* batch.hgetex(
* "myHash",
* ["field1", "field2"],
* { expiry: { type: TimeUnit.Seconds, count: 30 } }
* );
*
* // Get fields and remove expiration (make persistent)
* batch.hgetex(
* "myHash",
* ["field1", "field2"],
* { expiry: "PERSIST" }
* );
*
* // Get fields and set millisecond precision expiration
* batch.hgetex(
* "myHash",
* ["field3"],
* { expiry: { type: TimeUnit.Milliseconds, count: 5000 } }
* );
* ```
*
* Command Response - 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.
*
* @since Valkey 9.0.0
* @see https://valkey.io/commands/hgetex/
*/
hgetex(key, fields, options) {
return this.addAndReturn((0, _1.createHGetEx)(key, fields, 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 arguments for the HEXPIRE command. See {@link HExpireOptions}.
*
* Command Response - 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)
*/
hexpire(key, seconds, fields, options) {
return this.addAndReturn((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.
*
* Command Response - 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.
*/
hpersist(key, fields) {
return this.addAndReturn((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 HExpireOptions}.
*
* Command Response - An array of boolean values indicating whether expiration was set for each field.
* `true` if expiration was set, `false` if the field doesn't exist or the condition wasn't met.
*/
hpexpire(key, milliseconds, fields, options) {
return this.addAndReturn((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}.
*
* Command Response - 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)
*/
hexpireat(key, unixTimestampSeconds, fields, options) {
return this.addAndReturn((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}.
*
* Command Response - An array of boolean values indicating whether expiration was set for each field.
* `true` if expiration was set, `false` if the field doesn't exist or the condition wasn't met.
*/
hpexpireat(key, unixTimestampMilliseconds, fields, options) {
return this.addAndReturn((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.
*
* Command Response - 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.
*/
httl(key, fields) {
return this.addAndReturn((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.
*
* Command Response - 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.
*/
hexpiretime(key, fields) {
return this.addAndReturn((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.
*
* Command Response - 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.
*/
hpexpiretime(key, fields) {
return this.addAndReturn((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.
*
* Command Response - 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.
*/
hpttl(key, fields) {
return this.addAndReturn((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.
* @see {@link https://valkey.io/commands/lpush/|valkey.io} for details.
*
* @param key - The key of the list.
* @param elements - The elements to insert at the head of the list stored at `key`.
*
* Command Response - the length of the list after the push operations.
*/
lpush(key, elements) {
return this.addAndReturn((0, _1.createLPush)(key, elements));
}
/**
* Inserts specified values at the head of the `list`, only if `key` already
* exists and holds a list.
*
* @see {@link https://valkey.io/commands/lpushx/|valkey.io} for details.
*
* @param key - The key of the list.
* @param elements - The elements to insert at the head of the list stored at `key`.
*
* Command Response - The length of the list after the push operation.
*/
lpushx(key, elements) {
return this.addAndReturn((0, _1.createLPushX)(key, elements));
}
/** Removes and returns the first elements of the list stored at `key`.
* The command pops a single element from the beginning of the list.
* @see {@link https://valkey.io/commands/lpop/|valkey.io} for details.
*
* @param key - The key of the list.
*
* Command Response - The value of the first element.
* If `key` does not exist null will be returned.
*/
lpop(key) {
return this.addAndReturn((0, _1.createLPop)(key));
}
/** Removes and returns up to `count` elements of the list stored at `key`, depending on the list's length.
* @see {@link https://valkey.io/commands/lpop/|valkey.io} for details.
*
* @param key - The key of the list.
* @param count - The count of the elements to pop from the list.
*
* Command Response - A list of the popped elements will be returned depending on the list's length.
* If `key` does not exist null will be returned.
*/
lpopCount(key, count) {
return this.addAndReturn((0, _1.createLPop)(key, count));
}
/** Returns the specified elements of the list stored at `key`.
* The offsets `start` and `end` are zero-based indexes, with 0 being the first element of the list, 1 being the next element and so on.
* These offsets can also be negative numbers indicating offsets starting at the end of the list,
* with -1 being the last element of the list, -2 being the penultimate, and so on.
* @see {@link https://valkey.io/commands/lrange/|valkey.io} for details.
*
* @param key - The key of the list.
* @param start - The starting point of the range.
* @param end - The end of the range.
*
* Command Response - list of elements in the specified range.
* If `start` exceeds the end of the list, or if `start` is greater than `end`, an empty list will be returned.
* If `end` exceeds the actual end of the list, the range will stop at the actual end of the list.
* If `key` does not exist an empty list will be returned.
*/
lrange(key, start, end) {
return this.addAndReturn((0, _1.createLRange)(key, start, end));
}
/** Returns the length of the list stored at `key`.
* @see {@link https://valkey.io/commands/llen/|valkey.io} for details.
*
* @param key - The key of the list.
*
* Command Response - the length of the list at `key`.
* If `key` does not exist, it is interpreted as an empty list and 0 is returned.
*/
llen(key) {
return this.addAndReturn((0, _1.createLLen)(key));
}
/**
* Atomically pops and removes the left/right-most element to the list stored at `source`
* depending on `whereFrom`, and pushes the element at the first/last element of the list
* stored at `destination` depending on `whereTo`, see {@link ListDirection}.
*
* @see {@link https://valkey.io/commands/lmove/|valkey.io} for details.
* @remarks Since Valkey version 6.2.0.
*
* @param source - The key to the source list.
* @param destination - The key to the destination list.
* @param whereFrom - The {@link ListDirection} to remove the element from.
* @param whereTo - The {@link ListDirection} to add the element to.
*
* Command Response - The popped element, or `null` if `source` does not exist.
*/
lmove(source, destination, whereFrom, whereTo) {
return this.addAndReturn((0, _1.createLMove)(source, destination, whereFrom, whereTo));
}
/**
*
* Blocks the connection until it pops atomically and removes the left/right-most element to the
* list stored at `source` depending on `whereFrom`, and pushes the element at the first/last element
* of the list stored at `destination` depending on `whereTo`.
* `BLMOVE` is the blocking variant of {@link lmove}.
*
* @see {@link https://valkey.io/commands/blmove/|valkey.io} for details.
* @remarks When in cluster mode, both `source` and `destination` must map to the same hash slot.
* @remarks `BLMOVE` is a client blocking command, see {@link https://glide.valkey.io/how-to/connection-management/#blocking-commands|Valkey GLIDE Documentation} for more details and best practices.
* @remarks Since Valkey version 6.2.0.
*
* @param source - The key to the source list.
* @param destination - The key to the destination list.
* @param whereFrom - The {@link ListDirection} to remove the element from.
* @param whereTo - The {@link ListDirection} to add the element to.
* @param timeout - The number of seconds to wait for a blocking operation to complete. A value of `0` will block indefinitely.
*
* Command Response - The popped element, or `null` if `source` does not exist or if the operation timed-out.
*/
blmove(source, destination, whereFrom, whereTo, timeout) {
return this.addAndReturn((0, _1.createBLMove)(source, destination, whereFrom, whereTo, timeout));
}
/**
* Sets the list element at `index` to `element`.
* The index is zero-based, so `0` means the first element, `1` the second element and so on.
* Negative indices c