Merge remote-tracking branch 'upstream/main' into go/hrandfield

Signed-off-by: Yury-Fridlyand <yury.fridlyand@improving.com>

Author: Yury-Fridlyand

go/api/base_client.go

@@ -2,6 +2,8 @@
 
 package api
 
+import "github.com/valkey-io/valkey-glide/go/glide/api/options"
+
 // Supports commands and transactions for the "Generic Commands" group for standalone and cluster clients.
 //
 // See [valkey.io] for details.
@@ -527,4 +529,180 @@ type GenericBaseCommands interface {
 	//
 	// [valkey.io]: https://valkey.io/commands/dump/
 	Dump(key string) (Result[string], error)
+
+	ObjectFreq(key string) (Result[int64], error)
+
+	ObjectIdleTime(key string) (Result[int64], error)
+
+	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.Value(): 1
+	// result.IsNil(): false
+	//
+	// [valkey.io]: https://valkey.io/commands/sort/
+	SortStore(key string, destination string) (Result[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.Value(): 1
+	// result.IsNil(): false
+	//
+	// [valkey.io]: https://valkey.io/commands/sort/
+	SortStoreWithOptions(key string, destination string, sortOptions *options.SortOptions) (Result[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)
 }

go/api/generic_base_commands.go

@@ -290,63 +290,13 @@ type HashCommands interface {
 	// [valkey.io]: https://valkey.io/commands/hincrbyfloat/
 	HIncrByFloat(key string, field string, increment float64) (float64, error)
 
-	// Iterates fields of Hash types and their associated values. This definition of HSCAN command does not include the
-	// optional arguments of the command.
-	//
-	// See [valkey.io] for details.
-	//
-	// 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.
-	//
-	// Return value:
-	//	An array of the cursor and the subset of the hash held by `key`. The first element is always the `cursor`
-	//  for the next iteration of results. The `cursor` will be `"0"` on the last iteration of the subset.
-	//  The second element is always an array of the subset of the set held in `key`. The array in the
-	//  second element is always a flattened series of String pairs, where the key is at even indices
-	//  and the value is at odd indices.
-	//
-	// Example:
-	//  // Assume key contains a hash {{"a": "1"}, {"b", "2"}}
-	//	resCursor, resCollection, err = client.HScan(key, initialCursor)
-	//  // resCursor = {0 false}
-	//  // resCollection = [{a false} {1 false} {b false} {2 false}]
-	//
-	// [valkey.io]: https://valkey.io/commands/hscan/
-	HScan(key string, cursor string) (Result[string], []Result[string], error)
-
-	// Iterates fields of Hash types and their associated values. This definition of HSCAN includes optional arguments of the
-	// command.
-	//
-	// See [valkey.io] for details.
-	//
-	// 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].
-	//
-	// Return value:
-	//  An array of the cursor and the subset of the hash held by `key`. The first element is always the `cursor`
-	//  for the next iteration of results. The `cursor` will be `"0"` on the last iteration of the subset.
-	//  The second element is always an array of the subset of the set held in `key`. The array in the
-	//  second element is always a flattened series of String pairs, where the key is at even indices
-	//  and the value is at odd indices.
-	//
-	// 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.
-	//
-	// [valkey.io]: https://valkey.io/commands/hscan/
-	HScanWithOptions(key string, cursor string, options *options.HashScanOptions) (Result[string], []Result[string], error)
+	HScan(key string, cursor string) (string, []string, error)
 
 	HRandField(key string) (Result[string], error)
 
 	HRandFieldWithCount(key string, count int64) ([]string, error)
 
 	HRandFieldWithCountWithValues(key string, count int64) ([][]string, error)
+
+	HScanWithOptions(key string, cursor string, options *options.HashScanOptions) (string, []string, error)
 }

go/api/hash_commands.go

@@ -0,0 +1,131 @@
+// Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
+
+package options
+
+import (
+	"github.com/valkey-io/valkey-glide/go/glide/utils"
+)
+
+const (
+	// LIMIT subcommand string to include in the SORT and SORT_RO commands.
+	LIMIT_COMMAND_STRING = "LIMIT"
+	// ALPHA subcommand string to include in the SORT and SORT_RO commands.
+	ALPHA_COMMAND_STRING = "ALPHA"
+	// BY subcommand string to include in the SORT and SORT_RO commands.
+	// Supported in cluster mode since Valkey version 8.0 and above.
+	BY_COMMAND_STRING = "BY"
+	// GET subcommand string to include in the SORT and SORT_RO commands.
+	GET_COMMAND_STRING = "GET"
+)
+
+// SortLimit struct represents the range of elements to retrieve
+// The LIMIT argument is commonly used to specify a subset of results from the matching elements, similar to the
+// LIMIT clause in SQL (e.g., `SELECT LIMIT offset, count`).
+type SortLimit struct {
+	Offset int64
+	Count  int64
+}
+
+// OrderBy specifies the order to sort the elements. Can be ASC (ascending) or DESC(descending).
+type OrderBy string
+
+const (
+	ASC  OrderBy = "ASC"
+	DESC OrderBy = "DESC"
+)
+
+// SortOptions struct combines both the base options and additional sorting options
+type SortOptions struct {
+	SortLimit   *SortLimit
+	OrderBy     OrderBy
+	IsAlpha     bool
+	ByPattern   string
+	GetPatterns []string
+}
+
+func NewSortOptions() *SortOptions {
+	return &SortOptions{
+		OrderBy: ASC,   // Default order is ascending
+		IsAlpha: false, // Default is numeric sorting
+	}
+}
+
+// SortLimit Limits the range of elements
+// Offset is the starting position of the range, zero based.
+// Count is the maximum number of elements to include in the range.
+// A negative count returns all elements from the offset.
+func (opts *SortOptions) SetSortLimit(offset, count int64) *SortOptions {
+	opts.SortLimit = &SortLimit{Offset: offset, Count: count}
+	return opts
+}
+
+// OrderBy sets the order to sort by (ASC or DESC)
+func (opts *SortOptions) SetOrderBy(order OrderBy) *SortOptions {
+	opts.OrderBy = order
+	return opts
+}
+
+// IsAlpha determines whether to sort lexicographically (true) or numerically (false)
+func (opts *SortOptions) SetIsAlpha(isAlpha bool) *SortOptions {
+	opts.IsAlpha = isAlpha
+	return opts
+}
+
+// ByPattern - a pattern to sort by external keys instead of by the elements stored at the key themselves. The
+// pattern should contain an asterisk (*) as a placeholder for the element values, where the value
+// from the key replaces the asterisk to create the key name. For example, if key
+// contains IDs of objects, byPattern can be used to sort these IDs based on an
+// attribute of the objects, like their weights or timestamps.
+// Supported in cluster mode since Valkey version 8.0 and above.
+func (opts *SortOptions) SetByPattern(byPattern string) *SortOptions {
+	opts.ByPattern = byPattern
+	return opts
+}
+
+// A pattern used to retrieve external keys' values, instead of the elements at key.
+// The pattern should contain an asterisk (*) as a placeholder for the element values, where the
+// value from key replaces the asterisk to create the key name. This
+// allows the sorted elements to be transformed based on the related keys values. For example, if
+// key< contains IDs of users, getPatterns can be used to retrieve
+// specific attributes of these users, such as their names or email addresses. E.g., if
+// getPatterns is name_*, the command will return the values of the keys
+// name_&lt;element&gt; for each sorted element. Multiple getPatterns
+// arguments can be provided to retrieve multiple attributes. The special value # can
+// be used to include the actual element from key being sorted. If not provided, only
+// the sorted elements themselves are returned.
+// Supported in cluster mode since Valkey version 8.0 and above.
+func (opts *SortOptions) AddGetPattern(getPattern string) *SortOptions {
+	opts.GetPatterns = append(opts.GetPatterns, getPattern)
+	return opts
+}
+
+// ToArgs creates the arguments to be used in SORT and SORT_RO commands.
+func (opts *SortOptions) ToArgs() []string {
+	var args []string
+
+	if opts.SortLimit != nil {
+		args = append(
+			args,
+			LIMIT_COMMAND_STRING,
+			utils.IntToString(opts.SortLimit.Offset),
+			utils.IntToString(opts.SortLimit.Count),
+		)
+	}
+
+	if opts.OrderBy != "" {
+		args = append(args, string(opts.OrderBy))
+	}
+
+	if opts.IsAlpha {
+		args = append(args, ALPHA_COMMAND_STRING)
+	}
+
+	if opts.ByPattern != "" {
+		args = append(args, BY_COMMAND_STRING, opts.ByPattern)
+	}
+
+	for _, getPattern := range opts.GetPatterns {
+		args = append(args, GET_COMMAND_STRING, getPattern)
+	}
+	return args
+}