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 NanoID(size int) string
- func NanoIDWithAlphabet(size int, alphabet string) string
- 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 ULID() string
- func UUIDv4() string
- func UUIDv4Bytes() [16]byte
- func UUIDv7() string
- func UUIDv7Bytes() [16]byte
- type Snowflake
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidMachineID = errors.New("idgen: machineID out of range")
ErrInvalidMachineID is returned when the machine ID is out of range.
Functions ¶
func ClampSnowflakeUint ¶
ClampSnowflakeUint clears the sign bit so IDs remain scannable from signed INTEGER columns.
func NanoID ¶ added in v0.2.0
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
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 ¶
RandNumberText generates a random numeric string of length n.
Delegates to random.NumericString.
func RandText ¶
RandText generates a random lowercase-alphanumeric string of length n.
Delegates to random.StringWithCharset with the digits+lowercase charset.
func RandTextWithCharset ¶
RandTextWithCharset generates a random string of length n using the provided character set.
Delegates to random.StringWithCharset.
func RandomShortID ¶
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 ¶
ShortIDFromInt encodes an arbitrary uint64 into a Base62 short ID.
func ShortIDToInt ¶
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 ¶
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 ¶
NewSnowflakeWithID creates a snowflake generator with an explicit machine ID.