idgen

package module
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 3, 2026 License: MIT Imports: 11 Imported by: 0

README

idgen

ID generation utilities: Snowflake, UUID v4/v7, ShortID (Base62), Ordered UUID, and random strings.

Features

  • Snowflake: Twitter-style distributed unique IDs (microsecond precision, 10-bit machine ID)
  • 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 (ULID-style, 32 hex chars)
  • Random text and numeric strings

Key types

  • Snowflake -- snowflake ID generator (machine ID from MACHINE_ID env var)

Key functions

  • SnowflakeNext() / SnowflakeNextUint() -- package-level snowflake IDs
  • NewSnowflake() / NewSnowflakeWithID(machineID) -- custom generator
  • UUIDv4() / UUIDv4Bytes() -- random UUID
  • UUIDv7() / UUIDv7Bytes() -- time-ordered UUID
  • OrderedUUID() -- sortable 32-char hex string
  • ShortID() / ShortIDFromID(id) -- Base62 short ID
  • RandText(n) / RandNumberText(n) -- random strings

Quick start

import "github.com/LingByte/ling-base/common/idgen"

id := idgen.SnowflakeNext()       // int64
uid := idgen.SnowflakeNextUint()  // uint (sign-bit cleared)

u4 := idgen.UUIDv4()   // "550e8400-e29b-41d4-a716-446655440000"
u7 := idgen.UUIDv7()   // time-ordered
sid := idgen.ShortID() // "7B3XkQ9m2P"
ouid := idgen.OrderedUUID() // sortable hex

License

MIT

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

Constants

This section is empty.

Variables

View Source
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 NanoID added in v0.2.0

func NanoID(size int) string

NanoID generates a NanoID string of the given size using the default URL-safe alphabet. If size <= 0 the default size (21) is used.

Example: "V1StGXR8_Z5jdHi6B-myT"

func NanoIDWithAlphabet added in v0.2.0

func NanoIDWithAlphabet(size int, alphabet string) string

NanoIDWithAlphabet generates a NanoID string of the given size using a custom alphabet. The alphabet must be non-empty; if it is empty the default alphabet is used instead.

The implementation uses crypto/rand to securely select characters from the alphabet, avoiding modulo bias by masking random bytes.

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.

Delegates to random.NumericString.

func RandText

func RandText(n int) string

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

Delegates to random.StringWithCharset with the digits+lowercase charset.

func RandTextWithCharset

func RandTextWithCharset(n int, charset string) string

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

Delegates to random.StringWithCharset.

func RandomShortID

func RandomShortID(length int) string

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

Delegates to random.StringWithCharset with CharsetBase62, which uses rejection sampling to avoid modulo bias.

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 ULID added in v0.2.0

func ULID() string

ULID generates a 26-character Crockford Base32 encoded ULID (Universally Unique Lexicographically Sortable Identifier).

The first 10 characters encode a 48-bit Unix millisecond timestamp, making ULIDs lexicographically sortable by creation time. The remaining 16 characters are 80 bits of cryptographic randomness.

Example: "01ARZ3NDEKTSV4RRFFQ69G5FAV"

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.

Delegates to random.UUID for the underlying implementation.

func UUIDv4Bytes

func UUIDv4Bytes() [16]byte

UUIDv4Bytes generates a random UUID v4 as 16 raw bytes.

Delegates to random.UUIDBytes for the underlying implementation.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL