Utilities

Human-readable value types and ID generators for common programming tasks.

UUIDv7

Time-ordered UUIDs (RFC 9562) — the recommended ID format for internal use. UUIDv7 embeds a millisecond-precision Unix timestamp, is monotonically sortable, and can be compactly encoded with Base62.

import wvlet.uni.util.UUIDv7

// Generate a new UUIDv7
val id = UUIDv7.newUUIDv7()
println(id)  // e.g., "019078e5-3f6a-7b1c-8d4e-2f9a0b1c3d5e"

// Compact 22-character Base62 representation (URL-safe, sort-order preserving)
val short: String = id.toBase62  // e.g., "0K9mFb3xYz1Qw5Rv8NpJ2a"

// Parse back from Base62
val recovered = UUIDv7.fromBase62(short)

Timestamps and Conversion

val id = UUIDv7.newUUIDv7()

// Extract timestamp
val millis: Long = id.timestamp

// Convert to/from java.util.UUID
val uuid: java.util.UUID = id.toUUID
val back: UUIDv7 = UUIDv7.fromUUID(uuid)

// Binary representation
val bytes: Array[Byte] = UUIDv7.toBytes(id)   // 16 bytes
val fromBytes: UUIDv7 = UUIDv7.fromBytes(bytes)

// Parse from standard UUID string
val parsed = UUIDv7.fromString("019078e5-3f6a-7b1c-8d4e-2f9a0b1c3d5e")

Custom Generator

// Create an independent generator (useful for testing or isolated contexts)
val gen = UUIDv7.createGenerator()
val id = gen.newUUIDv7()

// With a custom random source
val gen2 = UUIDv7.createGenerator(new scala.util.Random(42))

Base62

Sort-order preserving encoding using the 0-9A-Za-z alphabet (62 characters). Encodes 128-bit values to compact 22-character URL-safe strings. Use UUIDv7.toBase62 / UUIDv7.fromBase62 for the common case.

import wvlet.uni.util.{Base62, UUIDv7}

// Most common usage: via UUIDv7
val id = UUIDv7.newUUIDv7()
val encoded: String = id.toBase62                           // 22 chars
val decoded: UUIDv7 = UUIDv7.fromBase62(encoded)

// Encode / decode raw 128-bit values
val raw: String = Base62.encode128bits(0x0123456789abcdefL, 0xfedcba9876543210L)
val (hi, low): (Long, Long) = Base62.decode128bits(raw)

// Validate
Base62.isValid("0K9mFb3xYz1Qw5Rv8NpJ2a")  // true

CrockfordBase32

Crockford's Base32 encoding — the case-insensitive, human-friendly alphabet (it excludes I, L, O, U to avoid ambiguity) that backs ULID. Use it directly when you need to encode raw 128-bit or 48-bit values in the same format.

import wvlet.uni.util.CrockfordBase32

// Encode / decode a 128-bit value (26 characters)
val s: String = CrockfordBase32.encode128bits(hi = 0x0123456789abcdefL, low = 0xfedcba9876543210L)
val (hi, low): (Long, Long) = CrockfordBase32.decode128bits(s)

// Decode a 48-bit value (e.g. a ULID timestamp prefix)
val millis: Long = CrockfordBase32.decode48bits("01ARZ3NDEK")

// Validate
CrockfordBase32.isValidBase32("01arz3ndektsv4rrffq69g5fav")  // true

For ID generation prefer ULID (which encodes with this alphabet) or Base62; reach for CrockfordBase32 only when you need the raw codec.

NanoId

Compact, URL-safe random IDs for cases where time-ordering is not needed. Useful as user-facing tokens, short links, or external keys that map back to an internal UUIDv7.

import wvlet.uni.util.NanoId

// Generate a default NanoId (21 chars, A-Za-z0-9_-)
val id: String = NanoId.generate()  // e.g., "V1StGXR8_Z5jdHi6B-myT"

// Custom size
val short = NanoId.generate(10)

// Custom alphabet and size
val hex = NanoId.generate("0123456789abcdef", 32)

ID Strategy

Use UUIDv7 as the internal primary key — it is time-ordered, monotonic, and embeds a timestamp. For user-facing URLs and APIs, either:

• Expose the UUIDv7 in Base62 format (22 chars, sortable, reversible), or
• Generate a NanoId as an external key and maintain a mapping to the internal UUIDv7.

ULID

Universally Unique Lexicographically Sortable Identifiers — 128-bit IDs encoded as 26-character Crockford Base32 strings. ULID predates UUIDv7 and serves a similar purpose; prefer UUIDv7 for new projects.

import wvlet.uni.util.ULID

// Generate a new ULID
val id = ULID.newULID
println(id)  // e.g., "01arz3ndektsv4rrffq69g5fav"

ULID API details

Parsing and Validation

val parsed = ULID.fromString("01arz3ndektsv4rrffq69g5fav")
ULID.isValid("01arz3ndektsv4rrffq69g5fav")  // true

Extracting Timestamps

val id = ULID.newULID
val millis: Long = id.epochMillis
val instant: java.time.Instant = id.toInstant
val historical = ULID.ofMillis(1609459200000L)

Converting to/from UUID

import java.util.UUID

val ulid = ULID.newULID
val uuid: UUID = ulid.toUUID
val back: ULID = ULID.fromUUID(uuid)
val bytes: Array[Byte] = ulid.toBytes  // 16 bytes
val fromBytes: ULID = ULID.fromBytes(bytes)

PrefixedULID

A ULID tagged with a human-readable type prefix — handy for self-describing IDs like user:01arz3ndektsv4rrffq69g5fav where the prefix identifies the entity. The string form is <prefix>:<ulid> (delimiter :), and values sort by prefix first, then by the embedded ULID timestamp.

import wvlet.uni.util.PrefixedULID

// Generate
val id: PrefixedULID = PrefixedULID.newPrefixedULID("user")
println(id)                    // "user:01arz3ndektsv4rrffq69g5fav"

// Or directly as a string
val s: String = PrefixedULID.newPrefixedULIDString("order")

// Access parts
id.prefix                      // "user"
id.ulid                        // the underlying ULID

// Parse back (splits on the last ':' so prefixes may contain ':')
val parsed = PrefixedULID.fromString("user:01arz3ndektsv4rrffq69g5fav")

DataSize

Human-readable data size representation with parsing and unit conversion.

import wvlet.uni.util.DataSize

// Parse from string
val size = DataSize("128MB")

// Create from bytes
val fromBytes = DataSize(1073741824L)  // 1GB

// Auto-select best unit
val succinct = DataSize.succinct(1536000L)
println(succinct)  // "1.46MB"

Unit Conversion

val size = DataSize("2.5GB")

size.toBytes                              // 2684354560L
size.valueOf(DataSizeUnit.MEGABYTE)       // 2560.0
size.convertTo(DataSizeUnit.MEGABYTE)     // DataSize(2560.0, MEGABYTE)
size.mostSuccinctDataSize                 // DataSize(2.5, GIGABYTE)

Units

Unit	Symbol	Bytes
BYTE	B	1
KILOBYTE	kB	1,024
MEGABYTE	MB	1,048,576
GIGABYTE	GB	1,073,741,824
TERABYTE	TB	1,099,511,627,776
PETABYTE	PB	1,125,899,906,842,624

Count

Human-readable large number representation.

import wvlet.uni.util.Count

// Parse from string
val count = Count("1.5M")

// Auto-select best unit
val succinct = Count.succinct(1500000L)
println(succinct)  // "1.50M"

// Raw value
count.toLong  // 1500000L

Unit Conversion

val count = Count(2500000L)

count.mostSuccinctCount                // Count(2.50, MILLION)
count.convertTo(CountUnit.THOUSAND)    // Count(2500, THOUSAND)
count.valueOf(CountUnit.MILLION)       // 2.5

Units

Unit	Symbol	Value
ONE	(none)	1
THOUSAND	K	1,000
MILLION	M	1,000,000
BILLION	B	1,000,000,000
TRILLION	T	1,000,000,000,000
QUADRILLION	Q	1,000,000,000,000,000

ElapsedTime

Human-readable duration representation with unit conversion.

import wvlet.uni.util.ElapsedTime

// Parse from string
val duration = ElapsedTime("5ms")
val timeout  = ElapsedTime("30s")
val window   = ElapsedTime("2.5h")

// Create from measurements
val fromNanos  = ElapsedTime.succinctNanos(1500000L)
println(fromNanos)   // "1.50ms"

val fromMillis = ElapsedTime.succinctMillis(3600000L)
println(fromMillis)  // "1.00h"

// Measure elapsed time
val start = System.nanoTime()
// ... do work ...
val elapsed = ElapsedTime.nanosSince(start)
println(elapsed)  // e.g., "42.30ms"

Unit Conversion

val duration = ElapsedTime("90s")

duration.toMillis                                       // 90000.0
duration.valueIn(java.util.concurrent.TimeUnit.MINUTES) // 1.5
duration.convertToMostSuccinctTimeUnit                  // ElapsedTime(1.50, MINUTES)

Units

Unit	Symbol	Example
NANOSECONDS	ns	"500ns"
MICROSECONDS	us	"100us"
MILLISECONDS	ms	"5ms"
SECONDS	s	"30s"
MINUTES	m	"5m"
HOURS	h	"2.5h"
DAYS	d	"1d"

StopWatch

A simple elapsed-time timer. It starts running on creation and reports seconds as a Double.

import wvlet.uni.util.StopWatch

val sw = StopWatch()
// ... do work ...
val seconds: Double = sw.getElapsedTime   // elapsed since creation/reset

sw.stop                                   // pause; returns the last interval
sw.resume                                 // continue measuring
sw.reset                                  // restart from zero
println(sw.reportElapsedTime)             // e.g. "0.42 sec."

Timer

For micro-benchmarking, extend the Timer trait and wrap code in time / nested block. A TimeReport captures total and per-block timing, and repeat runs blocks multiple times to smooth out JIT/GC noise.

import wvlet.uni.util.Timer

class Benchmark extends Timer:
  val report = time("search", repeat = 10) {
    block("linear") {
      // candidate A
    }
    block("binary") {
      // candidate B
    }
  }

  // Inspect per-block statistics
  report("linear").average   // average seconds over the repeats
  report("binary").min       // min / max / median / elapsedSeconds also available

val b = Benchmark()
println(b.report)            // formatted multi-line timing report

Best Practices

1. Use UUIDv7 for internal IDs — time-ordered, monotonic, with an embedded timestamp
2. Use Base62 encoding for user-facing UUIDv7 — compact (22 chars), URL-safe, sort-order preserving
3. Use NanoId for opaque external tokens — map them back to internal UUIDv7 when needed
4. Use succinct formatting in logs and UIs for readability (DataSize.succinct, Count.succinct)
5. Parse user input with the string constructors — they handle common formats ("128MB", "1.5M", "30s")
6. All value types implement Comparable for sorting and comparison