xuid

README

XUID

XUID (eXtended Unique IDentifier) is a Go library that enhances UUIDs with a type prefix while maintaining compatibility with standard UUID bit size. XUIDs are encoded in base32 rather than base16, ensuring they never exceed 36 characters in length while providing better human readability.

Features

• Fully compatible with standard UUIDs (same number of bits)
• Adds descriptive type prefixes (up to 5 characters)
• Encodes in base32 for shorter, more readable strings
• Case-insensitive matching
• Compatible with SQL databases via sql.Scanner and driver.Valuer interfaces
• JSON marshaling/unmarshaling support
• Easily convertible to and from standard UUIDs

Installation

go get -u github.com/KarpelesLab/xuid

Usage

package main

import (
    "fmt"
    "github.com/KarpelesLab/xuid"
)

func main() {
    // Create a new random XUID with a prefix
    id := xuid.New("user")
    fmt.Println(id) // e.g., user-h4nu2n-zu3f-dmnn-kguv-6f643nei

    // Parse an existing XUID
    parsed, err := xuid.Parse("user-h4nu2n-zu3f-dmnn-kguv-6f643nei")
    if err != nil {
        panic(err)
    }
    
    // Convert XUID to UUID
    uuidStr := parsed.ToUUID()
    fmt.Println(uuidStr) // e.g., 3f1b4d37-34d9-46c6-b546-a57c5f736d22
    
    // Create a XUID from a UUID
    fromUUID, _ := xuid.ParseUUID(uuidStr, "user")
    fmt.Println(fromUUID) // user-h4nu2n-zu3f-dmnn-kguv-6f643nei
    
    // Create deterministic XUIDs based on keys
    keyID, _ := xuid.FromKeyPrefix("specific-resource-name", "res")
    fmt.Println(keyID) // Will always be the same for this key and prefix
}

Type Prefixes

The type prefix (up to 5 characters) identifies what kind of object the ID represents, making it easier for both humans and automated systems to quickly identify the entity type without additional lookups.

Common prefix examples might include:

• user - User accounts
• doc - Documents
• img - Images
• prod - Products
• ord - Orders

Format

XUIDs use the following format:

prefix-aaaaaa-aaaa-aaaa-aaaa-aaaaaaaa

Where:

• prefix is 1-5 characters identifying the entity type
• The remaining parts are the base32-encoded UUID with hyphens for readability

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

License

See LICENSE file.

Documentation

Overview

Package xuid provides an extended UUID implementation that adds a type prefix while maintaining compatibility with standard UUIDs.

XUIDs consist of a standard UUID with an optional type prefix (up to 5 characters), encoded in base32 rather than base16 for better readability and shorter string representation. They are designed to be used as identifiers with built-in type information.

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 is returned when a XUID's prefix doesn't match the expected value
	// This is typically used by ParsePrefix to validate that an ID belongs to a specific entity type
	ErrBadPrefix = errors.New("xuid: bad prefix")
)

Package errors that can be returned by the XUID library functions

Functions

func Must

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

Must is a generic helper that transforms any error from the called function into a panic. It's useful for operations that shouldn't fail under normal circumstances, or when failure should be fatal.

If err is nil, it returns the value x. Otherwise, it panics with the error.

Types

type XUID

type XUID struct {
	// Prefix is a string of up to 5 characters identifying the type of entity
	Prefix string

	// UUID is the standard universally unique identifier that provides
	// the uniqueness guarantee
	UUID uuid.UUID
}

XUID represents an extended UUID with a type prefix. It consists of a standard UUID and an optional prefix string that identifies the type of entity this ID represents.

The prefix is limited to 5 characters maximum for string representation. When encoded to string, XUIDs use base32 encoding rather than base16 (hex) to produce more compact strings while maintaining the same information.

func FromKey

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

FromKey generates a deterministic XUID based on the provided key string. It always produces the same XUID for the same key value.

The generated XUID always has the prefix "utref" (utility reference). This is useful for creating reference objects with predictable IDs.

func FromKeyPrefix

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

FromKeyPrefix generates a deterministic XUID based on both a key and a prefix. It always produces the same XUID for the same combination of key and prefix.

This is useful for objects that need consistent IDs across different environments. The prefix is used both for generating the UUID and as the type prefix in the XUID.

func FromUUID

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

FromUUID creates a new XUID from an existing UUID and a prefix. This is useful when you want to convert a standard UUID to a XUID with type information.

func MustParse

func MustParse(s string) *XUID

MustParse parses a string into a XUID, panicking if parsing fails. This is useful for constants or when the XUID string is known to be valid.

func MustParseUUID

func MustParseUUID(inputUuid, prefix string) *XUID

MustParseUUID works like ParseUUID but panics if parsing fails. This is useful for constants or when the UUID string is known to be valid.

Takes a UUID-formatted string and an optional prefix to assign to the XUID.

func New

func New(prefix string) *XUID

New creates a new random XUID with the given prefix. It's a shorthand for Must(NewRandom(prefix)) and will panic if the random generator fails for some reason.

This is the most common method for creating new XUIDs.

func NewRandom

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

NewRandom generates a new random XUID with the given prefix. It uses the underlying uuid.NewRandom() function to generate a version 4 (random) UUID and assigns the provided prefix.

func Parse

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

Parse parses a string representation and returns the resulting XUID. It can handle XUID formatted strings as well as standard UUIDs. For XUIDs, it supports both prefixed and non-prefixed formats.

If the input string doesn't conform to XUID format, Parse will attempt to interpret it as a standard UUID and assign an empty prefix.

Returns the parsed XUID and any error encountered.

func ParsePrefix

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

ParsePrefix parses a XUID string and verifies that the prefix matches the provided one. Returns a parsed XUID if successful, or an error if either: - The input cannot be parsed as a XUID - The prefix doesn't match the expected value

This is useful for type-safe XUID parsing where the caller expects a specific entity type.

func ParseUUID

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

ParseUUID converts a standard UUID string into a XUID. It takes a UUID-formatted string and an optional prefix to assign to the XUID. If the prefix is empty, the XUID will have no type information.

This is useful for converting existing UUIDs to XUIDs or for working with existing systems that use standard UUIDs.

Returns a XUID pointer and any error encountered during parsing.

func (XUID) Equals

func (x XUID) Equals(y XUID) bool

Equals compares two XUIDs and returns true if they are equal, meaning they have the same prefix and UUID.

func (XUID) MarshalJSON

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

MarshalJSON implements the json.Marshaler interface for XUID. It converts the XUID to its string representation (prefix-aaaaaa-aaaa-aaaa-aaaa-aaaaaaaa) and then marshals that string to JSON.

This makes XUIDs appear as strings in JSON output, which is more readable and works better with other systems that expect string IDs.

func (*XUID) Scan

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

Scan implements the sql.Scanner interface for XUID. It allows XUIDs to be scanned directly from database query results.

The scan supports the following types: - string: Parses the string as a XUID - sql.RawBytes: Converts to string and parses as a XUID

This functionality enables XUIDs to be used directly with database/sql operations without manual type conversion.

func (XUID) String

func (x XUID) String() string

String formats the XUID as a string with the format: prefix-aaaaaa-aaaa-aaaa-aaaa-aaaaaaaa where 'prefix' is the type prefix (up to 5 characters) and the remaining parts are the base32-encoded UUID with hyphens for readability. The result is always lowercase and contains no padding characters.

func (*XUID) ToUUID

func (x *XUID) ToUUID() string

ToUUID returns the string representation of the underlying UUID in standard UUID format (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx). This is useful when you need the standard UUID representation rather than the XUID format.

func (*XUID) UnmarshalJSON

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

UnmarshalJSON implements the json.Unmarshaler interface for XUID. It allows XUIDs to be directly unmarshaled from JSON string representations.

The JSON value should be a string in valid XUID format or convertible to a valid XUID format through the Parse function.

func (XUID) Value

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

Value implements the driver.Valuer interface for XUID. It returns the string representation of the XUID, which can be directly stored in database fields.

This allows XUIDs to be used directly in database operations without manual type conversion.