xuid

README

XUID

XUID is an ID that contains the exact same number of bits as a UUID, adds a type prefix, and is encoded in a string that will not be larger than 36 characters.

This is achieved by using base32 instead of base16. Base32 still only uses one set of alphabetic characters, allowing caseless matches.

Type

The type is a up to 5 characters long code that specifies what kind of object the ID is of. It is used to allow easy identification of an ID, either by humans or automated code.

Examples

• UUID 3f1b4d37-34d9-46c6-b546-a57c5f736d22 with type shell becomes shell-h4nu2n-zu3f-dmnn-kguv-6f643nei
• UUID 00000000-0000-0000-0000-000000000000 with type null becomes null-aaaaaa-aaaa-aaaa-aaaa-aaaaaaaa

Documentation

Index

• Variables
• func Must[T any](x T, err error) T
• type XUID
  • func FromKey(key string) (*XUID, error)
  • func FromKeyPrefix(key, prefix string) (*XUID, error)
  • func FromUUID(u uuid.UUID, prefix string) (*XUID, error)
  • func MustParse(s string) *XUID
  • func MustParseUUID(inputUuid, prefix string) *XUID
  • func New(prefix string) *XUID
  • func NewRandom(prefix string) (*XUID, error)
  • func Parse(s string) (*XUID, error)
  • func ParsePrefix(s, prefix string) (*XUID, error)
  • func ParseUUID(inputUuid, prefix string) (*XUID, error)
  • func (x XUID) Equals(y XUID) bool
  • func (x XUID) MarshalJSON() ([]byte, error)
  • func (x *XUID) Scan(value any) error
  • func (x XUID) String() string
  • func (x *XUID) ToUUID() string
  • func (x *XUID) UnmarshalJSON(b []byte) error
  • func (x XUID) Value() (driver.Value, error)

Variables

var (
	ErrBadPrefix = errors.New("xuid: bad prefix")
)

Functions

func Must

func Must[T any](x T, err error) T

Must can be used to transform any error thrown by the called method into a panic, and is useful when we know a call cannot fail, or that failure should be fatal.

Types

type XUID

type XUID struct {
	Prefix string
	UUID   uuid.UUID
}

func FromKey

func FromKey(key string) (*XUID, error)

FromKey returns a fixed ID based on a given key that can be guaranteed to always have the same ID as long as the key is the same value. This can be used for a Util/Ref object that have fixed IDs for a given key.

func FromKeyPrefix

func FromKeyPrefix(key, prefix string) (*XUID, error)

FromKeyPrefix returns a fixed ID based on the key and prefix passed and is guaranteed to always return the same ID as long as the parameters are the same. This can be used for objects that need to keep the same ID no matter on which environment this runs.

func FromUUID

func FromUUID(u uuid.UUID, prefix string) (*XUID, error)

FromUUID returns a new xuid with the passed uuid and chosen prefix

func MustParse

func MustParse(s string) *XUID

MustParse will perform Parse and panic if the parsing failed

func MustParseUUID

func MustParseUUID(inputUuid, prefix string) *XUID

func New

func New(prefix string) *XUID

New is a shorthand for Must(NewRandom(prefix)) and will always return a new xuid with the given prefix, or panic if for some reason the random generator does not work.

func NewRandom

func NewRandom(prefix string) (*XUID, error)

NewRandom returns a new random xuid with the given prefix set

func Parse

func Parse(s string) (*XUID, error)

Parse parses a string and returns the resulting xuid

func ParsePrefix

func ParsePrefix(s, prefix string) (*XUID, error)

ParsePrefix will parse the provided string and ensure the prefix matches the passed parameter, or return a ErrBadPrefix-based error if not.

func ParseUUID

func ParseUUID(inputUuid, prefix string) (*XUID, error)

ParseUUID will parse a uuid-formatted string and return it as a xuid

func (XUID) Equals

func (x XUID) Equals(y XUID) bool

Equals return true if x==y

func (XUID) MarshalJSON

func (x XUID) MarshalJSON() ([]byte, error)

func (*XUID) Scan

func (x *XUID) Scan(value any) error

Scan sets the value of the XUID to the passed data, parsing it as needed.

func (XUID) String

func (x XUID) String() string

String formats the ID as a string and return it

func (*XUID) ToUUID

func (x *XUID) ToUUID() string

ToUUID returns the value of x as a UUID

func (*XUID) UnmarshalJSON

func (x *XUID) UnmarshalJSON(b []byte) error

func (XUID) Value

func (x XUID) Value() (driver.Value, error)

Value returns the xuid as a string value