com.github.franks42.uuidv7.core — com.github.franks42/uuidv7 0.5.0

Portable UUIDv7 generator for Clojure, ClojureScript, Babashka, nbb, and scittle.

Implements RFC 9562 Section 6.2 Method 3 (monotonic random):

• 48-bit millisecond Unix timestamp
• 74-bit monotonically increasing random counter
• Sub-millisecond ordering guaranteed from a single generator
• No blocking, no spinning, no overflow in practice

Usage: (require '[com.github.franks42.uuidv7.core :as uuidv7]) (uuidv7/uuidv7) ;=> #uuid "0195xxxx-xxxx-7xxx-xxxx-xxxxxxxxxxxx"

;; Extract embedded data: (uuidv7/extract-ts u) ;=> 1738934578991 (ms since epoch) (uuidv7/extract-inst u) ;=> #inst "2025-02-07..." (as Date) (uuidv7/extract-key u) ;=> [ts a bh bl] (sortable composite key)

The 74-bit counter space (~1.9 * 10^22 values per millisecond) is effectively inexhaustible. On each new millisecond the counter reseeds with fresh random bits. Within the same millisecond it increments by a random amount (1 to 2^31), preserving both monotonicity and unpredictability.

UUID Validation

The extraction functions (extract-ts, extract-counter, extract-key, extract-inst) require a UUIDv7. Use uuidv7? to validate first:

(when (uuidv7/uuidv7? u) (uuidv7/extract-ts u)) ;=> Safe to call after validation

Passing a non-v7 UUID to an extraction function will throw an AssertionError.

extract-counter clj/s

(extract-counter uuid)

Extract the 74-bit monotonic counter from a UUIDv7 as a three-element vector [rand-a rand-b-hi rand-b-lo] (12 + 30 + 32 bits).

The vector compares lexicographically, preserving the same total order as the original UUID. Suitable as a composite key component: [(extract-ts u) (extract-counter u)]

Consistent shape on all platforms (JVM and JS).

Throws AssertionError if the UUID is not version 7.

extract-inst clj/s

(extract-inst uuid)

Extract the creation timestamp from a UUIDv7 as a Date/inst. Useful for logging, auditing, and debugging.

Throws AssertionError if the UUID is not version 7.

extract-key clj/s

(extract-key uuid)

Extract a sortable composite key [ts rand-a rand-b-hi rand-b-lo] from a UUIDv7.

The four-element vector compares lexicographically with the same total order as the original UUID. Useful when you want the (timestamp, counter) tuple as a map key or sort key without carrying the UUID itself.

Throws AssertionError if the UUID is not version 7.

extract-ts clj/s

(extract-ts uuid)

Extract the Unix epoch timestamp (milliseconds) from a UUIDv7. Works with any UUID type or UUID string.

Throws AssertionError if the UUID is not version 7.

make-generator clj/s

(make-generator)

Create an independent UUIDv7 generator with its own monotonic state. Returns a zero-argument function that produces UUIDv7s.

Useful when you need multiple independent monotonic sequences, e.g. per-subsystem or per-thread dedicated generators.

uuidv7 clj/s

(uuidv7)

Generate a UUIDv7 with monotonic sub-millisecond ordering.

Returns java.util.UUID on JVM/BB, cljs.core/UUID on CLJS/nbb/scittle.

Successive calls from the same generator are guaranteed to produce strictly increasing UUIDs, even within the same millisecond.

uuidv7? clj/s

(uuidv7? uuid)

Check if a UUID is version 7 (timestamp-first). Accepts UUID objects, strings, or any type that can be converted to string.