Package kid (K-sortable ID) provides a goroutine-safe generator of short (10 byte binary, 16 bytes when base32 encoded), url-safe, k-sortable unique IDs.
Encoded IDs look like:
06hbcv4y3d9df8yt
go get github.com/mwyvr/kid/v2
import "github.com/mwyvr/kid/v2"
func main() {
id := kid.New()
fmt.Printf("%s %03v\n", id, id[:])
// Example output: 06bq7xhnr03mlz6r [001 149 115 246 021 192 007 073 252 216]
id, err := kid.Parse("06bq7xhnr03mlz6r")
if err != nil {
// handle the error
}
fmt.Printf("%s %03v\n", id, id[:])
// Output: 06bq7xhnr03mlz6r [001 149 115 246 021 192 007 073 252 216]
}Notes on v2:
- kid's v2 exported API is considered complete. The 80-bit layout and the text encoding are fixed.
- kid v2 will decode kid v1 IDs into the same binary representation and timestamp values, but sequence and random ID segments are not comparable between v1 and v2.
- Importing
github.com/mwyvr/kid(no /v2) resolves to the old v1.x line.
- 10 bytes binary, 16 bytes encoded. No dependencies outside the standard library. Requires Go 1.24+.
- Timestamp + sequence unique and strictly increasing per process, even if the wall clock steps backwards.
- Lock-free, allocation-free generation; no mutex in the New() path.
- K-orderable in both binary and encoded form.
- URL-friendly encoding without the vowels a, i, o, and u.
- (Un)marshalling for SQL, JSON, text, and binary.
cmd/kidfor generation and introspection.
Uniqueness is per process; two processes landing on the same timestamp+sequence are separated only by 20 bits of randomness (1 in 1,048,576). See DESIGN.md for the byte layout, capacity limits, and how to verify the claims yourself.
Security note: an ID carries only 20 bits of randomness alongside values derived from the clock; IDs are predictable by design. Do not use kid IDs where unguessability matters — session tokens, API keys, password reset codes.
$ kid
06hb42zvde2y9csj
$ kid -c 2
06hb42zvdkce6e6y
06hb42zvdktcjhwmkid <id> decodes and inspects; echo <id> | kid decodes from stdin.
go install github.com/mwyvr/kid/v2/cmd/kid@latest
- CHANGELOG.md — release history.
- DESIGN.md — byte layout, v1/v2 rationale, uniqueness guarantees, package comparisons.
- eval/bench/BENCHMARKS.md — benchmark numbers; run the suite yourself in eval/bench.
The API borrows from github.com/rs/xid. The lock-free ts+seq mechanism derives from google/uuid's getV7Time(). Third-party license texts are in NOTICES.