ulidk

Implements ULID generation and manipulation, offering random and monotonic sequences, string decoding, and UUID compatibility. Provides testing and benchmarking for performance evaluation.

#utility
#serialization
#performance-optimization
#parsing
#maven
#kotlin-dsl

Suggest an edit

Android JVMJVMKotlin/NativeWasmJS

GitHub stars1

Authorsreonaore

Open issues3

LicenseApache License 2.0

Creation dateover 2 years ago

Last activity5 days ago

Latest release0.3.0 (5 months ago)

GitHub repository GitHub pages

What?

ULID implementation in Kotin.

See kDoc to see the specification.

Install

Kotlin DSL

Add maven repository.

repositories {
    mavenCentral()
}

If you want to use snapshots, add another repository.

repositories {
    maven {
        url = uri("https://s01.oss.sonatype.org/content/repositories/snapshots/")
    }
}

Add dependency.

 implementation("io.github.reonaore:ulidk:0.1.0")

Usage

To generate a ULID, call randomULID().

import io.onare.ulidk.ULID

val ulid: ULID = ULID.randomULID()
val ulidString = ulid.toString() // e.g. 01ARZ3NDEKTSV4RRFFQ69G5FAV
val ulidBinary = ulid.binary // 16 bytes binary of the ULID

Decode from string

import io.onare.ulidk.ULID

val ulid: ULID = ULID.fromString("01ARZ3NDEKTSV4RRFFQ69G5FAV").getOrThrow()
val timestamp: Long = ulid.timestamp() // 48bit unix time of the ULID
val entropy: ByteArray = ulid.entropy() // randomness of the ULID

Monotonic ULIDs

import io.onare.ulidk.ULID

val ulidGen = ULID.MonotonicGenerator(ULID.randomULID(150000))

// Strict ordering for the same timestamp, by incrementing the least-significant random bit by 1
ulidGen() // 000XAL6S41ACTAV9WEVGEMMVR8
ulidGen() // 000XAL6S41ACTAV9WEVGEMMVR9
ulidGen() // 000XAL6S41ACTAV9WEVGEMMVRA
ulidGen() // 000XAL6S41ACTAV9WEVGEMMVRB
ulidGen() // 000XAL6S41ACTAV9WEVGEMMVRC

// Even if a lower timestamp is passed (or generated), it will preserve sort order
ulidGen(100000) // 000XAL6S41ACTAV9WEVGEMMVRD

UUID compatibility

import io.onare.ulidk.ULID
import java.util.*

val uuid = UUID.randomUUID()
val ulid = ULID.fromUUID(uuid)
assert(uuid.toString() == ulid.toUUID().toString())

Test

./gradlew test

Benchmark

./gradlew benchmark

result

on MacBook Air M1 2020, 8GB memory

Benchmark                                Mode  Cnt        Score         Error  Units
TestBenchmark.decodeThroughput          thrpt    5  2870482.675 ±   28929.819  ops/s
TestBenchmark.generationThroughput      thrpt    5  2222172.000 ±  337147.404  ops/s
TestBenchmark.monoGenerationThroughput  thrpt    5  7301193.431 ± 2717363.333  ops/s
TestBenchmark.uuidGenerationThroughput  thrpt    5  1997510.100 ± 2425175.330  ops/s
TestBenchmark.decodeAverage              avgt    5      526.944 ±     926.595  ns/op
TestBenchmark.generationAverage          avgt    5      550.906 ±     568.759  ns/op
TestBenchmark.monoGenerationAverage      avgt    5       33.213 ±       1.528  ns/op
TestBenchmark.uuidGenerationAverage      avgt    5      337.830 ±      91.290  ns/op