com.vadelabs.uid.interface — com.vadelabs/uid 2025.11.13-29

Unified interface for unique identifier generation.

This namespace provides a curated, client-friendly API exposing the most commonly used UUID and Flake operations. For advanced features and low-level operations, use the core namespaces directly:

• com.vadelabs.uid.uuid.core for UUID internals
• com.vadelabs.uid.flake.core for Flake internals

Quick Start - UUID

(require '[com.vadelabs.uid.interface :as uid])

;; Random UUID (most common)
(uid/v4)  ;=> #uuid "550e8400-e29b-41d4-a716-446655440000"

;; Time-ordered, sortable UUID (recommended for databases)
(uid/v7)  ;=> #uuid "01890a5d-ac96-774b-bcce-b302099a8057"

;; Name-based UUID (deterministic)
(uid/v5 uid/+namespace-dns+ "example.com")

Quick Start - Flake

;; Generate Flake (192-bit, nanosecond precision)
(uid/flake)  ;=> #flake/id "56S2f9LfyJJ52sY7JJuWL-etkrr2OBOC"

;; Generate as string directly
(uid/snowflake)  ;=> "56S2f9Lg0JJ52sY7JJuWL-etkrr2OBOC"

Design Philosophy

This interface exposes:

• ✓ High-frequency operations (generation, parsing, comparison)
• ✓ Essential metadata extraction (timestamps from time-based IDs)
• ✗ Low-level bit manipulation (use core namespaces)
• ✗ Rarely-used UUID versions (v0, v8, squuid)
• ✗ Internal implementation details

+namespace-dns+ clj

+namespace-oid+ clj

+namespace-url+ clj

+namespace-x500+ clj

< clj

(< _)

(< x y)

(< x y & more)

Compare UUIDs for < relation (lexical ordering).

Example: (< (v7) (v7)) ;=> true (time-ordered)

= clj

(= _)

(= x y)

(= x y & more)

Compare UUIDs for equality. Can be used with multiple UUIDs.

Example: (= (v4) (v4)) ;=> false (different random UUIDs) (= (v5 +namespace-dns+ "x") (v5 +namespace-dns+ "x")) ;=> true

> clj

(> _)

(> x y)

(> x y & more)

Compare UUIDs for > relation (lexical ordering).

as-uuid clj

(as-uuid x)

Parse or coerce value to UUID. Supports UUID strings, URN strings, and byte arrays.

Example: (as-uuid "550e8400-e29b-41d4-a716-446655440000") ;=> #uuid "550e8400-e29b-41d4-a716-446655440000"

(as-uuid "urn:uuid:550e8400-e29b-41d4-a716-446655440000") ;=> #uuid "550e8400-e29b-41d4-a716-446655440000"

flake clj

(flake)

Generate a new 192-bit time-ordered unique identifier with nanosecond precision.

Flakes are monotonically increasing and lexically sortable. Ideal for distributed systems requiring nanosecond-precision timestamps and high uniqueness guarantees.

Example: (flake) ;=> #flake/id "56S2f9LfyJJ52sY7JJuWL-etkrr2OBOC"

flake-time clj

(flake-time f)

Extract the nanosecond timestamp from a Flake.

Returns nanoseconds since Unix epoch (January 1, 1970 00:00:00 UTC).

Example: (flake-time (flake)) ;=> 1720626645123456789

flake? clj

(flake? x)

Check if value is a Flake.

Example: (flake? (flake)) ;=> true (flake? "not-a-flake") ;=> false

get-instant clj

(get-instant uuid)

Extract timestamp from time-based UUID as java.util.Date.

Works with v1, v6, and v7 UUIDs. Returns nil for other versions.

Example: (get-instant (v7)) ;=> #inst "2024-07-10T15:30:45.123Z"

get-unix-time clj

(get-unix-time uuid)

Extract timestamp from time-based UUID as milliseconds since epoch.

Works with v1, v6, and v7 UUIDs. Returns nil for other versions.

Example: (get-unix-time (v7)) ;=> 1720626645123

parse-flake clj

(parse-flake s)

Parse a Flake from its string representation.

Returns a Flake instance or nil if the string is invalid.

Example: (parse-flake "56S2f9Lg0JJ52sY7JJuWL-etkrr2OBOC") ;=> #flake/id "56S2f9Lg0JJ52sY7JJuWL-etkrr2OBOC"

(parse-flake "invalid") ;=> nil

snowflake clj

(snowflake)

Generate a new Flake directly as a URL-safe string.

Returns a 32-character string that preserves monotonic ordering. More efficient than calling (str (flake)).

Example: (snowflake) ;=> "56S2f9Lg0JJ52sY7JJuWL-etkrr2OBOC"

uuid? clj

(uuid? x)

Check if value is a UUID.

Example: (uuid? (v4)) ;=> true (uuid? "not-a-uuid") ;=> false

v1 clj

(v1)

Generate a v1 (time-based) UUID with MAC address-based node identifier.

Guaranteed unique and thread-safe. Less commonly used than v7 in modern applications due to privacy concerns (exposes MAC address).

Example: (v1) ;=> #uuid "58e0a7d7-eebc-11d8-9669-0800200c9a66"

v3 clj

(v3 namespace name)

Generate a v3 (name-based, MD5 hash) UUID for deterministic IDs.

Similar to v5 but uses MD5 instead of SHA1. Prefer v5 for new applications.

Args: namespace - A namespace UUID name - The name to hash within the namespace

Example: (v3 +namespace-dns+ "example.com") ;=> #uuid "9073926b-929f-31c2-abc9-fad77ae3e8eb"

v4 clj

(v4)

Generate a v4 (random) UUID using cryptographically secure randomness.

This is the most commonly used UUID version for general-purpose unique identifiers.

Example: (v4) ;=> #uuid "550e8400-e29b-41d4-a716-446655440000"

v5 clj

(v5 namespace name)

Generate a v5 (name-based, SHA1 hash) UUID for deterministic IDs.

Always produces the same UUID for the same namespace and name. Useful for generating consistent identifiers from existing data.

Args: namespace - A namespace UUID (use +namespace-dns+, +namespace-url+, etc.) name - The name to hash within the namespace

Example: (v5 +namespace-dns+ "example.com") ;=> #uuid "cfbff0d1-9375-5685-968c-48ce8b15ae17"

v6 clj

(v6)

Generate a v6 time-based, lexically sortable UUID.

Field-compatible version of v1, reordered for improved database locality. Alternative to v7 when compatibility with v1 fields is needed.

Example: (v6) ;=> #uuid "1d8eebc5-8e0a-67d7-9669-0800200c9a66"

v7 clj

(v7)

Generate a v7 unix time-based, lexically sortable UUID.

Recommended for database primary keys and distributed systems requiring time-ordering. Combines millisecond timestamp with random data and a monotonic counter for same-millisecond uniqueness.

Example: (v7) ;=> #uuid "01890a5d-ac96-774b-bcce-b302099a8057"