diff --git a/go/api/base_client.go b/go/api/base_client.go index 3defba9f9b..33eecc93e3 100644 --- a/go/api/base_client.go +++ b/go/api/base_client.go @@ -22,7 +22,7 @@ import ( "google.golang.org/protobuf/proto" ) -// BaseClient defines an interface for methods common to both [GlideClient] and [GlideClusterClient]. +// BaseClient defines an interface for methods common to both [GlideClientCommands] and [GlideClusterClientCommands]. type BaseClient interface { StringCommands HashCommands @@ -180,6 +180,25 @@ func toCStrings(args []string) ([]C.uintptr_t, []C.ulong) { return cStrings, stringLengths } +// Set the given key with the given value. The return value is a response from Valkey containing the string "OK". +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key to store. +// value - The value to store with the given key. +// +// Return value: +// +// `"OK"` response on success. +// +// For example: +// +// result, err := client.Set("key", "value") +// result: "OK" +// +// [valkey.io]: https://valkey.io/commands/set/ func (client *baseClient) Set(key string, value string) (string, error) { result, err := client.executeCommand(C.Set, []string{key, value}) if err != nil { @@ -189,6 +208,38 @@ func (client *baseClient) Set(key string, value string) (string, error) { return handleStringResponse(result) } +// SetWithOptions sets the given key with the given value using the given options. The return value is dependent on the +// passed options. If the value is successfully set, "OK" is returned. If value isn't set because of [OnlyIfExists] or +// [OnlyIfDoesNotExist] conditions, api.CreateNilStringResult() is returned. If [SetOptions#ReturnOldValue] is +// set, the old value is returned. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key to store. +// value - The value to store with the given key. +// options - The [api.SetOptions]. +// +// Return value: +// +// If the value is successfully set, return api.Result[string] containing "OK". +// If value isn't set because of ConditionalSet.OnlyIfExists or ConditionalSet.OnlyIfDoesNotExist conditions, return +// api.CreateNilStringResult(). +// If SetOptions.returnOldValue is set, return the old value as a String. +// +// For example: +// +// key: initialValue +// result, err := client.SetWithOptions("key", "value", api.NewSetOptionsBuilder() +// .SetExpiry(api.NewExpiryBuilder() +// .SetType(api.Seconds) +// .SetCount(uint64(5) +// )) +// result.Value(): "OK" +// result.IsNil(): false +// +// [valkey.io]: https://valkey.io/commands/set/ func (client *baseClient) SetWithOptions(key string, value string, options *SetOptions) (Result[string], error) { optionArgs, err := options.toArgs() if err != nil { @@ -203,6 +254,29 @@ func (client *baseClient) SetWithOptions(key string, value string, options *SetO return handleStringOrNilResponse(result) } +// Get string value associated with the given key, or api.CreateNilStringResult() is returned if no such value +// exists. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key to be retrieved from the database. +// +// Return value: +// +// If key exists, returns the value of key as a String. Otherwise, return [api.CreateNilStringResult()]. +// +// For example: +// 1. key: value +// result, err := client.Get("key") +// result.Value(): "value" +// result.IsNil(): false +// 2. result, err := client.Get("nonExistentKey") +// result.Value(): "" +// result.IsNil(): true +// +// [valkey.io]: https://valkey.io/commands/get/ func (client *baseClient) Get(key string) (Result[string], error) { result, err := client.executeCommand(C.Get, []string{key}) if err != nil { @@ -212,6 +286,29 @@ func (client *baseClient) Get(key string) (Result[string], error) { return handleStringOrNilResponse(result) } +// Get string value associated with the given key, or an empty string is returned [api.CreateNilStringResult()] if no such +// value exists. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key to be retrieved from the database. +// +// Return value: +// +// If key exists, returns the value of key as a Result[string]. Otherwise, return [api.CreateNilStringResult()]. +// +// For example: +// 1. key: value +// result, err := client.GetEx("key") +// result.Value(): "value" +// result.IsNil(): false +// 2. result, err := client.GetEx("nonExistentKey") +// result.Value(): "" +// result.IsNil(): true +// +// [valkey.io]: https://valkey.io/commands/getex/ func (client *baseClient) GetEx(key string) (Result[string], error) { result, err := client.executeCommand(C.GetEx, []string{key}) if err != nil { @@ -221,6 +318,31 @@ func (client *baseClient) GetEx(key string) (Result[string], error) { return handleStringOrNilResponse(result) } +// Get string value associated with the given key and optionally sets the expiration of the key. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key to be retrieved from the database. +// options - The [api.GetExOptions]. +// +// Return value: +// +// If key exists, returns the value of key as a Result[string]. Otherwise, return [api.CreateNilStringResult()]. +// +// For example: +// +// key: initialValue +// result, err := client.GetExWithOptions("key", api.NewGetExOptionsBuilder() +// .SetExpiry(api.NewExpiryBuilder() +// .SetType(api.Seconds) +// .SetCount(uint64(5) +// )) +// result.Value(): "initialValue" +// result.IsNil(): false +// +// [valkey.io]: https://valkey.io/commands/getex/ func (client *baseClient) GetExWithOptions(key string, options *GetExOptions) (Result[string], error) { optionArgs, err := options.toArgs() if err != nil { @@ -235,6 +357,31 @@ func (client *baseClient) GetExWithOptions(key string, options *GetExOptions) (R return handleStringOrNilResponse(result) } +// Sets multiple keys to multiple values in a single operation. +// +// Note: +// +// 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. +// +// Parameters: +// +// keyValueMap - A key-value map consisting of keys and their respective values to set. +// +// Return value: +// +// `"OK"` on success. +// +// For example: +// +// result, err := client.MSet(map[string]string{"key1": "value1", "key2": "value2"}) +// result: "OK" +// +// [valkey.io]: https://valkey.io/commands/mset/ func (client *baseClient) MSet(keyValueMap map[string]string) (string, error) { result, err := client.executeCommand(C.MSet, utils.MapToString(keyValueMap)) if err != nil { @@ -244,6 +391,34 @@ func (client *baseClient) MSet(keyValueMap map[string]string) (string, error) { return handleStringResponse(result) } +// 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. +// +// Note: +// +// 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. +// +// Parameters: +// +// keyValueMap - A key-value map consisting of keys and their respective values to set. +// +// Return value: +// +// A bool containing true, if all keys were set. false, if no key was set. +// +// For example: +// 1. result, err := client.MSetNX(map[string]string{"key1": "value1", "key2": "value2"}) +// result: true +// 2. key3: initialValue +// result, err := client.MSetNX(map[string]string{"key3": "value3", "key4": "value4"}) +// result: false +// +// [valkey.io]: https://valkey.io/commands/msetnx/ func (client *baseClient) MSetNX(keyValueMap map[string]string) (bool, error) { result, err := client.executeCommand(C.MSetNX, utils.MapToString(keyValueMap)) if err != nil { @@ -253,6 +428,37 @@ func (client *baseClient) MSetNX(keyValueMap map[string]string) (bool, error) { return handleBoolResponse(result) } +// Retrieves the values of multiple keys. +// +// Note: +// +// 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. +// +// Parameters: +// +// keys - A list of keys to retrieve values for. +// +// Return value: +// +// An array of values corresponding to the provided keys. +// If a key is not found, its corresponding value in the list will be a [api.CreateNilStringResult()] +// +// For example: +// +// key1: value1, key2: value2 +// result, err := client.MGet([]string{"key1", "key2", "key3"}) +// result : { +// api.CreateStringResult("value1), +// api.CreateStringResult("value2"), +// api.CreateNilStringResult() +// } +// +// [valkey.io]: https://valkey.io/commands/mget/ func (client *baseClient) MGet(keys []string) ([]Result[string], error) { result, err := client.executeCommand(C.MGet, keys) if err != nil { @@ -262,6 +468,25 @@ func (client *baseClient) MGet(keys []string) ([]Result[string], error) { return handleStringOrNilArrayResponse(result) } +// Increments the number stored at key by one. If key does not exist, it is set to 0 before performing the operation. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key to increment its value. +// +// Return value: +// +// The value of `key` after the increment. +// +// For example: +// +// key: 1 +// result, err := client.Incr("key"); +// result: 2 +// +// [valkey.io]: https://valkey.io/commands/incr/ func (client *baseClient) Incr(key string) (int64, error) { result, err := client.executeCommand(C.Incr, []string{key}) if err != nil { @@ -271,6 +496,26 @@ func (client *baseClient) Incr(key string) (int64, error) { return handleIntResponse(result) } +// Increments the number stored at key by amount. If key does not exist, it is set to 0 before performing the operation. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key to increment its value. +// amount - The amount to increment. +// +// Return value: +// +// The value of `key` after the increment. +// +// For example: +// +// key: 1 +// result, err := client.IncrBy("key", 2) +// result: 3 +// +// [valkey.io]: https://valkey.io/commands/incrby/ func (client *baseClient) IncrBy(key string, amount int64) (int64, error) { result, err := client.executeCommand(C.IncrBy, []string{key, utils.IntToString(amount)}) if err != nil { @@ -280,6 +525,28 @@ func (client *baseClient) IncrBy(key string, amount int64) (int64, error) { return handleIntResponse(result) } +// Increments the string representing a floating point number stored at key by amount. By using a negative increment 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 [valkey.io] for details. +// +// Parameters: +// +// key - The key to increment its value. +// amount - The amount to increment. +// +// Return value: +// +// The value of key after the increment. +// +// For example: +// +// key: 1 +// result, err := client.IncrBy("key", 0.5) +// result: 1.5 +// +// [valkey.io]: https://valkey.io/commands/incrbyfloat/ func (client *baseClient) IncrByFloat(key string, amount float64) (float64, error) { result, err := client.executeCommand( C.IncrByFloat, @@ -292,6 +559,25 @@ func (client *baseClient) IncrByFloat(key string, amount float64) (float64, erro return handleFloatResponse(result) } +// Decrements the number stored at key by one. If key does not exist, it is set to 0 before performing the operation. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key to decrement its value. +// +// Return value: +// +// The value of `key` after the decrement. +// +// For example: +// +// key: 1 +// result, err := client.Decr("key") +// result: 0 +// +// [valkey.io]: https://valkey.io/commands/decr/ func (client *baseClient) Decr(key string) (int64, error) { result, err := client.executeCommand(C.Decr, []string{key}) if err != nil { @@ -301,6 +587,26 @@ func (client *baseClient) Decr(key string) (int64, error) { return handleIntResponse(result) } +// Decrements the number stored at code by amount. If key does not exist, it is set to 0 before performing the operation. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key to decrement its value. +// amount - The amount to decrement. +// +// Return value: +// +// The value of `key` after the decrement. +// +// For example: +// +// key: 1 +// result, err := client.DecrBy("key", 2) +// result: -1 +// +// [valkey.io]: https://valkey.io/commands/decrby/ func (client *baseClient) DecrBy(key string, amount int64) (int64, error) { result, err := client.executeCommand(C.DecrBy, []string{key, utils.IntToString(amount)}) if err != nil { @@ -310,6 +616,26 @@ func (client *baseClient) DecrBy(key string, amount int64) (int64, error) { return handleIntResponse(result) } +// Returns the length of the string value stored at key. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key to check its length. +// +// Return value: +// +// The length of the string value stored at `key`. +// If key does not exist, it is treated as an empty string, and the command returns `0`. +// +// For example: +// +// key: value +// result, err := client.Strlen("key") +// result: 5 +// +// [valkey.io]: https://valkey.io/commands/strlen/ func (client *baseClient) Strlen(key string) (int64, error) { result, err := client.executeCommand(C.Strlen, []string{key}) if err != nil { @@ -319,6 +645,33 @@ func (client *baseClient) Strlen(key string) (int64, error) { return handleIntResponse(result) } +// Overwrites part of the string stored at key, starting at the specified byte's offset, for the entire length of value. +// If the offset is larger than the current length of the string at key, the string is padded with zero bytes to make +// offset fit. +// Creates the key if it doesn't exist. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key of the string to update. +// offset - The position in the string where value should be written. +// value - The string written with offset. +// +// Return value: +// +// The length of the string stored at `key` after it was modified. +// +// For example: +// 1. result, err := client.SetRange("key", 6, "GLIDE") +// result: 11 (New key created with length of 11 bytes) +// value, err := client.Get("key") +// value.Value(): "\x00\x00\x00\x00\x00\x00GLIDE" +// 2. "key": "愛" (value char takes 3 bytes) +// result, err := client.SetRange("key", 1, "a") +// result: 3 +// +// [valkey.io]: https://valkey.io/commands/setrange/ func (client *baseClient) SetRange(key string, offset int, value string) (int64, error) { result, err := client.executeCommand(C.SetRange, []string{key, strconv.Itoa(offset), value}) if err != nil { @@ -328,6 +681,34 @@ func (client *baseClient) SetRange(key string, offset int, value string) (int64, return handleIntResponse(result) } +// Returns the substring of the string value stored at key, determined by the byte's 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. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key of the string. +// start - The starting offset. +// end - The ending offset. +// +// Return value: +// +// A substring extracted from the value stored at key. Returns empty string if the offset is out of bounds. +// +// For example: +// 1. mykey: "This is a string" +// result, err := client.GetRange("mykey", 0, 3) +// result: "This" +// result, err := client.GetRange("mykey", -3, -1) +// result: "ing" (extracted last 3 characters of a string) +// 2. "key": "愛" (value char takes 3 bytes) +// result, err = client.GetRange("key", 0, 1) +// result: "�" (returns an invalid UTF-8 string) +// +// [valkey.io]: https://valkey.io/commands/getrange/ func (client *baseClient) GetRange(key string, start int, end int) (string, error) { result, err := client.executeCommand(C.GetRange, []string{key, strconv.Itoa(start), strconv.Itoa(end)}) if err != nil { @@ -337,6 +718,26 @@ func (client *baseClient) GetRange(key string, start int, end int) (string, erro return handleStringResponse(result) } +// Appends a value to a key. If key does not exist it is created and set as an empty string, so APPEND will be similar to +// SET in this special case. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key of the string. +// value - The value to append. +// +// Return value: +// +// The length of the string after appending the value. +// +// For example: +// +// result, err := client.Append("key", "value") +// result: 5 +// +// [valkey.io]: https://valkey.io/commands/append/ func (client *baseClient) Append(key string, value string) (int64, error) { result, err := client.executeCommand(C.Append, []string{key, value}) if err != nil { @@ -346,6 +747,38 @@ func (client *baseClient) Append(key string, value string) (int64, error) { return handleIntResponse(result) } +// Returns the longest common subsequence between strings stored at key1 and key2. +// +// Since: +// +// Valkey 7.0 and above. +// +// Note: +// +// 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. +// +// Parameters: +// +// key1 - The key that stores the first string. +// key2 - The key that stores the second string. +// +// Return value: +// +// The longest common subsequence between the 2 strings. +// An empty string is returned if the keys do not exist or have no common subsequences. +// +// For example: +// +// testKey1: foo, testKey2: fao +// result, err := client.LCS("testKey1", "testKey2") +// result: "fo" +// +// [valkey.io]: https://valkey.io/commands/lcs/ func (client *baseClient) LCS(key1 string, key2 string) (string, error) { result, err := client.executeCommand(C.LCS, []string{key1, key2}) if err != nil { @@ -355,6 +788,22 @@ func (client *baseClient) LCS(key1 string, key2 string) (string, error) { return handleStringResponse(result) } +// GetDel gets the value associated with the given key and deletes the key. +// +// Parameters: +// +// key - The key to get and delete. +// +// Return value: +// +// If key exists, returns the value of the key as a String and deletes the key. +// If key does not exist, returns a [api.NilResult[string]] (api.CreateNilStringResult()). +// +// For example: +// +// result, err := client.GetDel("key") +// +// [valkey.io]: https://valkey.io/commands/getdel/ func (client *baseClient) GetDel(key string) (Result[string], error) { if key == "" { return CreateNilStringResult(), errors.New("key is required") @@ -368,6 +817,30 @@ func (client *baseClient) GetDel(key string) (Result[string], error) { return handleStringOrNilResponse(result) } +// HGet returns the value associated with field in the hash stored at key. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key of the hash. +// field - The field in the hash stored at key to retrieve from the database. +// +// Return value: +// The Result[string] associated with field, or [api.NilResult[string]](api.CreateNilStringResult()) when field is not +// present in the hash or key does not exist. +// +// For example: +// +// Assume we have the following hash: +// my_hash := map[string]string{"field1": "value", "field2": "another_value"} +// payload, err := client.HGet("my_hash", "field1") +// // payload.Value(): "value" +// // payload.IsNil(): false +// payload, err = client.HGet("my_hash", "nonexistent_field") +// // payload equals api.CreateNilStringResult() +// +// [valkey.io]: https://valkey.io/commands/hget/ func (client *baseClient) HGet(key string, field string) (Result[string], error) { result, err := client.executeCommand(C.HGet, []string{key, field}) if err != nil { @@ -377,6 +850,24 @@ func (client *baseClient) HGet(key string, field string) (Result[string], error) return handleStringOrNilResponse(result) } +// HGetAll returns all fields and values of the hash stored at key. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key of the hash. +// +// Return value: +// +// A map of all fields and their values as Result[string] in the hash, or an empty map when key does not exist. +// +// For example: +// +// fieldValueMap, err := client.HGetAll("my_hash") +// // fieldValueMap equals map[string]string{field1: value1, field2: value2} +// +// [valkey.io]: https://valkey.io/commands/hgetall/ func (client *baseClient) HGetAll(key string) (map[string]string, error) { result, err := client.executeCommand(C.HGetAll, []string{key}) if err != nil { @@ -386,6 +877,32 @@ func (client *baseClient) HGetAll(key string) (map[string]string, error) { return handleStringToStringMapResponse(result) } +// HMGet returns the values associated with the specified fields in the hash stored at key. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key of the hash. +// fields - The fields in the hash stored at key to retrieve from the database. +// +// Return value: +// +// An array of Result[string]s associated with the given fields, in the same order as they are requested. +// +// For every field that does not exist in the hash, a [api.NilResult[string]](api.CreateNilStringResult()) is +// returned. +// +// If key does not exist, returns an empty string array. +// +// For example: +// +// values, err := client.HMGet("my_hash", []string{"field1", "field2"}) +// // value1 equals api.CreateStringResult("value1") +// // value2 equals api.CreateStringResult("value2") +// // values equals []api.Result[string]{value1, value2} +// +// [valkey.io]: https://valkey.io/commands/hmget/ func (client *baseClient) HMGet(key string, fields []string) ([]Result[string], error) { result, err := client.executeCommand(C.HMGet, append([]string{key}, fields...)) if err != nil { @@ -395,6 +912,27 @@ func (client *baseClient) HMGet(key string, fields []string) ([]Result[string], return handleStringOrNilArrayResponse(result) } +// HSet sets the specified fields to their respective values in the hash stored at key. +// This command overwrites the values of specified fields that exist in the hash. +// If key doesn't exist, a new key holding a hash is created. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key of the hash. +// values - A map of field-value pairs to set in the hash. +// +// Return value: +// +// The number of fields that were added or updated. +// +// For example: +// +// num, err := client.HSet("my_hash", map[string]string{"field": "value", "field2": "value2"}) +// // num: 2 +// +// [valkey.io]: https://valkey.io/commands/hset/ func (client *baseClient) HSet(key string, values map[string]string) (int64, error) { result, err := client.executeCommand(C.HSet, utils.ConvertMapToKeyValueStringArray(key, values)) if err != nil { @@ -404,6 +942,31 @@ func (client *baseClient) HSet(key string, values map[string]string) (int64, err return handleIntResponse(result) } +// HSetNX 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 [valkey.io] for details. +// +// Parameters: +// +// key - The key of the hash. +// field - The field to set. +// value - The value to set. +// +// Return value: +// +// A bool containing true if field is a new field in the hash and value was set. +// false if field already exists in the hash and no operation was performed. +// +// For example: +// +// payload1, err := client.HSetNX("myHash", "field", "value") +// // payload1: true +// payload2, err := client.HSetNX("myHash", "field", "newValue") +// // payload2: false +// +// [valkey.io]: https://valkey.io/commands/hsetnx/ func (client *baseClient) HSetNX(key string, field string, value string) (bool, error) { result, err := client.executeCommand(C.HSetNX, []string{key, field, value}) if err != nil { @@ -413,6 +976,26 @@ func (client *baseClient) HSetNX(key string, field string, value string) (bool, return handleBoolResponse(result) } +// HDel removes the specified fields from the hash stored at key. +// Specified fields that do not exist within this hash are ignored. +// If key does not exist, it is treated as an empty hash and this command returns 0. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key of the hash. +// fields - The fields to remove from the hash stored at key. +// +// Return value: +// The number of fields that were removed from the hash, not including specified but non-existing fields. +// +// For example: +// +// num, err := client.HDel("my_hash", []string{"field_1", "field_2"}) +// // num: 2 +// +// [valkey.io]: https://valkey.io/commands/hdel/ func (client *baseClient) HDel(key string, fields []string) (int64, error) { result, err := client.executeCommand(C.HDel, append([]string{key}, fields...)) if err != nil { @@ -422,6 +1005,27 @@ func (client *baseClient) HDel(key string, fields []string) (int64, error) { return handleIntResponse(result) } +// HLen returns the number of fields contained in the hash stored at key. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key of the hash. +// +// Return value: +// +// The number of fields in the hash, or `0` when key does not exist. +// If key holds a value that is not a hash, an error is returned. +// +// For example: +// +// num1, err := client.HLen("myHash") +// // num: 3 +// num2, err := client.HLen("nonExistingKey") +// // num: 0 +// +// [valkey.io]: https://valkey.io/commands/hlen/ func (client *baseClient) HLen(key string) (int64, error) { result, err := client.executeCommand(C.HLen, []string{key}) if err != nil { @@ -431,6 +1035,24 @@ func (client *baseClient) HLen(key string) (int64, error) { return handleIntResponse(result) } +// HVals returns all values in the hash stored at key. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key of the hash. +// +// Return value: +// +// A slice containing all the values in the hash, or an empty slice when key does not exist. +// +// For example: +// +// values, err := client.HVals("myHash") +// values: []string{"value1", "value2", "value3"} +// +// [valkey.io]: https://valkey.io/commands/hvals/ func (client *baseClient) HVals(key string) ([]string, error) { result, err := client.executeCommand(C.HVals, []string{key}) if err != nil { @@ -440,6 +1062,28 @@ func (client *baseClient) HVals(key string) ([]string, error) { return handleStringArrayResponse(result) } +// HExists returns if field is an existing field in the hash stored at key. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key of the hash. +// field - The field to check in the hash stored at key. +// +// Return value: +// +// A bool containing true if the hash contains the specified field. +// false if the hash does not contain the field, or if the key does not exist. +// +// For example: +// +// exists, err := client.HExists("my_hash", "field1") +// // exists: true +// exists, err = client.HExists("my_hash", "non_existent_field") +// // exists: false +// +// [valkey.io]: https://valkey.io/commands/hexists/ func (client *baseClient) HExists(key string, field string) (bool, error) { result, err := client.executeCommand(C.HExists, []string{key, field}) if err != nil { @@ -449,6 +1093,24 @@ func (client *baseClient) HExists(key string, field string) (bool, error) { return handleBoolResponse(result) } +// HKeys returns all field names in the hash stored at key. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key of the hash. +// +// Return value: +// +// A slice containing all the field names in the hash, or an empty slice when key does not exist. +// +// For example: +// +// names, err := client.HKeys("my_hash") +// names: []string{"field1", "field2"} +// +// [valkey.io]: https://valkey.io/commands/hkeys/ func (client *baseClient) HKeys(key string) ([]string, error) { result, err := client.executeCommand(C.HKeys, []string{key}) if err != nil { @@ -458,6 +1120,26 @@ func (client *baseClient) HKeys(key string) ([]string, error) { return handleStringArrayResponse(result) } +// HStrLen returns the string length of the value associated with field in the hash stored at key. +// If the key or the field do not exist, 0 is returned. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key of the hash. +// field - The field to get the string length of its value. +// +// Return value: +// +// The length of the string value associated with field, or `0` when field or key do not exist. +// +// For example: +// +// strlen, err := client.HStrLen("my_hash", "my_field") +// // strlen: 10 +// +// [valkey.io]: https://valkey.io/commands/hstrlen/ func (client *baseClient) HStrLen(key string, field string) (int64, error) { result, err := client.executeCommand(C.HStrlen, []string{key, field}) if err != nil { @@ -467,6 +1149,29 @@ func (client *baseClient) HStrLen(key string, field string) (int64, error) { return handleIntResponse(result) } +// 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 [valkey.io] for details. +// +// Parameters: +// +// key - The key of the hash. +// field - The field in the hash stored at `key` to increment its value. +// increment - The amount to increment. +// +// Return value: +// +// The value of `field` in the hash stored at `key` after the increment. +// +// Example: +// +// _, err := client.HSet("key", map[string]string{"field": "10"}) +// hincrByResult, err := client.HIncrBy("key", "field", 1) +// // hincrByResult: 11 +// +// [valkey.io]: https://valkey.io/commands/hincrby/ func (client *baseClient) HIncrBy(key string, field string, increment int64) (int64, error) { result, err := client.executeCommand(C.HIncrBy, []string{key, field, utils.IntToString(increment)}) if err != nil { @@ -476,6 +1181,29 @@ func (client *baseClient) HIncrBy(key string, field string, increment int64) (in return handleIntResponse(result) } +// Increments 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 [valkey.io] for details. +// +// Parameters: +// +// key - The key of the hash. +// field - The field in the hash stored at `key` to increment its value. +// increment - The amount to increment. +// +// Return value: +// +// The value of `field` in the hash stored at `key` after the increment. +// +// Example: +// +// _, err := client.HSet("key", map[string]string{"field": "10"}) +// hincrByFloatResult, err := client.HIncrByFloat("key", "field", 1.5) +// // hincrByFloatResult: 11.5 +// +// [valkey.io]: https://valkey.io/commands/hincrbyfloat/ func (client *baseClient) HIncrByFloat(key string, field string, increment float64) (float64, error) { result, err := client.executeCommand(C.HIncrByFloat, []string{key, field, utils.FloatToString(increment)}) if err != nil { @@ -526,9 +1254,9 @@ func (client *baseClient) HScan(key string, cursor string) (string, []string, er // // Parameters: // -// key - The key of the hash. -// cursor - The cursor that points to the next iteration of results. A value of "0" indicates the start of the search. -// options - The [api.HashScanOptions]. +// key - The key of the hash. +// cursor - The cursor that points to the next iteration of results. A value of "0" indicates the start of the search. +// options - The [api.HashScanOptions]. // // Return value: // @@ -540,13 +1268,13 @@ func (client *baseClient) HScan(key string, cursor string) (string, []string, er // // Example: // -// // Assume key contains a hash {{"a": "1"}, {"b", "2"}} -// opts := options.NewHashScanOptionsBuilder().SetMatch("a") -// resCursor, resCollection, err = client.HScan(key, initialCursor, opts) -// // resCursor = {0 false} -// // resCollection = [{a false} {1 false}] -// // The resCollection only contains the hash map entry that matches with the match option provided with the command -// // input. +// // Assume key contains a hash {{"a": "1"}, {"b", "2"}} +// opts := options.NewHashScanOptionsBuilder().SetMatch("a") +// resCursor, resCollection, err = client.HScan(key, initialCursor, opts) +// // resCursor = 0 +// // resCollection = [a 1] +// // The resCollection only contains the hash map entry that matches with the match option provided with the command +// // input. // // [valkey.io]: https://valkey.io/commands/hscan/ func (client *baseClient) HScanWithOptions( @@ -666,6 +1394,27 @@ func (client *baseClient) HRandFieldWithCountWithValues(key string, count int64) return handle2DStringArrayResponse(result) } +// 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 an empty +// list before performing the push operation. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key of the list. +// elements - The elements to insert at the head of the list stored at key. +// +// Return value: +// +// The length of the list after the push operation. +// +// For example: +// +// result, err := client.LPush("my_list", []string{"value1", "value2"}) +// result: 2 +// +// [valkey.io]: https://valkey.io/commands/lpush/ func (client *baseClient) LPush(key string, elements []string) (int64, error) { result, err := client.executeCommand(C.LPush, append([]string{key}, elements...)) if err != nil { @@ -675,6 +1424,30 @@ func (client *baseClient) LPush(key string, elements []string) (int64, error) { return handleIntResponse(result) } +// 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 [valkey.io] for details. +// +// Parameters: +// +// key - The key of the list. +// +// Return value: +// +// The Result[string] containing the value of the first element. +// If key does not exist, [api.CreateNilStringResult()] will be returned. +// +// For example: +// 1. result, err := client.LPush("my_list", []string{"value1", "value2"}) +// value, err := client.LPop("my_list") +// value.Value(): "value2" +// result.IsNil(): false +// 2. result, err := client.LPop("non_existent") +// result.Value(): "" +// result.IsNil(); true +// +// [valkey.io]: https://valkey.io/commands/lpop/ func (client *baseClient) LPop(key string) (Result[string], error) { result, err := client.executeCommand(C.LPop, []string{key}) if err != nil { @@ -684,6 +1457,27 @@ func (client *baseClient) LPop(key string) (Result[string], error) { return handleStringOrNilResponse(result) } +// Removes and returns up to count elements of the list stored at key, depending on the list's length. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key of the list. +// count - The count of the elements to pop from the list. +// +// Return value: +// +// An array of the popped elements as strings will be returned depending on the list's length +// If key does not exist, nil will be returned. +// +// For example: +// 1. result, err := client.LPopCount("my_list", 2) +// result: []string{"value1", "value2"} +// 2. result, err := client.LPopCount("non_existent") +// result: nil +// +// [valkey.io]: https://valkey.io/commands/lpop/ func (client *baseClient) LPopCount(key string, count int64) ([]string, error) { result, err := client.executeCommand(C.LPop, []string{key, utils.IntToString(count)}) if err != nil { @@ -693,6 +1487,28 @@ func (client *baseClient) LPopCount(key string, count int64) ([]string, error) { return handleStringArrayOrNilResponse(result) } +// Returns the index of the first occurrence of element inside the list specified by key. If no match is found, +// [api.CreateNilInt64Result()] is returned. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The name of the list. +// element - The value to search for within the list. +// +// Return value: +// The Result[int64] containing the index of the first occurrence of element, or [api.CreateNilInt64Result()] if element is +// not in the list. +// +// For example: +// +// result, err := client.RPush("my_list", []string{"a", "b", "c", "d", "e", "e"}) +// position, err := client.LPos("my_list", "e") +// position.Value(): 4 +// position.IsNil(): false +// +// [valkey.io]: https://valkey.io/commands/lpos/ func (client *baseClient) LPos(key string, element string) (Result[int64], error) { result, err := client.executeCommand(C.LPos, []string{key, element}) if err != nil { @@ -702,6 +1518,30 @@ func (client *baseClient) LPos(key string, element string) (Result[int64], error return handleIntOrNilResponse(result) } +// Returns the index of an occurrence of element within a list based on the given options. If no match is found, +// [api.CreateNilInt64Result()] is returned. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The name of the list. +// element - The value to search for within the list. +// options - The LPos options. +// +// Return value: +// +// The Result[int64] containing the index of element, or [api.CreateNilInt64Result()] if element is not in the list. +// +// For example: +// 1. result, err := client.RPush("my_list", []string{"a", "b", "c", "d", "e", "e"}) +// result, err := client.LPosWithOptions("my_list", "e", api.NewLPosOptionsBuilder().SetRank(2)) +// result.Value(): 5 (Returns the second occurrence of the element "e") +// 2. result, err := client.RPush("my_list", []string{"a", "b", "c", "d", "e", "e"}) +// result, err := client.LPosWithOptions("my_list", "e", api.NewLPosOptionsBuilder().SetRank(1).SetMaxLen(1000)) +// result.Value(): 4 +// +// [valkey.io]: https://valkey.io/commands/lpos/ func (client *baseClient) LPosWithOptions(key string, element string, options *LPosOptions) (Result[int64], error) { result, err := client.executeCommand(C.LPos, append([]string{key, element}, options.toArgs()...)) if err != nil { @@ -711,6 +1551,27 @@ func (client *baseClient) LPosWithOptions(key string, element string, options *L return handleIntOrNilResponse(result) } +// Returns an array of indices of matching elements within a list. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The name of the list. +// element - The value to search for within the list. +// count - The number of matches wanted. +// +// Return value: +// +// An array that holds the indices of the matching elements within the list. +// +// For example: +// +// _, err := client.RPush("my_list", []string{"a", "b", "c", "d", "e", "e", "e"}) +// result, err := client.LPosCount("my_list", "e", int64(3)) +// result: []int64{ 4, 5, 6 } +// +// [valkey.io]: https://valkey.io/commands/lpos/ func (client *baseClient) LPosCount(key string, element string, count int64) ([]int64, error) { result, err := client.executeCommand(C.LPos, []string{key, element, CountKeyword, utils.IntToString(count)}) if err != nil { @@ -720,6 +1581,36 @@ func (client *baseClient) LPosCount(key string, element string, count int64) ([] return handleIntArrayResponse(result) } +// Returns an array of indices of matching elements within a list based on the given options. If no match is found, an +// empty array is returned. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The name of the list. +// element - The value to search for within the list. +// count - The number of matches wanted. +// options - The LPos options. +// +// Return value: +// +// An array that holds the indices of the matching elements within the list. +// +// For example: +// 1. _, err := client.RPush("my_list", []string{"a", "b", "c", "d", "e", "e", "e"}) +// result, err := client.LPosWithOptions("my_list", "e", int64(1), api.NewLPosOptionsBuilder().SetRank(2)) +// result: []int64{ 5 } +// 2. _, err := client.RPush("my_list", []string{"a", "b", "c", "d", "e", "e", "e"}) +// result, err := client.LPosWithOptions( +// "my_list", +// "e", +// int64(3), +// api.NewLPosOptionsBuilder().SetRank(2).SetMaxLen(1000), +// ) +// result: []int64{ 5, 6 } +// +// [valkey.io]: https://valkey.io/commands/lpos/ func (client *baseClient) LPosCountWithOptions( key string, element string, @@ -737,6 +1628,27 @@ func (client *baseClient) LPosCountWithOptions( return handleIntArrayResponse(result) } +// Inserts all the specified values at the tail of the list stored at key. +// elements are inserted one after the other to the tail of the list, from the leftmost element to the rightmost element. +// If key does not exist, it is created as an empty list before performing the push operation. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key of the list. +// elements - The elements to insert at the tail of the list stored at key. +// +// Return value: +// +// The length of the list after the push operation. +// +// For example: +// +// result, err := client.RPush("my_list", []string{"a", "b", "c", "d", "e", "e", "e"}) +// result: 7 +// +// [valkey.io]: https://valkey.io/commands/rpush/ func (client *baseClient) RPush(key string, elements []string) (int64, error) { result, err := client.executeCommand(C.RPush, append([]string{key}, elements...)) if err != nil { @@ -746,6 +1658,25 @@ func (client *baseClient) RPush(key string, elements []string) (int64, error) { return handleIntResponse(result) } +// SAdd adds specified members to the set stored at key. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key where members will be added to its set. +// members - A list of members to add to the set stored at key. +// +// Return value: +// +// The number of members that were added to the set, excluding members already present. +// +// For example: +// +// result, err := client.SAdd("my_set", []string{"member1", "member2"}) +// // result: 2 +// +// [valkey.io]: https://valkey.io/commands/sadd/ func (client *baseClient) SAdd(key string, members []string) (int64, error) { result, err := client.executeCommand(C.SAdd, append([]string{key}, members...)) if err != nil { @@ -755,6 +1686,25 @@ func (client *baseClient) SAdd(key string, members []string) (int64, error) { return handleIntResponse(result) } +// SRem removes specified members from the set stored at key. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key from which members will be removed. +// members - A list of members to remove from the set stored at key. +// +// Return value: +// +// The number of members that were removed from the set, excluding non-existing members. +// +// For example: +// +// result, err := client.SRem("my_set", []string{"member1", "member2"}) +// // result: 2 +// +// [valkey.io]: https://valkey.io/commands/srem/ func (client *baseClient) SRem(key string, members []string) (int64, error) { result, err := client.executeCommand(C.SRem, append([]string{key}, members...)) if err != nil { @@ -764,6 +1714,30 @@ func (client *baseClient) SRem(key string, members []string) (int64, error) { return handleIntResponse(result) } +// SUnionStore stores the members of the union of all given sets specified by `keys` into a new set at `destination`. +// +// Note: When in cluster mode, `destination` and all `keys` must map to the same hash slot. +// +// See [valkey.io] for details. +// +// Parameters: +// +// destination - The key of the destination set. +// keys - The keys from which to retrieve the set members. +// +// Return value: +// +// The number of elements in the resulting set. +// +// Example: +// +// result, err := client.SUnionStore("my_set", []string{"set1", "set2"}) +// if err != nil { +// fmt.Println(result) +// } +// // Output: 2 - Two elements were stored at "my_set", and those elements are the union of "set1" and "set2". +// +// [valkey.io]: https://valkey.io/commands/sunionstore/ func (client *baseClient) SUnionStore(destination string, keys []string) (int64, error) { result, err := client.executeCommand(C.SUnionStore, append([]string{destination}, keys...)) if err != nil { @@ -773,6 +1747,26 @@ func (client *baseClient) SUnionStore(destination string, keys []string) (int64, return handleIntResponse(result) } +// SMembers retrieves all the members of the set value stored at key. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key from which to retrieve the set members. +// +// Return value: +// +// A `map[string]struct{}` containing all members of the set. +// Returns an empty collection if key does not exist. +// +// For example: +// +// // Assume set "my_set" contains: "member1", "member2" +// result, err := client.SMembers("my_set") +// // result: map[string]struct{}{ "member1": {}, "member2": {} } +// +// [valkey.io]: https://valkey.io/commands/smembers/ func (client *baseClient) SMembers(key string) (map[string]struct{}, error) { result, err := client.executeCommand(C.SMembers, []string{key}) if err != nil { @@ -782,6 +1776,24 @@ func (client *baseClient) SMembers(key string) (map[string]struct{}, error) { return handleStringSetResponse(result) } +// SCard retrieves the set cardinality (number of elements) of the set stored at key. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key from which to retrieve the number of set members. +// +// Return value: +// +// The cardinality (number of elements) of the set, or `0` if the key does not exist. +// +// Example: +// +// result, err := client.SCard("my_set") +// // result: 3 +// +// [valkey.io]: https://valkey.io/commands/scard/ func (client *baseClient) SCard(key string) (int64, error) { result, err := client.executeCommand(C.SCard, []string{key}) if err != nil { @@ -791,6 +1803,30 @@ func (client *baseClient) SCard(key string) (int64, error) { return handleIntResponse(result) } +// SIsMember returns if member is a member of the set stored at key. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key of the set. +// member - The member to check for existence in the set. +// +// Return value: +// +// A bool containing true if the member exists in the set, false otherwise. +// If key doesn't exist, it is treated as an empty set and the method returns false. +// +// Example: +// +// result1, err := client.SIsMember("mySet", "member1") +// // result1: true +// // Indicates that "member1" exists in the set "mySet". +// result2, err := client.SIsMember("mySet", "nonExistingMember") +// // result2: false +// // Indicates that "nonExistingMember" does not exist in the set "mySet". +// +// [valkey.io]: https://valkey.io/commands/sismember/ func (client *baseClient) SIsMember(key string, member string) (bool, error) { result, err := client.executeCommand(C.SIsMember, []string{key, member}) if err != nil { @@ -800,6 +1836,28 @@ func (client *baseClient) SIsMember(key string, member string) (bool, error) { return handleBoolResponse(result) } +// SDiff computes the difference between the first set and all the successive sets in keys. +// +// Note: When in cluster mode, all keys must map to the same hash slot. +// +// See [valkey.io] for details. +// +// Parameters: +// +// keys - The keys of the sets to diff. +// +// Return value: +// +// A `map[string]struct{}` representing the difference between the sets. +// If a key does not exist, it is treated as an empty set. +// +// Example: +// +// result, err := client.SDiff([]string{"set1", "set2"}) +// // result: map[string]struct{}{ "element": {} } +// // Indicates that "element" is present in "set1", but missing in "set2" +// +// [valkey.io]: https://valkey.io/commands/sdiff/ func (client *baseClient) SDiff(keys []string) (map[string]struct{}, error) { result, err := client.executeCommand(C.SDiff, keys) if err != nil { @@ -809,6 +1867,29 @@ func (client *baseClient) SDiff(keys []string) (map[string]struct{}, error) { return handleStringSetResponse(result) } +// SDiffStore stores the difference between the first set and all the successive sets in keys +// into a new set at destination. +// +// Note: When in cluster mode, destination and all keys must map to the same hash slot. +// +// See [valkey.io] for details. +// +// Parameters: +// +// destination - The key of the destination set. +// keys - The keys of the sets to diff. +// +// Return value: +// +// The number of elements in the resulting set. +// +// Example: +// +// result, err := client.SDiffStore("mySet", []string{"set1", "set2"}) +// // result: 5 +// // Indicates that the resulting set "mySet" contains 5 elements +// +// [valkey.io]: https://valkey.io/commands/sdiffstore/ func (client *baseClient) SDiffStore(destination string, keys []string) (int64, error) { result, err := client.executeCommand(C.SDiffStore, append([]string{destination}, keys...)) if err != nil { @@ -818,6 +1899,28 @@ func (client *baseClient) SDiffStore(destination string, keys []string) (int64, return handleIntResponse(result) } +// SInter gets the intersection of all the given sets. +// +// Note: When in cluster mode, all keys must map to the same hash slot. +// +// See [valkey.io] for details. +// +// Parameters: +// +// keys - The keys of the sets to intersect. +// +// Return value: +// +// A `map[string]struct{}` containing members which are present in all given sets. +// If one or more sets do not exist, an empty collection will be returned. +// +// Example: +// +// result, err := client.SInter([]string{"set1", "set2"}) +// // result: map[string]struct{}{ "element": {} } +// // Indicates that "element" is present in both "set1" and "set2" +// +// [valkey.io]: https://valkey.io/commands/sinter/ func (client *baseClient) SInter(keys []string) (map[string]struct{}, error) { result, err := client.executeCommand(C.SInter, keys) if err != nil { @@ -827,6 +1930,30 @@ func (client *baseClient) SInter(keys []string) (map[string]struct{}, error) { return handleStringSetResponse(result) } +// Stores the members of the intersection of all given sets specified by `keys` into a new set at `destination` +// +// Note: When in cluster mode, `destination` and all `keys` must map to the same hash slot. +// +// See [valkey.io] for details. +// +// Parameters: +// +// destination - The key of the destination set. +// keys - The keys from which to retrieve the set members. +// +// Return value: +// +// The number of elements in the resulting set. +// +// Example: +// +// result, err := client.SInterStore("my_set", []string{"set1", "set2"}) +// if err != nil { +// fmt.Println(result) +// } +// // Output: 2 - Two elements were stored at "my_set", and those elements are the intersection of "set1" and "set2". +// +// [valkey.io]: https://valkey.io/commands/sinterstore/ func (client *baseClient) SInterStore(destination string, keys []string) (int64, error) { result, err := client.executeCommand(C.SInterStore, append([]string{destination}, keys...)) if err != nil { @@ -836,6 +1963,33 @@ func (client *baseClient) SInterStore(destination string, keys []string) (int64, return handleIntResponse(result) } +// SInterCard gets the cardinality of the intersection of all the given sets. +// +// Since: +// +// Valkey 7.0 and above. +// +// Note: When in cluster mode, all keys must map to the same hash slot. +// +// See [valkey.io] for details. +// +// Parameters: +// +// keys - The keys of the sets to intersect. +// +// Return value: +// +// The cardinality of the intersection result. If one or more sets do not exist, `0` is returned. +// +// Example: +// +// result, err := client.SInterCard([]string{"set1", "set2"}) +// // result: 2 +// // Indicates that the intersection of "set1" and "set2" contains 2 elements +// result, err := client.SInterCard([]string{"set1", "nonExistingSet"}) +// // result: 0 +// +// [valkey.io]: https://valkey.io/commands/sintercard/ func (client *baseClient) SInterCard(keys []string) (int64, error) { result, err := client.executeCommand(C.SInterCard, append([]string{strconv.Itoa(len(keys))}, keys...)) if err != nil { @@ -845,6 +1999,35 @@ func (client *baseClient) SInterCard(keys []string) (int64, error) { return handleIntResponse(result) } +// SInterCardLimit gets the cardinality of the intersection of all the given sets, up to the specified limit. +// +// Since: +// +// Valkey 7.0 and above. +// +// Note: When in cluster mode, all keys must map to the same hash slot. +// +// See [valkey.io] for details. +// +// Parameters: +// +// keys - The keys of the sets to intersect. +// limit - The limit for the intersection cardinality value. +// +// Return value: +// +// The cardinality of the intersection result, or the limit if reached. +// If one or more sets do not exist, `0` is returned. +// If the intersection cardinality reaches 'limit' partway through the computation, returns 'limit' as the cardinality. +// +// Example: +// +// result, err := client.SInterCardLimit([]string{"set1", "set2"}, 3) +// // result: 2 +// // Indicates that the intersection of "set1" and "set2" contains 2 elements (or at least 3 if the actual +// // intersection is larger) +// +// [valkey.io]: https://valkey.io/commands/sintercard/ func (client *baseClient) SInterCardLimit(keys []string, limit int64) (int64, error) { args := utils.Concat([]string{utils.IntToString(int64(len(keys)))}, keys, []string{"LIMIT", utils.IntToString(limit)}) @@ -856,6 +2039,27 @@ func (client *baseClient) SInterCardLimit(keys []string, limit int64) (int64, er return handleIntResponse(result) } +// SRandMember returns a random element from the set value stored at key. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key from which to retrieve the set member. +// +// Return value: +// +// A Result[string] containing a random element from the set. +// Returns api.CreateNilStringResult() if key does not exist. +// +// Example: +// +// client.SAdd("test", []string{"one"}) +// response, err := client.SRandMember("test") +// // response.Value(): "one" +// // err: nil +// +// [valkey.io]: https://valkey.io/commands/srandmember/ func (client *baseClient) SRandMember(key string) (Result[string], error) { result, err := client.executeCommand(C.SRandMember, []string{key}) if err != nil { @@ -865,6 +2069,29 @@ func (client *baseClient) SRandMember(key string) (Result[string], error) { return handleStringOrNilResponse(result) } +// SPop removes and returns one random member from the set stored at key. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key of the set. +// +// Return value: +// +// A Result[string] containing the value of the popped member. +// Returns a NilResult if key does not exist. +// +// Example: +// +// value1, err := client.SPop("mySet") +// // value1.Value() might be "value1" +// // err: nil +// value2, err := client.SPop("nonExistingSet") +// // value2.IsNil(): true +// // err: nil +// +// [valkey.io]: https://valkey.io/commands/spop/ func (client *baseClient) SPop(key string) (Result[string], error) { result, err := client.executeCommand(C.SPop, []string{key}) if err != nil { @@ -874,6 +2101,30 @@ func (client *baseClient) SPop(key string) (Result[string], error) { return handleStringOrNilResponse(result) } +// SMIsMember returns whether each member is a member of the set stored at key. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key of the set. +// +// Return value: +// +// A []bool containing whether each member is a member of the set stored at key. +// +// Example: +// +// client.SAdd("myKey", []string{"one", "two"}) +// value1, err := client.SMIsMember("myKey", []string{"two", "three"}) +// // value1[0]: true +// // value1[1]: false +// // err: nil +// value2, err := client.SMIsMember("nonExistingKey", []string{"one"}) +// // value2[0]: false +// // err: nil +// +// [valkey.io]: https://valkey.io/commands/smismember/ func (client *baseClient) SMIsMember(key string, members []string) ([]bool, error) { result, err := client.executeCommand(C.SMIsMember, append([]string{key}, members...)) if err != nil { @@ -883,6 +2134,40 @@ func (client *baseClient) SMIsMember(key string, members []string) ([]bool, erro return handleBoolArrayResponse(result) } +// SUnion gets the union of all the given sets. +// +// Note: When in cluster mode, all keys must map to the same hash slot. +// +// See [valkey.io] for details. +// +// Parameters: +// +// keys - The keys of the sets. +// +// Return value: +// +// A `map[string]struct{}` of members which are present in at least one of the given sets. +// If none of the sets exist, an empty collection will be returned. +// +// Example: +// +// result1, err := client.SAdd("my_set1", []string {"member1", "member2"}) +// // result.Value(): 2 +// // result.IsNil(): false +// +// result2, err := client.SAdd("my_set2", []string {"member2", "member3"}) +// // result.Value(): 2 +// // result.IsNil(): false +// +// result3, err := client.SUnion([]string {"my_set1", "my_set2"}) +// // result3: "{'member1', 'member2', 'member3'}" +// // err: nil +// +// result4, err := client.SUnion([]string {"my_set1", "non_existing_set"}) +// // result4: "{'member1', 'member2'}" +// // err: nil +// +// [valkey.io]: https://valkey.io/commands/sunion/ func (client *baseClient) SUnion(keys []string) (map[string]struct{}, error) { result, err := client.executeCommand(C.SUnion, keys) if err != nil { @@ -997,6 +2282,29 @@ func (client *baseClient) SScanWithOptions( return handleScanResponse(result) } +// Moves `member` from the set at `source` to the set at `destination`, removing it from the source set. +// Creates a new destination set if needed. The operation is atomic. +// +// Note: When in cluster mode, `source` and `destination` must map to the same hash slot. +// +// See [valkey.io] for details. +// +// Parameters: +// +// source - The key of the set to remove the element from. +// destination - The key of the set to add the element to. +// member - The set element to move. +// +// Return value: +// +// `true` on success, or `false` if the `source` set does not exist or the element is not a member of the source set. +// +// Example: +// +// moved := SMove("set1", "set2", "element") +// fmt.Println(moved.Value()) // Output: true +// +// [valkey.io]: https://valkey.io/commands/smove/ func (client *baseClient) SMove(source string, destination string, member string) (bool, error) { result, err := client.executeCommand(C.SMove, []string{source, destination, member}) if err != nil { @@ -1005,6 +2313,35 @@ func (client *baseClient) SMove(source string, destination string, member string return handleBoolResponse(result) } +// 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 [valkey.io] for details. +// +// Parameters: +// +// key - The key of the list. +// start - The starting point of the range. +// end - The end of the range. +// +// Return value: +// +// Array of elements as Result[string] in the specified range. +// If start exceeds the end of the list, or if start is greater than end, an empty array 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 array will be returned. +// +// For example: +// 1. result, err := client.LRange("my_list", 0, 2) +// result: []string{ "value1", "value2", "value3" } +// 2. result, err := client.LRange("my_list", -2, -1) +// result: []string{ "value2", "value3" } +// 3. result, err := client.LRange("non_existent_key", 0, 2) +// result: []string{} +// +// [valkey.io]: https://valkey.io/commands/lrange/ func (client *baseClient) LRange(key string, start int64, end int64) ([]string, error) { result, err := client.executeCommand(C.LRange, []string{key, utils.IntToString(start), utils.IntToString(end)}) if err != nil { @@ -1014,6 +2351,32 @@ func (client *baseClient) LRange(key string, start int64, end int64) ([]string, return handleStringArrayResponse(result) } +// Returns the element at index from the list stored at key. +// The index is zero-based, so 0 means the first element, 1 the second element and so on. Negative indices can be used to +// designate elements starting at the tail of the list. Here, -1 means the last element, -2 means the penultimate and so +// forth. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key of the list. +// index - The index of the element in the list to retrieve. +// +// Return value: +// +// The Result[string] containing element at index in the list stored at key. +// If index is out of range or if key does not exist, [api.CreateNilStringResult()] is returned. +// +// For example: +// 1. result, err := client.LIndex("myList", 0) +// result.Value(): "value1" // Returns the first element in the list stored at 'myList'. +// result.IsNil(): false +// 2. result, err := client.LIndex("myList", -1) +// result.Value(): "value3" // Returns the last element in the list stored at 'myList'. +// result.IsNil(): false +// +// [valkey.io]: https://valkey.io/commands/lindex/ func (client *baseClient) LIndex(key string, index int64) (Result[string], error) { result, err := client.executeCommand(C.LIndex, []string{key, utils.IntToString(index)}) if err != nil { @@ -1023,6 +2386,33 @@ func (client *baseClient) LIndex(key string, index int64) (Result[string], error return handleStringOrNilResponse(result) } +// Trims an existing list so that it will contain only the specified range of elements specified. +// 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 [valkey.io] for details. +// +// Parameters: +// +// key - The key of the list. +// start - The starting point of the range. +// end - The end of the range. +// +// Return value: +// +// Always `"OK"`. +// If start exceeds the end of the list, or if start is greater than end, the result will be an empty list (which causes +// key to be removed). +// If end exceeds the actual end of the list, it will be treated like the last element of the list. +// If key does not exist, `"OK"` will be returned without changes to the database. +// +// For example: +// +// result, err := client.LTrim("my_list", 0, 1) +// result: "OK" +// +// [valkey.io]: https://valkey.io/commands/ltrim/ func (client *baseClient) LTrim(key string, start int64, end int64) (string, error) { result, err := client.executeCommand(C.LTrim, []string{key, utils.IntToString(start), utils.IntToString(end)}) if err != nil { @@ -1032,6 +2422,25 @@ func (client *baseClient) LTrim(key string, start int64, end int64) (string, err return handleStringResponse(result) } +// Returns the length of the list stored at key. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key of the list. +// +// Return value: +// +// The length of the list at `key`. +// If `key` does not exist, it is interpreted as an empty list and `0` is returned. +// +// For example: +// +// result, err := client.LLen("my_list") +// result: 3 // Indicates that there are 3 elements in the list. +// +// [valkey.io]: https://valkey.io/commands/llen/ func (client *baseClient) LLen(key string) (int64, error) { result, err := client.executeCommand(C.LLen, []string{key}) if err != nil { @@ -1041,6 +2450,31 @@ func (client *baseClient) LLen(key string) (int64, error) { return handleIntResponse(result) } +// Removes the first count occurrences of elements equal to element from the list stored at key. +// If count is positive: Removes elements equal to element moving from head to tail. +// If count is negative: Removes elements equal to element moving from tail to head. +// If count is 0 or count is greater than the occurrences of elements equal to element, it removes all elements equal to +// element. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key of the list. +// count - The count of the occurrences of elements equal to element to remove. +// element - The element to remove from the list. +// +// Return value: +// +// The number of the removed elements. +// If `key` does not exist, `0` is returned. +// +// For example: +// +// result, err := client.LRem("my_list", 2, "value") +// result: 2 +// +// [valkey.io]: https://valkey.io/commands/lrem/ func (client *baseClient) LRem(key string, count int64, element string) (int64, error) { result, err := client.executeCommand(C.LRem, []string{key, utils.IntToString(count), element}) if err != nil { @@ -1050,6 +2484,29 @@ func (client *baseClient) LRem(key string, count int64, element string) (int64, return handleIntResponse(result) } +// Removes and returns the last elements of the list stored at key. +// The command pops a single element from the end of the list. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key of the list. +// +// Return value: +// +// The Result[string] containing the value of the last element. +// If key does not exist, [api.CreateNilStringResult()] will be returned. +// +// For example: +// 1. result, err := client.RPop("my_list") +// result.Value(): "value1" +// result.IsNil(): false +// 2. result, err := client.RPop("non_exiting_key") +// result.Value(): "" +// result.IsNil(): true +// +// [valkey.io]: https://valkey.io/commands/rpop/ func (client *baseClient) RPop(key string) (Result[string], error) { result, err := client.executeCommand(C.RPop, []string{key}) if err != nil { @@ -1059,6 +2516,27 @@ func (client *baseClient) RPop(key string) (Result[string], error) { return handleStringOrNilResponse(result) } +// Removes and returns up to count elements from the list stored at key, depending on the list's length. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key of the list. +// count - The count of the elements to pop from the list. +// +// Return value: +// +// An array of popped elements as strings will be returned depending on the list's length. +// If key does not exist, nil will be returned. +// +// For example: +// 1. result, err := client.RPopCount("my_list", 2) +// result: []string{"value1", "value2"} +// 2. result, err := client.RPop("non_exiting_key") +// result: nil +// +// [valkey.io]: https://valkey.io/commands/rpop/ func (client *baseClient) RPopCount(key string, count int64) ([]string, error) { result, err := client.executeCommand(C.RPop, []string{key, utils.IntToString(count)}) if err != nil { @@ -1068,6 +2546,30 @@ func (client *baseClient) RPopCount(key string, count int64) ([]string, error) { return handleStringArrayOrNilResponse(result) } +// Inserts element in the list at key either before or after the pivot. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key of the list. +// insertPosition - The relative position to insert into - either api.Before or api.After the pivot. +// pivot - An element of the list. +// element - The new element to insert. +// +// Return value: +// +// The list length after a successful insert operation. +// If the `key` doesn't exist returns `-1`. +// If the `pivot` wasn't found, returns `0`. +// +// For example: +// +// "my_list": {"Hello", "Wprld"} +// result, err := client.LInsert("my_list", api.Before, "World", "There") +// result: 3 +// +// [valkey.io]: https://valkey.io/commands/linsert/ func (client *baseClient) LInsert( key string, insertPosition InsertPosition, @@ -1090,6 +2592,34 @@ func (client *baseClient) LInsert( return handleIntResponse(result) } +// Pops an element from the head of the first list that is non-empty, with the given keys being checked in the order that +// they are given. +// Blocks the connection when there are no elements to pop from any of the given lists. +// +// Note: +// - When in cluster mode, all keys must map to the same hash slot. +// - BLPop is a client blocking command, see [Blocking Commands] for more details and best practices. +// +// See [valkey.io] for details. +// +// Parameters: +// +// keys - The keys of the lists to pop from. +// timeoutSecs - The number of seconds to wait for a blocking operation to complete. A value of 0 will block indefinitely. +// +// Return value: +// +// A two-element array containing the key from which the element was popped and the value of the popped +// element, formatted as [key, value]. +// If no element could be popped and the timeout expired, returns `nil`. +// +// For example: +// +// result, err := client.BLPop("list1", "list2", 0.5) +// result: []string{ "list1", "element" } +// +// [valkey.io]: https://valkey.io/commands/blpop/ +// [Blocking Commands]: https://github.com/valkey-io/valkey-glide/wiki/General-Concepts#blocking-commands func (client *baseClient) BLPop(keys []string, timeoutSecs float64) ([]string, error) { result, err := client.executeCommand(C.BLPop, append(keys, utils.FloatToString(timeoutSecs))) if err != nil { @@ -1099,6 +2629,34 @@ func (client *baseClient) BLPop(keys []string, timeoutSecs float64) ([]string, e return handleStringArrayOrNilResponse(result) } +// Pops an element from the tail of the first list that is non-empty, with the given keys being checked in the order that +// they are given. +// Blocks the connection when there are no elements to pop from any of the given lists. +// +// Note: +// - When in cluster mode, all keys must map to the same hash slot. +// - BRPop is a client blocking command, see [Blocking Commands] for more details and best practices. +// +// See [valkey.io] for details. +// +// Parameters: +// +// keys - The keys of the lists to pop from. +// timeoutSecs - The number of seconds to wait for a blocking operation to complete. A value of 0 will block indefinitely. +// +// Return value: +// +// A two-element array containing the key from which the element was popped and the value of the popped +// element, formatted as [key, value]. +// If no element could be popped and the timeoutSecs expired, returns `nil`. +// +// For example: +// +// result, err := client.BRPop("list1", "list2", 0.5) +// result: []string{ "list1", "element" } +// +// [valkey.io]: https://valkey.io/commands/brpop/ +// [Blocking Commands]: https://github.com/valkey-io/valkey-glide/wiki/General-Concepts#blocking-commands func (client *baseClient) BRPop(keys []string, timeoutSecs float64) ([]string, error) { result, err := client.executeCommand(C.BRPop, append(keys, utils.FloatToString(timeoutSecs))) if err != nil { @@ -1108,6 +2666,27 @@ func (client *baseClient) BRPop(keys []string, timeoutSecs float64) ([]string, e return handleStringArrayOrNilResponse(result) } +// Inserts all the specified values at the tail of the list stored at key, only if key exists and holds a list. If key is +// not a list, this performs no operation. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key of the list. +// elements - The elements to insert at the tail of the list stored at key. +// +// Return value: +// +// The length of the list after the push operation. +// +// For example: +// +// my_list: {"value1", "value2"} +// result, err := client.RPushX("my_list", []string{"value3", value4}) +// result: 4 +// +// [valkey.io]: https://valkey.io/commands/rpushx/ func (client *baseClient) RPushX(key string, elements []string) (int64, error) { result, err := client.executeCommand(C.RPushX, append([]string{key}, elements...)) if err != nil { @@ -1117,6 +2696,27 @@ func (client *baseClient) RPushX(key string, elements []string) (int64, error) { return handleIntResponse(result) } +// Inserts all the specified values at the head of the list stored at key, only if key exists and holds a list. If key is +// not a list, this performs no operation. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key of the list. +// elements - The elements to insert at the head of the list stored at key. +// +// Return value: +// +// The length of the list after the push operation. +// +// For example: +// +// my_list: {"value1", "value2"} +// result, err := client.LPushX("my_list", []string{"value3", value4}) +// result: 4 +// +// [valkey.io]: https://valkey.io/commands/rpushx/ func (client *baseClient) LPushX(key string, elements []string) (int64, error) { result, err := client.executeCommand(C.LPushX, append([]string{key}, elements...)) if err != nil { @@ -1126,6 +2726,30 @@ func (client *baseClient) LPushX(key string, elements []string) (int64, error) { return handleIntResponse(result) } +// Pops one element from the first non-empty list from the provided keys. +// +// Since: +// +// Valkey 7.0 and above. +// +// See [valkey.io] for details. +// +// Parameters: +// +// keys - An array of keys to lists. +// listDirection - The direction based on which elements are popped from - see [api.ListDirection]. +// +// Return value: +// +// A map of key name mapped array of popped element. +// +// For example: +// +// result, err := client.LPush("my_list", []string{"one", "two", "three"}) +// result, err := client.LMPop([]string{"my_list"}, api.Left) +// result["my_list"] = []string{"three"} +// +// [valkey.io]: https://valkey.io/commands/lmpop/ func (client *baseClient) LMPop(keys []string, listDirection ListDirection) (map[string][]string, error) { listDirectionStr, err := listDirection.toString() if err != nil { @@ -1150,6 +2774,31 @@ func (client *baseClient) LMPop(keys []string, listDirection ListDirection) (map return handleStringToStringArrayMapOrNilResponse(result) } +// Pops one or more elements from the first non-empty list from the provided keys. +// +// Since: +// +// Valkey 7.0 and above. +// +// See [valkey.io] for details. +// +// Parameters: +// +// keys - An array of keys to lists. +// listDirection - The direction based on which elements are popped from - see [api.ListDirection]. +// count - The maximum number of popped elements. +// +// Return value: +// +// A map of key name mapped array of popped elements. +// +// For example: +// +// result, err := client.LPush("my_list", []string{"one", "two", "three"}) +// result, err := client.LMPopCount([]string{"my_list"}, api.Left, int64(1)) +// result["my_list"] = []string{"three"} +// +// [valkey.io]: https://valkey.io/commands/lmpop/ func (client *baseClient) LMPopCount( keys []string, listDirection ListDirection, @@ -1178,6 +2827,38 @@ func (client *baseClient) LMPopCount( return handleStringToStringArrayMapOrNilResponse(result) } +// Blocks the connection until it pops one element from the first non-empty list from the provided keys. BLMPop is the +// blocking variant of [api.LMPop]. +// +// Note: +// - When in cluster mode, all keys must map to the same hash slot. +// - BLMPop is a client blocking command, see [Blocking Commands] for more details and best practices. +// +// Since: +// +// Valkey 7.0 and above. +// +// See [valkey.io] for details. +// +// Parameters: +// +// keys - An array of keys to lists. +// listDirection - The direction based on which elements are popped from - see [api.ListDirection]. +// timeoutSecs - The number of seconds to wait for a blocking operation to complete. A value of 0 will block indefinitely. +// +// Return value: +// +// A map of key name mapped array of popped element. +// If no member could be popped and the timeout expired, returns nil. +// +// For example: +// +// result, err := client.LPush("my_list", []string{"one", "two", "three"}) +// result, err := client.BLMPop([]string{"my_list"}, api.Left, float64(0.1)) +// result["my_list"] = []string{"three"} +// +// [valkey.io]: https://valkey.io/commands/blmpop/ +// [Blocking Commands]: https://github.com/valkey-io/valkey-glide/wiki/General-Concepts#blocking-commands func (client *baseClient) BLMPop( keys []string, listDirection ListDirection, @@ -1206,6 +2887,41 @@ func (client *baseClient) BLMPop( return handleStringToStringArrayMapOrNilResponse(result) } +// Blocks the connection until it pops one or more elements from the first non-empty list from the provided keys. +// BLMPopCount is the blocking variant of [api.LMPopCount]. +// +// Note: +// - When in cluster mode, all keys must map to the same hash slot. +// - BLMPopCount is a client blocking command, see [Blocking Commands] for more details and best practices. +// +// Since: +// +// Valkey 7.0 and above. +// +// See [valkey.io] for details. +// +// Parameters: +// +// keys - An array of keys to lists. +// listDirection - The direction based on which elements are popped from - see [api.ListDirection]. +// count - The maximum number of popped elements. +// timeoutSecs - The number of seconds to wait for a blocking operation to complete. A value of 0 will block +// +// indefinitely. +// +// Return value: +// +// A map of key name mapped array of popped element. +// If no member could be popped and the timeout expired, returns nil. +// +// For example: +// +// result, err: client.LPush("my_list", []string{"one", "two", "three"}) +// result, err := client.BLMPopCount([]string{"my_list"}, api.Left, int64(1), float64(0.1)) +// result["my_list"] = []string{"three"} +// +// [valkey.io]: https://valkey.io/commands/blmpop/ +// [Blocking Commands]: https://github.com/valkey-io/valkey-glide/wiki/General-Concepts#blocking-commands func (client *baseClient) BLMPopCount( keys []string, listDirection ListDirection, @@ -1235,6 +2951,29 @@ func (client *baseClient) BLMPopCount( return handleStringToStringArrayMapOrNilResponse(result) } +// 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 can be used to +// designate elements starting at the tail of the list. Here, -1 means the last element, -2 means the penultimate and so +// forth. +// +// See [valkey.io] for details. +// +// Parameters: +// +// key - The key of the list. +// index - The index of the element in the list to be set. +// element - The element to be set. +// +// Return value: +// +// `"OK"`. +// +// For example: +// +// result, err: client.LSet("my_list", int64(1), "two") +// result: "OK" +// +// [valkey.io]: https://valkey.io/commands/lset/ func (client *baseClient) LSet(key string, index int64, element string) (string, error) { result, err := client.executeCommand(C.LSet, []string{key, utils.IntToString(index), element}) if err != nil { @@ -1244,6 +2983,34 @@ func (client *baseClient) LSet(key string, index int64, element string) (string, return handleStringResponse(result) } +// 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 [valkey.io] for details. +// +// Parameters: +// +// source - The key to the source list. +// destination - The key to the destination list. +// wherefrom - The ListDirection the element should be removed from. +// whereto - The ListDirection the element should be added to. +// +// Return value: +// +// A Result[string] containing the popped element or api.CreateNilStringResult() if source does not exist. +// +// For example: +// +// result, err: client.LPush("my_list", []string{"two", "one"}) +// result, err: client.LPush("my_list2", []string{"four", "three"}) +// result, err: client.LMove("my_list1", "my_list2", api.Left, api.Left) +// result.Value(): "one" +// updatedList1, err: client.LRange("my_list1", int64(0), int64(-1)) +// updatedList2, err: client.LRange("my_list2", int64(0), int64(-1)) +// updatedList1: []string{ "two" } +// updatedList2: []string{ "one", "three", "four" } +// +// [valkey.io]: https://valkey.io/commands/lmove/ func (client *baseClient) LMove( source string, destination string, @@ -1267,6 +3034,46 @@ func (client *baseClient) LMove( return handleStringOrNilResponse(result) } +// 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 . +// +// Example: +// +// result, err := client.Restore("key",ttl, value) +// +// if err != nil { +// // handle error +// } +// fmt.Println(result.Value()) // Output: OK +// +// [valkey.io]: https://valkey.io/commands/restore/ func (client *baseClient) Restore(key string, ttl int64, value string) (Result[string], error) { return client.RestoreWithOptions(key, ttl, value, NewRestoreOptionsBuilder()) } +// Create a key associated with a value that is obtained by +// deserializing the provided serialized value (obtained via [valkey.io]: Https://valkey.io/commands/dump/). +// +// Parameters: +// +// key - The key to create. +// ttl - The expiry time (in milliseconds). If 0, the key will persist. +// value - The serialized value to deserialize and assign to key. +// restoreOptions - Set restore options with replace and absolute TTL modifiers, object idletime and frequency +// +// Return value: +// +// Return OK if successfully create a key with a value. +// +// Example: +// +// restoreOptions := api.NewRestoreOptionsBuilder().SetReplace().SetABSTTL().SetEviction(api.FREQ, 10) +// resultRestoreOpt, err := client.RestoreWithOptions(key, ttl, value, restoreOptions) +// +// if err != nil { +// // handle error +// } +// fmt.Println(result.Value()) // Output: OK +// +// [valkey.io]: https://valkey.io/commands/restore/ func (client *baseClient) RestoreWithOptions(key string, ttl int64, value string, options *RestoreOptions, ) (Result[string], error) { @@ -2693,6 +5531,26 @@ func (client *baseClient) RestoreWithOptions(key string, ttl int64, return handleStringOrNilResponse(result) } +// Serialize the value stored at key in a Valkey-specific format and return it to the user. +// +// Parameters: +// +// The key to serialize. +// +// Return value: +// +// The serialized value of the data stored at key +// If key does not exist, null will be returned. +// +// Example: +// +// result, err := client.Dump([]string{"key"}) +// if err != nil { +// // handle error +// } +// fmt.Println(result.Value()) // Output: (Serialized Value) +// +// [valkey.io]: https://valkey.io/commands/dump/ func (client *baseClient) Dump(key string) (Result[string], error) { result, err := client.executeCommand(C.Dump, []string{key}) if err != nil { @@ -2701,6 +5559,31 @@ func (client *baseClient) Dump(key string) (Result[string], error) { return handleStringOrNilResponse(result) } +// Returns the internal encoding for the Valkey object stored at key. +// +// Note: +// +// When in cluster mode, both key and newkey must map to the same hash slot. +// +// Parameters: +// +// The key of the object to get the internal encoding of. +// +// Return value: +// +// If key exists, returns the internal encoding of the object stored at +// key as a String. Otherwise, returns null. +// +// Example: +// +// result, err := client.ObjectEncoding("mykeyRenamenx") +// +// if err != nil { +// // handle error +// } +// fmt.Println(result.Value()) // Output: embstr +// +// [valkey.io]: https://valkey.io/commands/object-encoding/ func (client *baseClient) ObjectEncoding(key string) (Result[string], error) { result, err := client.executeCommand(C.ObjectEncoding, []string{key}) if err != nil { @@ -3008,6 +5891,24 @@ func (client *baseClient) ObjectRefCount(key string) (Result[int64], error) { return handleIntOrNilResponse(result) } +// Sorts the elements in the list, set, or sorted set at key and returns the result. +// The sort command can be used to sort elements based on different criteria and apply +// transformations on sorted elements. +// To store the result into a new key, see the sortStore function. +// +// Parameters: +// key - The key of the list, set, or sorted set to be sorted. +// +// Return value: +// An Array of sorted elements. +// +// Example: +// +// result, err := client.Sort("key") +// result.Value(): [{1 false} {2 false} {3 false}] +// result.IsNil(): false +// +// [valkey.io]: https://valkey.io/commands/sort/ func (client *baseClient) Sort(key string) ([]Result[string], error) { result, err := client.executeCommand(C.Sort, []string{key}) if err != nil { @@ -3016,6 +5917,37 @@ func (client *baseClient) Sort(key string) ([]Result[string], error) { return handleStringOrNilArrayResponse(result) } +// Sorts the elements in the list, set, or sorted set at key and returns the result. +// The sort command can be used to sort elements based on different criteria and apply +// transformations on sorted elements. +// To store the result into a new key, see the sortStore function. +// +// Note: +// +// In cluster mode, if `key` 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. +// The use of SortOptions.byPattern and SortOptions.getPatterns in cluster mode is +// supported since Valkey version 8.0. +// +// Parameters: +// key - The key of the list, set, or sorted set to be sorted. +// sortOptions - The SortOptions type. +// +// Return value: +// An Array of sorted elements. +// +// Example: +// +// options := api.NewSortOptions().SetByPattern("weight_*").SetIsAlpha(false).AddGetPattern("object_*").AddGetPattern("#") +// result, err := client.Sort("key", options) +// result.Value(): [{Object_3 false} {c false} {Object_1 false} {a false} {Object_2 false} {b false}] +// result.IsNil(): false +// +// [valkey.io]: https://valkey.io/commands/sort/ func (client *baseClient) SortWithOptions(key string, options *options.SortOptions) ([]Result[string], error) { optionArgs := options.ToArgs() result, err := client.executeCommand(C.Sort, append([]string{key}, optionArgs...)) @@ -3025,6 +5957,24 @@ func (client *baseClient) SortWithOptions(key string, options *options.SortOptio return handleStringOrNilArrayResponse(result) } +// Sorts the elements in the list, set, or sorted set at key and returns the result. +// The sortReadOnly command can be used to sort elements based on different criteria and apply +// transformations on sorted elements. +// This command is routed depending on the client's ReadFrom strategy. +// +// Parameters: +// key - The key of the list, set, or sorted set to be sorted. +// +// Return value: +// An Array of sorted elements. +// +// Example: +// +// result, err := client.SortReadOnly("key") +// result.Value(): [{1 false} {2 false} {3 false}] +// result.IsNil(): false +// +// [valkey.io]: https://valkey.io/commands/sort/ func (client *baseClient) SortReadOnly(key string) ([]Result[string], error) { result, err := client.executeCommand(C.SortReadOnly, []string{key}) if err != nil { @@ -3033,6 +5983,37 @@ func (client *baseClient) SortReadOnly(key string) ([]Result[string], error) { return handleStringOrNilArrayResponse(result) } +// Sorts the elements in the list, set, or sorted set at key and returns the result. +// The sort command can be used to sort elements based on different criteria and apply +// transformations on sorted elements. +// This command is routed depending on the client's ReadFrom strategy. +// +// Note: +// +// In cluster mode, if `key` 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. +// The use of SortOptions.byPattern and SortOptions.getPatterns in cluster mode is +// supported since Valkey version 8.0. +// +// Parameters: +// key - The key of the list, set, or sorted set to be sorted. +// sortOptions - The SortOptions type. +// +// Return value: +// An Array of sorted elements. +// +// Example: +// +// options := api.NewSortOptions().SetByPattern("weight_*").SetIsAlpha(false).AddGetPattern("object_*").AddGetPattern("#") +// result, err := client.SortReadOnly("key", options) +// result.Value(): [{Object_3 false} {c false} {Object_1 false} {a false} {Object_2 false} {b false}] +// result.IsNil(): false +// +// [valkey.io]: https://valkey.io/commands/sort/ func (client *baseClient) SortReadOnlyWithOptions(key string, options *options.SortOptions) ([]Result[string], error) { optionArgs := options.ToArgs() result, err := client.executeCommand(C.SortReadOnly, append([]string{key}, optionArgs...)) @@ -3042,6 +6023,35 @@ func (client *baseClient) SortReadOnlyWithOptions(key string, options *options.S return handleStringOrNilArrayResponse(result) } +// Sorts the elements in the list, set, or sorted set at key and stores the result in +// destination. The sort command can be used to sort elements based on +// different criteria, apply transformations on sorted elements, and store the result in a new key. +// The sort command can be used to sort elements based on different criteria and apply +// transformations on sorted elements. +// To get the sort result without storing it into a key, see the sort or sortReadOnly function. +// +// Note: +// +// In cluster mode, if `key` and `destination` 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. +// +// Parameters: +// key - The key of the list, set, or sorted set to be sorted. +// destination - The key where the sorted result will be stored. +// +// Return value: +// The number of elements in the sorted key stored at destination. +// +// Example: +// +// result, err := client.SortStore("key","destkey") +// result: 1 +// +// [valkey.io]: https://valkey.io/commands/sort/ func (client *baseClient) SortStore(key string, destination string) (int64, error) { result, err := client.executeCommand(C.Sort, []string{key, "STORE", destination}) if err != nil { @@ -3050,6 +6060,39 @@ func (client *baseClient) SortStore(key string, destination string) (int64, erro return handleIntResponse(result) } +// Sorts the elements in the list, set, or sorted set at key and stores the result in +// destination. The sort command can be used to sort elements based on +// different criteria, apply transformations on sorted elements, and store the result in a new key. +// The sort command can be used to sort elements based on different criteria and apply +// transformations on sorted elements. +// To get the sort result without storing it into a key, see the sort or sortReadOnly function. +// +// Note: +// +// In cluster mode, if `key` and `destination` 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. +// The use of SortOptions.byPattern and SortOptions.getPatterns +// in cluster mode is supported since Valkey version 8.0. +// +// Parameters: +// key - The key of the list, set, or sorted set to be sorted. +// destination - The key where the sorted result will be stored. +// sortOptions - The SortOptions type. +// +// Return value: +// The number of elements in the sorted key stored at destination. +// +// Example: +// +// options := api.NewSortOptions().SetByPattern("weight_*").SetIsAlpha(false).AddGetPattern("object_*").AddGetPattern("#") +// result, err := client.SortStore("key","destkey",options) +// result: 1 +// +// [valkey.io]: https://valkey.io/commands/sort/ func (client *baseClient) SortStoreWithOptions( key string, destination string, @@ -3080,7 +6123,7 @@ func (client *baseClient) SortStoreWithOptions( // // Example: // -// //Creates the consumer "myconsumer" in consumer group "mygroup" +// // Creates the consumer "myconsumer" in consumer group "mygroup" // success, err := client.xgroupCreateConsumer("mystream", "mygroup", "myconsumer") // if err == nil && success { // fmt.Println("Consumer created") diff --git a/go/api/connection_management_commands.go b/go/api/connection_management_commands.go index f9d4a1dada..480b85af91 100644 --- a/go/api/connection_management_commands.go +++ b/go/api/connection_management_commands.go @@ -8,47 +8,9 @@ package api // // [valkey.io]: https://valkey.io/commands/#connection type ConnectionManagementCommands interface { - // Pings the server. - // - // Return value: - // Returns "PONG". - // - // For example: - // result, err := client.Ping() - // - // [valkey.io]: https://valkey.io/commands/ping/ Ping() (string, error) - // Pings the server with a custom message. - // - // Parameters: - // message - A message to include in the `PING` command. - // - // Return value: - // Returns the copy of message. - // - // For example: - // result, err := client.PingWithMessage("Hello") - // - // [valkey.io]: https://valkey.io/commands/ping/ PingWithMessage(message string) (string, error) - // Echo the provided message back. - // The command will be routed a random node. - // - // Parameters: - // message - The provided message. - // - // Return value: - // The provided message - // - // For example: - // result, err := client.Echo("Hello World") - // if err != nil { - // // handle error - // } - // fmt.Println(result.Value()) // Output: Hello World - // - // [valkey.io]: https://valkey.io/commands/echo/ Echo(message string) (Result[string], error) } diff --git a/go/api/generic_base_commands.go b/go/api/generic_base_commands.go index 1454063040..ca72d8e397 100644 --- a/go/api/generic_base_commands.go +++ b/go/api/generic_base_commands.go @@ -10,524 +10,52 @@ import "github.com/valkey-io/valkey-glide/go/glide/api/options" // // [valkey.io]: https://valkey.io/commands/?group=Generic type GenericBaseCommands interface { - // Del removes the specified keys from the database. A key is ignored if it does not exist. - // - // Note: - // 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. - // - // Parameters: - // keys - One or more keys to delete. - // - // Return value: - // Returns the number of keys that were removed. - // - // Example: - // result, err := client.Del([]string{"key1", "key2", "key3"}) - // if err != nil { - // // handle error - // } - // fmt.Println(result) // Output: 2 - // - // [valkey.io]: https://valkey.io/commands/del/ Del(keys []string) (int64, error) - // Exists returns the number of keys that exist in the database - // - // Note: - // 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. - // - // Parameters: - // keys - One or more keys to check if they exist. - // - // Return value: - // Returns the number of existing keys. - // - // Example: - // result, err := client.Exists([]string{"key1", "key2", "key3"}) - // result: 2 - // - // [valkey.io]: https://valkey.io/commands/exists/ Exists(keys []string) (int64, error) - // Expire sets a timeout on key. After the timeout has expired, the key will automatically be deleted - // - // If key already has an existing expire set, the time to live is updated to the new value. - // If seconds is a non-positive number, the key will be deleted rather than expired. - // The timeout will only be cleared by commands that delete or overwrite the contents of key - // - // Parameters: - // key - The key to expire. - // seconds - Time in seconds for the key to expire - // - // Return value: - // `true` if the timeout was set. `false` if the timeout was not set. e.g. key doesn't exist, - // or operation skipped due to the provided arguments. - // - // Example: - // result, err := client.Expire("key", 1) - // result: true - // - // [valkey.io]: https://valkey.io/commands/expire/ Expire(key string, seconds int64) (bool, error) - // Expire sets a timeout on key. After the timeout has expired, the key will automatically be deleted - // - // If key already has an existing expire set, the time to live is updated to the new value. - // If seconds is a non-positive number, the key will be deleted rather than expired. - // The timeout will only be cleared by commands that delete or overwrite the contents of key - // - // Parameters: - // key - The key to expire. - // seconds - Time in seconds for the key to expire - // option - The option to set expiry - NX, XX, GT, LT - // - // Return value: - // `true` if the timeout was set. `false` if the timeout was not set. e.g. key doesn't exist, - // or operation skipped due to the provided arguments. - // - // Example: - // result, err := client.Expire("key", 1, api.OnlyIfDoesNotExist) - // result: true - // - // [valkey.io]: https://valkey.io/commands/expire/ ExpireWithOptions(key string, seconds int64, expireCondition ExpireCondition) (bool, error) - // ExpireAt sets a timeout on key. It takes an absolute Unix timestamp (seconds since January 1, 1970) instead of - // specifying the number of seconds. A timestamp in the past will delete the key immediately. After the timeout has - // expired, the key will automatically be deleted. - // If key already has an existing expire set, the time to live is updated to the new value. - // The timeout will only be cleared by commands that delete or overwrite the contents of key - // If key already has an existing expire set, the time to live is updated to the new value. - // If seconds is a non-positive number, the key will be deleted rather than expired. - // The timeout will only be cleared by commands that delete or overwrite the contents of key - // - // Parameters: - // key - The key to expire. - // unixTimestampInSeconds - Absolute Unix timestamp - // - // Return value: - // `true` if the timeout was set. `false` if the timeout was not set. e.g. key doesn't exist, - // or operation skipped due to the provided arguments. - // - // Example: - // result, err := client.ExpireAt("key", time.Now().Unix()) - // result: true - // - // [valkey.io]: https://valkey.io/commands/expireat/ ExpireAt(key string, unixTimestampInSeconds int64) (bool, error) - // ExpireAt sets a timeout on key. It takes an absolute Unix timestamp (seconds since January 1, 1970) instead of - // specifying the number of seconds. A timestamp in the past will delete the key immediately. After the timeout has - // expired, the key will automatically be deleted. - // If key already has an existing expire set, the time to live is updated to the new value. - // The timeout will only be cleared by commands that delete or overwrite the contents of key - // If key already has an existing expire set, the time to live is updated to the new value. - // If seconds is a non-positive number, the key will be deleted rather than expired. - // The timeout will only be cleared by commands that delete or overwrite the contents of key - // - // Parameters: - // key - The key to expire. - // unixTimestampInSeconds - Absolute Unix timestamp - // option - The option to set expiry - NX, XX, GT, LT - // - // Return value: - // `true` if the timeout was set. `false` if the timeout was not set. e.g. key doesn't exist, - // or operation skipped due to the provided arguments. - // - // Example: - // result, err := client.ExpireAt("key", time.Now().Unix(), api.OnlyIfDoesNotExist) - // result: true - // - // [valkey.io]: https://valkey.io/commands/expireat/ ExpireAtWithOptions(key string, unixTimestampInSeconds int64, expireCondition ExpireCondition) (bool, error) - // Sets a timeout on key in milliseconds. After the timeout has expired, the key will automatically be deleted. - // If key already has an existing expire set, the time to live is updated to the new value. - // If milliseconds is a non-positive number, the key will be deleted rather than expired - // The timeout will only be cleared by commands that delete or overwrite the contents of key. - - // Parameters: - // key - The key to set timeout on it. - // milliseconds - The timeout in milliseconds. - // - // Return value: - // `true` if the timeout was set. `false` if the timeout was not set. e.g. key doesn't exist, - // or operation skipped due to the provided arguments. - // - // Example: - // result, err := client.PExpire("key", int64(5 * 1000)) - // result: true - // - // [valkey.io]: https://valkey.io/commands/pexpire/ PExpire(key string, milliseconds int64) (bool, error) - // Sets a timeout on key in milliseconds. After the timeout has expired, the key will automatically be deleted. - // If key already has an existing expire set, the time to live is updated to the new value. - // If milliseconds is a non-positive number, the key will be deleted rather than expired - // The timeout will only be cleared by commands that delete or overwrite the contents of key. - // - // Parameters: - // key - The key to set timeout on it. - // milliseconds - The timeout in milliseconds. - // option - The option to set expiry - NX, XX, GT, LT - // - // Return value: - // `true` if the timeout was set. `false` if the timeout was not set. e.g. key doesn't exist, - // or operation skipped due to the provided arguments. - // - // Example: - // result, err := client.PExpire("key", int64(5 * 1000), api.OnlyIfDoesNotExist) - // result: true - // - // [valkey.io]: https://valkey.io/commands/pexpire/ PExpireWithOptions(key string, milliseconds int64, expireCondition ExpireCondition) (bool, error) - // Sets a timeout on key. It takes an absolute Unix timestamp (milliseconds since - // January 1, 1970) instead of specifying the number of milliseconds. - // A timestamp in the past will delete the key immediately. After the timeout has - // expired, the key will automatically be deleted - // If key already has an existing expire set, the time to live is - // updated to the new value/ - // The timeout will only be cleared by commands that delete or overwrite the contents of key - // - // Parameters: - // key - The key to set timeout on it. - // unixMilliseconds - The timeout in an absolute Unix timestamp. - // - // Return value: - // `true` if the timeout was set. `false` if the timeout was not set. e.g. key doesn't exist, - // or operation skipped due to the provided arguments. - // - // Example: - // result, err := client.PExpire("key", time.Now().Unix()*1000) - // result: true - // - // [valkey.io]: https://valkey.io/commands/pexpireat/ PExpireAt(key string, unixTimestampInMilliSeconds int64) (bool, error) - // Sets a timeout on key. It takes an absolute Unix timestamp (milliseconds since - // January 1, 1970) instead of specifying the number of milliseconds. - // A timestamp in the past will delete the key immediately. After the timeout has - // expired, the key will automatically be deleted - // If key already has an existing expire set, the time to live is - // updated to the new value/ - // The timeout will only be cleared by commands that delete or overwrite the contents of key - // - // Parameters: - // key - The key to set timeout on it. - // unixMilliseconds - The timeout in an absolute Unix timestamp. - // option - The option to set expiry - NX, XX, GT, LT - // - // Return value: - // `true` if the timeout was set. `false` if the timeout was not set. e.g. key doesn't exist, - // or operation skipped due to the provided arguments. - // - // Example: - // result, err := client.PExpire("key", time.Now().Unix()*1000, api.OnlyIfDoesNotExist) - // result: true - // - // [valkey.io]: https://valkey.io/commands/pexpireat/ PExpireAtWithOptions(key string, unixTimestampInMilliSeconds int64, expireCondition ExpireCondition) (bool, error) - // Expire Time returns the absolute Unix timestamp (since January 1, 1970) at which the given key - // will expire, in seconds. - // - // Parameters: - // key - The key to determine the expiration value of. - // - // Return value: - // The expiration Unix timestamp in seconds. - // `-2` if key does not exist or `-1` is key exists but has no associated expiration. - // - // Example: - // - // result, err := client.ExpireTime("key") - // result: 1732118030 - // - // [valkey.io]: https://valkey.io/commands/expiretime/ ExpireTime(key string) (int64, error) - // PExpire Time returns the absolute Unix timestamp (since January 1, 1970) at which the given key - // will expire, in milliseconds. - // - // Parameters: - // key - The key to determine the expiration value of. - // - // Return value: - // The expiration Unix timestamp in milliseconds. - // `-2` if key does not exist or `-1` is key exists but has no associated expiration. - // - // Example: - // - // result, err := client.PExpireTime("key") - // result: 33177117420000 - // - // [valkey.io]: https://valkey.io/commands/pexpiretime/ PExpireTime(key string) (int64, error) - // TTL returns the remaining time to live of key that has a timeout, in seconds. - // - // Parameters: - // key - The key to return its timeout. - // - // Return value: - // Returns TTL in seconds, - // `-2` if key does not exist, or `-1` if key exists but has no associated expiration. - // - // Example: - // - // result, err := client.TTL("key") - // result: 3 - // - // [valkey.io]: https://valkey.io/commands/ttl/ TTL(key string) (int64, error) - // PTTL returns the remaining time to live of key that has a timeout, in milliseconds. - // - // Parameters: - // key - The key to return its timeout. - // - // Return value: - // Returns TTL in milliseconds, - // `-2` if key does not exist, or `-1` if key exists but has no associated expiration. - // - // Example: - // - // result, err := client.PTTL("key") - // result: 1000 - // - // [valkey.io]: https://valkey.io/commands/pttl/ PTTL(key string) (int64, error) - // Unlink (delete) multiple keys from the database. A key is ignored if it does not exist. - // This command, similar to Del However, this command does not block the server - // - // Note: - // 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. - // - // Parameters: - // keys - One or more keys to unlink. - // - // Return value: - // Return the number of keys that were unlinked. - // - // Example: - // result, err := client.Unlink([]string{"key1", "key2", "key3"}) - // if err != nil { - // // handle error - // } - // fmt.Println(result) // Output: 3 - // - // [valkey.io]: Https://valkey.io/commands/unlink/ Unlink(keys []string) (int64, error) - // Alters the last access time of a key(s). A key is ignored if it does not exist. - // - // Note: - // 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. - // - // Parameters: - // The keys to update last access time. - // - // Return value: - // The number of keys that were updated. - // - // Example: - // result, err := client.Touch([]string{"key1", "key2", "key3"}) - // if err != nil { - // // handle error - // } - // fmt.Println(result) // Output: 3 - // - // [valkey.io]: Https://valkey.io/commands/touch/ Touch(keys []string) (int64, error) - // Type returns the string representation of the type of the value stored at key. - // The different types that can be returned are: string, list, set, zset, hash and stream. - // - // Parameters: - // key - string - // - // Return value: - // If the key exists, the type of the stored value is returned. Otherwise, a "none" string is returned. - // - // Example: - // result, err := client.Type([]string{"key"}) - // if err != nil { - // // handle error - // } - // fmt.Println(result) // Output: string - // - // [valkey.io]: Https://valkey.io/commands/type/ Type(key string) (string, error) - // Renames key to new key. - // If new Key already exists it is overwritten. - // - // Note: - // When in cluster mode, both key and newKey must map to the same hash slot. - // - // Parameters: - // key to rename. - // newKey The new name of the key. - // - // Return value: - // If the key was successfully renamed, return "OK". If key does not exist, an error is thrown. - // - // Example: - // result, err := client.Rename([]string{"key", "newkey"}) - // if err != nil { - // // handle error - // } - // fmt.Println(result) // Output: OK - // - // [valkey.io]: https://valkey.io/commands/rename/ Rename(key string, newKey string) (string, error) - // Renames key to newkey if newKey does not yet exist. - // - // Note: - // When in cluster mode, both key and newkey must map to the same hash slot. - // - // Parameters: - // key to rename. - // newKey The new name of the key. - // - // Return value: - // `true` if k`ey was renamed to `newKey`, `false` if `newKey` already exists. - // - // Example: - // result, err := client.Renamenx([]string{"key", "newkey"}) - // if err != nil { - // // handle error - // } - // fmt.Println(result) // Output: true - // - // [valkey.io]: https://valkey.io/commands/renamenx/ Renamenx(key string, newKey string) (bool, error) - // Removes the existing timeout on key, turning the key from volatile - // (a key with an expire set) to persistent (a key that will never expire as no timeout is associated). - // - // Parameters: - // key - The key to remove the existing timeout on. - // - // Return value: - // `false` if key does not exist or does not have an associated timeout, `true` if the timeout has been removed. - // - // Example: - // result, err := client.Persist([]string{"key"}) - // if err != nil { - // // handle error - // } - // fmt.Println(result) // Output: true - // - // [valkey.io]: https://valkey.io/commands/persist/ Persist(key string) (bool, error) - // Create a key associated with a value that is obtained by - // deserializing the provided serialized value (obtained via [valkey.io]: Https://valkey.io/commands/dump/). - // - // Parameters: - // key - The key to create. - // ttl - The expiry time (in milliseconds). If 0, the key will persist. - // value - The serialized value to deserialize and assign to key. - // - // Return value: - // Return OK if successfully create a key with a value . - // - // Example: - // result, err := client.Restore("key",ttl, value) - // if err != nil { - // // handle error - // } - // fmt.Println(result.Value()) // Output: OK - // - // [valkey.io]: https://valkey.io/commands/restore/ Restore(key string, ttl int64, value string) (Result[string], error) - // Create a key associated with a value that is obtained by - // deserializing the provided serialized value (obtained via [valkey.io]: Https://valkey.io/commands/dump/). - // - // Parameters: - // key - The key to create. - // ttl - The expiry time (in milliseconds). If 0, the key will persist. - // value - The serialized value to deserialize and assign to key. - // restoreOptions - Set restore options with replace and absolute TTL modifiers, object idletime and frequency - // - // Return value: - // Return OK if successfully create a key with a value. - // - // Example: - // restoreOptions := api.NewRestoreOptionsBuilder().SetReplace().SetABSTTL().SetEviction(api.FREQ, 10) - // resultRestoreOpt, err := client.RestoreWithOptions(key, ttl, value, restoreOptions) - // if err != nil { - // // handle error - // } - // fmt.Println(result.Value()) // Output: OK - // - // [valkey.io]: https://valkey.io/commands/restore/ RestoreWithOptions(key string, ttl int64, value string, option *RestoreOptions) (Result[string], error) - // Returns the internal encoding for the Valkey object stored at key. - // - // Note: - // When in cluster mode, both key and newkey must map to the same hash slot. - // - // Parameters: - // The key of the object to get the internal encoding of. - // - // Return value: - // If key exists, returns the internal encoding of the object stored at - // key as a String. Otherwise, returns null. - // - // Example: - // result, err := client.ObjectEncoding("mykeyRenamenx") - // if err != nil { - // // handle error - // } - // fmt.Println(result.Value()) // Output: embstr - // - // [valkey.io]: https://valkey.io/commands/object-encoding/ ObjectEncoding(key string) (Result[string], error) - // Serialize the value stored at key in a Valkey-specific format and return it to the user. - // - // Parameters: - // The key to serialize. - // - // Return value: - // The serialized value of the data stored at key - // If key does not exist, null will be returned. - // - // Example: - // result, err := client.Dump([]string{"key"}) - // if err != nil { - // // handle error - // } - // fmt.Println(result.Value()) // Output: (Serialized Value) - // - // [valkey.io]: https://valkey.io/commands/dump/ Dump(key string) (Result[string], error) ObjectFreq(key string) (Result[int64], error) @@ -536,172 +64,16 @@ type GenericBaseCommands interface { ObjectRefCount(key string) (Result[int64], error) - // Sorts the elements in the list, set, or sorted set at key and returns the result. - // The sort command can be used to sort elements based on different criteria and apply - // transformations on sorted elements. - // To store the result into a new key, see the sortStore function. - // - // Parameters: - // key - The key of the list, set, or sorted set to be sorted. - // - // Return value: - // An Array of sorted elements. - // - // Example: - // - // result, err := client.Sort("key") - // result.Value(): [{1 false} {2 false} {3 false}] - // result.IsNil(): false - // - // [valkey.io]: https://valkey.io/commands/sort/ Sort(key string) ([]Result[string], error) - // Sorts the elements in the list, set, or sorted set at key and returns the result. - // The sort command can be used to sort elements based on different criteria and apply - // transformations on sorted elements. - // To store the result into a new key, see the sortStore function. - // - // Note: - // In cluster mode, if `key` 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. - // The use of SortOptions.byPattern and SortOptions.getPatterns in cluster mode is - // supported since Valkey version 8.0. - // - // Parameters: - // key - The key of the list, set, or sorted set to be sorted. - // sortOptions - The SortOptions type. - // - // Return value: - // An Array of sorted elements. - // - // Example: - // - // options := api.NewSortOptions().SetByPattern("weight_*").SetIsAlpha(false).AddGetPattern("object_*").AddGetPattern("#") - // result, err := client.Sort("key", options) - // result.Value(): [{Object_3 false} {c false} {Object_1 false} {a false} {Object_2 false} {b false}] - // result.IsNil(): false - // - // [valkey.io]: https://valkey.io/commands/sort/ SortWithOptions(key string, sortOptions *options.SortOptions) ([]Result[string], error) - // Sorts the elements in the list, set, or sorted set at key and stores the result in - // destination. The sort command can be used to sort elements based on - // different criteria, apply transformations on sorted elements, and store the result in a new key. - // The sort command can be used to sort elements based on different criteria and apply - // transformations on sorted elements. - // To get the sort result without storing it into a key, see the sort or sortReadOnly function. - // - // Note: - // In cluster mode, if `key` and `destination` 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. - // - // Parameters: - // key - The key of the list, set, or sorted set to be sorted. - // destination - The key where the sorted result will be stored. - // - // Return value: - // The number of elements in the sorted key stored at destination. - // - // Example: - // - // result, err := client.SortStore("key","destkey") - // result: 1 - // - // [valkey.io]: https://valkey.io/commands/sort/ SortStore(key string, destination string) (int64, error) - // Sorts the elements in the list, set, or sorted set at key and stores the result in - // destination. The sort command can be used to sort elements based on - // different criteria, apply transformations on sorted elements, and store the result in a new key. - // The sort command can be used to sort elements based on different criteria and apply - // transformations on sorted elements. - // To get the sort result without storing it into a key, see the sort or sortReadOnly function. - // - // Note: - // In cluster mode, if `key` and `destination` 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. - // The use of SortOptions.byPattern and SortOptions.getPatterns - // in cluster mode is supported since Valkey version 8.0. - // - // Parameters: - // key - The key of the list, set, or sorted set to be sorted. - // destination - The key where the sorted result will be stored. - // sortOptions - The SortOptions type. - // - // Return value: - // The number of elements in the sorted key stored at destination. - // - // Example: - // - // options := api.NewSortOptions().SetByPattern("weight_*").SetIsAlpha(false).AddGetPattern("object_*").AddGetPattern("#") - // result, err := client.SortStore("key","destkey",options) - // result: 1 - // - // [valkey.io]: https://valkey.io/commands/sort/ SortStoreWithOptions(key string, destination string, sortOptions *options.SortOptions) (int64, error) - // Sorts the elements in the list, set, or sorted set at key and returns the result. - // The sortReadOnly command can be used to sort elements based on different criteria and apply - // transformations on sorted elements. - // This command is routed depending on the client's ReadFrom strategy. - // - // Parameters: - // key - The key of the list, set, or sorted set to be sorted. - // - // Return value: - // An Array of sorted elements. - // - // Example: - // - // result, err := client.SortReadOnly("key") - // result.Value(): [{1 false} {2 false} {3 false}] - // result.IsNil(): false - // - // [valkey.io]: https://valkey.io/commands/sort/ SortReadOnly(key string) ([]Result[string], error) - // Sorts the elements in the list, set, or sorted set at key and returns the result. - // The sort command can be used to sort elements based on different criteria and apply - // transformations on sorted elements. - // This command is routed depending on the client's ReadFrom strategy. - // - // Note: - // In cluster mode, if `key` 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. - // The use of SortOptions.byPattern and SortOptions.getPatterns in cluster mode is - // supported since Valkey version 8.0. - // - // Parameters: - // key - The key of the list, set, or sorted set to be sorted. - // sortOptions - The SortOptions type. - // - // Return value: - // An Array of sorted elements. - // - // Example: - // - // options := api.NewSortOptions().SetByPattern("weight_*").SetIsAlpha(false).AddGetPattern("object_*").AddGetPattern("#") - // result, err := client.SortReadOnly("key", options) - // result.Value(): [{Object_3 false} {c false} {Object_1 false} {a false} {Object_2 false} {b false}] - // result.IsNil(): false - // - // [valkey.io]: https://valkey.io/commands/sort/ SortReadOnlyWithOptions(key string, sortOptions *options.SortOptions) ([]Result[string], error) Wait(numberOfReplicas int64, timeout int64) (int64, error) diff --git a/go/api/generic_cluster_commands.go b/go/api/generic_cluster_commands.go index cd46fca42b..3d5186caa3 100644 --- a/go/api/generic_cluster_commands.go +++ b/go/api/generic_cluster_commands.go @@ -8,30 +8,5 @@ package api // // [valkey.io]: https://valkey.io/commands/#generic type GenericClusterCommands interface { - // CustomCommand executes a single command, specified by args, without checking inputs. Every part of the command, - // including the command name and subcommands, should be added as a separate value in args. The returning value depends on - // the executed - // command. - // - // The command will be routed automatically based on the passed command's default request policy. - // - // See [Valkey GLIDE Wiki] for details on the restrictions and limitations of the custom command API. - // - // This function should only be used for single-response commands. Commands that don't return complete response and awaits - // (such as SUBSCRIBE), or that return potentially more than a single response (such as XREAD), or that change the client's - // behavior (such as entering pub/sub mode on RESP2 connections) shouldn't be called using this function. - // - // Parameters: - // args - Arguments for the custom command including the command name. - // - // Return value: - // The returned value for the custom command. - // - // For example: - // - // result, err := client.CustomCommand([]string{"ping"}) - // result.Value().(string): "PONG" - // - // [Valkey GLIDE Wiki]: https://github.com/valkey-io/valkey-glide/wiki/General-Concepts#custom-command CustomCommand(args []string) (ClusterValue[interface{}], error) } diff --git a/go/api/generic_commands.go b/go/api/generic_commands.go index 5da3b5e5ce..7443c13bcc 100644 --- a/go/api/generic_commands.go +++ b/go/api/generic_commands.go @@ -8,27 +8,5 @@ package api // // [valkey.io]: https://valkey.io/commands/#generic type GenericCommands interface { - // CustomCommand executes a single command, specified by args, without checking inputs. Every part of the command, - // including the command name and subcommands, should be added as a separate value in args. The returning value depends on - // the executed - // command. - // - // See [Valkey GLIDE Wiki] for details on the restrictions and limitations of the custom command API. - // - // This function should only be used for single-response commands. Commands that don't return complete response and awaits - // (such as SUBSCRIBE), or that return potentially more than a single response (such as XREAD), or that change the client's - // behavior (such as entering pub/sub mode on RESP2 connections) shouldn't be called using this function. - // - // Parameters: - // args - Arguments for the custom command including the command name. - // - // Return value: - // The returned value for the custom command. - // - // For example: - // result, err := client.CustomCommand([]string{"ping"}) - // result.(string): "PONG" - // - // [Valkey GLIDE Wiki]: https://github.com/valkey-io/valkey-glide/wiki/General-Concepts#custom-command CustomCommand(args []string) (interface{}, error) } diff --git a/go/api/glide_client.go b/go/api/glide_client.go index 51ea9ef4b4..60fe085cc7 100644 --- a/go/api/glide_client.go +++ b/go/api/glide_client.go @@ -11,31 +11,56 @@ import ( ) // GlideClient interface compliance check. -var _ GlideClient = (*glideClient)(nil) +var _ GlideClientCommands = (*GlideClient)(nil) -// GlideClient is a client used for connection in Standalone mode. -type GlideClient interface { +// GlideClientCommands is a client used for connection in Standalone mode. +type GlideClientCommands interface { BaseClient GenericCommands ServerManagementCommands } -// glideClient implements standalone mode operations by extending baseClient functionality. -type glideClient struct { +// GlideClient implements standalone mode operations by extending baseClient functionality. +type GlideClient struct { *baseClient } -// NewGlideClient creates a [GlideClient] in standalone mode using the given [GlideClientConfiguration]. -func NewGlideClient(config *GlideClientConfiguration) (GlideClient, error) { +// NewGlideClient creates a [GlideClientCommands] in standalone mode using the given [GlideClientConfiguration]. +func NewGlideClient(config *GlideClientConfiguration) (GlideClientCommands, error) { client, err := createClient(config) if err != nil { return nil, err } - return &glideClient{client}, nil + return &GlideClient{client}, nil } -func (client *glideClient) CustomCommand(args []string) (interface{}, error) { +// CustomCommand executes a single command, specified by args, without checking inputs. Every part of the command, +// including the command name and subcommands, should be added as a separate value in args. The returning value depends on +// the executed +// command. +// +// See [Valkey GLIDE Wiki] for details on the restrictions and limitations of the custom command API. +// +// This function should only be used for single-response commands. Commands that don't return complete response and awaits +// (such as SUBSCRIBE), or that return potentially more than a single response (such as XREAD), or that change the client's +// behavior (such as entering pub/sub mode on RESP2 connections) shouldn't be called using this function. +// +// Parameters: +// +// args - Arguments for the custom command including the command name. +// +// Return value: +// +// The returned value for the custom command. +// +// For example: +// +// result, err := client.CustomCommand([]string{"ping"}) +// result.(string): "PONG" +// +// [Valkey GLIDE Wiki]: https://github.com/valkey-io/valkey-glide/wiki/General-Concepts#custom-command +func (client *GlideClient) CustomCommand(args []string) (interface{}, error) { res, err := client.executeCommand(C.CustomCommand, args) if err != nil { return nil, err @@ -43,7 +68,27 @@ func (client *glideClient) CustomCommand(args []string) (interface{}, error) { return handleInterfaceResponse(res) } -func (client *glideClient) ConfigSet(parameters map[string]string) (string, error) { +// Sets configuration parameters to the specified values. +// +// Note: Prior to Version 7.0.0, only one parameter can be send. +// +// See [valkey.io] for details. +// +// Parameters: +// +// parameters - A map consisting of configuration parameters and their respective values to set. +// +// Return value: +// +// `"OK"` if all configurations have been successfully set. Otherwise, raises an error. +// +// For example: +// +// result, err := client.ConfigSet(map[string]string{"timeout": "1000", "maxmemory": "1GB"}) +// result: "OK" +// +// [valkey.io]: https://valkey.io/commands/config-set/ +func (client *GlideClient) ConfigSet(parameters map[string]string) (string, error) { result, err := client.executeCommand(C.ConfigSet, utils.MapToString(parameters)) if err != nil { return "", err @@ -51,7 +96,28 @@ func (client *glideClient) ConfigSet(parameters map[string]string) (string, erro return handleStringResponse(result) } -func (client *glideClient) ConfigGet(args []string) (map[string]string, error) { +// Gets the values of configuration parameters. +// +// Note: Prior to Version 7.0.0, only one parameter can be send. +// +// See [valkey.io] for details. +// +// Parameters: +// +// args - A slice of configuration parameter names to retrieve values for. +// +// Return value: +// +// A map of api.Result[string] corresponding to the configuration parameters. +// +// For example: +// +// result, err := client.ConfigGet([]string{"timeout" , "maxmemory"}) +// // result["timeout"] = "1000" +// // result["maxmemory"] = "1GB" +// +// [valkey.io]: https://valkey.io/commands/config-get/ +func (client *GlideClient) ConfigGet(args []string) (map[string]string, error) { res, err := client.executeCommand(C.ConfigGet, args) if err != nil { return nil, err @@ -59,7 +125,23 @@ func (client *glideClient) ConfigGet(args []string) (map[string]string, error) { return handleStringToStringMapResponse(res) } -func (client *glideClient) Select(index int64) (string, error) { +// Select changes the currently selected database. +// +// Parameters: +// +// index - The index of the database to select. +// +// Return value: +// +// A simple `"OK"` response. +// +// Example: +// +// result, err := client.Select(2) +// result: "OK" +// +// [valkey.io]: https://valkey.io/commands/select/ +func (client *GlideClient) Select(index int64) (string, error) { result, err := client.executeCommand(C.Select, []string{utils.IntToString(index)}) if err != nil { return "", err diff --git a/go/api/glide_cluster_client.go b/go/api/glide_cluster_client.go index cc672a91b5..2fba684d8c 100644 --- a/go/api/glide_cluster_client.go +++ b/go/api/glide_cluster_client.go @@ -7,30 +7,58 @@ package api import "C" // GlideClusterClient interface compliance check. -var _ GlideClusterClient = (*glideClusterClient)(nil) +var _ GlideClusterClientCommands = (*GlideClusterClient)(nil) -// GlideClusterClient is a client used for connection in cluster mode. -type GlideClusterClient interface { +// GlideClusterClientCommands is a client used for connection in cluster mode. +type GlideClusterClientCommands interface { BaseClient GenericClusterCommands } -// glideClusterClient implements cluster mode operations by extending baseClient functionality. -type glideClusterClient struct { +// GlideClusterClient implements cluster mode operations by extending baseClient functionality. +type GlideClusterClient struct { *baseClient } -// NewGlideClusterClient creates a [GlideClusterClient] in cluster mode using the given [GlideClusterClientConfiguration]. -func NewGlideClusterClient(config *GlideClusterClientConfiguration) (GlideClusterClient, error) { +// NewGlideClusterClient creates a [GlideClusterClientCommands] in cluster mode using the given +// [GlideClusterClientConfiguration]. +func NewGlideClusterClient(config *GlideClusterClientConfiguration) (GlideClusterClientCommands, error) { client, err := createClient(config) if err != nil { return nil, err } - return &glideClusterClient{client}, nil + return &GlideClusterClient{client}, nil } -func (client *glideClusterClient) CustomCommand(args []string) (ClusterValue[interface{}], error) { +// CustomCommand executes a single command, specified by args, without checking inputs. Every part of the command, +// including the command name and subcommands, should be added as a separate value in args. The returning value depends on +// the executed +// command. +// +// The command will be routed automatically based on the passed command's default request policy. +// +// See [Valkey GLIDE Wiki] for details on the restrictions and limitations of the custom command API. +// +// This function should only be used for single-response commands. Commands that don't return complete response and awaits +// (such as SUBSCRIBE), or that return potentially more than a single response (such as XREAD), or that change the client's +// behavior (such as entering pub/sub mode on RESP2 connections) shouldn't be called using this function. +// +// Parameters: +// +// args - Arguments for the custom command including the command name. +// +// Return value: +// +// The returned value for the custom command. +// +// For example: +// +// result, err := client.CustomCommand([]string{"ping"}) +// result.Value().(string): "PONG" +// +// [Valkey GLIDE Wiki]: https://github.com/valkey-io/valkey-glide/wiki/General-Concepts#custom-command +func (client *GlideClusterClient) CustomCommand(args []string) (ClusterValue[interface{}], error) { res, err := client.executeCommand(C.CustomCommand, args) if err != nil { return CreateEmptyClusterValue(), err diff --git a/go/api/hash_commands.go b/go/api/hash_commands.go index 0d1eecac6e..30ae6a3772 100644 --- a/go/api/hash_commands.go +++ b/go/api/hash_commands.go @@ -10,275 +10,30 @@ import "github.com/valkey-io/valkey-glide/go/glide/api/options" // // [valkey.io]: https://valkey.io/commands/#hash type HashCommands interface { - // HGet returns the value associated with field in the hash stored at key. - // - // See [valkey.io] for details. - // - // Parameters: - // key - The key of the hash. - // field - The field in the hash stored at key to retrieve from the database. - // - // Return value: - // The Result[string] associated with field, or [api.NilResult[string]](api.CreateNilStringResult()) when field is not - // present in the hash or key does not exist. - // - // For example: - // Assume we have the following hash: - // my_hash := map[string]string{"field1": "value", "field2": "another_value"} - // payload, err := client.HGet("my_hash", "field1") - // // payload.Value(): "value" - // // payload.IsNil(): false - // payload, err = client.HGet("my_hash", "nonexistent_field") - // // payload equals api.CreateNilStringResult() - // - // [valkey.io]: https://valkey.io/commands/hget/ HGet(key string, field string) (Result[string], error) - // HGetAll returns all fields and values of the hash stored at key. - // - // See [valkey.io] for details. - // - // Parameters: - // key - The key of the hash. - // - // Return value: - // A map of all fields and their values as Result[string] in the hash, or an empty map when key does not exist. - // - // For example: - // fieldValueMap, err := client.HGetAll("my_hash") - // // fieldValueMap equals map[string]string{field1: value1, field2: value2} - // - // [valkey.io]: https://valkey.io/commands/hgetall/ HGetAll(key string) (map[string]string, error) - // HMGet returns the values associated with the specified fields in the hash stored at key. - // - // See [valkey.io] for details. - // - // Parameters: - // key - The key of the hash. - // fields - The fields in the hash stored at key to retrieve from the database. - // - // Return value: - // An array of Result[string]s associated with the given fields, in the same order as they are requested. - // For every field that does not exist in the hash, a [api.NilResult[string]](api.CreateNilStringResult()) is - // returned. - // If key does not exist, returns an empty string array. - // - // For example: - // values, err := client.HMGet("my_hash", []string{"field1", "field2"}) - // // value1 equals api.CreateStringResult("value1") - // // value2 equals api.CreateStringResult("value2") - // // values equals []api.Result[string]{value1, value2} - // - // [valkey.io]: https://valkey.io/commands/hmget/ HMGet(key string, fields []string) ([]Result[string], error) - // HSet sets the specified fields to their respective values in the hash stored at key. - // This command overwrites the values of specified fields that exist in the hash. - // If key doesn't exist, a new key holding a hash is created. - // - // See [valkey.io] for details. - // - // Parameters: - // key - The key of the hash. - // values - A map of field-value pairs to set in the hash. - // - // Return value: - // The number of fields that were added or updated. - // - // For example: - // num, err := client.HSet("my_hash", map[string]string{"field": "value", "field2": "value2"}) - // // num: 2 - // - // [valkey.io]: https://valkey.io/commands/hset/ HSet(key string, values map[string]string) (int64, error) - // HSetNX 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 [valkey.io] for details. - // - // Parameters: - // key - The key of the hash. - // field - The field to set. - // value - The value to set. - // - // Return value: - // A bool containing true if field is a new field in the hash and value was set. - // false if field already exists in the hash and no operation was performed. - // - // For example: - // payload1, err := client.HSetNX("myHash", "field", "value") - // // payload1.Value(): true - // // payload1.IsNil(): false - // payload2, err := client.HSetNX("myHash", "field", "newValue") - // // payload2.Value(): false - // // payload2.IsNil(): false - // - // [valkey.io]: https://valkey.io/commands/hsetnx/ HSetNX(key string, field string, value string) (bool, error) - // HDel removes the specified fields from the hash stored at key. - // Specified fields that do not exist within this hash are ignored. - // If key does not exist, it is treated as an empty hash and this command returns 0. - // - // See [valkey.io] for details. - // - // Parameters: - // key - The key of the hash. - // fields - The fields to remove from the hash stored at key. - // - // Return value: - // The number of fields that were removed from the hash, not including specified but non-existing fields. - // - // For example: - // num, err := client.HDel("my_hash", []string{"field_1", "field_2"}) - // // num: 2 - // - // [valkey.io]: https://valkey.io/commands/hdel/ HDel(key string, fields []string) (int64, error) - // HLen returns the number of fields contained in the hash stored at key. - // - // See [valkey.io] for details. - // - // Parameters: - // key - The key of the hash. - // - // Return value: - // The number of fields in the hash, or `0` when key does not exist. - // If key holds a value that is not a hash, an error is returned. - // - // For example: - // num1, err := client.HLen("myHash") - // // num: 3 - // num2, err := client.HLen("nonExistingKey") - // // num: 0 - // - // [valkey.io]: https://valkey.io/commands/hlen/ HLen(key string) (int64, error) - // HVals returns all values in the hash stored at key. - // - // See [valkey.io] for details. - // - // Parameters: - // key - The key of the hash. - // - // Return value: - // A slice containing all the values in the hash, or an empty slice when key does not exist. - // - // For example: - // values, err := client.HVals("myHash") - // values: []string{"value1", "value2", "value3"} - // - // [valkey.io]: https://valkey.io/commands/hvals/ HVals(key string) ([]string, error) - // HExists returns if field is an existing field in the hash stored at key. - // - // See [valkey.io] for details. - // - // Parameters: - // key - The key of the hash. - // field - The field to check in the hash stored at key. - // - // Return value: - // A bool containing true if the hash contains the specified field. - // false if the hash does not contain the field, or if the key does not exist. - // - // For example: - // exists, err := client.HExists("my_hash", "field1") - // // exists.Value(): true - // // exists.IsNil(): false - // exists, err = client.HExists("my_hash", "non_existent_field") - // // exists.Value(): false - // // exists.IsNil(): false - // - // [valkey.io]: https://valkey.io/commands/hexists/ HExists(key string, field string) (bool, error) - // HKeys returns all field names in the hash stored at key. - // - // See [valkey.io] for details. - // - // Parameters: - // key - The key of the hash. - // - // Return value: - // A slice containing all the field names in the hash, or an empty slice when key does not exist. - // - // For example: - // names, err := client.HKeys("my_hash") - // names: []string{"field1", "field2"} - // - // [valkey.io]: https://valkey.io/commands/hkeys/ HKeys(key string) ([]string, error) - // HStrLen returns the string length of the value associated with field in the hash stored at key. - // If the key or the field do not exist, 0 is returned. - // - // See [valkey.io] for details. - // - // Parameters: - // key - The key of the hash. - // field - The field to get the string length of its value. - // - // Return value: - // The length of the string value associated with field, or `0` when field or key do not exist. - // - // For example: - // strlen, err := client.HStrLen("my_hash", "my_field") - // // strlen.Value(): 10 - // // strlen.IsNil(): false - // - // [valkey.io]: https://valkey.io/commands/hstrlen/ HStrLen(key string, field string) (int64, error) - // 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 [valkey.io] for details. - // - // Parameters: - // key - The key of the hash. - // field - The field in the hash stored at `key` to increment its value. - // increment - The amount to increment. - // - // Return value: - // The value of `field` in the hash stored at `key` after the increment. - // - // Example: - // _, err := client.HSet("key", map[string]string{"field": "10"}) - // hincrByResult, err := client.HIncrBy("key", "field", 1) - // // hincrByResult: 11 - // - // [valkey.io]: https://valkey.io/commands/hincrby/ HIncrBy(key string, field string, increment int64) (int64, error) - // Increments 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 [valkey.io] for details. - // - // Parameters: - // key - The key of the hash. - // field - The field in the hash stored at `key` to increment its value. - // increment - The amount to increment. - // - // Return value: - // The value of `field` in the hash stored at `key` after the increment. - // - // Example: - // _, err := client.HSet("key", map[string]string{"field": "10"}) - // hincrByFloatResult, err := client.HIncrByFloat("key", "field", 1.5) - // // hincrByFloatResult: 11.5 - // - // [valkey.io]: https://valkey.io/commands/hincrbyfloat/ HIncrByFloat(key string, field string, increment float64) (float64, error) HScan(key string, cursor string) (string, []string, error) diff --git a/go/api/hyperloglog_commands.go b/go/api/hyperloglog_commands.go index 196c397d7b..a09dcd7da2 100644 --- a/go/api/hyperloglog_commands.go +++ b/go/api/hyperloglog_commands.go @@ -8,48 +8,7 @@ package api // // [valkey.io]: https://valkey.io/commands/#hyperloglog type HyperLogLogCommands interface { - // PfAdd adds all elements to the HyperLogLog data structure stored at the specified key. - // Creates a new structure if the key does not exist. - // When no elements are provided, and key exists and is a HyperLogLog, then no operation is performed. - // If key does not exist, then the HyperLogLog structure is created. - // - // Parameters: - // key - The key of the HyperLogLog data structure to add elements into. - // elements - An array of members to add to the HyperLogLog stored at key. - // - // Return value: - // If the HyperLogLog is newly created, or if the HyperLogLog approximated cardinality is - // altered, then returns `1`. Otherwise, returns `0`. - // - // Example: - // result, err := client.PfAdd("key",[]string{"value1", "value2", "value3"}) - // result: 1 - // - // [valkey.io]: https://valkey.io/commands/pfadd/ PfAdd(key string, elements []string) (int64, error) - // Estimates the cardinality of the data stored in a HyperLogLog structure for a single key or - // calculates the combined cardinality of multiple keys by merging their HyperLogLogs temporarily. - // - // Note: - // 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. - // - // Parameters: - // key - The keys of the HyperLogLog data structures to be analyzed. - // - // Return value: - // The approximated cardinality of given HyperLogLog data structures. - // The cardinality of a key that does not exist is `0`. - // - // Example: - // result, err := client.PfCount([]string{"key1","key2"}) - // result: 5 - // - // [valkey.io]: https://valkey.io/commands/pfcount/ PfCount(keys []string) (int64, error) } diff --git a/go/api/list_commands.go b/go/api/list_commands.go index 1d2942e5ae..d1f688bb5c 100644 --- a/go/api/list_commands.go +++ b/go/api/list_commands.go @@ -8,578 +8,52 @@ package api // // [valkey.io]: https://valkey.io/commands/#list type ListCommands interface { - // 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 an empty - // list before performing the push operation. - // - // See [valkey.io] for details. - // - // Parameters: - // key - The key of the list. - // elements - The elements to insert at the head of the list stored at key. - // - // Return value: - // The length of the list after the push operation. - // - // For example: - // result, err := client.LPush("my_list", []string{"value1", "value2"}) - // result: 2 - // - // [valkey.io]: https://valkey.io/commands/lpush/ LPush(key string, elements []string) (int64, error) - // 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 [valkey.io] for details. - // - // Parameters: - // key - The key of the list. - // - // Return value: - // The Result[string] containing the value of the first element. - // If key does not exist, [api.CreateNilStringResult()] will be returned. - // - // For example: - // 1. result, err := client.LPush("my_list", []string{"value1", "value2"}) - // value, err := client.LPop("my_list") - // value.Value(): "value2" - // result.IsNil(): false - // 2. result, err := client.LPop("non_existent") - // result.Value(): "" - // result.IsNil(); true - // - // [valkey.io]: https://valkey.io/commands/lpop/ LPop(key string) (Result[string], error) - // Removes and returns up to count elements of the list stored at key, depending on the list's length. - // - // See [valkey.io] for details. - // - // Parameters: - // key - The key of the list. - // count - The count of the elements to pop from the list. - // - // Return value: - // An array of the popped elements as Result[string] will be returned depending on the list's length - // If key does not exist, nil will be returned. - // - // For example: - // 1. result, err := client.LPopCount("my_list", 2) - // result: []api.Result[string]{api.CreateStringResult("value1"), api.CreateStringResult("value2")} - // 2. result, err := client.LPopCount("non_existent") - // result: nil - // - // [valkey.io]: https://valkey.io/commands/lpop/ LPopCount(key string, count int64) ([]string, error) - // Returns the index of the first occurrence of element inside the list specified by key. If no match is found, - // [api.CreateNilInt64Result()] is returned. - // - // See [valkey.io] for details. - // - // Parameters: - // key - The name of the list. - // element - The value to search for within the list. - // - // Return value: - // The Result[int64] containing the index of the first occurrence of element, or [api.CreateNilInt64Result()] if element is - // not in the list. - // - // For example: - // result, err := client.RPush("my_list", []string{"a", "b", "c", "d", "e", "e"}) - // position, err := client.LPos("my_list", "e") - // position.Value(): 4 - // position.IsNil(): false - // - // [valkey.io]: https://valkey.io/commands/lpos/ LPos(key string, element string) (Result[int64], error) - // Returns the index of an occurrence of element within a list based on the given options. If no match is found, - // [api.CreateNilInt64Result()] is returned. - // - // See [valkey.io] for details. - // - // Parameters: - // key - The name of the list. - // element - The value to search for within the list. - // options - The LPos options. - // - // Return value: - // The Result[int64] containing the index of element, or [api.CreateNilInt64Result()] if element is not in the list. - // - // For example: - // 1. result, err := client.RPush("my_list", []string{"a", "b", "c", "d", "e", "e"}) - // result, err := client.LPosWithOptions("my_list", "e", api.NewLPosOptionsBuilder().SetRank(2)) - // result.Value(): 5 (Returns the second occurrence of the element "e") - // 2. result, err := client.RPush("my_list", []string{"a", "b", "c", "d", "e", "e"}) - // result, err := client.LPosWithOptions("my_list", "e", api.NewLPosOptionsBuilder().SetRank(1).SetMaxLen(1000)) - // result.Value(): 4 - // - // [valkey.io]: https://valkey.io/commands/lpos/ LPosWithOptions(key string, element string, options *LPosOptions) (Result[int64], error) - // Returns an array of indices of matching elements within a list. - // - // See [valkey.io] for details. - // - // Parameters: - // key - The name of the list. - // element - The value to search for within the list. - // count - The number of matches wanted. - // - // Return value: - // An array that holds the indices of the matching elements within the list. - // - // For example: - // _, err := client.RPush("my_list", []string{"a", "b", "c", "d", "e", "e", "e"}) - // result, err := client.LPosCount("my_list", "e", int64(3)) - // result: []int64{ 4, 5, 6 } - // - // [valkey.io]: https://valkey.io/commands/lpos/ LPosCount(key string, element string, count int64) ([]int64, error) - // Returns an array of indices of matching elements within a list based on the given options. If no match is found, an - // empty array is returned. - // - // See [valkey.io] for details. - // - // Parameters: - // key - The name of the list. - // element - The value to search for within the list. - // count - The number of matches wanted. - // options - The LPos options. - // - // Return value: - // An array that holds the indices of the matching elements within the list. - // - // For example: - // 1. _, err := client.RPush("my_list", []string{"a", "b", "c", "d", "e", "e", "e"}) - // result, err := client.LPosWithOptions("my_list", "e", int64(1), api.NewLPosOptionsBuilder().SetRank(2)) - // result: []int64{ 5 } - // 2. _, err := client.RPush("my_list", []string{"a", "b", "c", "d", "e", "e", "e"}) - // result, err := client.LPosWithOptions( - // "my_list", - // "e", - // int64(3), - // api.NewLPosOptionsBuilder().SetRank(2).SetMaxLen(1000), - // ) - // result: []int64{ 5, 6 } - // - // - // [valkey.io]: https://valkey.io/commands/lpos/ LPosCountWithOptions(key string, element string, count int64, options *LPosOptions) ([]int64, error) - // Inserts all the specified values at the tail of the list stored at key. - // elements are inserted one after the other to the tail of the list, from the leftmost element to the rightmost element. - // If key does not exist, it is created as an empty list before performing the push operation. - // - // See [valkey.io] for details. - // - // Parameters: - // key - The key of the list. - // elements - The elements to insert at the tail of the list stored at key. - // - // Return value: - // The length of the list after the push operation. - // - // For example: - // result, err := client.RPush("my_list", []string{"a", "b", "c", "d", "e", "e", "e"}) - // result: 7 - // - // [valkey.io]: https://valkey.io/commands/rpush/ RPush(key string, elements []string) (int64, error) - // 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 [valkey.io] for details. - // - // Parameters: - // key - The key of the list. - // start - The starting point of the range. - // end - The end of the range. - // - // Return value: - // Array of elements as Result[string] in the specified range. - // If start exceeds the end of the list, or if start is greater than end, an empty array 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 array will be returned. - // - // For example: - // 1. result, err := client.LRange("my_list", 0, 2) - // result: []string{ "value1", "value2", "value3" } - // 2. result, err := client.LRange("my_list", -2, -1) - // result: []string{ "value2", "value3" } - // 3. result, err := client.LRange("non_existent_key", 0, 2) - // result: []string{} - // - // [valkey.io]: https://valkey.io/commands/lrange/ LRange(key string, start int64, end int64) ([]string, error) - // Returns the element at index from the list stored at key. - // The index is zero-based, so 0 means the first element, 1 the second element and so on. Negative indices can be used to - // designate elements starting at the tail of the list. Here, -1 means the last element, -2 means the penultimate and so - // forth. - // - // See [valkey.io] for details. - // - // Parameters: - // key - The key of the list. - // index - The index of the element in the list to retrieve. - // - // Return value: - // The Result[string] containing element at index in the list stored at key. - // If index is out of range or if key does not exist, [api.CreateNilStringResult()] is returned. - // - // For example: - // 1. result, err := client.LIndex("myList", 0) - // result.Value(): "value1" // Returns the first element in the list stored at 'myList'. - // result.IsNil(): false - // 2. result, err := client.LIndex("myList", -1) - // result.Value(): "value3" // Returns the last element in the list stored at 'myList'. - // result.IsNil(): false - // - // [valkey.io]: https://valkey.io/commands/lindex/ LIndex(key string, index int64) (Result[string], error) - // Trims an existing list so that it will contain only the specified range of elements specified. - // 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 [valkey.io] for details. - // - // Parameters: - // key - The key of the list. - // start - The starting point of the range. - // end - The end of the range. - // - // Return value: - // Always `"OK"`. - // If start exceeds the end of the list, or if start is greater than end, the result will be an empty list (which causes - // key to be removed). - // If end exceeds the actual end of the list, it will be treated like the last element of the list. - // If key does not exist, `"OK"` will be returned without changes to the database. - // - // For example: - // result, err := client.LTrim("my_list", 0, 1) - // result: "OK" - // - // [valkey.io]: https://valkey.io/commands/ltrim/ LTrim(key string, start int64, end int64) (string, error) - // Returns the length of the list stored at key. - // - // See [valkey.io] for details. - // - // Parameters: - // key - The key of the list. - // - // Return value: - // The length of the list at `key`. - // If `key` does not exist, it is interpreted as an empty list and `0` is returned. - // - // For example: - // result, err := client.LLen("my_list") - // result: 3 // Indicates that there are 3 elements in the list. - // - // [valkey.io]: https://valkey.io/commands/llen/ LLen(key string) (int64, error) - // Removes the first count occurrences of elements equal to element from the list stored at key. - // If count is positive: Removes elements equal to element moving from head to tail. - // If count is negative: Removes elements equal to element moving from tail to head. - // If count is 0 or count is greater than the occurrences of elements equal to element, it removes all elements equal to - // element. - // - // See [valkey.io] for details. - // - // Parameters: - // key - The key of the list. - // count - The count of the occurrences of elements equal to element to remove. - // element - The element to remove from the list. - // - // Return value: - // The number of the removed elements. - // If `key` does not exist, `0` is returned. - // - // For example: - // result, err := client.LRem("my_list", 2, "value") - // result: 2 - // - // [valkey.io]: https://valkey.io/commands/lrem/ LRem(key string, count int64, element string) (int64, error) - // Removes and returns the last elements of the list stored at key. - // The command pops a single element from the end of the list. - // - // See [valkey.io] for details. - // - // Parameters: - // key - The key of the list. - // - // Return value: - // The Result[string] containing the value of the last element. - // If key does not exist, [api.CreateNilStringResult()] will be returned. - // - // For example: - // 1. result, err := client.RPop("my_list") - // result.Value(): "value1" - // result.IsNil(): false - // 2. result, err := client.RPop("non_exiting_key") - // result.Value(): "" - // result.IsNil(): true - // - // [valkey.io]: https://valkey.io/commands/rpop/ RPop(key string) (Result[string], error) - // Removes and returns up to count elements from the list stored at key, depending on the list's length. - // - // See [valkey.io] for details. - // - // Parameters: - // key - The key of the list. - // count - The count of the elements to pop from the list. - // - // Return value: - // An array of popped elements as Result[string] will be returned depending on the list's length. - // If key does not exist, nil will be returned. - // - // For example: - // 1. result, err := client.RPopCount("my_list", 2) - // result: []api.Result[string]{api.CreateStringResult("value1"), api.CreateStringResult("value2")} - // 2. result, err := client.RPop("non_exiting_key") - // result: nil - // - // [valkey.io]: https://valkey.io/commands/rpop/ RPopCount(key string, count int64) ([]string, error) - // Inserts element in the list at key either before or after the pivot. - // - // See [valkey.io] for details. - // - // Parameters: - // key - The key of the list. - // insertPosition - The relative position to insert into - either api.Before or api.After the pivot. - // pivot - An element of the list. - // element - The new element to insert. - // - // Return value: - // The list length after a successful insert operation. - // If the `key` doesn't exist returns `-1`. - // If the `pivot` wasn't found, returns `0`. - // - // For example: - // "my_list": {"Hello", "Wprld"} - // result, err := client.LInsert("my_list", api.Before, "World", "There") - // result: 3 - // - // [valkey.io]: https://valkey.io/commands/linsert/ LInsert(key string, insertPosition InsertPosition, pivot string, element string) (int64, error) - // Pops an element from the head of the first list that is non-empty, with the given keys being checked in the order that - // they are given. - // Blocks the connection when there are no elements to pop from any of the given lists. - // - // Note: - // - When in cluster mode, all keys must map to the same hash slot. - // - BLPop is a client blocking command, see [Blocking Commands] for more details and best practices. - // - // See [valkey.io] for details. - // - // Parameters: - // keys - The keys of the lists to pop from. - // timeoutSecs - The number of seconds to wait for a blocking operation to complete. A value of 0 will block indefinitely. - // - // Return value: - // A two-element array containing the key from which the element was popped and the value of the popped - // element, formatted as [key, value]. - // If no element could be popped and the timeout expired, returns `nil`. - // - // For example: - // result, err := client.BLPop("list1", "list2", 0.5) - // result: []string{ "list1", "element" } - // - // [valkey.io]: https://valkey.io/commands/blpop/ - // [Blocking Commands]: https://github.com/valkey-io/valkey-glide/wiki/General-Concepts#blocking-commands BLPop(keys []string, timeoutSecs float64) ([]string, error) - // Pops an element from the tail of the first list that is non-empty, with the given keys being checked in the order that - // they are given. - // Blocks the connection when there are no elements to pop from any of the given lists. - // - // Note: - // - When in cluster mode, all keys must map to the same hash slot. - // - BRPop is a client blocking command, see [Blocking Commands] for more details and best practices. - // - // See [valkey.io] for details. - // - // Parameters: - // keys - The keys of the lists to pop from. - // timeoutSecs - The number of seconds to wait for a blocking operation to complete. A value of 0 will block indefinitely. - // - // Return value: - // A two-element array containing the key from which the element was popped and the value of the popped - // element, formatted as [key, value]. - // If no element could be popped and the timeoutSecs expired, returns `nil`. - // - // For example: - // result, err := client.BRPop("list1", "list2", 0.5) - // result: []string{ "list1", "element" } - // - // [valkey.io]: https://valkey.io/commands/brpop/ - // [Blocking Commands]: https://github.com/valkey-io/valkey-glide/wiki/General-Concepts#blocking-commands BRPop(keys []string, timeoutSecs float64) ([]string, error) - // Inserts all the specified values at the tail of the list stored at key, only if key exists and holds a list. If key is - // not a list, this performs no operation. - // - // See [valkey.io] for details. - // - // Parameters: - // key - The key of the list. - // elements - The elements to insert at the tail of the list stored at key. - // - // Return value: - // The length of the list after the push operation. - // - // For example: - // my_list: {"value1", "value2"} - // result, err := client.RPushX("my_list", []string{"value3", value4}) - // result: 4 - // - // [valkey.io]: https://valkey.io/commands/rpushx/ RPushX(key string, elements []string) (int64, error) - // Inserts all the specified values at the head of the list stored at key, only if key exists and holds a list. If key is - // not a list, this performs no operation. - // - // See [valkey.io] for details. - // - // Parameters: - // key - The key of the list. - // elements - The elements to insert at the head of the list stored at key. - // - // Return value: - // The length of the list after the push operation. - // - // For example: - // my_list: {"value1", "value2"} - // result, err := client.LPushX("my_list", []string{"value3", value4}) - // result: 4 - // - // [valkey.io]: https://valkey.io/commands/rpushx/ LPushX(key string, elements []string) (int64, error) - // Pops one element from the first non-empty list from the provided keys. - // - // Since: - // Valkey 7.0 and above. - // - // See [valkey.io] for details. - // - // Parameters: - // keys - An array of keys to lists. - // listDirection - The direction based on which elements are popped from - see [api.ListDirection]. - // - // Return value: - // A map of key name mapped array of popped element. - // - // For example: - // result, err := client.LPush("my_list", []string{"one", "two", "three"}) - // result, err := client.LMPop([]string{"my_list"}, api.Left) - // result["my_list"] = []string{"three"} - // - // [valkey.io]: https://valkey.io/commands/lmpop/ LMPop(keys []string, listDirection ListDirection) (map[string][]string, error) - // Pops one or more elements from the first non-empty list from the provided keys. - // - // Since: - // Valkey 7.0 and above. - // - // See [valkey.io] for details. - // - // Parameters: - // keys - An array of keys to lists. - // listDirection - The direction based on which elements are popped from - see [api.ListDirection]. - // count - The maximum number of popped elements. - // - // Return value: - // A map of key name mapped array of popped elements. - // - // For example: - // result, err := client.LPush("my_list", []string{"one", "two", "three"}) - // result, err := client.LMPopCount([]string{"my_list"}, api.Left, int64(1)) - // result["my_list"] = []string{"three"} - // - // [valkey.io]: https://valkey.io/commands/lmpop/ LMPopCount(keys []string, listDirection ListDirection, count int64) (map[string][]string, error) - // Blocks the connection until it pops one element from the first non-empty list from the provided keys. BLMPop is the - // blocking variant of [api.LMPop]. - // - // Note: - // - When in cluster mode, all keys must map to the same hash slot. - // - BLMPop is a client blocking command, see [Blocking Commands] for more details and best practices. - // - // Since: - // Valkey 7.0 and above. - // - // See [valkey.io] for details. - // - // Parameters: - // keys - An array of keys to lists. - // listDirection - The direction based on which elements are popped from - see [api.ListDirection]. - // timeoutSecs - The number of seconds to wait for a blocking operation to complete. A value of 0 will block - // indefinitely. - // - // Return value: - // A map of key name mapped array of popped element. - // If no member could be popped and the timeout expired, returns nil. - // - // For example: - // result, err := client.LPush("my_list", []string{"one", "two", "three"}) - // result, err := client.BLMPop([]string{"my_list"}, api.Left, float64(0.1)) - // result["my_list"] = []string{"three"} - // - // [valkey.io]: https://valkey.io/commands/blmpop/ - // [Blocking Commands]: https://github.com/valkey-io/valkey-glide/wiki/General-Concepts#blocking-commands BLMPop(keys []string, listDirection ListDirection, timeoutSecs float64) (map[string][]string, error) - // Blocks the connection until it pops one or more elements from the first non-empty list from the provided keys. - // BLMPopCount is the blocking variant of [api.LMPopCount]. - // - // Note: - // - When in cluster mode, all keys must map to the same hash slot. - // - BLMPopCount is a client blocking command, see [Blocking Commands] for more details and best practices. - // - // Since: - // Valkey 7.0 and above. - // - // See [valkey.io] for details. - // - // Parameters: - // keys - An array of keys to lists. - // listDirection - The direction based on which elements are popped from - see [api.ListDirection]. - // count - The maximum number of popped elements. - // timeoutSecs - The number of seconds to wait for a blocking operation to complete. A value of 0 will block - // indefinitely. - // - // Return value: - // A map of key name mapped array of popped element. - // If no member could be popped and the timeout expired, returns nil. - // - // For example: - // result, err: client.LPush("my_list", []string{"one", "two", "three"}) - // result, err := client.BLMPopCount([]string{"my_list"}, api.Left, int64(1), float64(0.1)) - // result["my_list"] = []string{"three"} - // - // [valkey.io]: https://valkey.io/commands/blmpop/ - // [Blocking Commands]: https://github.com/valkey-io/valkey-glide/wiki/General-Concepts#blocking-commands BLMPopCount( keys []string, listDirection ListDirection, @@ -587,92 +61,10 @@ type ListCommands interface { timeoutSecs float64, ) (map[string][]string, error) - // 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 can be used to - // designate elements starting at the tail of the list. Here, -1 means the last element, -2 means the penultimate and so - // forth. - // - // See [valkey.io] for details. - // - // Parameters: - // key - The key of the list. - // index - The index of the element in the list to be set. - // element - The element to be set. - // - // Return value: - // `"OK"`. - // - // For example: - // result, err: client.LSet("my_list", int64(1), "two") - // result: "OK" - // - // [valkey.io]: https://valkey.io/commands/lset/ LSet(key string, index int64, element string) (string, error) - // 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 [valkey.io] for details. - // - // Parameters: - // source - The key to the source list. - // destination - The key to the destination list. - // wherefrom - The ListDirection the element should be removed from. - // whereto - The ListDirection the element should be added to. - // - // Return value: - // A Result[string] containing the popped element or api.CreateNilStringResult() if source does not exist. - // - // For example: - // result, err: client.LPush("my_list", []string{"two", "one"}) - // result, err: client.LPush("my_list2", []string{"four", "three"}) - // result, err: client.LMove("my_list1", "my_list2", api.Left, api.Left) - // result.Value(): "one" - // updatedList1, err: client.LRange("my_list1", int64(0), int64(-1)) - // updatedList2, err: client.LRange("my_list2", int64(0), int64(-1)) - // updatedList1: []string{ "two" } - // updatedList2: []string{ "one", "three", "four" } - // - // [valkey.io]: https://valkey.io/commands/lmove/ LMove(source string, destination string, whereFrom ListDirection, whereTo ListDirection) (Result[string], error) - // 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 request timeout var testClient api.BaseClient - if _, ok := client.(api.GlideClient); ok { + if _, ok := client.(api.GlideClientCommands); ok { testClient = suite.client(api.NewGlideClientConfiguration(). WithAddress(&suite.standaloneHosts[0]). WithUseTLS(suite.tls)) @@ -5572,7 +5572,7 @@ func (suite *GlideTestSuite) TestXPending() { // each use of CustomCommand would make the tests difficult to read and maintain. These tests can be // collapsed once the native commands are added in a subsequent release. - execStandalone := func(client api.GlideClient) { + execStandalone := func(client api.GlideClientCommands) { // 1. Arrange the data key := uuid.New().String() groupName := "group" + uuid.New().String() @@ -5646,7 +5646,7 @@ func (suite *GlideTestSuite) TestXPending() { assert.Equal(suite.T(), streamid_2.Value(), detailResult[1].Id) } - execCluster := func(client api.GlideClusterClient) { + execCluster := func(client api.GlideClusterClientCommands) { // 1. Arrange the data key := uuid.New().String() groupName := "group" + uuid.New().String() @@ -5728,9 +5728,9 @@ func (suite *GlideTestSuite) TestXPending() { // this is only needed in order to be able to use custom commands. // Once the native commands are added, this logic will be refactored. switch c := client.(type) { - case api.GlideClient: + case api.GlideClientCommands: execStandalone(c) - case api.GlideClusterClient: + case api.GlideClusterClientCommands: execCluster(c) } }) @@ -5746,7 +5746,7 @@ func (suite *GlideTestSuite) TestXPendingFailures() { // each use of CustomCommand would make the tests difficult to read and maintain. These tests can be // collapsed once the native commands are added in a subsequent release. - execStandalone := func(client api.GlideClient) { + execStandalone := func(client api.GlideClientCommands) { // 1. Arrange the data key := uuid.New().String() missingKey := uuid.New().String() @@ -5896,7 +5896,7 @@ func (suite *GlideTestSuite) TestXPendingFailures() { assert.True(suite.T(), strings.Contains(err.Error(), "WRONGTYPE")) } - execCluster := func(client api.GlideClusterClient) { + execCluster := func(client api.GlideClusterClientCommands) { // 1. Arrange the data key := uuid.New().String() missingKey := uuid.New().String() @@ -6052,9 +6052,9 @@ func (suite *GlideTestSuite) TestXPendingFailures() { // this is only needed in order to be able to use custom commands. // Once the native commands are added, this logic will be refactored. switch c := client.(type) { - case api.GlideClient: + case api.GlideClientCommands: execStandalone(c) - case api.GlideClusterClient: + case api.GlideClusterClientCommands: execCluster(c) } })