typeid.uuid — io.github.unisoma/typeid 0.3.0

UUID utility functions for TypeID library.

Provides cross-platform utilities for working with UUID objects:

• Convert UUIDs to/from byte arrays
• Generate UUIDv7 (timestamp-ordered UUIDs)

All functions work with platform-native UUID types:

• JVM: java.util.UUID
• ClojureScript: cljs.core/UUID

Examples:

;; Convert UUID to bytes (uuid->bytes #uuid "018c3f9e-9e4e-7a8a-8b2a-7e8e9e4e7a8a") ;; => #object["[B" ...] (16-byte array)

;; Convert bytes to UUID (bytes->uuid (uuid->bytes my-uuid)) ;; => #uuid "018c3f9e-9e4e-7a8a-8b2a-7e8e9e4e7a8a"

;; Generate new UUIDv7 bytes and convert to UUID object (bytes->uuid (generate-uuidv7)) ;; => #uuid "018d5e9e-..." (timestamp-based)

;; Use with TypeID (require '[typeid.core :as typeid]) (typeid/create "user" (bytes->uuid (generate-uuidv7))) ;; => "user_01h455vb4pex5vsknk084sn02q"

bytes->uuid clj/s

(bytes->uuid uuid-bytes)

Convert a 16-byte array to a platform-native UUID object.

Accepts:

• JVM: byte array (byte[])
• ClojureScript: Uint8Array

Returns platform-native UUID object:

• JVM: java.util.UUID
• ClojureScript: cljs.core/UUID

This is the inverse operation of uuid->bytes.

Examples:

;; JVM
(bytes->uuid (byte-array [0x01 0x8c 0x3f 0x9e 0x9e 0x4e 0x7a 0x8a
                           0x8b 0x2a 0x7e 0x8e 0x9e 0x4e 0x7a 0x8a]))
;; => #uuid "018c3f9e-9e4e-7a8a-8b2a-7e8e9e4e7a8a"

;; ClojureScript
(bytes->uuid (js/Uint8Array. [0x01 0x8c 0x3f 0x9e 0x9e 0x4e 0x7a 0x8a
                               0x8b 0x2a 0x7e 0x8e 0x9e 0x4e 0x7a 0x8a]))
;; => #uuid "018c3f9e-9e4e-7a8a-8b2a-7e8e9e4e7a8a"

;; Round-trip property
(= uuid (-> uuid uuid->bytes bytes->uuid)) ; => true

Throws if input is not exactly 16 bytes.

generate-uuidv7 clj/s

(generate-uuidv7)

Generate UUIDv7 (RFC 9562) bytes with timestamp-based ordering.

UUIDv7 structure:

• Bytes 0-5: Unix timestamp in milliseconds (48 bits)
• Byte 6: Version bits (4 bits = 0111 for v7) + random (12 bits)
• Byte 8: Variant bits (2 bits = 10) + random (6 bits)
• Bytes 9-15: Random data (56 bits)

Returns a 16-byte array in UUID format:

• JVM: byte[] (primitive byte array)
• ClojureScript: Uint8Array

Each call produces unique bytes with chronological sortability. Later calls will have higher timestamp values.

Examples:

;; JVM: Generate UUIDv7 bytes
(generate-uuidv7)
;; => #object["[B" 0x...] (16 bytes)

;; ClojureScript: Generate UUIDv7 bytes
(generate-uuidv7)
;; => #object[Uint8Array [1 140 63 ...]] (16 bytes)

;; Convert to UUID object
(bytes->uuid (generate-uuidv7))
;; => #uuid "018d5e9e-9e4e-7a8a-8b2a-7e8e9e4e7a8a"

;; Use with TypeID
(require '[typeid.core :as typeid])
(typeid/create "order" (bytes->uuid (generate-uuidv7)))
;; => "order_01h455vb4pex5vsknk084sn02q"

The generated bytes conform to UUIDv7 spec and are chronologically sortable.

uuid->bytes clj/s

(uuid->bytes uuid)

Convert a platform-native UUID object to a 16-byte array.

Accepts:

• JVM: java.util.UUID
• ClojureScript: cljs.core/UUID

Returns 16-byte array representation of the UUID:

• JVM: byte[] (primitive byte array)
• ClojureScript: Uint8Array

The byte array is always exactly 16 bytes in big-endian order.

Examples:

;; JVM
(uuid->bytes #uuid "018c3f9e-9e4e-7a8a-8b2a-7e8e9e4e7a8a")
;; => #object["[B" 0x...] (16-byte array)

;; ClojureScript
(uuid->bytes #uuid "018c3f9e-9e4e-7a8a-8b2a-7e8e9e4e7a8a")
;; => #object[Uint8Array [1 140 63 158 158 78 122 138 139 42 126 142 158 78 122 138]]

;; Use with TypeID
(require '[typeid.core :as typeid])
(let [tid (typeid/create "user")
      parsed (typeid/parse tid)
      uuid (:uuid parsed)]
  (uuid->bytes uuid))
;; => #object["[B" ...] (16 bytes)

Throws ex-info with type :typeid/invalid-uuid if input is not a valid UUID object.