Add command GeoAdd and the geospatial command interface (#3366)

* Add command GeoAdd and the geospatial command interface

Signed-off-by: TJ Zhang <[email protected]>

Author: tjzhang-BQ

CHANGELOG.md

@@ -15,6 +15,7 @@
 * Go: Adding support for Az Affinity ([#3235](https://github.com/valkey-io/valkey-glide/pull/3235))
 * Go: Adding support for advanced client configs and connectionTimeout ([#3290](https://github.com/valkey-io/valkey-glide/pull/3290))
 * Go: Add Cluster Scan support ([#3295](https://github.com/valkey-io/valkey-glide/pull/3295))
+* Go: Add `GeoAdd` and the Geospatial interface ([#3366](https://github.com/valkey-io/valkey-glide/pull/3366))
 
 #### Breaking Changes
 

go/api/base_client.go

@@ -42,6 +42,7 @@ type BaseClient interface {
 	HyperLogLogCommands
 	GenericBaseCommands
 	BitmapCommands
+	GeoSpatialCommands
 	// Close terminates the client by closing all associated resources.
 	Close()
 }
@@ -6465,3 +6466,66 @@ func (client *baseClient) ZLexCount(key string, rangeQuery *options.RangeByLex)
 	}
 	return handleIntResponse(result)
 }
+
+// Adds geospatial members with their positions to the specified sorted set stored at `key`.
+// If a member is already a part of the sorted set, its position is updated.
+//
+// See [valkey.io] for details.
+//
+// Parameters:
+//
+//	key - The key of the sorted set.
+//	membersToGeospatialData - A map of member names to their corresponding positions. See [options.GeospatialData].
+//	  The command will report an error when index coordinates are out of the specified range.
+//
+// Return value:
+//
+//	The number of elements added to the sorted set.
+//
+// [valkey.io]: https://valkey.io/commands/geoadd/
+func (client *baseClient) GeoAdd(key string, membersToGeospatialData map[string]options.GeospatialData) (int64, error) {
+	result, err := client.executeCommand(
+		C.GeoAdd,
+		append([]string{key}, options.MapGeoDataToArray(membersToGeospatialData)...),
+	)
+	if err != nil {
+		return defaultIntResponse, err
+	}
+	return handleIntResponse(result)
+}
+
+// Adds geospatial members with their positions to the specified sorted set stored at `key`.
+// If a member is already a part of the sorted set, its position is updated.
+//
+// See [valkey.io] for details.
+//
+// Parameters:
+//
+//	key - The key of the sorted set.
+//	membersToGeospatialData - A map of member names to their corresponding positions. See [options.GeospatialData].
+//	  The command will report an error when index coordinates are out of the specified range.
+//	geoAddOptions - The options for the GeoAdd command, see - [options.GeoAddOptions].
+//
+// Return value:
+//
+//	The number of elements added to the sorted set.
+//
+// [valkey.io]: https://valkey.io/commands/geoadd/
+func (client *baseClient) GeoAddWithOptions(
+	key string,
+	membersToGeospatialData map[string]options.GeospatialData,
+	geoAddOptions options.GeoAddOptions,
+) (int64, error) {
+	args := []string{key}
+	optionsArgs, err := geoAddOptions.ToArgs()
+	if err != nil {
+		return defaultIntResponse, err
+	}
+	args = append(args, optionsArgs...)
+	args = append(args, options.MapGeoDataToArray(membersToGeospatialData)...)
+	result, err := client.executeCommand(C.GeoAdd, args)
+	if err != nil {
+		return defaultIntResponse, err
+	}
+	return handleIntResponse(result)
+}

go/api/example_utils.go

@@ -80,7 +80,10 @@ func getExampleGlideClusterClient() *GlideClusterClient {
 	})
 
 	// Flush the database before each test to ensure a clean state.
-	_, err := clusterClient.CustomCommandWithRoute([]string{"FLUSHALL"}, config.AllPrimaries) // todo: replace with client.FlushAll() when implemented
+	_, err := clusterClient.CustomCommandWithRoute(
+		[]string{"FLUSHALL"},
+		config.AllPrimaries,
+	) // todo: replace with client.FlushAll() when implemented
 	if err != nil {
 		fmt.Println("error flushing database: ", err)
 	}

go/api/geospacial_commands.go

@@ -0,0 +1,23 @@
+// Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
+
+package api
+
+import (
+	"github.com/valkey-io/valkey-glide/go/api/options"
+)
+
+// GeoSpatialCommands supports commands and transactions for the "Geo Spatial Commands" group
+// for standalone and cluster clients.
+//
+// See [valkey.io] for details.
+//
+// [valkey.io]: https://valkey.io/commands/#geo-spatial
+type GeoSpatialCommands interface {
+	GeoAdd(key string, membersToGeospatialData map[string]options.GeospatialData) (int64, error)
+
+	GeoAddWithOptions(
+		key string,
+		membersToGeospatialData map[string]options.GeospatialData,
+		options options.GeoAddOptions,
+	) (int64, error)
+}

go/api/geospacial_commands_test.go

@@ -0,0 +1,48 @@
+// Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
+
+package api
+
+import (
+	"fmt"
+
+	"github.com/google/uuid"
+	"github.com/valkey-io/valkey-glide/go/api/options"
+)
+
+func ExampleGlideClient_GeoAdd() {
+	client := getExampleGlideClient()
+
+	membersToCoordinates := map[string]options.GeospatialData{
+		"Palermo": {Longitude: 13.361389, Latitude: 38.115556},
+		"Catania": {Longitude: 15.087269, Latitude: 37.502669},
+	}
+
+	result, err := client.GeoAdd(uuid.New().String(), membersToCoordinates)
+	if err != nil {
+		fmt.Println("Glide example failed with an error: ", err)
+	}
+
+	fmt.Println(result)
+
+	// Output:
+	// 2
+}
+
+func ExampleGlideClusterClient_GeoAdd() {
+	client := getExampleGlideClusterClient()
+
+	membersToCoordinates := map[string]options.GeospatialData{
+		"Palermo": {Longitude: 13.361389, Latitude: 38.115556},
+		"Catania": {Longitude: 15.087269, Latitude: 37.502669},
+	}
+
+	result, err := client.GeoAdd(uuid.New().String(), membersToCoordinates)
+	if err != nil {
+		fmt.Println("Glide example failed with an error: ", err)
+	}
+
+	fmt.Println(result)
+
+	// Output:
+	// 2
+}

go/api/options/constants.go

@@ -20,6 +20,8 @@ const (
 	StoreKeyword      string = "STORE"
 	DbKeyword         string = "DB"
 	TypeKeyword       string = "TYPE"
+	ChangedKeyword    string = "CH"   // Valkey API keyword used to return total number of elements changed
+	IncrKeyword       string = "INCR" // Valkey API keyword to make zadd act like ZINCRBY.
 	/// Valkey API keywords for stream commands
 	IdleKeyword         string = "IDLE"       // ValKey API string to designate IDLE time in milliseconds
 	TimeKeyword         string = "TIME"       // ValKey API string to designate TIME time in unix-milliseconds

go/api/options/geoadd_options.go

@@ -0,0 +1,64 @@
+// Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
+
+package options
+
+import (
+	"github.com/valkey-io/valkey-glide/go/utils"
+)
+
+// Represents a geographic position defined by longitude and latitude
+// The exact limits, as specified by `EPSG:900913 / EPSG:3785 / OSGEO:41001` are:
+// - Longitude: -180 to 180 degrees
+// - Latitude: -85.05112878 to 85.05112878 degrees
+type GeospatialData struct {
+	Latitude  float64
+	Longitude float64
+}
+
+// Helper function to convert a geospatial members to geospatial data mapping to a slice of strings
+// The format is: latitude, longitude, member,...
+func MapGeoDataToArray(memberGeoMap map[string]GeospatialData) []string {
+	result := make([]string, 0, len(memberGeoMap)*3)
+	for member, geoData := range memberGeoMap {
+		result = append(result, utils.FloatToString(geoData.Longitude), utils.FloatToString(geoData.Latitude), member)
+	}
+	return result
+}
+
+// Optional arguments to `GeoAdd` in [GeoSpatialCommands]
+type GeoAddOptions struct {
+	conditionalChange ConditionalSet
+	changed           bool
+}
+
+func NewGeoAddOptions() *GeoAddOptions {
+	return &GeoAddOptions{}
+}
+
+// `conditionalChange` defines conditions for updating or adding elements with `ZADD` command.
+func (options *GeoAddOptions) SetConditionalChange(conditionalChange ConditionalSet) *GeoAddOptions {
+	options.conditionalChange = conditionalChange
+	return options
+}
+
+// `Changed` changes the return value from the number of new elements added to the total number of elements changed.
+func (options *GeoAddOptions) SetChanged(changed bool) *GeoAddOptions {
+	options.changed = changed
+	return options
+}
+
+// `ToArgs` converts the options to a list of arguments.
+func (opts *GeoAddOptions) ToArgs() ([]string, error) {
+	args := []string{}
+	var err error
+
+	if opts.conditionalChange == OnlyIfExists || opts.conditionalChange == OnlyIfDoesNotExist {
+		args = append(args, string(opts.conditionalChange))
+	}
+
+	if opts.changed {
+		args = append(args, ChangedKeyword)
+	}
+
+	return args, err
+}

go/api/options/zadd_options.go

@@ -88,8 +88,3 @@ const (
 	// to "GT" in the Valkey API.
 	ScoreGreaterThanCurrent UpdateOptions = "GT"
 )
-
-const (
-	ChangedKeyword string = "CH"   // Valkey API keyword used to return total number of elements changed
-	IncrKeyword    string = "INCR" // Valkey API keyword to make zadd act like ZINCRBY.
-)

go/integTest/shared_commands_test.go

@@ -9064,3 +9064,107 @@ func (suite *GlideTestSuite) TestZLexCount() {
 		assert.IsType(t, &errors.RequestError{}, err)
 	})
 }
+
+func (suite *GlideTestSuite) TestGeoAdd() {
+	suite.runWithDefaultClients(func(client api.BaseClient) {
+		t := suite.T()
+		key1 := "{testKey}:1-" + uuid.New().String()
+		key2 := "{testKey}:2-" + uuid.New().String()
+
+		// Test basic GEOADD
+		membersToCoordinates := map[string]options.GeospatialData{
+			"Palermo": {Longitude: 13.361389, Latitude: 38.115556},
+			"Catania": {Longitude: 15.087269, Latitude: 37.502669},
+		}
+
+		result, err := client.GeoAdd(key1, membersToCoordinates)
+		assert.NoError(t, err)
+		assert.Equal(t, int64(2), result)
+
+		// Test with NX option (only if not exists)
+		membersToCoordinates = map[string]options.GeospatialData{
+			"Catania": {Longitude: 15.087269, Latitude: 39},
+		}
+		result, err = client.GeoAddWithOptions(
+			key1,
+			membersToCoordinates,
+			*options.NewGeoAddOptions().SetConditionalChange(options.OnlyIfDoesNotExist),
+		)
+		assert.NoError(t, err)
+		assert.Equal(t, int64(0), result)
+
+		// Test with XX option (only if exists)
+		result, err = client.GeoAddWithOptions(
+			key1,
+			membersToCoordinates,
+			*options.NewGeoAddOptions().SetConditionalChange(options.OnlyIfExists),
+		)
+		assert.NoError(t, err)
+		assert.Equal(t, int64(0), result)
+
+		// Test with CH option (change coordinates)
+		membersToCoordinates = map[string]options.GeospatialData{
+			"Catania":  {Longitude: 15.087269, Latitude: 40},
+			"Tel-Aviv": {Longitude: 32.0853, Latitude: 34.7818},
+		}
+		result, err = client.GeoAddWithOptions(
+			key1,
+			membersToCoordinates,
+			*options.NewGeoAddOptions().SetChanged(true),
+		)
+		assert.NoError(t, err)
+		assert.Equal(t, int64(2), result)
+
+		// Test error case with wrong key type
+		_, err = client.Set(key2, "bar")
+		assert.NoError(t, err)
+
+		_, err = client.GeoAddWithOptions(
+			key2,
+			membersToCoordinates,
+			*options.NewGeoAddOptions().SetChanged(true),
+		)
+		assert.Error(t, err)
+		assert.IsType(t, &errors.RequestError{}, err)
+	})
+}
+
+func (suite *GlideTestSuite) TestGeoAdd_InvalidArgs() {
+	suite.runWithDefaultClients(func(client api.BaseClient) {
+		t := suite.T()
+		key := "{testKey}:3-" + uuid.New().String()
+
+		// Test empty members
+		_, err := client.GeoAdd(key, map[string]options.GeospatialData{})
+		assert.Error(t, err)
+		assert.IsType(t, &errors.RequestError{}, err)
+
+		// Test invalid longitude (-181)
+		_, err = client.GeoAdd(key, map[string]options.GeospatialData{
+			"Place": {Longitude: -181, Latitude: 0},
+		})
+		assert.Error(t, err)
+		assert.IsType(t, &errors.RequestError{}, err)
+
+		// Test invalid longitude (181)
+		_, err = client.GeoAdd(key, map[string]options.GeospatialData{
+			"Place": {Longitude: 181, Latitude: 0},
+		})
+		assert.Error(t, err)
+		assert.IsType(t, &errors.RequestError{}, err)
+
+		// Test invalid latitude (86)
+		_, err = client.GeoAdd(key, map[string]options.GeospatialData{
+			"Place": {Longitude: 0, Latitude: 86},
+		})
+		assert.Error(t, err)
+		assert.IsType(t, &errors.RequestError{}, err)
+
+		// Test invalid latitude (-86)
+		_, err = client.GeoAdd(key, map[string]options.GeospatialData{
+			"Place": {Longitude: 0, Latitude: -86},
+		})
+		assert.Error(t, err)
+		assert.IsType(t, &errors.RequestError{}, err)
+	})
+}