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() stringFormat
Section titled “Format”Implements fmt.Formatter: %v/%s render like String(), %#v renders
like GoString(), %d prints numeric values, and %q quotes the
String() output.
func (id ID[B, V]) Format(f fmt.State, verb rune)Optional 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])Sentinel Errors
Section titled “Sentinel Errors”All ID operations return wrapped sentinel errors. Match with errors.Is to branch on error category.
| Sentinel | When it fires |
|---|---|
ErrInvalidID |
ValidateID called on a zero ID |
ErrNotOrdered |
Compare called on a non-ordered type (e.g. float) |
ErrUnsupportedType |
Serialization format doesn’t support value type V |
ErrCannotScan |
SQL Scan source type doesn’t match target V |
ErrInsufficientData |
Binary data too short to decode |
ErrMarshal |
A marshaler (JSON, binary, SQL text) returned error |
ErrUnmarshal |
An unmarshaler (JSON, text, binary) returned error |
ErrNilReceiver |
Method called on nil pointer receiver |
ErrInternal |
Defensive: unreachable type assertion (never fires) |
See the Error Handling guide for usage examples.
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.