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
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 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.
func RandTextWithCharset ¶
RandTextWithCharset generates a random string of length n using the provided character set.
func RandomShortID ¶
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 ¶
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 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 ¶
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.
Source Files