#ulid

#Prerequisites

• 🌙 MoonBit - A modern programming language optimized for WebAssembly

# Verify installation
moon version

#Installation

moon add paveg/ulid

#Development

# Build the project
moon build

# Run tests
moon test

# Format code
moon fmt

# Check for errors without building
moon check

#Packages

• paveg/ulid/lib: Core ULID implementation

#Features

• Full ULID specification compliance (ulid/spec)
• Crockford's Base32 encoding/decoding
• Monotonic ULID generation (strictly increasing within same millisecond)
• String and binary (16-byte) representation
• Validation and comparison support
• Based on MoonBit standard library (@random)

#Usage

#Basic ULID Generation

// Create a generator with time source and random generator
let rand = @random.Rand::chacha8()
fn get_time() -> Int64 {
  // Return current Unix timestamp in milliseconds
  // This is runtime-dependent (see Design Notes below)
  1234567890123L
}

let gen = @lib.Generator::new(get_time, rand)
let ulid = gen.generate()
println(ulid.to_string())  // e.g., "01ARYZ6S41DEADBEEFDEADBEEF"

#Monotonic Generation

// Monotonic generator ensures strict ordering within same millisecond
let mono_gen = @lib.MonotonicGenerator::new(get_time, rand)
let ulid1 = mono_gen.generate()
let ulid2 = mono_gen.generate()
// ulid1 < ulid2 guaranteed (lexicographically)

#Parsing and Validation

// Parse from string
match @lib.ULID::from_string("01ARYZ6S410000000000000000") {
  Ok(ulid) => println(ulid.timestamp())
  Err(e) => println(e)
}

// Validate without parsing
if @lib.is_valid("01ARYZ6S410000000000000000") {
  println("Valid ULID")
}

#Binary Representation

// Convert to 16-byte binary (big-endian)
let bytes = ulid.to_bytes()

// Create from binary
match @lib.ULID::from_bytes(bytes) {
  Ok(ulid) => println(ulid.to_string())
  Err(e) => println(e)
}

#Comparison

let ulid1 = @lib.ULID::from_string("00000000000000000000000000").unwrap()
let ulid2 = @lib.ULID::from_string("01ARYZ6S410000000000000000").unwrap()

// Compare
if ulid1.compare(ulid2) < 0 {
  println("ulid1 < ulid2")
}

// Equality
if ulid1 == ulid2 {
  println("Equal")
}

#API Reference

#Types

#Functions

#Design Notes

#Time Source Injection

fn get_time() -> Int64 {
  // Implement based on your runtime environment:
  // - Browser: Use JavaScript interop to call Date.now()
  // - Node.js: Use JavaScript interop
  // - Native: Use FFI to call system time functions
  // - Testing: Return mock timestamps
}

• Follows MoonBit standard library patterns
• Enables easy testing with mock time
• Allows runtime-specific implementations

#Random Generation

#ULID Specification

• Format: 26-character string (Crockford's Base32)
• Components: 48-bit timestamp + 80-bit randomness
• Encoding: 0123456789ABCDEFGHJKMNPQRSTVWXYZ (excludes I, L, O, U)
• Sorting: Lexicographically sortable
• Maximum: 7ZZZZZZZZZZZZZZZZZZZZZZZZZ (year 10889)

#License