idgen

Documentation

Overview

Package idgen provides ID generation utilities:

• Snowflake: Twitter-style distributed unique IDs (microsecond precision)
• UUID v4: random UUIDs (RFC 4122)
• UUID v7: time-ordered UUIDs (RFC 9562)
• ShortID: Base62-encoded compact IDs from snowflake or random bytes
• Ordered UUID: lexicographically sortable UUIDs (ULID-style)

Quick start

// Snowflake (distributed, needs MACHINE_ID env)
id := idgen.SnowflakeNext()        // int64
uid := idgen.SnowflakeNextUint()  // uint (sign-bit cleared)

// UUID
u4 := idgen.UUIDv4()              // "550e8400-e29b-41d4-a716-446655440000"
u7 := idgen.UUIDv7()              // "01905c9e-8a1e-7e3e-9c8a-2b4f8a3d1e5a"

// Short ID (Base62, 10-22 chars)
sid := idgen.ShortID()            // "7B3XkQ9m2P"

// Ordered UUID (sortable, 32 hex chars no dashes)
ouid := idgen.OrderedUUID()       // "01905c9e8a1e1d3e9c8a2b4f8a3d1e5a"

// Random strings
text := idgen.RandText(16)        // "a3b9f2e1c8d7..."
num  := idgen.RandNumberText(6)   // "384726"

Index

• Variables
• func ClampSnowflakeUint(id uint) uint
• func OrderedUUID() string
• func RandNumberText(n int) string
• func RandText(n int) string
• func RandTextWithCharset(n int, charset string) string
• func RandomShortID(length int) string
• func ShortID() string
• func ShortIDFromInt(id uint64) string
• func ShortIDToInt(s string) (uint64, error)
• func SnowflakeNext() int64
• func SnowflakeNextUint() uint
• func UUIDv4() string
• func UUIDv4Bytes() [16]byte
• func UUIDv7() string
• func UUIDv7Bytes() [16]byte
• type Snowflake
  • func NewSnowflake() (*Snowflake, error)
  • func NewSnowflakeWithID(machineID int64) (*Snowflake, error)
  • func (s *Snowflake) NextID() int64

Variables

var ErrInvalidMachineID = errors.New("idgen: machineID out of range")

ErrInvalidMachineID is returned when the machine ID is out of range.

Functions

func ClampSnowflakeUint

func ClampSnowflakeUint(id uint) uint

ClampSnowflakeUint clears the sign bit so IDs remain scannable from signed INTEGER columns.

func OrderedUUID

func OrderedUUID() string

OrderedUUID generates a 32-character hex string (no dashes) that is lexicographically sortable by creation time. The first 12 hex chars encode a 48-bit millisecond timestamp; the remaining 20 hex chars are random. This is similar to ULID but uses hex encoding for simplicity.

Example: "01905c9e8a1e-1d3e9c8a2b4f8a3d1e5a" (without the dash)

func RandNumberText

func RandNumberText(n int) string

RandNumberText generates a random numeric string of length n.

func RandText

func RandText(n int) string

RandText generates a random lowercase-alphanumeric string of length n.

func RandTextWithCharset

func RandTextWithCharset(n int, charset string) string

RandTextWithCharset generates a random string of length n using the provided character set.

func RandomShortID

func RandomShortID(length int) string

RandomShortID generates a random Base62 string of the given length. Use length >= 10 for reasonable collision resistance.

func ShortID

func ShortID() string

ShortID generates a short Base62-encoded ID from a snowflake ID. The result is typically 10-12 characters, URL-safe, and sortable.

func ShortIDFromInt

func ShortIDFromInt(id uint64) string

ShortIDFromInt encodes an arbitrary uint64 into a Base62 short ID.

func ShortIDToInt

func ShortIDToInt(s string) (uint64, error)

ShortIDToInt decodes a Base62 short ID back to uint64.

func SnowflakeNext

func SnowflakeNext() int64

SnowflakeNext returns the next snowflake ID from the package-level generator.

func SnowflakeNextUint

func SnowflakeNextUint() uint

SnowflakeNextUint returns a snowflake ID safe for uint + signed INTEGER stores (e.g. SQLite). Clears the sign bit so values never exceed math.MaxInt64.

func UUIDv4

func UUIDv4() string

UUIDv4 generates a random UUID v4 string in canonical form: "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx" where y is 8, 9, a, or b.

func UUIDv4Bytes

func UUIDv4Bytes() [16]byte

UUIDv4Bytes generates a random UUID v4 as 16 raw bytes.

func UUIDv7

func UUIDv7() string

UUIDv7 generates a time-ordered UUID v7 string. The first 48 bits encode a Unix timestamp in milliseconds, making UUIDs lexicographically sortable by creation time. The remaining bits are random.

func UUIDv7Bytes

func UUIDv7Bytes() [16]byte

UUIDv7Bytes generates a time-ordered UUID v7 as 16 raw bytes.

Types

type Snowflake

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

Snowflake is a Twitter-style snowflake ID generator with microsecond precision, 10-bit machine ID, and 9-bit sequence.

func NewSnowflake

func NewSnowflake() (*Snowflake, error)

NewSnowflake creates a snowflake generator using the MACHINE_ID env var (defaults to 1 when unset or invalid). Machine ID must be in [0, 1023].

func NewSnowflakeWithID

func NewSnowflakeWithID(machineID int64) (*Snowflake, error)

NewSnowflakeWithID creates a snowflake generator with an explicit machine ID.

func (*Snowflake) NextID

func (s *Snowflake) NextID() int64

NextID returns the next 64-bit snowflake ID. Returns 0 on clock rollback.