Jiff 1.0 ships: Rust datetime library commits to its API
Jiff is a datetime library for Rust that puts time zone handling front and center in its API, so that many common daylight saving time problems are handled automatically. Its author has announced the 1.0 release in a blog post that doubles as a tour of the API. The target audience is Rust programmers who need convenient datetime handling. The name is pronounced like "gif" with a soft "g," as in "gem."
The headline news is the stability commitment. The post says Jiff is already used in production in many projects: uv, Cargo, Starship, fd, Nushell, mise, Jujutsu and uutils/coreutils, and even as the basis for a Temporal implementation in AWS LLRT. So the author says it is time to call it 1.0. The wording of the promise is careful: unless some significant defect is found in Jiff's API, the plan is to commit to Jiff 1.0 indefinitely. The reasoning is that Jiff is meant to be an ecosystem building block that appears in the public API of other libraries. That makes it an attractive public dependency, and it also means semver-incompatible releases are likely to cause significant pain in the ecosystem, so they "will not be made lightly." Breaking changes between Jiff 0.2 and 1.0 are listed in the CHANGELOG.
The post then explains the design philosophy. The author believes datetime handling has been hard because the domain is poorly modeled: many libraries pass complexity on to their users instead of encapsulating it. Jiff tries to hide that complexity and make it hard to do the wrong thing, though the author notes Jiff is not the first library to try this.
The tour starts with vocabulary. Civil time is the time on your clock. UTC is the time standard underlying civil time. TAI is atomic time. A leap second is an adjustment to TAI that brings it closer to mean solar time and forms the basis of UTC. Unix time is UTC but ignoring leap seconds.
Jiff's types are described as an onion. A civil::Date is a plain Gregorian date with no location. A civil::Time is a plain time on a clock, to nanosecond precision. A civil::DateTime combines the two. A Timestamp is an unambiguous instant, stored as nanoseconds since the Unix epoch. A TimeZone is a set of rules for mapping a Timestamp to a civil::DateTime and back in a specific region. A ZonedDateTime combines a Timestamp, a civil::DateTime and a TimeZone to represent a specific instant in a specific place.
The examples use 1 November 2026 in America/New_York. Building the civil datetime 17:30 and attaching the zone yields a timestamp of 1793572200 seconds, and going the other way, from that timestamp plus the zone, yields the same civil datetime. The offset is the amount you adjust UTC to get civil time: 22:30 UTC on that day minus 5 hours is 17:30 in New York. The zone name is an IANA Time Zone Database identifier, like Australia/Sydney, Asia/Tokyo or Europe/Berlin.
A time zone maps an instant to an offset, and maps a civil datetime to a possibly ambiguous offset. Ambiguity arises when a civil time does not exist (clocks move ahead) or occurs twice (clocks move back). In New York on 1 November 2026 the clocks were set back at 2AM, so the 1AM hour repeats. The offset is -04:00 at 00:30 (summer time) and -05:00 at 02:30 (standard time). For 01:30, which falls in the "fold," Jiff picks the first occurrence by default, giving -04:00.
That default is the "compatible" strategy. Lower-level TimeZone APIs offer others: earlier() also picks the first occurrence in a fold, later() picks the second occurrence (offset -05:00), and unambiguous() returns an error whenever there is any ambiguity, with a message saying the datetime falls into a fold between offsets -04 and -05. The same idea applies to gaps, such as New York on 8 March 2026, when civil time skipped from 2AM to 3AM.
Key facts
- Jiff, a Rust datetime library that puts time zone handling at the center of its API, has reached version 1.0.
- The author's plan is to commit to the 1.0 API indefinitely, unless a significant defect is found in it; semver-incompatible releases "will not be made lightly."
- The post lists production users: uv, Cargo, Starship, fd, Nushell, mise, Jujutsu, uutils/coreutils, and AWS LLRT's Temporal implementation.
- In an ambiguous fold such as 1:30AM on 1 November 2026 in New York, Jiff picks the first occurrence (offset -04:00) by default, the "compatible" strategy; earlier(), later() and unambiguous() are alternatives.
- Breaking changes between Jiff 0.2 and 1.0 are listed in the CHANGELOG.
Why it matters
Datetime code is a classic source of bugs, and the author's argument is that most of them come from libraries that pass the domain's complexity on to users. Jiff's answer is to make time zones part of the core API, so that daylight saving time folds and gaps are handled by default rather than left to the caller. The 1.0 label matters because the author wants Jiff to appear in the public API of other libraries. A library in that position needs a stable surface, and the post ties the commitment directly to that goal.
Who it affects
Rust programmers who need convenient datetime handling, which is the stated audience. It also affects maintainers of libraries that might expose datetime types in their own public APIs, since the 1.0 commitment is aimed at making Jiff a safe public dependency. The projects the post lists as existing production users are uv, Cargo, Starship, fd, Nushell, mise, Jujutsu and uutils/coreutils, plus a Temporal implementation in AWS LLRT.
How to use it
The post gives a quick start: create a Cargo project, run cargo add jiff anyhow, paste an example into src/main.rs and run cargo run. Most examples are complete, self-contained programs. Basic flows include building a civil date and time, attaching an IANA zone name such as America/New_York with in_tz, or converting a Timestamp into a zoned datetime. Anyone upgrading from 0.2 should read the CHANGELOG for the list of breaking changes. To change how ambiguous times are resolved, use the TimeZone APIs: compatible(), earlier(), later() or unambiguous().
How solid is it
This is the library author's own first-party announcement, so it is a reliable statement of intent and of the design, but not an independent assessment. The adoption claims (the named projects and AWS LLRT) come from the author. The code examples carry assertions, such as the 1793572200 timestamp and the -04:00 and -05:00 offsets around the New York fold. The stability promise is phrased as a plan, "my plan is to commit to Jiff 1.0 indefinitely," and is conditional on no significant defect being found.
Risks and caveats
The 1.0 commitment is a plan, not a guarantee, and it has an explicit escape clause for a significant defect in the API. No timescale is given for how long "indefinitely" lasts, and no mechanism for the commitment beyond the author's stated plan. Upgrading from 0.2 involves breaking changes, which the post defers to the CHANGELOG. The default of picking the first occurrence in a fold is a choice; code that needs a different behaviour has to select earlier(), later() or unambiguous() explicitly.
“Unless some significant defect is found in Jiff’s API, my plan is to commit to Jiff 1.0 indefinitely.”
— Jiff 1.0 announcement post