ids

Documentation

Overview

Package ids generates time-sortable, globally-unique identifiers (UUIDv7): a 48-bit millisecond timestamp followed by randomness. They sort by creation time, so inserts land at the tail of a database index (tight pages, high cache hit-rate) and they never collide across instances - which matters once records sync across a fleet.

Time and entropy are injectable, so a replay can reproduce the exact same IDs deterministically; the package default uses the system clock and crypto/rand.

Index

• func New() string
• func Token() (string, error)
• type Generator
  • func NewGenerator(opts ...Option) *Generator
  • func (g *Generator) New() string
  • func (g *Generator) Token(nBytes int) (string, error)
• type Option
  • func WithClock(c clock.Clock) Option
  • func WithEntropy(r io.Reader) Option

Functions

func New

func New() string

New returns a new UUIDv7 from the default generator.

func Token

func Token() (string, error)

Token returns an opaque 256-bit bearer secret from the default generator.

Types

type Generator

type Generator struct {
	// contains filtered or unexported fields
}

Generator produces UUIDv7 identifiers from an injectable clock and entropy source. The zero value is not usable; construct one with NewGenerator. It is safe for concurrent use.

func NewGenerator

func NewGenerator(opts ...Option) *Generator

NewGenerator returns a Generator, defaulting to the system clock and crypto/rand.

func (*Generator) New

func (g *Generator) New() string

New returns a new UUIDv7 in canonical 8-4-4-4-12 form.

func (*Generator) Token

func (g *Generator) Token(nBytes int) (string, error)

Token returns an opaque, cryptographically-random secret with nBytes of entropy, URL-safe base64 without padding. Unlike New, it carries no timestamp and is not an identifier: it is a bearer secret (an API token, say), so it is all entropy and reveals nothing about when it was made. A non-positive nBytes uses 256 bits. The entropy comes from the generator's source, so a deterministic source reproduces the token for a replay just as it does for an ID.

type Option

type Option func(*Generator)

Option configures a Generator.

func WithClock

func WithClock(c clock.Clock) Option

WithClock sets the time source (default: clock.System).

func WithEntropy

func WithEntropy(r io.Reader) Option

WithEntropy sets the randomness source (default: crypto/rand). A deterministic reader makes generated IDs reproducible for replay.