Skip to content

Changelog 1.20

  • The core functions, which every industry uses.

Release notes of @northguild/gmt 1.20.0, newest first, built from packages/gmt/CHANGELOG.md. Back to Changelog.

Released 2026-10-22

  • 8871bc6: Add classifyStoredZoned, which says why a stored zoned time no longer resolves (Story CORE-83). It is in the new @northguild/gmt/zoned/classify subpath, and the root and @northguild/gmt/zoned export it too.

    Apps store a future event as an RFC 9557 string with both an offset and a zone, such as 2016-12-01T09:00:00+02:00[Europe/Istanbul]. When the zone’s rules change after the string is written, the offset and the zone can disagree, or the local time can land in a new gap or overlap. toOffsetInstant returns null for such a string and does not say why. classifyStoredZoned names the cause and returns every reading, so your code chooses one.

    import { classifyStoredZoned } from "@northguild/gmt/zoned/classify";
    classifyStoredZoned("2016-12-01T09:00:00+02:00[Europe/Istanbul]");
    // { kind: "offsetMismatch", storedOffset: "+02:00", zoneOffset: "+03:00",
    // atStoredOffset: "2016-12-01T07:00:00Z", atZoneOffset: "2016-12-01T06:00:00Z" }
    classifyStoredZoned("2026-03-29T01:30:00+00:00[Europe/London]");
    // { kind: "nonexistent", earlier: "2026-03-29T00:30:00Z",
    // later: "2026-03-29T01:30:00Z", atStoredOffset: "2026-03-29T01:30:00Z" }
    classifyStoredZoned("2026-03-29T01:30:00[Europe/London]"); // null (no offset)

    The result has one of five kinds: valid, validInOverlap, offsetMismatch, ambiguous and nonexistent. Every kind carries atStoredOffset, the instant that Temporal’s offset: "use" gives. From the returned fields you can reproduce each of Temporal’s four offset options. The function returns null for a string that lacks an offset or a zone, names an unknown zone, or uses a calendar other than iso8601.

    The answer depends on the time zone rules of the host, so the same string can be valid on one runtime and offsetMismatch on another. On Node, process.versions.tz names the tzdb release. A string ending in Z before the zone is always valid, as the Temporal specification reads it.

    The StoredZonedClassification type is exported from @northguild/gmt. The docs add the Stored Time Audit tool at /tools/stored-time-audit/ and a section in the offset-instants guide.

  • f939505: Add the timescale/ namespace for leap seconds and TAI, and the gnss/ namespace for the time scales of six satellite navigation systems (Stories MAR-16 and SPA-48). getFiscalPeriod and getQuarter now take the 53rd-week placement and the fiscal year label from the caller. Three changes break existing code, and Breaking changes covers each: isLeapSecond in plain/ is renamed hasSecond60, a fiscal calendar needs two new fields, and the hours-of-work functions move from @northguild/gmt/duty to @northguild/gmt/workforce.

    UTC has leap seconds. TAI and most satellite time scales do not. So the offset between UTC and a satellite clock is not a constant: it grew by one second with each of the 27 leap seconds inserted since 1972. A receiver’s week number also wraps, so one week number names several dates decades apart. The new functions take every offset from the IERS leap-second table built into GMT, never from a literal.

    import {
    fromTAI,
    gnssToUtc,
    gnssWeekToUtc,
    isLeapSecond,
    leapSecondsBetween,
    nextLeapSecond,
    rinexWeekToUtc,
    taiMinusUtc,
    toTAI,
    utcToGnss,
    utcToGnssWeek,
    utcToRinexWeek,
    } from "@northguild/gmt";
    // The leap-second table.
    taiMinusUtc("2024-01-01T00:00:00Z"); // 37
    taiMinusUtc("2016-01-01T00:00:00Z"); // 36
    taiMinusUtc("1971-01-01T00:00:00Z"); // null (before 1972)
    leapSecondsBetween("2000-01-01T00:00:00Z", "2024-01-01T00:00:00Z"); // 5
    nextLeapSecond("2016-01-01T00:00:00Z"); // "2016-12-31T23:59:60Z"
    nextLeapSecond("2024-01-01T00:00:00Z"); // "" (there are no more)
    isLeapSecond("2016-12-31T23:59:60Z"); // true
    isLeapSecond("2024-12-31T23:59:60Z"); // false (well-formed, but no leap second that day)
    // TAI.
    toTAI("2026-01-01T00:00:00Z"); // "2026-01-01T00:00:37 TAI"
    toTAI("2016-12-31T23:59:60.5Z"); // "2017-01-01T00:00:36.5 TAI"
    fromTAI("2017-01-01T00:00:36 TAI"); // "2016-12-31T23:59:60Z"
    // Six satellite time scales, one pair of functions for all of them.
    utcToGnss("GPS", "1980-01-06T00:00:00Z"); // "1980-01-06T00:00:00 GPS" (0 s at the GPS epoch)
    utcToGnss("GPS", "2024-01-01T00:00:00Z"); // "2024-01-01T00:00:18 GPS"
    utcToGnss("BDT", "2024-01-01T00:00:00Z"); // "2024-01-01T00:00:04 BDT"
    utcToGnss("GAL", "1999-08-22T00:00:00Z"); // "1999-08-22T00:00:13 GAL"
    utcToGnss("GLO", "2016-12-31T23:59:60Z"); // "2016-12-31T23:59:60 GLO" (UTC's own clock)
    gnssToUtc("GPS", "2017-01-01T00:00:17 GPS"); // "2016-12-31T23:59:60Z"
    // A broadcast week: name the counter and the era.
    gnssWeekToUtc("GPS-LNAV", 100, 0, 0); // "1981-12-05T23:59:59Z"
    gnssWeekToUtc("GPS-LNAV", 100, 0, 1); // "2001-07-21T23:59:47Z" (era 1: 1024 GPS weeks later)
    gnssWeekToUtc("GPS-LNAV", 1020, 0, { notBefore: "2019-04-07T00:00:00Z" }); // "2038-10-23T23:59:42Z"
    utcToGnssWeek("GPS-LNAV", "2019-04-07T00:00:00Z"); // { week: 0, timeOfWeekSeconds: 18, era: 2 }
    utcToGnssWeek("GAL", "2019-04-07T00:00:00Z"); // { week: 1024, timeOfWeekSeconds: 18, era: 0 }
    // A RINEX navigation-file week never wraps.
    rinexWeekToUtc("IRN", 2295, 86418); // "2024-01-01T00:00:00Z"
    utcToRinexWeek("BDT", "2021-07-05T21:59:56Z"); // { week: 809, timeOfWeekSeconds: 165600 }
    • timescale/ holds the IERS leap-second table as a closed record. The table runs to the last insertion, 2016-12-31, and is current through IERS Bulletin C 72 (6 July 2026). The CGPM decided in 2026 that UTC becomes continuous on 20 May 2027, so TAI − UTC stays 37 s for every later date. No function takes a table argument. A weekly check in this repository compares the table with the IERS file.
    • taiMinusUtc, leapSecondsBetween and nextLeapSecond read the table. Before 1972-01-01, TAI − UTC was fractional, so each returns the sentinel there instead of a whole number. leapSecondsBetween is signed, and counts a leap second when its second starts, at 23:59:60.000, inside [start, end).
    • isLeapSecond is a table lookup. It is true for the 27 inserted seconds only, in any offset spelling. A smeared clock never reads 23:59:60, so GMT cannot detect smearing. For the syntax test alone, use hasSecond60.
    • The timescale/ and gnss/ functions accept a listed second 60. "2016-12-31T23:59:60Z" is a real instant to them, and a second 60 on any other day returns the sentinel. Every other GMT function still rejects a second of 60.
    • toTAI and fromTAI convert between UTC and a TAI string, YYYY-MM-DDTHH:MM:SS[.fraction] TAI. The token is the FITS 4.0 time-scale name.
    • gnss/ treats six systems as peers: GPS, Galileo, BeiDou, QZSS, GLONASS and NavIC, named by their RINEX 4.02 time-system tokens GPS, GAL, BDT, QZS, GLO and IRN. No system is a default, and none has functions of its own.
    • utcToGnss and gnssToUtc convert between UTC and a system’s time-scale string, such as "2024-01-01T00:00:18 GPS". GPS, Galileo, QZSS and NavIC time run 19 s behind TAI, and BeiDou time 33 s. GLO is GLONASS time as RINEX reports it: UTC’s own hours, leap seconds included, not UTC + 3 h. Each system returns the sentinel before its own epoch. The offsets are nominal: the nanosecond corrections a satellite broadcasts are not applied.
    • gnssWeekToUtc and utcToGnssWeek read a broadcast week by its counter. Each GnssWeekCounter has one modulus. "GPS-LNAV", "QZS-LNAV" and "IRN-LNAV" wrap every 1024 weeks, "GAL" every 4096, and "GPS-CNAV", "QZS-CNAV", "BDT" and "IRN-L1NV" every 8192. GLONASS has no week counter.
    • rolloverEra is required, because a week number alone cannot say which pass of the counter it belongs to. Pass an integer era for stored data. Pass "rolling" for live receiver output: it picks the era within half a counter period of today, so it reads the clock. Pass { notBefore } to take the earliest match at or after an instant you state, such as a receiver’s firmware build date. It gives the same answer in any year.
    • rinexWeekToUtc and utcToRinexWeek read the week of a RINEX navigation record. That week is a continuous count that never wraps, from 1980 for GPS, Galileo, QZSS and NavIC, and from 2006 for BeiDou, so it has no era. A RINEX NavIC week read as a broadcast NavIC week is 1024 weeks off, which is why the two kinds of week have separate functions.
    • Also exported: the GnssSystem, GnssWeekCounter, RolloverEra, GnssWeek, RinexWeekSystem and RinexWeek types, and the @northguild/gmt/timescale, /timescale/calculate, /timescale/convert, /timescale/validate, @northguild/gmt/gnss and /gnss/convert subpaths.

    Fiscal calendars. IFRS 18 ¶29 (formerly IAS 1 ¶37) does not preclude a reporting period of 52 weeks, and no international standard says where a 53rd week goes or which calendar year names the fiscal year. Published calendars disagree on both. The NRF 4-5-4 calendar (US) adds the week to the last period and names the year by the year it starts in. The ONS retail trading periods (UK) add it to the first period and name the year by the calendar year that holds most of it. IFRS 18 ¶27(c) (formerly IAS 1 ¶51(c)) lets a reporting period be identified by the date it ends. IFRS 18 replaces IAS 1 for reporting periods beginning on or after 2027-01-01. So the caller now states both choices, and there is no default.

    import { getFiscalPeriod, getQuarter, isValidFiscalCalendar } from "@northguild/gmt";
    const ons = { pattern: "4-4-5", yearEndsOn: "2022-12-31", extraWeek: "firstPeriod", yearLabel: "majorityYear" } as const;
    getFiscalPeriod("2024-12-29", ons); // { year: 2025, period: 1, week: 1 } (ONS 2025 opens in December 2024)
    getFiscalPeriod("2025-02-01", ons); // { year: 2025, period: 1, week: 5 } (a five-week January)
    const nrf = { pattern: "4-5-4", yearEndsOn: "2026-01-31", extraWeek: "lastPeriod", yearLabel: "endYear" } as const;
    getFiscalPeriod("2024-01-28", nrf); // { year: 2024, period: 12, week: 53 } (week 53, named by the year it ends in)
    getQuarter("2023-10-15", { fiscalYearStartMonth: 7, yearLabel: "majorityYear" }); // { year: 2023, quarter: 2 }
    isValidFiscalCalendar({ pattern: "4-5-4", yearEndsOn: "2026-01-31" }); // false (no extraWeek or yearLabel)
    • extraWeek is the period a 53rd week is added to: "firstPeriod" or "lastPeriod". It has no effect in a 52-week year.
    • yearLabel names the fiscal year: "startYear", "endYear" or "majorityYear", the calendar year holding the most of its days. It is a field of FiscalCalendar and an option of getQuarter. When two calendar years hold 182 days each, "majorityYear" gives the end year, because IFRS 18 ¶27(c) (formerly IAS 1 ¶51(c)) lets a period be identified by its end date. For getQuarter, start months 1 to 7 put the most days in the start year and 8 to 12 in the end year, so a month-based fiscal year never ties.
    • year is still not a unique key for every year end. A 364- or 371-day year drifts against the calendar, so each label rule has a few year ends where two fiscal years share a label. The JSDoc lists them. If your year end is one of them, key on the fiscal year’s start date.
    • New validators. isValidFiscalCalendar checks a whole calendar, so you can tell a bad calendar from a date getFiscalPeriod cannot place. isValidFiscalExtraWeek and isValidFiscalYearLabel narrow a string read from configuration.
    • Fix: getFiscalPeriod returns a value for every date Temporal accepts. 1.19 returned null near Temporal’s first and last dates when the fiscal year ran past that limit. getFiscalPeriod("-271821-04-19", { pattern: "4-5-4", yearEndsOn: "2026-01-31", extraWeek: "lastPeriod", yearLabel: "startYear" }) now returns { year: -271821, period: 3, week: 12 }.
    • Fix: an array is not a fiscal calendar. 1.19 read an array with pattern and yearEndsOn set as properties as a calendar. getFiscalPeriod now returns null for any array, and isValidFiscalCalendar returns false, as isValidBusinessCalendar does.
    • Also exported: the FiscalExtraWeek and FiscalYearLabel types.

    Other changes.

    • The pattern parsers read names in "en" when no locale is given, not "en-US". This covers parseDateWithPattern, parseDateTimeWithPattern and parseTimeWithPattern. CLDR gives "en" the same month, weekday, era and AM/PM names as "en-US", so every result is unchanged.
    • The NRF 4-5-4 calendar is described as one published example (US), not the retail standard. The JSDoc quotes NRF’s current wording: a 53rd week is added when “there are four or more days left in January”.
    • isBusinessDay’s fixed Monday-to-Friday week is described correctly. ISO 8601 defines no weekend. Saturday and Sunday off is CLDR’s world default.
    • The JSDoc examples use zones and locales from several countries, such as London, Tokyo, Sydney, São Paulo, Johannesburg and Kolkata. Only the zone and its offset changed in each example, and every changed result was run again.
    • Each industry layer has its own TanStack Intent skill: gmt-gnss, gmt-transport, gmt-intermodal and gmt-workforce. Their functions have moved out of the topic skills, so gmt-integration, gmt-timezone, gmt-arithmetic and gmt-basics now cover Core alone. timescale/ is Core, so its leap-second table stays in gmt-integration. If you installed a skill with --map, map the new industry skills you need.
    • The notes for readers moving from date-fns are corrected. date-fns numbers Sunday 0, so nextDay(value, 0) becomes nextWeekday(value, 7), and previousDay maps the same way. date-fns starts a week on Sunday by default, so isSameWeek(a, b) becomes areDatesEqualBy(a, b, "week", { weekStartsOn: "sunday" }). Rules that cited another library now cite ECMA-402, UTS #35 or Temporal.

    1. isLeapSecond in plain/ is renamed hasSecond60. The name isLeapSecond now belongs to the table lookup in timescale/. An import from @northguild/gmt/plain or @northguild/gmt/plain/validate fails to compile. An import from @northguild/gmt still compiles and now runs the lookup, so its result can change with no type error:

    Call1.191.20
    isLeapSecond("2024-06-15T12:34:60Z")truefalse (no leap second can occur at 12:34)
    isLeapSecond("2024-12-31T23:59:60Z")truefalse (no leap second that day)
    isLeapSecond("23:59:60")truefalse (not an instant)
    isLeapSecond("2016-12-31T23:59:60Z")truetrue
    // 1.19: the syntax test
    import { isLeapSecond } from "@northguild/gmt/plain/validate";
    isLeapSecond("2024-06-15T12:34:60Z"); // true
    // 1.20: the same test, renamed
    import { hasSecond60 } from "@northguild/gmt/plain/validate";
    hasSecond60("2024-06-15T12:34:60Z"); // true
    // 1.20: whether a leap second was inserted
    import { isLeapSecond } from "@northguild/gmt/timescale";
    isLeapSecond("2024-06-15T12:34:60Z"); // false
    isLeapSecond("2016-12-31T23:59:60Z"); // true

    Migration: to keep the 1.19 result, rename the call and its import to hasSecond60. Its arguments and results are the same. To ask whether a second 60 is a real leap second, use isLeapSecond.

    2. A fiscal calendar needs extraWeek and yearLabel, and fiscal getQuarter options need yearLabel.

    Call that compiled in 1.191.20Migration
    getFiscalPeriod(value, { pattern, yearEndsOn })a type error, and null at run timeadd extraWeek: "lastPeriod", yearLabel: "startYear"
    getQuarter(value, { fiscalYearStartMonth })a type error, and null at run timeadd yearLabel: "startYear"
    getQuarter(value, {})a type error, and null at run timedrop the options to get calendar quarters
    // 1.19
    getFiscalPeriod("2024-01-28", { pattern: "4-5-4", yearEndsOn: "2026-01-31" }); // { year: 2023, period: 12, week: 53 }
    // 1.20, the same result
    getFiscalPeriod("2024-01-28", { pattern: "4-5-4", yearEndsOn: "2026-01-31", extraWeek: "lastPeriod", yearLabel: "startYear" }); // { year: 2023, period: 12, week: 53 }
    // 1.19
    getQuarter("2024-03-31", { fiscalYearStartMonth: 4 }); // { year: 2023, quarter: 4 }
    // 1.20, the same result
    getQuarter("2024-03-31", { fiscalYearStartMonth: 4, yearLabel: "startYear" }); // { year: 2023, quarter: 4 }

    Migration: each migration in the table gives exactly the 1.19 result. fiscalYearStartMonth no longer defaults to 1. If you added one to year to label a fiscal year by the year it ends in, pass yearLabel: "endYear" and remove the + 1. getQuarter with no options still returns calendar quarters.

    3. The hours-of-work functions move to @northguild/gmt/workforce. Hours-of-work rules serve drivers, seafarers, rail crew, flight crew and resident doctors alike, so they sit in a workforce layer of their own. The /duty subpaths are removed, and no alias is kept.

    1.191.20
    @northguild/gmt/duty@northguild/gmt/workforce
    @northguild/gmt/duty/calculate@northguild/gmt/workforce/calculate
    @northguild/gmt/duty/validate@northguild/gmt/workforce/validate
    // 1.19
    import { evaluateDutyLog } from "@northguild/gmt/duty";
    import { isValidDutyLog } from "@northguild/gmt/duty/validate";
    // 1.20
    import { evaluateDutyLog } from "@northguild/gmt/workforce";
    import { isValidDutyLog } from "@northguild/gmt/workforce/validate";

    Migration: change the import path. The function names, the types, the arguments and the results are the same, and an import from @northguild/gmt is unchanged.

  • 57b0556: The documentation moves to https://northguild.dev/gmt/. The package homepage, the README and the agent skills link there; old gmt-dox.northguild.workers.dev links redirect.

  • e043391: Long spans and long logs are much faster, and the business-day functions are smaller. No option or signature changes, and every function returns what it returned before, with one exception: a holiday array with its own Symbol.iterator is now read by index in rollDate and isBusinessDay, as businessDaysBetween already read it.

    Speed (Node 24, warm, before → after):

    FunctionInputBeforeAfter
    dutyViolations365-day log336 msabout 14 ms
    dutyViolationssplit sleeper rule, 10 years10,460 ms194 ms
    businessDaysBetween480 holidays, 1 to 30 years3.74 ms0.048 ms
    operatingTimeBetween1 year62.6 ms0.40 ms
    operatingTimeBetween10 years444 ms0.67 ms (4.3 ms the first time)
    addOperatingTime400 hours12.2 ms0.79 ms
    chargeableDays and freeTimeExpiry10 years, Europe/London162.6 ms0.70 ms (4.7 ms the first time)
    chargeableDays and freeTimeExpiry10 years, working days218.4 ms0.79 ms
    chargeableDays and freeTimeExpiry10 years, America/Port_of_Spain177.7 ms0.59 ms
    intervalCountZoned, intervalOverlappingDaysZoned, dwellTime100 years, Europe/London42 to 48 msabout 2 ms
    intervalSplitAtZoned1,000 points65.5 ms56.5 ms
    Offset-change search40-year span, Asia/Kolkata34.8 ms19.8 ms the first time, 0.06 ms after
    formatDatede-DE0.073 ms0.0068 ms
    getLocaleMonthNamesone locale1.28 ms0.036 ms
    cutoffSchedule50 entries13.1 ms5.6 ms

    The cost of the day-count and operating-hours functions no longer grows with the number of days. A 10-year span now costs a small multiple of a 1-year span.

    Size (minified / gzipped kB, one function imported):

    ImportBeforeAfter
    businessDaysBetween172.5 / 50.1155.9 / 45.6
    addBusinessDays173.6 / 50.6157.0 / 46.0
    formatDate155.4 / 45.2156.8 / 45.7
    chargeableDays197.3 / 57.8196.4 / 58.5
    operatingTimeBetween200.8 / 58.8204.0 / 60.6
    dutyViolations226.7 / 67.1228.5 / 68.2
    the whole package (root)487.1 / 127.9500.9 / 133.6

    @js-temporal/polyfill alone is 152.5 / 44.2 kB, so it is most of every figure. The business-day functions are smaller because checking a time zone no longer loads the Temporal workarounds. operatingTimeBetween, dutyViolations and the root are a little larger, and chargeableDays a little larger gzipped: they hold the new methods and keep the day-by-day one for spans near the limits of Temporal’s range. formatDate is 1.4 kB larger for its formatter cache.

  • 0645a85: formatCalendar reads a timeStyle given as an object, such as new String("long"), as the plain string. Before, it printed the UTC zone name it uses internally, as in “tomorrow at 2:30:00 PM UTC”.

  • 0645a85: roundZoned and roundUnix now round to the day as Temporal specifies when a clock change makes a date start twice, such as America/Goose_Bay on 6 November 2010.

  • 8871bc6: Fix a zoned value ending in Z and carrying a calendar annotation, such as +275760-09-12T23:00:00Z[America/Sao_Paulo][u-ca=hebrew], being refused near the end of the supported range. addZoned returned "" for it, as did the other functions that read the calendar first, because GMT read the time of day in the zone instead of taking the instant the Z names, which is how the Temporal specification reads it. They now return the result.

Last updated:

© 2026 NorthGuild · Licences

Code examples: MIT-0. Packages: MIT. Third-party data and components: their own licences, credited where they appear. Everything else: © 2026 NorthGuild, all rights reserved.