Go

Our API Reference has generic examples in every supported language, and we strive to make the experience of each SDK very similar. However, there are some things specific to the Go SDK that we want to call out here.

Key Path Helper

The github.com/StatelyCloud/go-sdk/stately.ToKeyID(value) function can be used to format an ID value (especially a UUID) correctly to include in a key path:

1
kp := "/movie-"+stately.ToKeyID(movieID)+"/actor-"+stately.ToKeyID(actorID)

The ToKeyID helper has generic support for types string, []byte, [16]byte, uint64, uint32, int64, and uint64. When using a typed version of these it may be necessary to convert to one of these types first. See examples below:

A typed primitive:

1
type UserID uint64
2
userID := UserID(123)
3
kp := "/userID-"+stately.ToKeyID(uint64(userID))
4

5
type EmailAddress string
6
email := EmailAddress("[email protected]")
7
kp := "/email-"+stately.ToKeyID(string(email))

github.com/gofrs/uuid/v5 UUID:

1
moveID := uuid.Must(uuid.NewV4())
2
kp := "/movie-"+stately.ToKeyID(id[:])
3
kp := "/movie-"+stately.ToKeyID(id.Bytes())
4
kp := "/movie-"+stately.ToKeyID([16]byte(id))

github.com/google/uuid UUID:

1
moveID := uuid.New()
2
kp := "/movie-"+stately.ToKeyID(id[:])
3
kp := "/movie-"+stately.ToKeyID([16]byte(id))

Checking an Item’s Type

Many client APIs return a *stately.Item, but you want to know exactly what type it is. You can use standard Go type checks for this:

1
if movie, ok := item.(*schema.Movie); ok {
2
  // it's a movie
3
}
4

5
switch v := item.(type) {
6
  case *schema.Movie:
7
    // it's a movie
8
  case *schema.Character:
9
    // it's a character
10
}

Protobuf

The Go types generated from your schema expose each of their fields as properties, but also have a method version that is nil-safe. For example if you have a name field, the Go object will have a Name property and a GetName() method. The method version will return the zero value (in this case an empty string) even if called on a nil pointer.

UUIDs

The Go code generator will automatically choose which package to use for UUID-typed fields based on what is available in the go.mod file in the output directory. This allows you to use you preferred UUID package with the generated code. The generator can currently detect and use github.com/google/uuid, [github.com/gofrs/uuid], or github.com/satori/go.uuid. If you don’t already have a UUID package specified, it defaults to github.com/google/uuid.

Errors

Clients can throw errors, which will all be of the type *sdkerror.Error. These errors have an associated StatelyCode which can give more details about the error, plus a higher-level gRPC/Connect error code that can be used to generally group errors into different categories. There is also a helper function sdkerror.Is which lets you quickly check if any error matches a StatelyCode:

1
if sdkerror.Is(err, sdkerror.StoreRequestLimitExceeded) {
2
  // handle
3
}

The github.com/StatelyCloud/go-sdk/sdkerror package includes a handful of defined error codes under the StatelyErrorCode type that cover common error cases that you might need to handle in your own code, such as “ConcurrentModification” or “StoreThroughputExceeded”. Each of these are documented with what they mean and how to handle them.