API Reference
Core Type
Section titled “Core Type”A branded identifier wrapping a value of type V, branded by phantom type B.
type ID[B any, V comparable] struct { // contains filtered or unexported fields}Constructors
Section titled “Constructors”Creates a new branded ID. For strings, the value type is inferred.
func NewID[B any, V comparable](v V) ID[B, V]Core Methods
Section titled “Core Methods”Returns the underlying value.
func (id ID[B, V]) Get() VIsZero
Section titled “IsZero”Returns true if the ID has its zero value (unset).
func (id ID[B, V]) IsZero() boolSets the ID to its zero value.
func (id ID[B, V]) Reset()Returns true if both IDs have the same value. Both must be the same brand and value type.
func (id ID[B, V]) Equal(other ID[B, V]) boolCompare
Section titled “Compare”Returns -1, 0, or 1 for ordered comparison. Only supports ordered types (int/uint/string families). Returns ErrNotOrdered for other types.
func (id ID[B, V]) Compare(other ID[B, V]) (int, error)Returns the ID itself if not zero, otherwise returns the provided default.
func (id ID[B, V]) Or(defaultID ID[B, V]) ID[B, V]Formatting
Section titled “Formatting”String
Section titled “String”Returns "Brand:value" for named brands, or just the value for unnamed brands. For display only.
func (id ID[B, V]) String() stringGoString
Section titled “GoString”Returns id.Brand(value) for debugging. Display format, not valid Go syntax.
func (id ID[B, V]) GoString() stringOptional Fields
Section titled “Optional Fields”Returns a pointer to the ID. Useful for optional struct fields.
func (id ID[B, V]) Ptr() *ID[B, V]FromPtr
Section titled “FromPtr”Dereferences a pointer to an ID. Returns zero value if the pointer is nil.
func FromPtr[B any, V comparable](ptr *ID[B, V]) ID[B, V]Serialization
Section titled “Serialization”| Method | Interface |
|---|---|
MarshalJSON() |
json.Marshaler |
UnmarshalJSON([]byte) |
json.Unmarshaler |
MarshalText() |
encoding.TextMarshaler |
UnmarshalText([]byte) |
encoding.TextUnmarshaler |
MarshalBinary() |
encoding.BinaryMarshaler |
UnmarshalBinary([]byte) |
encoding.BinaryUnmarshaler |
GobEncode() |
gob.GobEncoder |
GobDecode([]byte) |
gob.GobDecoder |
Scan(any) |
sql.Scanner |
Value() |
driver.Valuer |
Brand Utilities
Section titled “Brand Utilities”BrandName
Section titled “BrandName”Returns the brand name. Calls Name() if the brand implements BrandNamer, otherwise returns fmt.Sprintf("%T", brand).
func BrandName[B any]() stringValidateID
Section titled “ValidateID”Returns an error if the ID is zero. Error message includes the brand name for named brands.
func ValidateID[B any, V comparable](id ID[B, V]) errorValidateIDWithValue
Section titled “ValidateIDWithValue”Validates that the ID is non-zero, then calls the provided validator function on the value.
func ValidateIDWithValue[B any, V comparable](id ID[B, V], validate func(V) error) errorMustValidateID
Section titled “MustValidateID”Panics if the ID is zero. For init-time checks.
func MustValidateID[B any, V comparable](id ID[B, V])API Summary
Section titled “API Summary”| Symbol | Description |
|---|---|
ID[B, V] |
Phantom-typed identifier |
NewID[B, V](v) |
Constructor |
Get() |
Raw value accessor |
IsZero() / Reset() |
Zero value semantics |
Equal(other) |
Type-safe equality |
Compare(other) |
Ordered comparison |
Or(default) |
Fallback for zero values |
String() / GoString() |
Display formatting |
Ptr() / FromPtr() |
Optional field helpers |
BrandName[B]() |
Brand name introspection |
ValidateID(id) |
Zero-value validation |
ValidateIDWithValue(id, fn) |
Custom value validation |
MustValidateID(id) |
Panicking validation |
Full API on pkg.go.dev
Section titled “Full API on pkg.go.dev”For the complete, always-up-to-date API documentation, see pkg.go.dev.