kid

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.

The 10-byte binary representation of an ID is composed of:

• 6-byte value representing Unix time in milliseconds
• 2-byte sequence, and,
• 2-byte random value.

IDs encode (base32) as 16-byte url-friendly strings that look like:

06bqj05bhh2lcbdb

kid.ID features

• Size: 10 bytes as binary, 16 bytes if stored/transported as an encoded string.
• Timestamp + sequence is guaranteed to be unique for each call to New().
• 2 bytes of trailing randomness to avoid counter-based attacks.
• K-orderable in both binary and base32 encoded representations.
• URL-friendly custom encoding without the vowels a, i, o, and u.
• Automatic (un)/marshalling for SQL and JSON.
• cmd/kid tool for ID generation and introspection.

Example usage

func main() {
    id := kid.New()
	  fmt.Printf("%s %s %03v\n", id, id.String(), id[:])
	  // Example output: 06bq7xhnr03mlz6r 06bq7xhnr03mlz6r [001 149 115 246 021 192 007 073 252 216]

	  id, err := kid.FromString("06bq7xhnr03mlz6r")
	  if err != nil {
	  	// do something
	  }
	  fmt.Printf("%s %s %03v\n", id, id.String(), id[:])
	  // Output: 06bq7xhnr03mlz6r 06bq7xhnr03mlz6r [001 149 115 246 021 192 007 073 252 216]
}

Acknowledgments

• While the ID payload differs greatly, the API and much of this package borrows heavily from github.com/rs/xid, a zero-configuration globally-unique ID generator.

• Unique timestamp+sequence pairs are generated by the github.com/google/uuid getV7Time() algorithm.

Uniqueness

Each call to kid.New() is guaranteed to return a unique ID with a timestamp+sequence greater than any previous call.

To satisfy whether kid.IDs are unique, run eval/uniqcheck/main.go:

$ go run eval/uniqcheck/main.go -count 2000000 -goroutines 20
# example  output:
Generating 2,000,000 IDs per 20 goroutines:
Total keys: 40,000,000. Keys in last time tick: 1,380. Number of dupes: 0

Or, at the command line, produce IDs and use OS utilities to check (single-threaded):

$ go install github.com/mwyvr/kid/cmd/kid@latest
$ kid -c 2000000 | sort | uniq -d
// None output

CLI

Package kid also provides a tool for id generation and inspection:

$ kid
06bpwm8x107evvh9

$ kid -c 2
06bpwm3hkm371gz4
06bpwm3hkm3d5ezr

# produce 4 and inspect
kid $(kid -c 4)
06bpwlvhb86bypp7 ts:1741312454738 seq:3247 rnd:23239 2025-03-07 01:54:14.738 +0000 UTC ID{  0x1, 0x95, 0x6e, 0x4f, 0x70, 0x52,  0xc, 0xaf, 0x5a, 0xc7 }
06bpwlvhb86gcdw6 ts:1741312454738 seq:3317 rnd:45958 2025-03-07 01:54:14.738 +0000 UTC ID{  0x1, 0x95, 0x6e, 0x4f, 0x70, 0x52,  0xc, 0xf5, 0xb3, 0x86 }
06bpwlvhb86gkmks ts:1741312454738 seq:3320 rnd:53817 2025-03-07 01:54:14.738 +0000 UTC ID{  0x1, 0x95, 0x6e, 0x4f, 0x70, 0x52,  0xc, 0xf8, 0xd2, 0x39 }
06bpwlvhb86gmb73 ts:1741312454738 seq:3322 rnd:10467 2025-03-07 01:54:14.738 +0000 UTC ID{  0x1, 0x95, 0x6e, 0x4f, 0x70, 0x52,  0xc, 0xfa, 0x28, 0xe3 }

Change Log

• 2025-03-24 Drop minimum supported Go version to 1.23, thanks to heads up from @sergeevabc.
• 2025-03-08 v1.2.0 released.
• 2025-03-06 Forked rid in favour of kid for true k-sortability, requiring a new ID payload, now expected to remain static. Improved code coverage and documentation.

Contributing

Contributions are welcome.

Package Comparisons

kid was born out of a desire for a short, k-sortable unique ID where global uniqueness or inter-process ID generation coordination is not required.

A comparison of various Go ID generators:

Package Benchmarks

A benchmark suite comparing some of the above-noted packages can be found in eval/bench/bench_test.go. All runs were done with scaling_governor set to performance:

echo "performance" | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor

$ go test -cpu 1,2,4,8,16,32 -test.benchmem -bench .
goos: linux
goarch: amd64
pkg: github.com/mwyvr/kid/eval/bench
cpu: Intel(R) Core(TM) i9-14900K
BenchmarkKid                	25668646	       44.42 ns/op	      0 B/op	      0 allocs/op
BenchmarkKid-2              	24071296	       50.45 ns/op	      0 B/op	      0 allocs/op
BenchmarkKid-4              	15894621	       75.01 ns/op	      0 B/op	      0 allocs/op
BenchmarkKid-8              	12931524	       95.28 ns/op	      0 B/op	      0 allocs/op
BenchmarkKid-16             	10273124	      114.5 ns/op	      0 B/op	      0 allocs/op
BenchmarkKid-32             	8641492	      138.6 ns/op	      0 B/op	      0 allocs/op
BenchmarkXid                	39413270	       28.53 ns/op	      0 B/op	      0 allocs/op
BenchmarkXid-2              	42305062	       27.39 ns/op	      0 B/op	      0 allocs/op
BenchmarkXid-4              	42286348	       27.95 ns/op	      0 B/op	      0 allocs/op
BenchmarkXid-8              	40082140	       29.77 ns/op	      0 B/op	      0 allocs/op
BenchmarkXid-16             	36853810	       32.59 ns/op	      0 B/op	      0 allocs/op
BenchmarkXid-32             	58261640	       21.51 ns/op	      0 B/op	      0 allocs/op
BenchmarkKsuid              	15683168	       75.23 ns/op	      0 B/op	       0 allocs/op
BenchmarkKsuid-2            	14172432	       84.61 ns/op	      0 B/op	       0 allocs/op
BenchmarkKsuid-4            	11290425	      101.4 ns/op	      0 B/op	       0 allocs/op
BenchmarkKsuid-8            	9389043	      119.3 ns/op	      0 B/op	       0 allocs/op
BenchmarkKsuid-16           	7758454	      153.2 ns/op	      0 B/op	       0 allocs/op
BenchmarkKsuid-32           	6843870	      181.9 ns/op	      0 B/op	       0 allocs/op
BenchmarkGoogleUuid         	24592844	       47.72 ns/op	     16 B/op	       1 allocs/op
BenchmarkGoogleUuid-2       	29907156	       37.78 ns/op	     16 B/op	       1 allocs/op
BenchmarkGoogleUuid-4       	36956997	       31.78 ns/op	     16 B/op	       1 allocs/op
BenchmarkGoogleUuid-8       	44705392	       29.42 ns/op	     16 B/op	       1 allocs/op
BenchmarkGoogleUuid-16      	38979994	       33.91 ns/op	     16 B/op	       1 allocs/op
BenchmarkGoogleUuid-32      	43177587	       28.15 ns/op	     16 B/op	       1 allocs/op
BenchmarkGoogleUuidV7       	14226376	       83.90 ns/op	     16 B/op	       1 allocs/op
BenchmarkGoogleUuidV7-2     	12127534	       89.25 ns/op	     16 B/op	       1 allocs/op
BenchmarkGoogleUuidV7-4     	12975457	       92.48 ns/op	     16 B/op	       1 allocs/op
BenchmarkGoogleUuidV7-8     	12842493	       95.62 ns/op	     16 B/op	       1 allocs/op
BenchmarkGoogleUuidV7-16    	10053843	      119.1 ns/op	     16 B/op	       1 allocs/op
BenchmarkGoogleUuidV7-32    	7877816	      152.3 ns/op	     16 B/op	       1 allocs/op
BenchmarkUlid               	19653237	       60.15 ns/op	     16 B/op	       1 allocs/op
BenchmarkUlid-2             	29194627	       39.72 ns/op	     16 B/op	       1 allocs/op
BenchmarkUlid-4             	42736906	       29.85 ns/op	     16 B/op	       1 allocs/op
BenchmarkUlid-8             	38114436	       30.23 ns/op	     16 B/op	       1 allocs/op
BenchmarkUlid-16            	39977670	       34.00 ns/op	     16 B/op	       1 allocs/op
BenchmarkUlid-32            	41136363	       28.09 ns/op	     16 B/op	       1 allocs/op
BenchmarkBetterguid         	25478740	       46.51 ns/op	     24 B/op	       1 allocs/op
BenchmarkBetterguid-2       	24268438	       47.96 ns/op	     24 B/op	       1 allocs/op
BenchmarkBetterguid-4       	18773090	       64.66 ns/op	     24 B/op	       1 allocs/op
BenchmarkBetterguid-8       	14096698	       81.05 ns/op	     24 B/op	       1 allocs/op
BenchmarkBetterguid-16      	10897140	      110.5 ns/op	     24 B/op	       1 allocs/op
BenchmarkBetterguid-32      	9171368	      132.2 ns/op	     24 B/op	       1 allocs/op
PASS
ok  	github.com/mwyvr/kid/eval/bench	53.240s