workclock

Fast, correct business-time arithmetic (working hours, SLAs, shifts) for Rust, Python and JavaScript — a maintained replacement for businesstimedelta, with a compatibility layer for existing code.

Status: pre-1.0; the API may still change in a minor release.

Install

cargo add workclock jiff
pip install workclock
uv add workclock
npm i workclock

The Rust API takes and returns jiff 0.2 types, so Rust code depends on jiff too.

Requirements

• Rust: 1.85 or later.
• Python: CPython 3.9 or later. The wheels use the stable ABI (abi3), one per platform: Linux x86_64 and aarch64 (manylinux and musllinux), macOS x86_64 and arm64, and Windows x64. Free-threaded CPython cannot load abi3 wheels. Other platforms build from the sdist, which needs a Rust toolchain.
• JavaScript: Node.js 22 or later. Browsers load the package through a bundler, or without one from workclock/web.

Time zone data

The Python wheels and the npm package bundle the IANA time zone database, so they need no system tzdata. The npm package always uses its bundled copy, whose zone rules are as current as the workclock release. The Python wheels use the system database when there is one, and the bundled copy otherwise.

The Rust crate uses jiff's defaults: the system database (/usr/share/zoneinfo, or the directory in TZDIR) on Linux and macOS, and a bundled copy on Windows. On a Linux image without tzdata, as some slim and distroless images are, every named zone, even "UTC", is an unknown-zone error. Install the tzdata package, point TZDIR at a zoneinfo directory, or enable jiff's tzdb-bundle-always feature to bundle the database.

Use cases

• Support-ticket SLAs: when is a ticket due, and how much of its SLA has elapsed?
• Payroll and overtime: how many hours of a shift fell inside contracted time?
• Staff rosters, including overnight shifts.
• Delivery ETAs that only count operating hours.

Quickstart

A support desk in London works 09:00–17:00 on weekdays with a lunch hour, and is closed on 25 and 28 December 2026. A ticket opened at 16:30 on Christmas Eve with an 8-hour SLA is due at 09:30 on 30 December.

Rust

use jiff::civil::{date, time};
use jiff::{SignedDuration, Zoned};
use workclock::{Break, Holidays, Schedule, Weekdays, WorkDay};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let support = Schedule::builder()
        .time_zone("Europe/London")
        .rule(WorkDay::new(time(9, 0, 0, 0), time(17, 0, 0, 0), Weekdays::MON_TO_FRI))
        .rule(Break::new(time(12, 0, 0, 0), time(13, 0, 0, 0), Weekdays::MON_TO_FRI))
        .rule(Holidays::new([date(2026, 12, 25), date(2026, 12, 28)]))
        .build()?;

    let opened: Zoned = "2026-12-24T16:30[Europe/London]".parse()?;
    let due = support.add(&opened, SignedDuration::from_hours(8))?;
    assert_eq!(due.to_string(), "2026-12-30T09:30:00Z");

    let now: Zoned = "2026-12-29T11:00[Europe/London]".parse()?;
    assert_eq!(support.between(&opened, &now), SignedDuration::from_mins(150));
    Ok(())
}

API documentation is on docs.rs.

Python

from datetime import date, datetime, time
from zoneinfo import ZoneInfo

from workclock import Break, Holidays, Schedule, WorkDay

london = ZoneInfo("Europe/London")
support = Schedule(
    [
        WorkDay(time(9), time(17)),  # Monday to Friday by default
        Break(time(12), time(13)),
        Holidays([date(2026, 12, 25), date(2026, 12, 28)]),
    ],
    time_zone=london,
)

opened = datetime(2026, 12, 24, 16, 30, tzinfo=london)
support.add(opened, hours=8)  # 2026-12-30 09:30, London time
support.between(opened, datetime(2026, 12, 29, 11, tzinfo=london))  # 2:30:00

between_many, add_many and sub_many take lists or NumPy arrays and process them in one call. Most code written for businesstimedelta runs unchanged with import workclock.compat as businesstimedelta; MIGRATING.md lists where it differs.

JavaScript

import { Schedule } from "workclock";

const support = new Schedule({
  timeZone: "Europe/London",
  rules: [
    { type: "workday", start: "09:00", end: "17:00" },
    { type: "break", start: "12:00", end: "13:00" },
    { type: "holidays", dates: ["2026-12-25", "2026-12-28"] },
  ],
});

support.add("2026-12-24T16:30:00Z", 8 * 3_600_000); // Date 2026-12-30T09:30:00.000Z
support.between("2026-12-24T16:30:00Z", new Date("2026-12-29T11:00:00Z")); // 9000000 ms

Instants are Dates or ISO 8601 strings with an offset; durations are milliseconds. In browsers without a bundler, import the default init from workclock/web and await init() first.

More complete programs are in crates/workclock/examples, examples/python and js/examples. The errors each binding raises are listed in DESIGN.md.

Why workclock

Correct

businesstimedelta 1.0.1 has had no release since 2019. workclock fixes:

• Overnight shifts. A 22:00–06:00 shift counts 0 hours between Monday 22:00 and Tuesday 06:00, and adding 4 hours at Monday 22:00 lands on Wednesday. workclock gives 8 hours and Tuesday 02:00.
• Crashes past the last holiday (#8, #10): TypeError once a query passes the last date in a holiday list.
• Infinite loops (#9) when holidays and working hours use different time zones. Every workclock search is bounded.
• Signed differences (#12): Schedule.between(a, b) is negative when b is before a.
• DST. Working hours are wall-clock times in each rule's IANA zone, and ambiguous or skipped times resolve the way jiff, RFC 5545 and JavaScript Temporal do.

Every rule is specified with examples in DESIGN.md, and each binding is checked against a brute-force oracle with property-based tests.

Fast

Medians on a 2017 laptop (Intel i5-8250U, Windows 11), from Python:

The same single call takes 1.7 µs from Rust and 2.2 µs from JavaScript, and 16 µs through workclock.compat, which keeps the schedule it builds from businesstimedelta's mutable rules until their attributes change. benchmarks/RESULTS.md has every case with p95s, and DESIGN.md explains where the time goes.

Prior art & credits

workclock ports the test suite and the API of businesstimedelta by Sebastiaan Boer, released under the MIT license. Its last release, 1.0.1, was in September 2019, and issues #3, #8, #9, #10 and #12 remain open. The ported API is workclock.compat, and the ported tests run against it in CI. The original copyright notice is kept in NOTICE.

License

MIT