Stories

Jiff 1.0: A Rust Datetime Library That Takes Time Zones Seriously

Published 16 November, 20266 min read

Datetime code has a reputation problem. Most of us have shipped a bug caused by a time zone, a leap day, or an offset that quietly changed under us, and most libraries have responded by handing the complexity back to the caller. Jiff, Andrew Gallant's datetime library for Rust, takes the opposite approach: it hides the hard parts inside a type system that makes the wrong thing unusually difficult to express.

On November 15, 2026, Jiff shipped version 1.0. That release is less about new features than about a promise: the API is now considered settled, and breaking changes will be rare. That matters because Jiff has already spread through the Rust ecosystem into places where a stability guarantee is not optional. Among its users are uv, Cargo, Starship, fd, Nushell, mise, Jujutsu and uutils/coreutils, and it is the basis for a Temporal implementation in AWS LLRT. At the time of release, crates.io listed roughly 284 million downloads and close to 1,900 dependent crates.

This article walks through the design that got Jiff there: the layered type model, the unusual amount of attention paid to ambiguous clock times, the difference between calendar and clock arithmetic, and the trade-offs you accept by choosing it.

Why the Rust ecosystem needed another one

Rust already had chrono, time, hifitime and the icu crates. Gallant's argument, laid out in the project's design rationale, is that these libraries had reached a local maximum, and that the gap was less about missing features than about API design and default behavior.

The sharpest version of the critique concerns time zones. Chrono does not ship IANA time zone support itself; you add chrono-tz or tzfile, each with different trade-offs. One embeds the whole database into your binary, meaning you wait for a crate update and re-ship to pick up a rule change. The other reads from the system copy but, in its early versions, re-parsed the file on every lookup. The time crate offers only limited IANA support, which pushes users toward fixed-offset datetimes.

Fixed offsets are the crux of it. An offset tells you how far a region was from UTC at a particular instant, but it does not tell you which region you are in, and therefore cannot tell you what happens when the rules change. Store -05:00 and you have thrown away the information that would let you compute what 9am means in New York three months from now. For logging and measurement, an instant is enough. For anything a human scheduled, it is not.

The type onion

Jiff's model can be read as a series of layers, each adding information until you reach a ZonedDateTime. The definitions are worth internalizing because everything else in the API follows from them.

A ZonedDateTime can be built from either direction, and the two directions correspond to two different kinds of programmer intent. If you know what the clock should say, you start civil. If you know which instant you mean, you start with a timestamp.

use jiff::civil;

fn main() -> anyhow::Result<()> {
    let date = civil::date(2026, 11, 1);
    let time = civil::time(17, 30, 0, 0);
    let zdt = date.to_datetime(time).in_tz("America/New_York")?;

    assert_eq!(zdt.timestamp().as_second(), 1793572200);
    Ok(())
}
use jiff::{civil, Timestamp};

fn main() -> anyhow::Result<()> {
    let ts = Timestamp::from_second(1793572200)?;
    let zdt = ts.in_tz("America/New_York")?;

    assert_eq!(zdt.datetime(), civil::date(2026, 11, 1).at(17, 30, 0, 0));
    Ok(())
}

Both programs produce the same value. One begins with a wall clock, the other with a database row or a file timestamp. Keeping those two entry points distinct in the API is a large part of why Jiff code reads the way it does.

Time zones are rules, not offsets

An offset is the amount you subtract from UTC to get civil time. For New York on November 1, 2026, that amount is five hours, so 2026-11-01T22:30:00Z becomes 2026-11-01T17:30:00-05:00. Every ZonedDateTime carries such an offset, and you can inspect it directly with zdt.offset().seconds() or compare it against tz::offset(-5).

But a time zone is more than its current offset. Jiff defines it as a geographic region whose civil clocks agree, supplying two mappings: from an instant to an offset, and from a civil datetime to a possibly ambiguous offset. The second mapping is where the trouble lives.

Two things can go wrong when a region shifts its clocks. In spring, an hour of civil time may not exist at all. In autumn, an hour may occur twice. A library that ignores this forces every caller to rediscover it in production; a library that panics forces every caller to defend against a case that is usually irrelevant. Jiff's answer is to pick a defensible default and expose the alternative strategies explicitly.

When New York falls back at 2am on November 1, 2026, the 1am hour repeats. Ask Jiff for 1:30am and it returns the first repetition, using the -04:00 offset. Reach for the lower-level API and you can choose differently:

use jiff::{
    civil::date,
    tz::{offset, TimeZone},
};

fn main() -> anyhow::Result<()> {
    let tz = TimeZone::get("America/New_York")?;
    let dt = date(2026, 11, 1).at(1, 30, 0, 0);

    // The default: first occurrence, matching Temporal's behavior.
    let zdt = tz.to_ambiguous_zoned_datetime(dt).compatible()?;
    assert_eq!(zdt.offset(), offset(-4));

    // Always the earlier of the two candidates.
    let zdt = tz.to_ambiguous_zoned_datetime(dt).earlier()?;
    assert_eq!(zdt.offset(), offset(-4));

    // Always the later one, i.e. the second 1:30am.
    let zdt = tz.to_ambiguous_zoned_datetime(dt).later()?;
    assert_eq!(zdt.offset(), offset(-5));

    Ok(())
}

A fourth strategy, reject, turns ambiguity and gaps into errors rather than guesses. For a scheduling system where a silently duplicated slot could double-book a meeting, that is the right call. For a log viewer, it is not. Making the choice a named method rather than an implicit behavior is the whole idea.

The asymmetry between the two transitions is worth noting. During a fold, the