Changelog 1.21
Release notes of @northguild/gmt 1.21.0, newest first, built from packages/gmt/CHANGELOG.md. Back to Changelog.
@northguild/gmt
Section titled “@northguild/gmt”1.21.0
Section titled “1.21.0”Released 2026-11-03
Minor Changes
Section titled “Minor Changes”-
03aa25f: The core string validators now accept a value of any type. A value typed
unknown, such as a function argument or the output of a schema check, needed a cast before you could ask whether it is valid. The functions already returnedfalsefor a value that is not a string, so for 26 of the 27 only the types change. Two rare type-level uses stop compiling, and Breaking changes covers both.One result changes:
isValidTimeZonereturnedtruefor aTemporal.ZonedDateTimewhosetoStringgives a zone id. It now returnsfalsefor every value that is not a string.- A value typed
unknownneeds no cast, and atrueresult narrows it tostring. The three duration-unit predicates narrow it to their unit union. - A
stringargument staysstringwhen the result isfalse. - A typed union such as
string | nullorstring | undefinedgets a plainbooleanand is not narrowed. Afalseresult does not show which part of the union the value is. values.filter(isValidDate)on anunknown[]givesstring[].
import { isValidDate } from "@northguild/gmt";declare const input: unknown;if (isValidDate(input)) {input; // string}Two functions whose typed calls cannot fail now return a plain value.
getUnixNow()returnsnumber, soaddUnix(getUnixNow(), { years: 1 })compiles with no null check, andx12TimeCodeZonereturnsX12NamedZonefor anX12ZoneTimeCode. A value outside the parameter type, such as astringvariable, a value typedunknownor a misspelt unit, still compiles and returnsnumber | nullorX12NamedZone | null. These overloads change only the types.The validator change covers 27 functions:
isValidDate,isValidDateTime,isValidTime,isValidYearMonth,isValidMonthDay,isValidCalendarDate,isValidIsoDateLike,isValidSqlDateTime,isValidDateDurationUnit,isValidDateTimeDurationUnit,isValidTimeDurationUnit,isValidZonedDateTime,isValidTimeZone,isValidCalendarZonedDateTime,isValidRfc2822DateTime,isValidRfc3339DateTime,isValidInstant,isValidInt64NanosecondDateTime,isValidInt64NanosecondInstant,isValidNanoPattern,isValidUtc,isValidHttpDate,isValidUtcTimestamp,isValidDuration,isValidUtcOffset,isValidEpcisEventTimeandisValidEpcisTimeZoneOffset.The clock functions no longer return a moment one millisecond early. After a test faked a clock set before 1970, the polyfill’s next reading of the real clock could land one millisecond before
Date.now(), so a test that then faked a 2027 clock could see the last millisecond of 2026. Every function that reads the clock now checks its reading againstDate.now()and corrects a one-millisecond shortfall. A nativeTemporaland a fixed polyfill are not affected. The defect is filed as tc39/proposal-temporal#3335.Breaking changes
Section titled “Breaking changes”1.
Parameters<typeof fn>readsunknown. TypeScript takesParameters<>from the last overload, which now takesunknown. This applies to the 27 validators above,getUnixNowandx12TimeCodeZone. Name the parameter type yourself:// 1.20: v is stringconst f = (v: Parameters<typeof isValidDate>[0]) => v.length;// 1.21: v is unknown, so v.length fails with TS18046. Name the type:const f = (v: string) => v.length;// The same for the other two:type UnixNowOptions = { epochUnit?: UnixUnit }; // was Parameters<typeof getUnixNow>[0]type ZoneCode = X12ZoneTimeCode; // was Parameters<typeof x12TimeCodeZone>[0]2. A value typed
anynarrows tostring. Atrueresult from one of the 24 string validators now narrows ananyargument tostring, as it narrowsunknown. Code that then assigns it to a branded string type fails with TS2322. The three duration-unit predicates already narrowedany, so they do not change. Only a variable or parameter typedanynarrows. A property of ananyvalue, such asJSON.parse(text).dateorbody.date, does not, so most untyped data is unaffected.type IsoDate = string & { readonly __brand: "IsoDate" };// 1.20: a stays any after the check, so this compiledfunction read(a: any): IsoDate | null {return isValidDate(a) ? a : null;}// 1.21: a is string after the check, so state the brandfunction read(a: any): IsoDate | null {return isValidDate(a) ? (a as IsoDate) : null;} - A value typed
-
e271bb0: Add a holiday rule engine in the new
@northguild/gmt/calendar/rulessubpath (Story CORE-54). The root and@northguild/gmt/calendarexport it too. Most holidays are rules, not lists, so you describe a holiday once and get its date for any year. GMT ships no holiday list: you supply the rules.Six functions and three types:
nthWeekdayOfMonth(year, month, weekday, n)finds the third Monday or the last Sunday of a month.nis1to5,-1to-5or"last".easterSunday(year, options?)gives Easter Sunday. Thecomputusoption is"gregorian"(default) or"julian", and a Julian date comes back as an ISO date.observedDate(isoDate, policy, calendar?)moves a date that falls on a day off.ObservancePolicyis keyed by ISO weekday, and each shift is"nextWorkingDay",{ next: weekday }or{ previous: weekday }. There is no default policy.holidayDates(rule, year, options?)returns the dates of oneHolidayRule. A rule isfixed,calendarFixed(such as 1 Shawwal in an Islamic calendar),nthWeekday,easterRelativeordates.buildBusinessCalendar(spec)expands rules over a year range into theBusinessCalendarthatisBusinessDayandaddBusinessDaysalready take.isValidHolidayRule(rule)is a type guard. It tells a rule that is wrong from a year in which the rule has no date. AcalendarFixedday must be one its month has in some year, so HebrewM01day 31 is not a rule. GMT reads each month’s longest length from the calendar and keeps no table.
import { buildBusinessCalendar, easterSunday, nthWeekdayOfMonth, observedDate } from "@northguild/gmt/calendar/rules";nthWeekdayOfMonth(2026, 3, 7, "last"); // "2026-03-29"easterSunday(2024, { computus: "julian" }); // "2024-05-05"observedDate("2027-12-25", { 6: { previous: 5 }, 7: { next: 1 } }); // "2027-12-24"buildBusinessCalendar({timeZone: "UTC",weekend: [6, 7],rules: [{ name: "Christmas", kind: "fixed", month: 12, day: 25, observed: { 6: "nextWorkingDay", 7: "nextWorkingDay" } },{ name: "Second day", kind: "fixed", month: 12, day: 26, observed: { 6: "nextWorkingDay", 7: "nextWorkingDay" } },],years: { from: 2021, to: 2021 },}); // { weekend: [6, 7], holidays: ["2021-12-27", "2021-12-28"], timeZone: "UTC" }A
"nextWorkingDay"shift walks past the weekend, every holiday that does not walk and the walks of the rules above it. The days that close do not depend on the rule order; the order decides only which holiday takes which day. A moved holiday closes only the date it moved to; list the rule twice, once withoutobserved, to close both. A date a year lacks, such as 29 February, is skipped and never clamped. Bad input gives""(the date functions),[](holidayDates) ornull(buildBusinessCalendar).The docs add the Holiday Rule Builder, Observance Comparator and Moving Feasts tools, and a section in the business calendars guide.
-
584594f: Add
parseHumanDurationandformatHumanDuration, which read and write the duration strings people type, such as2h 30mand3 days(Story CORE-85).parseHumanDurationis in@northguild/gmt/duration/parseandformatHumanDurationis in@northguild/gmt/duration/format. The root and@northguild/gmt/durationexport both.Config files and command-line flags hold
30s,2h 30mor7d, notPT30SorP7D, andparseDurationreads ISO 8601 only. Each caller wrote a parser, and each one decided alone what1mmeans. These two functions use one grammar that is written out in full on the function page.import { parseHumanDuration } from "@northguild/gmt/duration/parse";import { formatHumanDuration } from "@northguild/gmt/duration/format";parseHumanDuration("2h 30m"); // "PT2H30M"parseHumanDuration("3 days"); // "P3D"parseHumanDuration("1.5h"); // "PT1H30M"parseHumanDuration("1s 500ms"); // "PT1.5S"parseHumanDuration("1m"); // "PT1M" (a minute)parseHumanDuration("1mo"); // "P1M" (a month)parseHumanDuration("1.5h 30m"); // "" (a fraction only on the last unit)parseHumanDuration("P1M"); // "" (ISO 8601, so use parseDuration)formatHumanDuration("PT2H30M"); // "2h 30m"formatHumanDuration("PT90M"); // "90m"formatHumanDuration("PT1.5S"); // "1.5s"formatHumanDuration("-PT2H30M"); // "-2h 30m"mis always a minute andmoalways a month. Unit names are not case-sensitive, so1Mis also a minute.- Units are kept as you wrote them:
3 daysisP3D, notPT72H. A day is not always 24 hours, so the function does not guess. - Write a unit at most once, largest first. A typo such as
2h 3hor30m 2hreturns"", so it is never summed. - A fraction is allowed only on hours, minutes or seconds, and only on the last unit. Temporal spreads it into smaller units.
msjoins the seconds and takes no fraction. - Separate units with spaces, a comma,
and, or nothing at all:2h30m. Only the plain space counts. A leading or trailing space, a tab or a no-break space returns"", so trim the input first. parseHumanDurationreturns""for anything outside the grammar.formatHumanDurationreturns""for anything that is not an ISO 8601 duration. For a duration in the words of a locale, useformatDuration.parseHumanDuration(formatHumanDuration(d))gives the same duration asparseDuration(d), for every valid ISO 8601 durationd.
No string is valid in both grammars, so to accept either form write
parseDuration(text) || parseHumanDuration(text).The docs add the Duration Parser Bench tool at
/tools/duration-parser-bench/and a section in the durations guide. -
e05f791: Add 19 functions for a length of time counted from now (Story CORE-104): one year, one month or 90 days, given back as seconds, an epoch, an HTTP date or a UTC timestamp, and the seconds left until a stored time. The seconds in “one year” depend on today’s date: 31536000 from 2026-06-15, 31622400 from 2027-06-15, because the second year holds 29 February 2028. A hand-written
31_536_000is a day short in that case.import { ttlFromNow, getUtcIn, formatHttpDateFromNow, secondsUntilRetryAfter } from "@northguild/gmt";ttlFromNow({ days: 90 });// { seconds: 7776000, milliseconds: 7776000000, epochSeconds: 1820836800,// httpDate: "Mon, 13 Sep 2027 12:00:00 GMT", iso: "2027-09-13T12:00:00Z" } (from 2027-06-15T12:00:00Z)getUtcIn({ months: 1 }); // "2027-07-15T12:00:00Z"formatHttpDateFromNow({ years: 1 }); // "Thu, 15 Jun 2028 12:00:00 GMT"secondsUntilRetryAfter("120"); // 120- A length from now, one form per function:
getUnixIn,getUnixAgo,getUtcIn,getUtcAgo,getDateIn,getDateAgo,getDateTimeIn,getDateTimeAgo,getTimeIn,getTimeAgo,getZonedIn(zone first),getZonedAgo,formatHttpDateFromNow,totalUnitsFromNowandttlFromNow. They take a unit object such as{ days: 90 }. A duration string, an empty object or a negative amount returns the sentinel, sonullstill means bad input only. The name gives the direction: a pastExpiresisformatHttpDate(getUtcAgo({ days: 1 })). - Counted in UTC. Unix, UTC, HTTP-date and
ttlFromNowresults do not change with the server’s time zone.totalUnitsFromNowtakes atimeZoneoption for a wall-clock count, andgetZonedInandgetZonedAgocount on the zone’s wall clock. The plain functions start from the system zone, sogetDateIn({ days: 0 })equalsgetToday(). ttlFromNowreads the clock once, soseconds,milliseconds,epochSeconds,httpDateandisoname the same instant. If any form cannot be written (a result past year 9999, for example) the whole result isnull.- The reverse job:
secondsUntilUnix,secondsUntilHttpDateandsecondsUntilRetryAfterreturn the whole seconds left, rounded up, and a negative number once the time has passed.secondsUntilRetryAftertakes either form of aRetry-Afterheader.spanSecondsreturns the signed, fractional seconds between two instants, likespanMsin another unit. - No cap on a length. A draft revision of RFC 6265 has browsers limit
Max-AgeandExpiresto 400 days; applying that limit is the caller’s choice.
Behaviour change: near a clock change, in either direction, some results were wrong and are now right:
totalDuration,normalizeDuration,diffZoned,diffZonedAsDuration,intervalLengthZoned, and, with atimeZone,diffUnix,diffUnixAsDurationandintervalLengthUnix.formatRelativeZoned,formatRelativeUnixandformatRelativeUtcchange too. Where the Temporal specification has no value for the case (tc39/proposal-temporal #3336, #3311 and #3310), these functions now return the sentinel (nullor"") instead of a number. For example,totalDuration("-PT23H20M", "days", { relativeTo: "2024-03-11T02:30:00-04:00[America/New_York]" })returned about-1.0145and now returnsnull. A caller that read that number now getsnull, so check for it. - A length from now, one form per function:
-
c7a63b2: Add month-day values (
--12-25, a month and a day with no year) and year-month values (2026-10, a year and a month with no day): 23 functions and two regexes (Story CORE-102). A birthday, an anniversary or a fixed holiday has no year, and a card expiry or a billing month has no day. Until now the only way to store them was to invent the missing part, which turns 29 February into 1 March and puts a made-up-01on every month.All 23 functions are in
plain/and in the root. They return"",falseornullfor bad input and never throw.import {parseMonthDay,parseMonthDayWithPattern,monthDayToDate,formatMonthDay,} from "@northguild/gmt";import { isValidYearMonth, addYearMonth, endOfYearMonth } from "@northguild/gmt";parseMonthDay("12-25"); // "--12-25"parseMonthDayWithPattern("25 décembre", "d MMMM", "fr"); // "--12-25"formatMonthDay("--12-25", "en-US", { month: "long", day: "numeric" }); // "December 25"monthDayToDate("--02-29", 2023); // "2023-02-28" (a common year clamps, as Temporal does)monthDayToDate("--02-29", 2024); // "2024-02-29"isValidYearMonth("2026-10"); // trueaddYearMonth("2026-12", { months: 1 }); // "2027-01"endOfYearMonth("2024-02"); // "2024-02-29"- Month-day:
isValidMonthDay,parseMonthDay,parseMonthDayFromDate,parseMonthDayFromDateTime,parseMonthDayWithPattern,formatMonthDay,compareMonthDays,areMonthDaysEqual,monthDayToDate.parseMonthDayaccepts--MM-DDandMM-DDand always writes--MM-DD.--02-29is valid;--02-30is not. - Year-month:
isValidYearMonth,parseYearMonth,parseYearMonthFromDate,parseYearMonthFromDateTime,parseYearMonthWithPattern,formatYearMonth,compareYearMonths,areYearMonthsEqual,addYearMonth,subtractYearMonth,diffYearMonth,startOfYearMonth,endOfYearMonth,getDaysInYearMonth. They acceptYYYY-MMand±YYYYYY-MM.addYearMonthandsubtractYearMonthtakeyearsandmonthsonly. - Regexes:
plainMonthDayandplainYearMonthin@northguild/gmt/regex. isValidDate("2026-10")andparseDateWithPattern("10/2026", "MM/yyyy")still returnfalseand"". Use the year-month functions for those strings.formatMonthDayandformatYearMonthdrop a field the value does not have, asformatDatedoes with a time field, and return""for atimeStyleor a calendar other thangregoryoriso8601. AdateStyletakes its widths from the locale’s own date pattern, as ECMA-402 says, so the output is what nativetoLocaleStringprints in Chromium and Safari, on the polyfill too:formatMonthDay("--12-25", "de-DE", { dateStyle: "medium" })is"25.12.".[u-ca=ISO8601]in upper case now parses in both new readers on the polyfill, as it does on native Temporal.
Fixed:
parseDateWithPatternandparseDateTimeWithPatternnow read a month name written in a sentence, soparseDateWithPattern("15 марта 2024", "d MMMM yyyy", "ru")returns"2024-03-15"instead of"". A pattern may useL–LLLLfor the stand-alone name, andM–MMMMmatch either form when the name is unambiguous. - Month-day:
-
6ed1a08: Add recurrence rules and cron lines in a zone, in the new
@northguild/gmt/recurrencesubpath. The root exports it too. A schedule such as “every weekday at 02:30” is written in local time, so a daylight-saving change can leave an occurrence with a time that does not exist or that happens twice. GMT expands the schedule into instants and marks every occurrence a change touched.Four functions and the types they use (
RecurrenceRule,CronExpression,OccurrenceWindow,RecurrenceOccurrence,CronRun):parseRecurrenceRule(value)reads an RFC 5545RRULEvalue, all 14 parts, with the rule’s validity checks. It returnsnullfor anything else, includingEXRULE,RSCALEandSKIP.expandRecurrence(rule, start, timeZone, window, options?)gives the occurrences as instants, withRDATEandEXDATElists.disambiguationis"compatible"(default, the RFC’s reading),"earlier","later"or"reject". Each row carries itsclassificationplus theearlierandlaterinstants.parseCronExpression(value)reads five crontab fields, with ranges, lists,/step, month and weekday names,7as Sunday and the nicknames@hourlyto@annually. It returnsnullfor a seconds field,@rebootand theL,W,#and?tokens.cronRuns(expression, timeZone, window, policy)gives the runs. There is no default policy, because real cron daemons disagree."crontabMatch"never runs a time that does not exist and runs a repeated time twice."daemonCatchUp"runs a fixed-time job from a skipped interval once, at the change, when the gap is under 3 hours, and a job in a repeated interval only once when the overlap is 3 hours or less, as cronie’s daemon does.
The window is
{ start, end }(half-open) or{ after, count }with a count of 1 to 10,000. Bad input givesnullfrom the parsers and[]from the other two. A start,RDATEorEXDATEwith a bracketed annotation such as[Europe/Paris]is bad input, because a call has one zone.[]also comes back for a cron line that never matches, a window of more than 10,000 rows, and"reject"when the start, a wall-timeRDATEorEXDATE, or a returned row is not unique.import { cronRuns, expandRecurrence, parseCronExpression, parseRecurrenceRule } from "@northguild/gmt/recurrence";expandRecurrence(parseRecurrenceRule("FREQ=DAILY;COUNT=3"), "2024-03-09T02:30:00", "America/New_York", {after: "2024-03-08T00:00:00Z",count: 3,}).map((row) => [row.instant, row.classification]);// [["2024-03-09T07:30:00Z", "unique"], ["2024-03-10T07:30:00Z", "nonexistent"], ["2024-03-11T06:30:00Z", "unique"]]cronRuns(parseCronExpression("30 2 * * *"),"America/New_York",{ start: "2024-03-09T00:00:00Z", end: "2024-03-12T00:00:00Z" },"daemonCatchUp",).map((run) => run.instant);// ["2024-03-09T07:30:00Z", "2024-03-10T07:00:00Z", "2024-03-11T06:30:00Z"]DTSTARTis always the first occurrence. A{ after, count }window for a rule with fewer thancountoccurrences returns the ones it has. A rule that never matches again, such as February 30, gives DTSTART alone. A rare rule, such as a leap day or a Friday the 13th, still fills a count of 10,000.UNTILmust be a UTC date-time with a capitalTandZ. When a cron line restricts both the day of month and the day of week, a day that matches either one runs. The root bundle grows by about 27 KB.The docs add the Cron in a Zone tool and a recurrence and cron guide.
-
9cf156d: Add
parseSqlOffsetDateTimeandisValidSqlOffsetDateTime, which read the timestamp-with-time-zone text a database prints, and thesqlOffsetDateTimeregex they match. PostgreSQLtimestamptzprints2024-03-15 14:30:00+00, and SQL Serverdatetimeoffsetprints2007-05-08 12:35:29.1234567 +12:15. Neither is the RFC 3339 form the library’s other readers take: PostgreSQL may print an hour-only offset (+00), and SQL Server puts a space before the offset. Until now no function in the library read them.parseSqlOffsetDateTimereturns an ISO 8601 date-time that keeps the offset, or""when the text is not a SQL offset timestamp.isValidSqlOffsetDateTimereturnstruefor the same text. It accepts a value of any type, and atrueresult narrows it tostring. A date that does not exist, such as 30 February, is rejected by both.import { parseSqlOffsetDateTime } from "@northguild/gmt/instant/parse";import { isValidSqlOffsetDateTime } from "@northguild/gmt/instant/validate";parseSqlOffsetDateTime("2024-03-15 14:30:00-08"); // "2024-03-15T14:30:00-08:00"parseSqlOffsetDateTime("2007-05-08 12:35:29.1234567 +12:15"); // "2007-05-08T12:35:29.1234567+12:15"parseSqlOffsetDateTime("2024-03-15 14:30:00"); // "" (no offset: use parseSqlDateTime)isValidSqlOffsetDateTime("2024-03-15 14:30:00+00"); // trueisValidSqlOffsetDateTime("2024-02-30 00:00:00+00"); // falseThe result keeps the offset the database printed, so pass it to
toOffsetInstantto get the instant. To write a value for a database, usefromOffsetInstantorformatRfc3339: every major database reads that ISO 8601 form.- The new subpath
@northguild/gmt/instant/parseholdsparseSqlOffsetDateTime. The root export has it too. convertUnixToPlainDate,convertUnixToPlainDateTimeandconvertUnixToPlainTimenow name their first parametervalue, asconvertUnixToUtcandconvertUnixToZoneddo. It wasunix. No call changes, but your editor’s hover text and the API reference show the new name.
- The new subpath
-
5dac948: Read the time out of a UUID, ULID, MongoDB ObjectId, Snowflake or KSUID, and bridge Parquet
INT96, Arrow and protobuf timestamps (Story CORE-56). Seven functions are in the new@northguild/gmt/precision/identifierssubpath, ten converters join the foreign-epoch bridges in@northguild/gmt/precision/convert, and two guards join@northguild/gmt/precision/validate. The root and@northguild/gmt/precisionexport them too.Many identifiers are timestamps. Each has its own epoch and width, so code that decodes them by hand often reads the wrong date. GMT decodes IDs and generates none.
import {fromUuidTimestamp,fromSnowflake,uuidV7TimestampPrefix,} from "@northguild/gmt/precision/identifiers";fromUuidTimestamp("017F22E2-79B0-7CC3-98C4-DC0C0C07398F"); // "2022-02-22T19:22:22Z"fromUuidTimestamp("f81d4fae-7dec-41d0-a765-00a0c91e6bf6"); // "" (version 4 carries no time)fromSnowflake("175928847299117063", { epochMs: 1420070400000, shift: 22 });// "2016-04-30T11:18:25.796Z"uuidV7TimestampPrefix("2024-01-01T00:00:00Z"); // "018cc251-f400"fromUuidTimestampreads versions 1, 6 and 7 and returns""for any other. Versions 1 and 6 keep their 100 ns ticks, and version 7 gives milliseconds.uuidV7TimestampPrefixandulidTimestampPrefixgive the start of an ID for a range scan.fromUlid,fromObjectIdandfromKsuidreturn""for text that is not an ID. They accept only the exact form, so a ULID with anI,L,OorUis rejected and a KSUID is case-sensitive.fromSnowflaketakes the layout as a required argument (SnowflakeLayout), because one ID read with another system’s epoch gives a plausible wrong date. It takes abigintor a string and never anumber.toParquetInt96/fromParquetInt96,toArrowTimestamp/fromArrowTimestamp,toArrowLocalTimestamp/fromArrowLocalTimestamp,toProtoTimestamp/fromProtoTimestampandtoProtoDuration/fromProtoDurationconvert both ways. An Arrow column without a timezone holds wall-clock time, sofromArrowLocalTimestampreturns a plain date-time and not an instant.- An
int64of nanoseconds holds only 1677 to 2262, sotoArrowTimestampgives0npast either end.isValidInt64NanosecondInstantandisValidInt64NanosecondDateTimetell that0napart from the epoch. A protobufTimestampcountsnanosforward fromseconds, so-0.5 sbefore the epoch is{ seconds: -1n, nanos: 500000000 }.
The docs add the ID Timestamp Decoder at
/tools/id-timestamp-decoder/, the Column Timestamp Bridge at/tools/column-timestamp-bridge/, a time-ordered identifiers guide and three scenarios.
Patch Changes
Section titled “Patch Changes”-
7ef1197: Fix
formatZonedRangelosing the zone name you asked for on Chrome, Node and Safari. WithtimeZoneName: "long"or"longGeneric"the range printed a short name (EST,ET), and with"shortOffset"or"longOffset"it printed no zone at all. A range now keeps the requested style, as Firefox does:10:00 AM - 12:00 PM Eastern Standard Time,... GMT-5,... GMT-05:00. The cause is an ICU bug (ICU-20548) that cuts the zone width from ranges; GMT checks for it once per style and only repairs on an engine that has it. Output with notimeZoneName, or withshortorshortGeneric, is unchanged.Also fix
formatZonedRangeon Firefox whendayPeriodandtimeZoneNameare both set andhourCycleandhour12are not: the range printed10 AM GMT-5 - 12 PM GMT-5instead of the flexible day periods10 in the morning GMT-5 - 12 noon GMT-5that a singleformatZonedcall gives. GMT checks for it once and only repairs on an engine that has it. -
36b0a31: Islamic calendar dates before the Hijra (622 CE) read and compute correctly in WebKit (Safari). WebKit prints such a date as a positive year in a second era and the polyfill takes the year as printed, so
calendarDatefields were wrong anddiffDateAsDuration,addDateand the other date arithmetic across that epoch inislamic-civil,islamic-tblaorislamic-umalquranever returned. GMT now reads the era, corrects the year and runs the specification’s arithmetic itself for those years. Output is unchanged on every other engine (temporalCompat workaround D18). -
b1cf491: Each package’s npm description and keywords now say what it does.
@northguild/gmtnames time zones, DST, business days and ISO 8601. Each lint package says it bans theDateobject and points to the@northguild/gmtreplacement.The
getTimezoneOffset()lint message in all three lint packages now namesgetTimeZoneOffset(timeZone, instant)from@northguild/gmt, instead of “zoned methods”.The
no-date-library-importsmessage in all three lint packages now names the banned library and links its migration guide on northguild.dev, which maps that library’s calls to their@northguild/gmtreplacements. Moment.js, Day.js, Luxon and date-fns each get their own guide;spacetimelinks the list of guides.All three lint packages now also ban
@date-fns/tz, the time zone package for date-fns v4. The Biome plugin now bans the same packages as the other two, and no longer flags names outside that list such asmoment-tzorluxon-timezone. -
fa0fd00: Fix
diffZoned,diffZonedAsDurationandintervalLengthZonedreturningnullfor a calendar unit between two names of one time zone, such asUTCandEtc/UTCorAsia/KolkataandAsia/Calcutta, when GMT runs on the polyfill in WebKit. The polyfill finds a zone name’s primary form throughIntl.DateTimeFormat, which JavaScriptCore returns as written, so it took the two names for two zones. GMT checks for this once. Where the check fails:Etc/UTC,Etc/GMTandGMTcount asUTC, as ECMA-402 requires. This works in every WebKit, Safari 27 included.- For any other pair, GMT asks the browser’s own
Temporal. This works in WebKit builds that shipTemporal, such as Playwright WebKit 26.6. Safari 27 has noTemporal, and no other browser API there names a zone’s primary form, so in Safari 27 a pair such asAsia/KolkataandAsia/Calcuttastill counts as two zones.
On Chrome, Firefox and Node nothing changes.
-
b1cf491:
areZonedEqualnow compares the instant, the time zone and the calendar, as Temporal’sZonedDateTime.prototype.equalsdoes, instead of the wall-clock fields and the zone name. Two readings of a repeated wall clock, such as02:30+02:00and02:30+01:00in Europe/Berlin on 2024-10-27, are an hour apart and no longer compare equal. Two names for one time zone, such asUTCandEtc/UTC, now compare equal on every host, and so do IANA link names such asEurope/KievandEurope/Kyivwherever the host resolves them (Safari 27 withoutTemporalkeeps two such names as written).areZonedEqualBy,mapZonedDatesInRangeandformatZonedRangetreat two names for one time zone as the same zone too, so a range or comparison that used to return the empty result or compare by clock label now works.diffZonedanddiffZonedAsDurationdo the same: between two names of one time zone they accept a calendar unit and round by months as they do within one name, so2024-01-31T00:00:00+00:00[UTC]to2024-02-29T12:00:00+00:00[Etc/UTC]rounds up toP2Mand truncates toP1M. The same holds forintervalLengthZoned.
© 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.