jiff

Jiff is a datetime library for Rust built around a simple idea: the easiest way to use the API should also be the correct way. Its central type, Zoned, ties a Timestamp, a civil date and time, and an IANA time zone into one value, so daylight saving time transitions, offset changes, and calendar arithmetic are handled automatically instead of left to the caller to get wrong.

The library takes deliberate influence from Temporal, the TC39 proposal to overhaul date and time handling in JavaScript, adapting its type separation between absolute and civil time and its Result-returning, panic-averse API surface to Rust. Jiff ships with automatic IANA Time Zone Database integration (bundled on platforms without a system copy), Serde support behind a feature flag, RFC 3339/2822 and strftime/strptime-style formatting and parsing, and a bespoke human-friendly duration format. It works in no_std environments via optional alloc/std features, making it usable from embedded targets as well as ordinary applications.

What You Get

• A Zoned / Timestamp / civil::DateTime type triad that separates absolute time from civil (calendar) time.
• Automatic IANA Time Zone Database integration, with a bundled copy for platforms like Windows and wasm that lack a system tzdb.
• Span, a calendar-and-clock duration type, plus SignedDuration, a signed counterpart to std::time::Duration.
• Lossless Temporal-style formatting/parsing plus RFC 2822 and strftime/strptime-compatible routines.
• Opt-in Serde integration and a bespoke human-friendly duration format for humantime-style output.
• no_std and no-alloc support via Cargo feature flags for embedded and constrained targets.

Common Use Cases

• Scheduling logic that must survive DST transitions, such as recurring meetings or cron-like jobs.
• Parsing and round-tripping RFC 3339 / RFC 9557 zoned timestamps from APIs and logs.
• Calendar arithmetic such as “add 1 month” that has to respect variable month lengths and leap years.
• Serializing and deserializing datetimes in Rust web services via optional Serde support.
• Formatting durations for human-readable CLI or log output using the friendly duration format.
• Embedded or no_std projects that need timezone-aware datetime handling without heap allocation.

Under The Hood

Architecture Jiff splits its implementation across a workspace: jiff-core holds low-level, no_std-first datetime primitives (bounds-checked integer types, civil date/time math, tz building blocks) that both jiff and jiff-static depend on, while the public jiff crate (crates/jiff/src) layers the ergonomic API on top — zoned.rs, timestamp.rs, civil/, tz/, span.rs, signed_duration.rs, and fmt/ each own one concern and compose through a small set of shared types (Zoned wraps Timestamp + civil::DateTime + tz::TimeZone, as seen at the top of zoned.rs). Error handling runs through a single Error type in error/mod.rs (the “One True God Error Type Pattern,” explicitly documented and justified against a linked GitHub issue), with an Arc-wrapped internal representation so Error stays small and cheaply cloneable across the crate’s many fallible operations. Optional integrations (jiff-diesel, jiff-sqlx, jiff-icu, jiff-tzdb, jiff-tzdb-platform, jiff-static, jiff-wasm) live as separate workspace crates rather than features baked into jiff itself, keeping the core dependency-free on Unix while still letting downstream users opt into ORM, localization, or const-context time zone support.

Tech Stack The library targets stable Rust 1.70+ (MSRV pinned in Cargo.toml) and is designed to be no_std/no-alloc capable via layered std/alloc Cargo features, with the tz-system, tzdb-bundle-platform, tzdb-zoneinfo, and tzdb-concatenated features controlling how the IANA Time Zone Database is discovered or embedded per platform (Unix reads /usr/share/zoneinfo, Windows/wasm get a bundled copy via jiff-tzdb-platform). Optional dependencies are kept deliberately minimal — serde_core behind the serde feature, log behind logging, windows-link only on Windows, portable-atomic/portable-atomic-util only on targets without pointer-width atomics — reflecting the dependency philosophy stated in the README (“very conservative,” dependencies only when practically required for a platform or interop). Companion crates add ecosystem glue: jiff-diesel/jiff-sqlx bridge to Postgres/MySQL/SQLite via Diesel and SQLx, jiff-icu bridges to ICU4X for localization, and jiff-static/jiff-wasm cover const-context and WebAssembly use.

Code Quality Testing is extensive and layered: hundreds of inline #[test] functions spread across dozens of files under crates/jiff/src cover unit-level behavior next to the code they exercise, a separate crates/jiff/tests/ integration suite (built via a single tests/lib.rs entry point per the autotests = false setting) adds broader coverage, and a tests/tc39_262/ directory specifically ports relevant cases from the TC39 Temporal spec’s conformance suite to cross-check Jiff’s behavior against the JavaScript proposal it’s modeled on. A dedicated [profile.testrelease] disables debug assertions to exercise the actual arithmetic paths used in release builds, on top of the default debug-assertion-heavy test profile that catches overflow bugs in Jiff’s internal ranged-integer types. CI runs the full test suite across stable/beta/nightly Rust on Linux and macOS, with a nightly cron in addition to PR/push triggers. Errors are represented, not panicked on — the crate’s own docs state that “APIs that panic by design are clearly documented as such and few in number,” backed by the crate-wide Result-returning Error type.

API Design Jiff’s differentiator is bringing Temporal’s type-safety model — separating absolute time (Timestamp, Zoned) from civil/calendar time (civil::DateTime) — into Rust, where existing crates like chrono and time don’t draw that line as sharply (per the project’s own COMPARE.md, which documents this in detail rather than asserting it). Its Span duration type mixes calendar units (years, months) and clock units (hours, seconds) in one value that still performs DST-aware arithmetic correctly against a Zoned, and its formatting supports lossless round-tripping of zone-aware datetimes (including RFC 9557’s [America/New_York]-style annotations) rather than only offset-based output. The library’s own DESIGN.md walks through its API rationale as an FAQ, and getting started requires little boilerplate: cargo add jiff plus a handful of imports covers most common cases. The “fat tzdb” feature is a deliberate, documented trade-off — pre-expanding transition tables at the cost of memory to smooth out lookup-performance variance across platforms with differing TZif generation policies.