# workclock

> Fast, correct business-time arithmetic (working hours, SLAs, shifts) for Rust, Python and JavaScript, and 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` (Rust; the API uses jiff 0.2 types), `pip install workclock` or `uv add workclock` (Python), `npm i workclock` (JavaScript and TypeScript).
- Requires Rust 1.85+, CPython 3.9+, Node.js 22+.
- Inputs must be timezone-aware: Python `datetime` with `tzinfo`, JavaScript `Date` or ISO 8601 string with an offset, Rust `jiff::Zoned` or `jiff::Timestamp`. Time zones are IANA names such as `Europe/London`.
- JavaScript durations are milliseconds.

## Docs

- [Overview](https://workclock.karthik.nz/docs.md): What workclock computes, what it is for, and where to start in Rust, Python or JavaScript.
- [Install](https://workclock.karthik.nz/docs/install.md): Add workclock to a Rust, Python or JavaScript project, with the toolchain and time zone data each one needs.
- [Quickstart: Rust](https://workclock.karthik.nz/docs/quickstart/rust.md): Build a Rust program that finds when a support ticket is due and how much of its SLA has been used.
- [Quickstart: Python](https://workclock.karthik.nz/docs/quickstart/python.md): Build a Python program that finds when a support ticket is due and how much of its SLA has been used.
- [Quickstart: JavaScript](https://workclock.karthik.nz/docs/quickstart/javascript.md): Build a Node.js program that finds when a support ticket is due and how much of its SLA has been used.
- [Schedules](https://workclock.karthik.nz/docs/concepts/schedules.md): What a schedule is, how its rules combine into working time, and how to build one in Rust, Python and JavaScript.
- [Rules](https://workclock.karthik.nz/docs/concepts/rules.md): How WorkDay, Break and Holidays rules produce working time and time off, including overnight shifts and per-rule time zones.
- [Adding time](https://workclock.karthik.nz/docs/concepts/adding-time.md): Find the instant reached after adding or subtracting an amount of working time, with add and sub.
- [Measuring time](https://workclock.karthik.nz/docs/concepts/measuring-time.md): Count the working time between two instants with between, and read the sign of the result.
- [Periods](https://workclock.karthik.nz/docs/concepts/periods.md): Find the stretch of working time at, after or before an instant, with next_period and previous_period.
- [Time zones and DST](https://workclock.karthik.nz/docs/concepts/time-zones-and-dst.md): How rule times follow each rule's IANA time zone, and how workclock resolves daylight saving time gaps and overlaps.
- [Errors](https://workclock.karthik.nz/docs/concepts/errors.md): The three errors workclock raises in Rust, Python and JavaScript, when each is raised, and how to handle them.
- [Inputs and precision](https://workclock.karthik.nz/docs/concepts/inputs-and-precision.md): Which instant, duration and time zone types each language accepts, how precise results are, and which inputs are rejected.
- [Support SLAs](https://workclock.karthik.nz/docs/guides/support-slas.md): Find when a support ticket is due, and how much of its SLA has been used and how much is left, with add and between.
- [Payroll and overtime](https://workclock.karthik.nz/docs/guides/payroll-and-overtime.md): Split the time on a timesheet into contracted hours and overtime by counting the working time inside each clock-in and clock-out span with between.
- [Overnight shifts](https://workclock.karthik.nz/docs/guides/overnight-shifts.md): Count, extend and look up 22:00–06:00 shifts that cross midnight, with between, add and next_period.
- [Delivery ETAs](https://workclock.karthik.nz/docs/guides/delivery-etas.md): Find when an order is dispatched by adding a handling time to the time it was placed, counting only the warehouse's operating hours, with add.
- [Batch operations](https://workclock.karthik.nz/docs/guides/batch-operations.md): Run add, sub and between over many instants in one call with the Python and JavaScript batch methods, and see when batching pays off.
- [Migrating](https://workclock.karthik.nz/docs/guides/migrating-from-businesstimedelta.md): Run businesstimedelta 1.0.1 code on workclock by changing one import, see what changes, and move to the typed workclock.Schedule API.
- [Python](https://workclock.karthik.nz/docs/reference/python.md): Every public class, method and exception of the workclock Python package, with signatures, parameters, return values and errors.
- [Python compat](https://workclock.karthik.nz/docs/reference/python-compat.md): Every public class and function of workclock.compat, the businesstimedelta 1.0.1 API on the workclock engine, with parameters and errors.
- [JavaScript](https://workclock.karthik.nz/docs/reference/javascript.md): Every export of the workclock npm package, with TypeScript signatures, parameters, return values and errors.
- [FAQ](https://workclock.karthik.nz/docs/faq.md): Short answers about workclock's relationship to businesstimedelta, installation, time zone data, naive datetimes, termination and scope.

## Reference

- [Rust API on docs.rs](https://docs.rs/workclock)
- [DESIGN.md](https://raw.githubusercontent.com/Karthik-beta/workclock/main/DESIGN.md): the specification, with an example and an ID for every edge case

## Optional

- [Benchmarks](https://workclock.karthik.nz/docs/benchmarks.md): How fast each binding is, measured against businesstimedelta 1.0.1 and a hand-written standard-library loop.
- [Changelog](https://raw.githubusercontent.com/Karthik-beta/workclock/main/CHANGELOG.md)