Changelog 1.20
Release notes of @northguild/gmt 1.20.0, newest first, built from packages/gmt/CHANGELOG.md. Back to Changelog.
@northguild/gmt
Section titled “@northguild/gmt”1.20.0
Section titled “1.20.0”Released 2026-10-22
Minor Changes
Section titled “Minor Changes”-
8871bc6: Add
classifyStoredZoned, which says why a stored zoned time no longer resolves (Story CORE-83). It is in the new@northguild/gmt/zoned/classifysubpath, and the root and@northguild/gmt/zonedexport 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.toOffsetInstantreturnsnullfor such a string and does not say why.classifyStoredZonednames 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,ambiguousandnonexistent. Every kind carriesatStoredOffset, the instant that Temporal’soffset: "use"gives. From the returned fields you can reproduce each of Temporal’s fouroffsetoptions. The function returnsnullfor a string that lacks an offset or a zone, names an unknown zone, or uses a calendar other thaniso8601.The answer depends on the time zone rules of the host, so the same string can be
validon one runtime andoffsetMismatchon another. On Node,process.versions.tznames the tzdb release. A string ending inZbefore the zone is alwaysvalid, as the Temporal specification reads it.The
StoredZonedClassificationtype 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 thegnss/namespace for the time scales of six satellite navigation systems (Stories MAR-16 and SPA-48).getFiscalPeriodandgetQuarternow take the 53rd-week placement and the fiscal year label from the caller. Three changes break existing code, and Breaking changes covers each:isLeapSecondinplain/is renamedhasSecond60, a fiscal calendar needs two new fields, and the hours-of-work functions move from@northguild/gmt/dutyto@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"); // 37taiMinusUtc("2016-01-01T00:00:00Z"); // 36taiMinusUtc("1971-01-01T00:00:00Z"); // null (before 1972)leapSecondsBetween("2000-01-01T00:00:00Z", "2024-01-01T00:00:00Z"); // 5nextLeapSecond("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"); // trueisLeapSecond("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,leapSecondsBetweenandnextLeapSecondread the table. Before 1972-01-01, TAI − UTC was fractional, so each returns the sentinel there instead of a whole number.leapSecondsBetweenis signed, and counts a leap second when its second starts, at23:59:60.000, inside[start, end).isLeapSecondis a table lookup. It is true for the 27 inserted seconds only, in any offset spelling. A smeared clock never reads23:59:60, so GMT cannot detect smearing. For the syntax test alone, usehasSecond60.- The
timescale/andgnss/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. toTAIandfromTAIconvert 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 tokensGPS,GAL,BDT,QZS,GLOandIRN. No system is a default, and none has functions of its own.utcToGnssandgnssToUtcconvert 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.GLOis 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.gnssWeekToUtcandutcToGnssWeekread a broadcast week by its counter. EachGnssWeekCounterhas 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.rolloverErais 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.rinexWeekToUtcandutcToRinexWeekread 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,RinexWeekSystemandRinexWeektypes, and the@northguild/gmt/timescale,/timescale/calculate,/timescale/convert,/timescale/validate,@northguild/gmt/gnssand/gnss/convertsubpaths.
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)extraWeekis the period a 53rd week is added to:"firstPeriod"or"lastPeriod". It has no effect in a 52-week year.yearLabelnames the fiscal year:"startYear","endYear"or"majorityYear", the calendar year holding the most of its days. It is a field ofFiscalCalendarand an option ofgetQuarter. 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. ForgetQuarter, 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.yearis 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.
isValidFiscalCalendarchecks a whole calendar, so you can tell a bad calendar from a dategetFiscalPeriodcannot place.isValidFiscalExtraWeekandisValidFiscalYearLabelnarrow a string read from configuration. - Fix:
getFiscalPeriodreturns a value for every date Temporal accepts. 1.19 returnednullnear 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
patternandyearEndsOnset as properties as a calendar.getFiscalPeriodnow returnsnullfor any array, andisValidFiscalCalendarreturnsfalse, asisValidBusinessCalendardoes. - Also exported: the
FiscalExtraWeekandFiscalYearLabeltypes.
Other changes.
- The pattern parsers read names in
"en"when no locale is given, not"en-US". This coversparseDateWithPattern,parseDateTimeWithPatternandparseTimeWithPattern. 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-intermodalandgmt-workforce. Their functions have moved out of the topic skills, sogmt-integration,gmt-timezone,gmt-arithmeticandgmt-basicsnow cover Core alone.timescale/is Core, so its leap-second table stays ingmt-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)becomesnextWeekday(value, 7), andpreviousDaymaps the same way. date-fns starts a week on Sunday by default, soisSameWeek(a, b)becomesareDatesEqualBy(a, b, "week", { weekStartsOn: "sunday" }). Rules that cited another library now cite ECMA-402, UTS #35 or Temporal.
Breaking changes
Section titled “Breaking changes”1.
isLeapSecondinplain/is renamedhasSecond60. The nameisLeapSecondnow belongs to the table lookup intimescale/. An import from@northguild/gmt/plainor@northguild/gmt/plain/validatefails to compile. An import from@northguild/gmtstill compiles and now runs the lookup, so its result can change with no type error:Call 1.19 1.20 isLeapSecond("2024-06-15T 12:34:60Z") truefalse(no leap second can occur at 12:34)isLeapSecond("2024-12-31T 23:59:60Z") truefalse(no leap second that day)isLeapSecond("23:59:60") truefalse(not an instant)isLeapSecond("2016-12-31T 23:59:60Z") truetrue// 1.19: the syntax testimport { isLeapSecond } from "@northguild/gmt/plain/validate";isLeapSecond("2024-06-15T12:34:60Z"); // true// 1.20: the same test, renamedimport { hasSecond60 } from "@northguild/gmt/plain/validate";hasSecond60("2024-06-15T12:34:60Z"); // true// 1.20: whether a leap second was insertedimport { isLeapSecond } from "@northguild/gmt/timescale";isLeapSecond("2024-06-15T12:34:60Z"); // falseisLeapSecond("2016-12-31T23:59:60Z"); // trueMigration: 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, useisLeapSecond.2. A fiscal calendar needs
extraWeekandyearLabel, and fiscalgetQuarteroptions needyearLabel.Call that compiled in 1.19 1.20 Migration getFiscalPeriod(value, { pattern, yearEndsOn }) a type error, and nullat run timeadd extraWeek: "lastPeriod", yearLabel: "startYear"getQuarter(value, { fiscalYearStartMonth }) a type error, and nullat run timeadd yearLabel: "startYear"getQuarter(value, {}) a type error, and nullat run timedrop the options to get calendar quarters // 1.19getFiscalPeriod("2024-01-28", { pattern: "4-5-4", yearEndsOn: "2026-01-31" }); // { year: 2023, period: 12, week: 53 }// 1.20, the same resultgetFiscalPeriod("2024-01-28", { pattern: "4-5-4", yearEndsOn: "2026-01-31", extraWeek: "lastPeriod", yearLabel: "startYear" }); // { year: 2023, period: 12, week: 53 }// 1.19getQuarter("2024-03-31", { fiscalYearStartMonth: 4 }); // { year: 2023, quarter: 4 }// 1.20, the same resultgetQuarter("2024-03-31", { fiscalYearStartMonth: 4, yearLabel: "startYear" }); // { year: 2023, quarter: 4 }Migration: each migration in the table gives exactly the 1.19 result.
fiscalYearStartMonthno longer defaults to1. If you added one toyearto label a fiscal year by the year it ends in, passyearLabel: "endYear"and remove the+ 1.getQuarterwith 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/dutysubpaths are removed, and no alias is kept.1.19 1.20 @northguild/gmt/ duty @northguild/gmt/ workforce @northguild/gmt/ duty/ calculate @northguild/gmt/ workforce/ calculate @northguild/gmt/ duty/ validate @northguild/gmt/ workforce/ validate // 1.19import { evaluateDutyLog } from "@northguild/gmt/duty";import { isValidDutyLog } from "@northguild/gmt/duty/validate";// 1.20import { 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/gmtis unchanged.
Patch Changes
Section titled “Patch Changes”-
57b0556: The documentation moves to https://northguild.dev/gmt/. The package
homepage, the README and the agent skills link there; oldgmt-dox.northguild.workers.devlinks 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.iteratoris now read by index inrollDateandisBusinessDay, asbusinessDaysBetweenalready read it.Speed (Node 24, warm, before → after):
Function Input Before After dutyViolations365-day log 336 ms about 14 ms dutyViolationssplit sleeper rule, 10 years 10,460 ms 194 ms businessDaysBetween480 holidays, 1 to 30 years 3.74 ms 0.048 ms operatingTimeBetween1 year 62.6 ms 0.40 ms operatingTimeBetween10 years 444 ms 0.67 ms (4.3 ms the first time) addOperatingTime400 hours 12.2 ms 0.79 ms chargeableDaysandfreeTimeExpiry10 years, Europe/London 162.6 ms 0.70 ms (4.7 ms the first time) chargeableDaysandfreeTimeExpiry10 years, working days 218.4 ms 0.79 ms chargeableDaysandfreeTimeExpiry10 years, America/Port_of_Spain 177.7 ms 0.59 ms intervalCountZoned,intervalOverlappingDaysZoned,dwellTime100 years, Europe/London 42 to 48 ms about 2 ms intervalSplitAtZoned1,000 points 65.5 ms 56.5 ms Offset-change search 40-year span, Asia/Kolkata 34.8 ms 19.8 ms the first time, 0.06 ms after formatDatede-DE0.073 ms 0.0068 ms getLocaleMonthNamesone locale 1.28 ms 0.036 ms cutoffSchedule50 entries 13.1 ms 5.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):
Import Before After businessDaysBetween172.5 / 50.1 155.9 / 45.6 addBusinessDays173.6 / 50.6 157.0 / 46.0 formatDate155.4 / 45.2 156.8 / 45.7 chargeableDays197.3 / 57.8 196.4 / 58.5 operatingTimeBetween200.8 / 58.8 204.0 / 60.6 dutyViolations226.7 / 67.1 228.5 / 68.2 the whole package (root) 487.1 / 127.9 500.9 / 133.6 @js-temporal/polyfillalone 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,dutyViolationsand the root are a little larger, andchargeableDaysa little larger gzipped: they hold the new methods and keep the day-by-day one for spans near the limits of Temporal’s range.formatDateis 1.4 kB larger for its formatter cache. -
0645a85:
formatCalendarreads atimeStylegiven as an object, such asnew 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:
roundZonedandroundUnixnow 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
Zand 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.addZonedreturned""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 theZnames, which is how the Temporal specification reads it. They now return the result.
© 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.