buid: universally unique lexicographically sortable identifiers

8.16.0.4

buid: universally unique lexicographically sortable identifiers🔗ℹ

This package provides an implementation of flake ids that are lexicographically-sortable and highly unlikely to collide in a distributed system.

BUIDs can (and are meant to!) be safely stored inside a PostgreSQL UUID field.

1 Spec🔗ℹ

A BUID is made up of a 40 bit time component and an 88 bit randomness component. The time component represents the current number of centiseconds since the UNIX timestamp 1586026830000.

BUIDs are represented as 22 character strings where the first 7 characters represent the 0-padded time component encoded in base 62 and the remaining 15 characters represent the 0-padded randomness component encoded in base 62.

The randomness component must have its most significant bit initially set to 0 and all ids generated within the same centisecond must increase monotonically.

In binary, BUIDs are represented as 16 bytes, encoded in network order.

2 Reference🔗ℹ

value
buid/c : string?

Represents a BUID string.

value
buid-bytes/c : bytes?

Represents the binary representation of a BUID.

procedure
(make-buid-factory) → (-> (and/c buid/c immutable?))

Returns a function that can be used to generate BUIDs. Any BUIDs generated within the same centisecond by the resulting function will increase monotonically.

The generator functions are thread-safe.

procedure
(buid) → (-> (and/c buid/c immutable?))

Generates an BUID.

> (require buid)
> (for ([_ (in-range 10)]) (displayln (buid)))
0HCXjus7NQn9xGsGCJemRX
0HCXjus7NQn9xGsGCJemRY
0HCXjus7NQn9xGsGCJemRZ
0HCXjus7NQn9xGsGCJemRa
0HCXjus7NQn9xGsGCJemRb
0HCXjus7NQn9xGsGCJemRc
0HCXjus7NQn9xGsGCJemRd
0HCXjus7NQn9xGsGCJemRe
0HCXjus7NQn9xGsGCJemRf
0HCXjus7NQn9xGsGCJemRg

procedure
(buid-time s) → exact-nonnegative-integer?
s : buid/c

Returns the time component of the BUID s.

procedure
(buid-posix-time s) → exact-nonnegative-integer?
s : buid/c

Returns the time component of the BUID s, adjusted to a POSIX timestamp in milliseconds.

procedure
(buid-randomness s) → exact-nonnegative-integer?
s : buid/c

Returns the random component of the BUID s.

procedure
(buid->bytes u) → buid-bytes/c
u : buid/c

Returns the binary representation of the BUID u.

procedure
(bytes->buid bs) → buid/c
bs : buid-bytes/c

Converts bs to a BUID. Raises an error if the result is not a valid BUID.

procedure
(buid->uuid b) → string?
b : buid/c

Returns the UUID representation of b.

Added in version 1.2 of package buid-lib.

procedure
(uuid->buid s) → buid/c
s : string?

Returns the BUID representation of the UUID s.

Added in version 1.2 of package buid-lib.