Crate hourglass_rs

hourglass-rs

A time abstraction crate that provides consistent time handling for both production and test environments, with safe time manipulation capabilities for testing.

Features

• Zero overhead in production - thin wrapper around system time
• Time manipulation in tests - advance time, set specific times
• Async support - works seamlessly with tokio’s async runtime
• Type safety - can’t accidentally manipulate time in production
• Test isolation - each test gets its own time control

Quick Start

use hourglass_rs::{SafeTimeProvider, TimeSource};
use chrono::Duration;
 
#[tokio::main]
async fn main() {
    // Production usage
    let time = SafeTimeProvider::new(TimeSource::System);
    println!("Current time: {}", time.now());
     
    // Wait for 5 seconds (actually waits in production)
    time.wait(Duration::seconds(5)).await;
}

Testing Example

use hourglass_rs::{SafeTimeProvider, TimeSource};
use chrono::Duration;
 
#[tokio::test]
async fn test_time_dependent_code() {
    // Create a test time provider
    let time = SafeTimeProvider::new(
        TimeSource::Test("2024-01-01T00:00:00Z".parse().unwrap())
    );
     
    // Get time control for the test
    let control = time.test_control().expect("Should be in test mode");
     
    // Your time-dependent code
    let start = time.now();
    time.wait(Duration::days(30)).await; // Returns immediately in tests
    let end = time.now();
     
    // Verify the behavior
    assert_eq!(end - start, Duration::days(30));
    assert_eq!(control.total_waited(), Duration::days(30));
}

Re-exports

pub use config::TimeSource;

pub use control::TimeControl;

pub use provider::SharedTimeProvider;

pub use provider::TimeProvider;

pub use safe::SafeTimeProvider;

pub use system::SystemTimeProvider;

pub use test::TestTimeProvider;

Modules

config

control

provider

safe

system

test

Structs

DateTime

ISO 8601 combined date and time with time zone.

Utc

The UTC time zone. This is the most efficient time zone when you don’t need the local time. It is also used as an offset (which is also a dummy type).

Type Aliases

Duration

Alias of TimeDelta.