TypeID Go

To add the TypeID Go library as a dependency to your Go module, use the go get command with the v2 module path.

go get go.jetify.com/typeid/v2

When checking the state of a TypeID, it is important to distinguish between a zero-value ID and an ID that simply has a zero suffix.

• HasSuffix(): Returns false if the suffix is the zero suffix (00000000000000000000000000). This check is independent of the prefix. For example, prefix_00000000000000000000000000 will return false.
• IsZero(): Returns true only if the TypeID has an empty prefix AND a zero suffix. An empty struct TypeID{} is considered a zero ID.

Use MustGenerate(prefix string) when you want to create a new TypeID but do not want to handle errors manually. This function will panic if the provided prefix is invalid. Use Generate() instead if you need robust error handling.

tid := typeid.MustGenerate("order")

The AppendText(dst []byte) method appends the string representation of a TypeID to an existing byte slice dst and returns the extended buffer. This is an efficient way to build strings or byte slices without extra allocations.

If the TypeID is empty (zero value), it appends the ZeroSuffix to the buffer.

// Append a TypeID to an existing buffer
buffer := []byte("id: ")
tid := typeid.MustParse("prefix.uuid")

newBuffer, err := tid.AppendText(buffer)
// newBuffer is now []byte("id: prefix.uuid")

Use FromUUID(prefix, uidStr string) to encode an existing UUID (provided as a hex string) into a TypeID format.

• prefix: The prefix to use (pass "" for no prefix).
• uidStr: The UUID string to encode.

Returns an error if the prefix is invalid or if the uidStr is not in a valid UUID format.

tid, err := typeid.FromUUID("account", "550e8400-e29b-41d4-a716-446655440000")
if err != nil {
	// handle error
}

When performing operations that validate TypeID formats, the package may return ErrValidation. This is a sentinel error used to indicate that a TypeID is malformed or invalid.

To check if an error is a validation error, use errors.Is(err, ErrValidation). The error may wrap an underlying cause (such as a base32 decoding error) which can be accessed via errors.Unwrap(err).

import (
	"errors"
	"fmt"
	"github.com/jetify-com/typeid-go"
)

func handleResult(err error) {
	if errors.Is(err, typeid.ErrValidation) {
		fmt.Println("The provided TypeID is invalid")
	} else if err != nil {
		fmt.Printf("An unexpected error occurred: %v\n", err)
	}
}

Use Generate(prefix string) to create a new TypeID consisting of a provided prefix and a random suffix. The suffix is generated using a UUID v7 and encoded into a 26-character base32 string.

To create a TypeID without a prefix, pass an empty string ("").

tid, err := typeid.Generate("user")
if err != nil {
	// handle error
}
// tid will be in the format "user_..."

The TypeID type implements the standard Go encoding.TextMarshaler and encoding.TextUnmarshaler interfaces. This allows TypeID to be seamlessly used with encoders like encoding/json or encoding/xml.

• MarshalText(): Encodes the TypeID as its string representation.
• UnmarshalText(text []byte): Parses a TypeID from the provided byte slice using the same logic as Parse().

// Example of marshaling/unmarshaling via standard interfaces
var tid typeid.TypeID

// UnmarshalText
err := tid.UnmarshalText([]byte("prefix.uuid"))
if err != nil {
    // handle error
}

// MarshalText
bytes, err := tid.MarshalText()

Use FromBytes(prefix string, uidBytes []byte) to create a TypeID from a raw 16-byte UUID slice. This method is optimized for zero allocations during the conversion process.

• prefix: The prefix to use (pass "" for no prefix).
• uidBytes: A byte slice that must be exactly 16 bytes long.

Returns an error if uidBytes is not exactly 16 bytes or if the prefix is invalid.

// Assuming bytes is a 16-byte slice
tid, err := typeid.FromBytes("session", bytes)
if err != nil {
	// handle error
}

Use Parse(s string) to convert a string of the form <prefix>_<suffix> into a TypeID object.

If the string does not contain an underscore (_), the entire string is treated as the suffix with an empty prefix. If an underscore is present but the prefix is empty (e.g., "_suffix"), Parse will return an error.

tid, err := typeid.Parse("user_abc123")
if err != nil {
	// handle error
}