⏰ Tempotime

A Luxon.js-inspired datetime library for Rust with zero dependencies by default.

Tempotime brings the elegant, immutable, and chainable API of Luxon.js to Rust, while offering unique advantages like optional zero-dependency operation for UTC-only use cases.

use tempotime::{dt, Duration};

let result = dt()
    .plus(&Duration::from_object(&[("weeks", 2), ("days", 3)]))
    .start_of("day")
    .to_format("MMMM do, yyyy 'at' h:mm a");

println!("{}", result);
// Output: "November 16th, 2025 at 12:00 am"

✨ Features

🚀 Zero Dependencies by Default

Use only std::time for UTC operations – no external crates required. Perfect for microservices, CLI tools, and fast compilation.

🔒 Immutable by Design

All operations return new instances, preventing common date manipulation bugs.

⛓️ Fluent & Chainable

Write clean, readable date manipulation code with method chaining.

🌍 Optional Timezone Support

Enable IANA timezone database when you need it with the tz feature.

📝 Luxon-Compatible Formatting

Familiar, intuitive token-based formatting inspired by Luxon.js.

📦 Tiny Binary Footprint

Zero-deps mode: ~175 KB
With timezone support: ~2 MB

📥 Installation

Add to your Cargo.toml:

# Zero-deps mode (UTC only, minimal binary size)

[dependencies]

tempotime = "0.1"

Feature Flags

# Accurate month/year arithmetic

tempotime = { version = "0.1", features = ["chrono"] }



# Full IANA timezone support

tempotime = { version = "0.1", features = ["tz"] }



# JSON serialization

tempotime = { version = "0.1", features = ["serde"] }



# All features

tempotime = { version = "0.1", features = ["tz", "serde"] }

🚀 Quick Start

use tempotime::{dt, DateTime, Duration};

// Get current time
let now = dt();

// Parse from ISO 8601
let date = DateTime::from_iso("2025-10-30T14:30:00Z").unwrap();

// Add/subtract durations
let tomorrow = now.plus(&Duration::from_object(&[("days", 1)]));
let last_week = now.minus(&Duration::from_object(&[("weeks", 1)]));

// Format output
println!("{}", tomorrow.to_format("yyyy-MM-dd HH:mm:ss"));

Chainable Operations

use tempotime::{dt, Duration};

let result = dt()
    .plus(&Duration::from_object(&[("days", 3), ("hours", 2)]))
    .start_of("day")
    .to_format("EEEE, MMMM do");

println!("{}", result);  // "Saturday, November 2nd"

📖 Core API

DateTime

// Creation
DateTime::now()                                        // Current UTC time
DateTime::from_iso("2025-10-30T14:30:00Z")           // Parse ISO 8601
DateTime::from_format("Oct 30, 2025", "MMM dd, yyyy") // Parse custom format

// Manipulation
dt.plus(&Duration::from_object(&[("days", 7)]))      // Add duration
dt.minus(&Duration::from_object(&[("hours", 3)]))    // Subtract duration
dt.start_of("day")                                    // Round down
dt.end_of("month")                                    // Round up
dt.set_zone("America/New_York")                       // Convert timezone

// Formatting
dt.to_iso()                                           // ISO 8601 string
dt.to_format("yyyy-MM-dd")                           // Custom format
dt.to_locale_string(DateTime::DATE_FULL)             // Locale preset

// Comparison
dt.diff(&other, "days")                               // Difference in days
dt > other_dt                                         // Compare dates

Duration

let dur = Duration::from_object(&[
    ("weeks", 2),
    ("days", 3),
    ("hours", 4),
]);

dur.as_unit("days")       // Convert to days
dur.to_object()           // Export as HashMap

Interval

use tempotime::{dt, Duration, Interval};

let start = dt();
let end = start.clone().plus(&Duration::from_object(&[("days", 30)]));
let interval = Interval::from_date_times(start, end);

interval.contains(&dt())                              // Check if in range
interval.length("days").as_unit("days")               // Get length

🎨 Format Tokens

Token	Output	Description
`yyyy`	2025	4-digit year
`yy`	25	2-digit year
`MMMM`	October	Full month name
`MMM`	Oct	Short month name
`MM`	10	2-digit month
`dd`	30	2-digit day
`do`	30th	Day with ordinal
`EEEE`	Wednesday	Full weekday
`EEE`	Wed	Short weekday
`HH`	14	24-hour (padded)
`hh`	02	12-hour (padded)
`mm`	30	Minutes
`ss`	05	Seconds
`SSS`	123	Milliseconds
`a`	pm	AM/PM
`'text'`	text	Literal text

Examples

let dt = dt();

dt.to_format("yyyy-MM-dd");                    // "2025-10-30"
dt.to_format("MMMM do, yyyy");                 // "October 30th, 2025"
dt.to_format("EEEE 'at' h:mm a");              // "Wednesday at 2:30 pm"

🎯 Zero-Deps Mode

By default, Tempotime uses only std::time::SystemTime for UTC timestamps.

✅ Advantages

Zero external dependencies
Fast compilation (~2-3 seconds)
Tiny binary (~175 KB)
Full API compatibility

⚠️ Limitations

UTC only
Approximate month/year math
No DST support
.local() returns UTC

When to Upgrade

Enable features when you need:

✓ Accurate month/year arithmetic (chrono)
✓ Timezone conversions (tz)
✓ DST handling (tz)

🆚 Comparison with Other Libraries

vs. `chrono`

chrono:

use chrono::{Utc, Duration};

let dt = Utc::now()
    .checked_add_signed(Duration::days(3))
    .unwrap()
    .format("%Y-%m-%d")
    .to_string();

tempotime:

use tempotime::{dt, Duration};

let dt = dt()
    .plus(&Duration::from_object(&[("days", 3)]))
    .to_format("yyyy-MM-dd");

vs. `time`

Tempotime provides:

✓ Immutable-by-default design
✓ Luxon-style formatting
✓ Object-based durations
✓ More chainable API
✓ Optional zero-dependency mode

📊 Feature Comparison

Feature	Zero-Deps	`chrono`	`tz`
Binary Size	~175 KB	~2 MB	~2 MB
Dependencies	0	1	2
Compilation	~2-3s	~15-20s	~25-30s
UTC Operations	✅	✅	✅
Month/Year Math	~30d/365d	Accurate	Accurate
Timezones	UTC only	UTC only	IANA (600+)
DST Support	❌	❌	✅

📚 Examples

Run the included examples:

# Basic demo

cargo run --example demo


# Timezone example

cargo run --example timezone --features tz


# Zero-deps demonstration  

cargo run --example zero_deps

🧪 Testing

# Run tests (zero-deps mode)

cargo test


# Run tests with all features

cargo test --all-features


# Run benchmarks

cargo bench

🤝 Contributing

Contributions are welcome! This is a community-driven port of Luxon.js to Rust.

Fork the repository
Create a feature branch
Add tests for new features
Submit a pull request

📜 License

Licensed under either of:

Apache License, Version 2.0 (LICENSE-APACHE)
MIT license (LICENSE-MIT)

at your option.

🙏 Acknowledgments

This project is inspired by Luxon.js, the modern successor to Moment.js.

🔗 Links

📦 Crates.io: https://crates.io/crates/tempotime
📖 Documentation: https://docs.rs/tempotime
🐙 GitHub: https://github.com/hyoussef07/tempotime
🌟 Luxon.js: https://moment.github.io/luxon/

⭐ If you find Tempotime useful, please consider giving it a star on GitHub! ⭐

Made with ❤️ for the Rust community

tempotime 0.1.3