[tz] JavaScript IANA date/time library, now with support for leap seconds, TAI, TDT

Kerry Shetline kerry at shetline.com
Thu Apr 22 18:01:38 UTC 2021

About two months ago I released the first major version of @tubular/time, a JavaScript/TypeScript npm package for date/time handling, with solid support for IANA timezones, including dealing with weird edge cases like 47-hour days and negative DST and such.

I’ve just finished up adding a feature I’ve always wanted to have in a date/time package, and that’s the ability to properly handle and represent leap seconds. Along with that comes conversion to and from TAI (International Atomic Time) and astronomical time systems.


One interesting issue was how to handle a broad range of years (thousands of years forward and backward in time) in a way that was nicely integrated with Universal Coordinated Time. The idea for UTC got something of a wobbly start around 1960, and wasn’t implemented in its current form until 1972. Going forward in time, UTC is only strictly defined for up to six months beyond the next announced leap second, or next announced lack of any leap second on the way.

I settled on the following scheme for resolving these issues, and I’m curious what others might think about it:

* For all dates prior to 1957, estimated UT1 is in effect. This is most accurate back to 1600, for which there is sufficient astronomical data for reasonable approximate conversions from UT1 to TAI and dynamical time. Further back in time less accurate approximations are in effect.
* From 1957-1958, using a sliding weighted average, UT1 transitions to proleptic UTC.
* From 1958-1972 proleptic UTC, as proposed by Tony Finch (https://fanf.livejournal.com/69586.html), is used, with the first non-official leap second occurring at 1959-06-30 23:59:60.
* From 1972 up until the latest updates provided by the International Bureau of Weights and Measures, well-defined UTC prevails, with the first official leap second occurring at 1972-06-30 23:59:60.
* For a year to 18 months after the current time, or after the last defined leap second (whichever is later), a presumed leap-second-free span of UTC is projected to occur.
* A sliding weighted average transition from UTC to estimated UT1 follows for the next 365 days.
* Formulaic predicted UT1 is used for all later dates and times thereafter.

Another project I’ve been working on (which isn’t quite ready for prime time because it’s utterly without documentation) is a new JavaScript timezone compiler. This has replaced an old Java project I used for generating the timezone data used by @tubular/time: https://github.com/kshetline/tubular_time_tzdb

More information about the tz mailing list