Skip to content
mwyvrPublic

About

Package kid provides a performant, goroutine-safe generator of short, url-safe, k-sortable unique IDs suitable for situations where inter-process ID generation coordination is not required.

Resources

Stars

0 stars

Watchers

1 watching

Forks

Repository files navigation

GitHub go.mod Go version godoc Test codecov License: MIT

kid

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

Install

go get github.com/mwyvr/kid/v2

Usage

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.

Features

  • 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/kid for 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.

CLI

$ kid
06hb42zvde2y9csj

$ kid -c 2
06hb42zvdkce6e6y
06hb42zvdktcjhwm

kid <id> decodes and inspects; echo <id> | kid decodes from stdin.

go install github.com/mwyvr/kid/v2/cmd/kid@latest

More

Acknowledgments

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.

About

Package kid provides a performant, goroutine-safe generator of short, url-safe, k-sortable unique IDs suitable for situations where inter-process ID generation coordination is not required.

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages