bomboni_common

The bomboni_common crate provides common utilities used throughout the Bomboni library, including sortable unique identifiers and UTC date-time handling.

Id

A semi-globally unique and sortable identifier based on ULID (Universally Unique Lexicographically Sortable Identifier).

Type Definition

pub struct Id(u128)

The Id type provides both uniqueness and sortability, making it ideal for distributed systems and database records.

Methods

Id::new

const fn(u128) -> Self

Creates a new ID from a 128-bit integer.

let id = Id::new(123456789);

Id::generate

fn() -> Self

Generates a new random sortable ID.

let id = Id::generate();

Id::generate_multiple

fn(count: usize) -> Vec<Self>

Generates multiple random sortable IDs. Generated IDs are monotonically increasing.Panics: Panics if the ULID generator fails to generate an ID.

let ids = Id::generate_multiple(10);
assert_eq!(ids.len(), 10);

Id::from_worker_parts

fn(time: OffsetDateTime, worker: u16, sequence: u16) -> Self

Creates an ID from worker parts. Useful for distributed ID generation.Panics: Panics if the timestamp, worker ID, or sequence number is too large.

use time::OffsetDateTime;

let id = Id::from_worker_parts(
  OffsetDateTime::now_utc(),
  42,  // worker ID
  0    // sequence number
);

Id::from_time_and_random

const fn(time: OffsetDateTime, random: u128) -> Self

Creates an ID from time and a random number.

use time::OffsetDateTime;

let id = Id::from_time_and_random(
  OffsetDateTime::now_utc(),
  rand::random()
);

Id::decode_worker

fn(self) -> (OffsetDateTime, u16, u16)

Decodes the ID into worker parts: timestamp, worker ID, and sequence number.

let id = Id::from_worker_parts(time, 42, 7);
let (timestamp, worker, sequence) = id.decode_worker();
assert_eq!(worker, 42);
assert_eq!(sequence, 7);

Id::decode_time_and_random

fn(self) -> (OffsetDateTime, u128)

Decodes the ID into time and randomness parts.

let id = Id::generate();
let (timestamp, random) = id.decode_time_and_random();

Traits

The Id type implements several standard traits:

Display - Formats the ID as a ULID string
FromStr - Parses an ID from a ULID string
From<u8>, From<u16>, From<u32>, From<u64> - Converts from unsigned integers
From<i8>, From<i16>, From<i32>, From<i64>, From<i128> - Converts from signed integers
From<Ulid> and Into<Ulid> - Converts to/from ULID
Into<u128> - Converts to 128-bit integer
Serialize and Deserialize (with serde feature)

ParseIdError

Errors that can occur when parsing an Id from a string.

pub enum ParseIdError {
    InvalidString,
}

WorkerIdGenerator

Generator for IDs with a specific worker ID, suitable for distributed systems.

Type Definition

pub struct WorkerIdGenerator {
    // fields omitted
}

Methods

WorkerIdGenerator::new

const fn(worker: u16) -> Self

Creates a new worker ID generator with the specified worker ID.

use bomboni_common::id::worker::WorkerIdGenerator;

let mut generator = WorkerIdGenerator::new(42);

WorkerIdGenerator::generate

fn(&mut self) -> Id

Generates a new ID with the worker’s identifier. Each call increments an internal sequence number.

let mut g = WorkerIdGenerator::new(1);
let id1 = g.generate();
let id2 = g.generate();
assert_ne!(id1, id2);

WorkerIdGenerator::generate_async

async fn(&mut self) -> Id

Generates a new ID asynchronously. Same as generate but async-friendly.Requires: tokio feature

let mut g = WorkerIdGenerator::new(1);
let id = g.generate_async().await;

WorkerIdGenerator::generate_multiple

fn(&mut self, count: usize) -> Vec<Id>

Generates multiple IDs at once. More efficient than calling generate repeatedly.

let mut g = WorkerIdGenerator::new(1);
let ids = g.generate_multiple(100);
assert_eq!(ids.len(), 100);

WorkerIdGenerator::generate_multiple_async

async fn(&mut self, count: usize) -> Vec<Id>

Generates multiple IDs asynchronously. Same as generate_multiple but async-friendly.Requires: tokio feature

let mut g = WorkerIdGenerator::new(1);
let ids = g.generate_multiple_async(100).await;

UtcDateTime

A date and time in the UTC time zone with support for various serialization formats.

Type Definition

pub struct UtcDateTime(OffsetDateTime)

Constants

UtcDateTime::UNIX_EPOCH

UtcDateTime

The Unix epoch (1970-01-01 00:00:00 UTC).

use bomboni_common::date_time::UtcDateTime;

let epoch = UtcDateTime::UNIX_EPOCH;

Methods

UtcDateTime::now

fn() -> Self

Returns the current UTC date and time.

let now = UtcDateTime::now();

UtcDateTime::new

const fn(seconds: i64, nanoseconds: i32) -> Self

Creates a new UTC date time from seconds and nanoseconds since Unix epoch.If the timestamp is invalid, returns Unix epoch.

let dt = UtcDateTime::new(1609459200, 0); // 2021-01-01 00:00:00 UTC

UtcDateTime::from_timestamp

fn(seconds: i64, nanoseconds: i32) -> Result<Self, UtcDateTimeError>

Creates a UTC date time from seconds and nanoseconds.Returns UtcDateTimeError::NotUtc if the timestamp is not valid.

let dt = UtcDateTime::from_timestamp(1609459200, 0)?;

UtcDateTime::from_seconds

const fn(seconds: i64) -> Result<Self, UtcDateTimeError>

Creates a UTC date time from seconds since the Unix epoch.

let dt = UtcDateTime::from_seconds(1609459200)?;

UtcDateTime::from_nanoseconds

const fn(nanoseconds: i128) -> Result<Self, UtcDateTimeError>

Creates a UTC date time from nanoseconds since the Unix epoch.

let dt = UtcDateTime::from_nanoseconds(1609459200_000_000_000)?;

UtcDateTime::timestamp

const fn(self) -> (i64, i32)

Returns the timestamp as (seconds, nanoseconds) tuple.

let dt = UtcDateTime::now();
let (seconds, nanos) = dt.timestamp();

UtcDateTime::parse_rfc3339

fn(input: impl AsRef<str>) -> Result<Self, UtcDateTimeError>

Parses an RFC 3339 formatted date time string.

let dt = UtcDateTime::parse_rfc3339("2021-01-01T00:00:00Z")?;

UtcDateTime::format_rfc3339

fn(&self) -> Result<String, time::error::Format>

Formats the date time as an RFC 3339 string.

let dt = UtcDateTime::now();
let formatted = dt.format_rfc3339()?;
// Output: "2024-03-04T12:34:56Z"

Traits

The UtcDateTime type implements several traits:

Display - Formats as RFC 3339 string
FromStr - Parses from RFC 3339 string
From<OffsetDateTime> and Into<OffsetDateTime>
From<PrimitiveDateTime> and Into<PrimitiveDateTime>
From<SystemTime>
TryFrom<DateTime<Utc>> and Into<DateTime<Utc>> (with chrono feature)
Serialize and Deserialize (with serde feature)

UtcDateTimeError

Errors that can occur when working with UtcDateTime.

pub enum UtcDateTimeError {
    InvalidNanoseconds,
    NotUtc,
    InvalidFormat(String),
    OutOfRange,
}

Feature Flags

The bomboni_common crate supports the following optional features:

serde

feature

Enables serialization and deserialization support via serde.

tokio

feature

Enables async methods for ID generation using tokio runtime.

chrono

feature

Enables conversions between UtcDateTime and chrono’s DateTime<Utc>.

wasm

feature

Enables WebAssembly support with JavaScript interop.

postgres

feature

Enables PostgreSQL type conversions for Id and UtcDateTime.

mysql

feature

Enables MySQL type conversions for Id and UtcDateTime.

Examples

Generating Unique IDs

use bomboni_common::id::Id;

// Generate a single ID
let id = Id::generate();
println!("Generated ID: {}", id);

// Generate multiple IDs efficiently
let ids = Id::generate_multiple(100);

// Parse from string
let parsed: Id = "01ARZ3NDEKTSV4RRFFQ69G5FAV".parse()?;

Worker-based ID Generation

use bomboni_common::id::worker::WorkerIdGenerator;

// Create a generator for worker 42
let mut generator = WorkerIdGenerator::new(42);

// Generate IDs with worker identifier
let id1 = generator.generate();
let id2 = generator.generate();

// Decode to verify worker ID
let (timestamp, worker_id, sequence) = id1.decode_worker();
assert_eq!(worker_id, 42);

Working with UTC DateTimes

use bomboni_common::date_time::UtcDateTime;

// Current time
let now = UtcDateTime::now();

// Parse from RFC 3339 string
let dt = UtcDateTime::parse_rfc3339("2021-01-01T00:00:00Z")?;

// Format as string
let formatted = dt.format_rfc3339()?;
println!("Formatted: {}", formatted);

// Create from timestamp
let dt = UtcDateTime::from_seconds(1609459200)?;

Core APIs

Protocol Buffers

Request Handling

WebAssembly

Utilities

Id

Type Definition

Methods

Traits

ParseIdError

WorkerIdGenerator

Type Definition

Methods

UtcDateTime

Type Definition

Constants

Methods

Traits

UtcDateTimeError

Feature Flags

Examples

Generating Unique IDs

Worker-based ID Generation

Working with UTC DateTimes

Build docs developers (and LLMs) love

Core APIs

Protocol Buffers

Request Handling

WebAssembly

Utilities

​Id

​Type Definition

​Methods

​Traits

​ParseIdError

​WorkerIdGenerator

​Type Definition

​Methods

​UtcDateTime

​Type Definition

​Constants

​Methods

​Traits

​UtcDateTimeError

​Feature Flags

​Examples

​Generating Unique IDs

​Worker-based ID Generation

​Working with UTC DateTimes

Build docs developers (and LLMs) love

Id

Type Definition

Methods

Traits

ParseIdError

WorkerIdGenerator

Type Definition

Methods

UtcDateTime

Type Definition

Constants

Methods

Traits

UtcDateTimeError

Feature Flags

Examples

Generating Unique IDs

Worker-based ID Generation

Working with UTC DateTimes