identifier

README

identifier

identifier provides strict, immutable UUID, ULID, TypeID, KSUID, and NanoID values, compile-time domain wrappers, and explicit compatibility profiles for derived public identifiers. Each generated family keeps its own clock, entropy, ordering, leakage, and persistence contract; an identifier is never treated as a secret, authorization fact, idempotency proof, or tracing context merely because it is unique.

The minimum toolchain is Go 1.26.6. Random generators use crypto/rand by default and own all mutable state. Tests can inject deterministic clocks and entropy through idtest.

Choose a family

Family	Best fit	Ordering	Exposed time	Random strength
UUIDv4	Standard opaque database/API ID	None	None	122 random bits
UUIDv7	Standard time-local database key	Millisecond, monotonic per generator	Millisecond	74 bits initially
ULID	Existing 26-byte text schemas	Millisecond, monotonic per generator	Millisecond	80 bits initially
TypeID	Human-visible typed UUID values	Prefix then UUIDv7	Millisecond	UUIDv7 contract
KSUID	Existing Segment-compatible values	Second, monotonic per generator	Second	128 bits initially
NanoID	Compact URL-safe random text	None	None	At least 120 configured bits

Read selection guidance before choosing. Sortable generators reveal creation time and may reveal local issuance order.

Quick start

clock := identifier.ClockFunc(time.Now)
generator := uuid.NewV7Generator(clock, nil)
id, err := generator.New()
if err != nil {
    return err
}
fmt.Println(id.String())

There is no package-global generator. Keep one generator per ownership and failure domain, and share that instance only when its monotonic sequence should also be shared.

The slug package is intentionally narrower than a general transliteration library. slug.LaravelEnglish reproduces the frozen Laravel 13 and spatie/laravel-sluggable 4.0.2 English profile needed when an existing public slug contract must survive a service rewrite. Database uniqueness and suffix selection remain application persistence concerns.

Contracts

• Selection
• Guarantees and leakage
• Hardening evidence
• Serialization
• Database behavior
• Migration
• Security
• Performance
• Compatibility
• API map
• Architecture
• FAQ

Development

Run make check for every blocking local gate. make check-all additionally runs advisory NilAway. Fuzzing, race tests, mutation tests, API fingerprints, documentation links, security scans, and comparative benchmarks are independently reproducible targets.

License

MIT. See LICENSE and NOTICE.

Ecosystem

Use the Golib documentation portal to choose companion packages, supported stacks, recipes, and operations guidance.

Documentation

Overview

Package identifier defines contracts shared by concrete identifier families.

Index

• Variables
• type Clock
• type ClockFunc
  • func (clock ClockFunc) Now() time.Time
• type Family
• type Generator
• type ID
  • func Parse[Tag Validator](text string) (ID[Tag], error)
  • func (id ID[Tag]) Compare(other ID[Tag]) int
  • func (id ID[Tag]) IsZero() bool
  • func (id ID[Tag]) LogValue() slog.Value
  • func (id ID[Tag]) MarshalBinary() ([]byte, error)
  • func (id ID[Tag]) MarshalJSON() ([]byte, error)
  • func (id ID[Tag]) MarshalText() ([]byte, error)
  • func (id *ID[Tag]) Scan(src any) error
  • func (id ID[Tag]) String() string
  • func (id *ID[Tag]) UnmarshalBinary(data []byte) error
  • func (id *ID[Tag]) UnmarshalJSON(data []byte) error
  • func (id *ID[Tag]) UnmarshalText(text []byte) error
  • func (id ID[Tag]) Value() (driver.Value, error)
• type Inspection
• type Validator

Examples

• ID

Variables

var (
	// ErrInvalid reports malformed, non-canonical, or disallowed input.
	ErrInvalid = errors.New("invalid identifier")
	// ErrEntropy reports failure while acquiring random bytes.
	ErrEntropy = errors.New("identifier entropy failure")
	// ErrClockRollback reports a clock moving behind supported generator state.
	ErrClockRollback = errors.New("identifier clock rollback")
	// ErrOverflow reports exhausted monotonic or sequence space.
	ErrOverflow = errors.New("identifier sequence overflow")
	// ErrUnsupported reports a valid but unsupported identifier feature.
	ErrUnsupported = errors.New("unsupported identifier")
)

Types

type Clock

type Clock interface {
	Now() time.Time
}

Clock is an explicitly owned time source.

type ClockFunc

type ClockFunc func() time.Time

ClockFunc adapts a function to Clock.

func (ClockFunc) Now

func (clock ClockFunc) Now() time.Time

Now calls the underlying function.

type Family

type Family string

Family identifies an encoding without implying equivalent guarantees.

const (
	// FamilyUUID identifies RFC UUID values.
	FamilyUUID Family = "uuid"
	// FamilyULID identifies canonical ULID values.
	FamilyULID Family = "ulid"
	// FamilyTypeID identifies TypeID values.
	FamilyTypeID Family = "typeid"
	// FamilyKSUID identifies Segment-compatible KSUID values.
	FamilyKSUID Family = "ksuid"
	// FamilyNanoID identifies configured NanoID values.
	FamilyNanoID Family = "nanoid"
)

type Generator

type Generator[T any] interface {
	New() (T, error)
}

Generator produces identifiers without relying on package-global mutable state.

type ID

type ID[Tag Validator] struct {
	// contains filtered or unexported fields
}

ID is a strongly typed canonical identifier. Different Tag arguments are distinct Go types and cannot be mixed without an explicit conversion.

Example

package main

import (
	identifier "github.com/faustbrian/go-identifier"

	identifieruuid "github.com/faustbrian/go-identifier/uuid"
)

func main() {
	// Domain tags validate canonical family text without reflection or a
	// runtime registry. See the package documentation for a complete tag.
	var _ identifier.Generator[identifieruuid.ID] = identifieruuid.NewV4Generator(nil)
}

func Parse

func Parse[Tag Validator](text string) (ID[Tag], error)

Parse validates canonical text for Tag.

func (ID[Tag]) Compare

func (id ID[Tag]) Compare(other ID[Tag]) int

Compare returns -1, 0, or 1 according to canonical lexical ordering.

func (ID[Tag]) IsZero

func (id ID[Tag]) IsZero() bool

IsZero reports whether no identifier has been assigned.

func (ID[Tag]) LogValue

func (id ID[Tag]) LogValue() slog.Value

LogValue redacts the identifier from structured logs. Callers must opt in explicitly with String when an identifier has been approved for logging.

func (ID[Tag]) MarshalBinary

func (id ID[Tag]) MarshalBinary() ([]byte, error)

MarshalBinary uses canonical text so typed values remain family-neutral.

func (ID[Tag]) MarshalJSON

func (id ID[Tag]) MarshalJSON() ([]byte, error)

MarshalJSON encodes the canonical identifier as a JSON string.

func (ID[Tag]) MarshalText

func (id ID[Tag]) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (*ID[Tag]) Scan

func (id *ID[Tag]) Scan(src any) error

Scan implements sql.Scanner for strings, byte slices, and NULL.

func (ID[Tag]) String

func (id ID[Tag]) String() string

String returns canonical text.

func (*ID[Tag]) UnmarshalBinary

func (id *ID[Tag]) UnmarshalBinary(data []byte) error

UnmarshalBinary validates canonical text.

func (*ID[Tag]) UnmarshalJSON

func (id *ID[Tag]) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes and validates a canonical JSON string.

func (*ID[Tag]) UnmarshalText

func (id *ID[Tag]) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

func (ID[Tag]) Value

func (id ID[Tag]) Value() (driver.Value, error)

Value implements driver.Valuer. An unassigned ID is stored as SQL NULL.

type Inspection

type Inspection struct {
	Family    Family
	Version   int
	Timestamp time.Time
	HasTime   bool
	Sortable  bool
}

Inspection exposes only properties actually defined by an identifier family.

type Validator

type Validator interface {
	Validate(string) error
}

Validator validates the canonical text used by a typed ID. Implementations must be usable as their zero value so decoding never needs registration.