Changelog 1.16
Release notes of @northguild/gmt 1.16.0, newest first, built from packages/gmt/CHANGELOG.md. Back to Changelog.
@northguild/gmt
Section titled “@northguild/gmt”1.16.0
Section titled “1.16.0”Released 2026-09-23
Minor Changes
Section titled “Minor Changes”-
a845422: Add the
calendar/namespace: ISO week and ordinal dates, quarter and fiscal periods, and zone-aware bucketing (Story CORE-5).Two absences with outsized consequences, and they turn out to be the same absence twice: a calendar boundary is not a fixed number of hours, and it is not in UTC.
Week and period identifiers. Vessel schedules are published by week number and retail runs on 52/53-week fiscal calendars. GMT could express neither.
import {getFiscalPeriod,getIsoWeekDate,getOrdinalDate,getQuarter,} from "@northguild/gmt";getIsoWeekDate("2027-01-01"); // { year: 2026, week: 53, weekday: 5 } — week-year 2026, not 2027getOrdinalDate("2024-12-31"); // { year: 2024, dayOfYear: 366 }getQuarter("2024-03-31", { fiscalYearStartMonth: 4 }); // { year: 2023, quarter: 4 }// The NRF retail calendar, stated as its published rule: "the Saturday nearest to January 31".const nrf = { pattern: "4-5-4", yearEndsOn: "2026-01-31" } as const;getFiscalPeriod("2024-06-15", nrf); // { year: 2024, period: 5, week: 19 }getFiscalPeriod("2024-01-28", nrf); // { year: 2023, period: 12, week: 53 } — a 53-week yearZone-aware bucketing. “Group by day in
America/New_York” over UTC timestamps is the most common observability bug there is, and the same operation decides how many chargeable days a container accrued, because free time is counted in terminal-local calendar days.import { bucketRange, floorToZone } from "@northguild/gmt";floorToZone("2024-06-15T03:00:00Z", "day", "America/New_York"); // "2024-06-14T04:00:00Z"floorToZone("2024-06-15T03:00:00Z", "day", "UTC"); // "2024-06-15T00:00:00Z"bucketRange("2024-03-09T05:00:00Z", "2024-03-12T04:00:00Z", "day", "America/New_York");// ["2024-03-09T05:00:00Z", "2024-03-10T05:00:00Z", "2024-03-11T04:00:00Z"] — 24h, then 23h- Identifiers take a zoneless date or datetime; a moment is refused. An instant has no calendar date until a zone is named, and answering “which ISO week is this?” in whatever zone the string happened to be written in is the bug this story exists to prevent. Floor it with
floorToZonefirst, or convert it in the zone you mean. getFiscalPeriod’syearEndsOnstates the year-end rule, by example — not one year’s end. Fiscal years end on that date’s weekday, on the occurrence nearest that date’s month and day. The NRF’s published rule, “the Saturday nearest to January 31” (NRF 4-5-4 calendar), is"2026-01-31"— a Saturday falling exactly on January 31 — and it regenerates every year boundary the NRF publishes for 2017 through 2028, all three 53-week years included. Whether a year has 52 or 53 weeks is derived from the gap between its own two ends, never read from a bundled table: there is no single correct retail calendar to bundle. A 53rd week is appended to period 12, which is where the NRF adds it.yearis the calendar year a fiscal year starts in, for bothgetFiscalPeriodandgetQuarter— matching the NRF, where fiscal 2023 runs 2023-01-29 to 2024-02-03. Conventions that label by the end year (the US federal October-start FY2025 begins in October 2024) should add one. It is not a unique key for a rule anchored near 1 January: a 364/371-day year drifts against the calendar, so under “the Saturday nearest to 31 December” two consecutive fiscal years share a label and some calendar years label none. The JSDoc says so; GMT does not invent a label the inputs do not fix.- Buckets are deliberately not uniform in length. A local day that springs forward is 23 hours and one that falls back is 25; forcing 24 is what makes a daily aggregate drift an hour twice a year. The same honesty applies to boundaries that do not exist: the calendar day Samoa deleted crossing the date line is absent from
bucketRange, a local day whose midnight is skipped starts at 01:00, and in a zone that falls back by half an hour (Australia/Lord_Howe) the local 01:00 hour bucket is genuinely 90 minutes long. - Boundaries are measured in exact time, not by truncating a wall clock. Truncating and
re-resolving is what most implementations do, and it breaks in zones whose shift is not a
whole hour:
Pacific/Chathamsprings forward 02:45 → 03:45, so a truncated local 03:00 does not exist and resolving it lands after the instant being floored. GMT measures how far into the unit the wall clock sits and subtracts that exactly, so a floor never moves forward, and a bucket shorter than its own unit — Chatham’s 15-minute 03:00 hour,America/Goose_Bay’s 60-second local midnight — is never skipped. Checked against 2,576 transition windows across all 418 IANA zones. bucketRangeis half-open,[start, end), so anendlanding exactly on a boundary does not open that bucket; a zero-length range mid-bucket still returns the one bucket holding it. It returns at most 10,000 boundaries and[]past that, since an unbounded hour walk over Temporal’s ±273,790-year range would exhaust memory.- Weeks start on Monday (ISO 8601) in both
floorToZoneandbucketRange, matchingstartOfZonedandintervalCountZoned. - Also exported: the
FiscalCalendar,FiscalPatternandZoneBucketUnittypes, and the type guards that narrow the two unions —isValidFiscalPatternandisValidZoneBucketUnit. BothgetFiscalPeriodandfloorToZone/bucketRangereturn their sentinel for an unrecognised pattern or unit, which is the same sentinel a date or instant they cannot use returns; a pattern or unit read from config, an env var or a form is a bare string until one of these narrows it.
- Identifiers take a zoneless date or datetime; a moment is refused. An instant has no calendar date until a zone is named, and answering “which ISO week is this?” in whatever zone the string happened to be written in is the bug this story exists to prevent. Floor it with
-
3b39fdd: Add the business calendar engine: holiday calendars, calendar composition and roll conventions (Story CORE-7).
BusinessCalendaris{ weekend: number[], holidays: string[], timeZone: string }. The weekend is explicit ISO weekday numbers because Saturday–Sunday is not universal — much of the Middle East is Friday–Saturday, and some markets keep a one-day weekend. Holidays are caller-supplied: GMT bundles no holiday table on the default import path, because holiday data is jurisdictional and changes annually, sometimes with days of notice.New in
calendar/business/:businessDaysBetween("2024-07-01", "2024-07-05", usCalendar); // 3 — start exclusive, end inclusivenextBusinessDay("2024-07-03", usCalendar); // "2024-07-05" — strictly after, skipping 4 JulypreviousBusinessDay("2024-07-05", usCalendar); // "2024-07-03"rollDate("2024-05-31", "modifiedFollowing", usCalendar); // "2024-05-30" — forward would leave MaymergeCalendars([usCalendar, ukCalendar]); // working days both jurisdictions sharerollDateimplements the six conventions —following,modifiedFollowing,preceding,modifiedPreceding,endOfMonthandnone.mergeCalendarsunions weekend rules and holidays, so a date survives only if it is a working day in every input: the two-currency intersection FX settlement needs, and the two-port one an intermodal move needs.isBusinessDay,addBusinessDaysandsubtractBusinessDaystake an optionalBusinessCalendaras a new trailing argument. Omitting it keeps their existing Monday–Friday, no-holiday behaviour exactly, so no shipped call changes. All three are re-exported fromcalendar/businessalongside the new functions.isValidBusinessCalendarandisValidRollConventionnarrow a candidate, telling a misconfigured calendar or contract term apart from bad date input when a function returns its sentinel.Fixes a defect in
addBusinessDays/subtractBusinessDays/addZonedBusinessDays/subtractZonedBusinessDays: the shared walker recursed once per calendar day, so an amount above roughly 6,000 business days overflowed the stack and returned the invalid-input sentinel for a valid request —addBusinessDays("2024-01-01", 10000)returned""instead of"2062-05-01". The walk is now a bounded loop, capped at 200,000 calendar days (about 547 years), returning the sentinel only when that cap is reached. -
8ecc54c: Add foreign epoch bridges to
precision/convert/: NTP, WindowsFILETIME, .NET ticks, Excel day serials, and PostgreSQL’s internal microseconds (Story CORE-3).Nothing else counts from 1970. NTP counts from 1900 and rolls over in 2036;
FILETIMEcounts 100-nanosecond intervals from 1601; .NET ticks count the same interval from year 1; Excel uses a day serial carrying a deliberate 1900 leap-year bug; PostgreSQL stores microseconds from 2000-01-01. None of it was in gmt, so every integration hardcoded the constants — usually wrongly.import {toNtpTimestamp,fromNtpTimestamp,toFileTime,fromFileTime,toDotNetTicks,fromDotNetTicks,toExcelSerial,fromExcelSerial,toPgMicroseconds,fromPgMicroseconds,} from "@northguild/gmt";toFileTime("1970-01-01T00:00:00Z");// 116444736000000000n — 100 ns intervals since 1601-01-01toDotNetTicks("1970-01-01T00:00:00Z");// 621355968000000000n — same unit, counted from 0001-01-01toPgMicroseconds("2024-03-10T12:00:00Z");// 763387200000000n — microseconds since 2000-01-01toExcelSerial("2024-03-10T12:00:00Z");// 45361.5 — days, with the time of day as the fraction- NTP timestamps are era-ambiguous by design. The seconds field is unsigned 32-bit, so it wraps every ~136.19 years and the value carries no era.
toNtpTimestamp("2036-02-07T06:28:15Z")is18446744069414584320n, the last second of era 0, and the next second is0nagain — the wire format’s own ambiguity, not a gmt limitation, so instants outside era 0 wrap rather than being rejected.fromNtpTimestamptakes the era as an explicit second argument, defaulting to 0. - Excel’s serial 60 is the phantom 29 February 1900 — a date that never existed, since 1900 was not a leap year. Lotus 1-2-3 got it wrong and Excel keeps the bug for compatibility, so
fromExcelSerial(60)is"": 59 is 1900-02-28 and 61 is 1900-03-01, and mapping 60 onto either neighbour would put gmt one day out from Excel for every earlier date.{ system: "1904" }selects the legacy Mac system, whose serials are exactly 1462 lower and which has no phantom day. - Each bridge accepts only what its target format can hold, and returns the namespace’s sentinel otherwise rather than an out-of-range number:
toFileTimeon a pre-1601 instant is0n, not a negative tick count, andtoExcelSerialpast 9999-12-31 isnull. The ranges are the formats’ own — unsigned 64-bit forFILETIME,DateTime.MinValue/MaxValuefor .NET ticks, serials 1–2958465 (or 0–2957003 in the 1904 system) for Excel, and PostgreSQL’sMIN_TIMESTAMP(4713 BC) fortimestamptz, which is 40× later than the earliest instant Temporal can represent. - Round trips are exact to the target format’s unit. Where that unit is coarser than a nanosecond, the conversion floors toward negative infinity so the grid stays uniform either side of the epoch: 100 ns for
FILETIMEand .NET ticks, 1 µs for PostgreSQL, 1 ms for Excel. NTP is the exception in the other direction — its 2^-32 s unit is finer than a nanosecond, sofromNtpTimestamprounds to the nearest nanosecond, which is what makes the round trip exact rather than one nanosecond early. - Every bridge returns a sentinel (
"",0n,null) on invalid input and never throws. For thebigint-returning ones0nis also their own epoch — 1900-01-01 for NTP, 1601-01-01 forFILETIME, 0001-01-01 for .NET ticks, 2000-01-01 for PostgreSQL — so validate the input first when the two must be told apart. - These are plain instant conversions; no leap seconds are involved in any of them.
toNanosecondsnow delegates to a shared internal instant parser, so all six functions in the namespace that take an instant string apply one leap-second and calendar-annotation gate. Its behaviour is unchanged. - NTP timestamps are era-ambiguous by design. The seconds field is unsigned 32-bit, so it wraps every ~136.19 years and the value carries no era.
-
727a3f4: Make a
diff*units array return the whole difference, number Sunday-first weeks by UTS #35, and read microseconds and nanoseconds in everyparseUnitFrom*function (Story CORE-8).A units array accounts for the whole difference.
diffDate,diffDateTime,diffTime,diffUtc,diffZonedanddiffUnixused the largest listed unit as Temporal’slargestUnitand returned only the listed fields. The amount in any unit not listed was dropped:["years", "days"]across 1 year and 2 months returned{ years: 1, days: 0 }. Weeks were dropped too, because Temporal fills weeks only when they are the largest unit. Unlisted amounts now fold into the next smaller listed unit, measured from the start moved by the larger listed amounts, so the record adds back up to the difference. A contiguous list keeps Temporal’s own fields and rounding.import { diffDate, diffDateTime } from "@northguild/gmt/plain";import { diffZoned } from "@northguild/gmt/zoned";diffDate("2024-01-01", "2025-03-15", ["years", "days"]); // { years: 1, days: 73 }diffDate("2024-01-01", "2024-03-20", ["months", "weeks", "days"]); // { months: 2, weeks: 2, days: 5 }diffDateTime("2024-01-01T00:00", "2024-03-20T05:00", ["months", "weeks", "hours"]); // { months: 2, weeks: 2, hours: 125 }diffZoned("2024-02-10T00:00:00-05:00[America/New_York]", "2024-03-11T23:00:00-04:00[America/New_York]", ["months", "hours"]); // { months: 1, hours: 46 }An empty units array is invalid. All six functions return
nullfor[], since no unit was asked for.diffUnixreads singular unit names in an array. It returnednullfor["month", "week"]. It now returns plural keys like the other five, and its return type isRecord<DateTimeDurationUnit, number>.import { diffUnix } from "@northguild/gmt/unix";diffUnix(1704067200000, 1710892800000, ["month", "week"]); // { months: 2, weeks: 2 }Sunday-first week numbers follow UTS #35.
getWeekNumber(value, "sunday")counted weeks within the calendar year, so the last days of December could be week 53 or 54. UTS #35 Part 4, with a minimum of one day in the first week, puts them in week 1 of the next year when that week holds 1 January. The same rule applies toparseWeekFromDate,parseWeekFromDateTime,parseWeekFromUtc,parseWeekFromZoned,parseWeekFromUnixandparseUnitFrom*(…, "week")withweekStartsOn: "sunday". Week numbers are 1–53 in both modes. Monday-first weeks were already ISO 8601 and are unchanged.import { getWeekNumber, parseWeekFromDate } from "@northguild/gmt/plain";getWeekNumber("2024-12-31", "sunday"); // 1getWeekNumber("2000-12-31", "sunday"); // 1getWeekNumber("2024-12-28", "sunday"); // 52parseWeekFromDate("2024-12-31", { weekStartsOn: "sunday" }); // 1parseUnitFromDateTime,parseUnitFromTime,parseUnitFromUtcandparseUnitFromZonedread"microsecond"and"nanosecond".parseUnitFromUnixalready did. Each field is three digits, as Temporal’smicrosecondandnanosecondfields are.import { parseUnitFromTime } from "@northguild/gmt/plain";import { parseUnitFromUtc } from "@northguild/gmt/utc";parseUnitFromUtc("2023-11-14T22:13:20.123456789Z", "microseconds"); // "456"parseUnitFromTime("22:13:20.123456789", "nanosecond"); // "789"Breaking changes
Section titled “Breaking changes”Call 1.15 1.16 diffDate("2024-01-01", "2025-03-01", ["years", "days"]) { years: 1, days: 0 }{ years: 1, days: 59 }diffDate("2024-01-01", "2024-03-20", ["months", "weeks"]) { months: 2, weeks: 0 }{ months: 2, weeks: 2 }diffDate(, likewisea, b, []) diffDateTime,diffTime,diffUtc,diffZoned,diffUnix{}nullgetWeekNumber("2024-12-31", "sunday") 531getWeekNumber("2000-12-31", "sunday") 541Migration: to get only the listed fields of Temporal’s own difference, list every unit between the largest and the smallest you need, and ignore the ones you do not. For a calendar-year count of Sunday weeks, count from the year’s first Sunday yourself.
-
358e91e: Export the
nanosecondDecimalpattern from@northguild/gmt/regexand the package root.isValidNanoPatterndocumented it as aregex/pattern, but theregexbarrel never re-exported its file, so it could not be imported. It now can. -
727a3f4: Make the positional interval functions in
plain/,utc/,zoned/andunix/half-open[start, end), the rule theinterval/namespace already follows (Story CORE-8).Earlier releases read most of these functions’ intervals as closed
[start, end], with both endpoints inside, and stepped one unit in from every cut to make that work: one nanosecond, one day, or one epoch unit. A result fromintervalsOverlapUtccould then disagree withintervalsOverlapon the same instants. Every positional family now usesstart ≤ t < end, as SQL:2011’s closed-openPERIOD, RFC 5545’s non-inclusiveDTENDand EWD831 do, and the one-unit steps are gone.import { intervalAbutsDate, intervalContainsDate, intervalDifferenceUtc, intervalsOverlapUtc } from "@northguild/gmt";intervalsOverlapUtc("2024-01-01T09:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T17:00:00Z"); // falseintervalDifferenceUtc("2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T13:00:00Z");// [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" }, { start: "2024-01-01T13:00:00Z", end: "2024-01-01T17:00:00Z" }]intervalContainsDate("2024-01-01", "2024-02-01", "2024-01-31"); // trueintervalAbutsDate("2024-01-01", "2024-07-01", "2024-07-01", "2024-12-31"); // true- Which functions. Every variant (
Date,DateTime,Time,Utc,Zoned,Unix) ofintervalsOverlap*,intervalContains*,intervalEngulfs*,intervalIntersection*,intervalUnion*,mergeIntervals*,intervalDifference*,intervalXor*,intervalXorAll*,intervalAbuts*andintervalOverlappingDays*. TheUtcvariants callinterval/’sintervalsOverlap,intervalContains,intersectIntervals,mergeIntervalsandsubtractIntervals, so both namespaces give the same answer. - Touching intervals do not overlap and have no intersection. They abut:
intervalAbuts*is Allen’s “meets”, one interval’sendequal to the other’sstart.intervalUnion*,mergeIntervals*andintervalXor*join them into one run. - Empty intervals.
start === endholds no instant. It abuts nothing, and it is contained or engulfed only strictly inside another interval.intervalUnion*ignores it, and returnsnullwhen both inputs are empty. - The tiling functions keep their output.
intervalSplitAt*,splitIntervalByUnit*andintervalDivideEqually*still give each piece’sendas the next piece’sstart. Under the half-open rule those pieces share no instant, so they partition the interval. - Outputs are still re-serialised in each type’s canonical spelling, so a row whose value did not change returns the same string.
intervalCount*counts an empty interval as0. A zero-length interval holds no instant, so it touches no unit. All six families counted1when the point fell inside a unit.intervalOverlappingDaysZonedandintervalOverlappingDaysUnixreturn0for an empty intersection. An empty interval strictly inside the other one counted as one day.intervalOverlappingDaysUtc,…Dateand…DateTimereturn0too.import { intervalCountUnix, intervalOverlappingDaysUnix } from "@northguild/gmt/unix";intervalCountUnix(1800000, 1800000, "hour"); // 0intervalOverlappingDaysUnix(0, 172800000, 129600000, 129600000); // 0splitIntervalByUnit*rejects a unit its type does not have, even for an empty interval. A zero-length interval returned a one-piece split for any unit. It now returns[], as a non-empty interval does.splitIntervalByUnitDateaccepts only date units, andsplitIntervalByUnitTimeonly time units.import { splitIntervalByUnitDate } from "@northguild/gmt/plain";splitIntervalByUnitDate("2024-01-01", "2024-01-01", "hour", 1); // []Breaking changes
Section titled “Breaking changes”Ais2024-01-01T09:00:00Z,Bis…T12:00:00Z,Cis…T13:00:00ZandDis…T17:00:00Z. Each row applies to every variant of its family.Call 1.15 (closed) 1.16 (half-open) intervalsOverlapUtc(A, B, B, D) truefalseintervalContainsUtc(, a point atA, B, B) endtruefalseintervalIntersectionUtc(A, B, B, D) { start: B, end: B }nullintervalDifferenceUtc(A, D, B, C) [{ A, …T11:59:59.999999999Z }, { …T13:00:00.000000001Z, D }][{ A, B }, { C, D }]intervalDifferenceDate("2024-01-01", "2024-12-31", "2024-06-01", "2024-07-01") [{ 01-01, 05-31 }, { 07-02, 12-31 }][{ 01-01, 06-01 }, { 07-01, 12-31 }]intervalXorUtc(,A, C, B, D) intervalXorAllUtc([{ A, C }, { B, D }]) [{ A, …T11:59:59.999999999Z }, { …T13:00:00.000000001Z, D }][{ A, B }, { C, D }]intervalAbutsUtc(, a shared endpointA, B, B, D) falsetrueintervalAbutsUtc(A, B, "2024-01-01T 12:00:00.000000001Z", D) truefalseintervalAbutsDate("2024-01-01", "2024-06-30", "2024-07-01", "2024-12-31") truefalseintervalOverlappingDaysUtc("2024-01-01T 00:00:00Z", "2024-01-02T 00:00:00Z", "2024-01-02T 00:00:00Z", "2024-01-03T 00:00:00Z") 10intervalCountUnix(1800000, 1800000, "hour") 10splitIntervalByUnitDate("2024-01-01", "2024-01-01", "hour", 1) one piece []Unchanged:
intervalUnionUtc(A, B, B, D)is{ start: A, end: D },intervalIntersectionUtc(A, C, B, D)is{ start: B, end: C },intervalSplitAtUtc(A, D, [B])is[{ A, B }, { B, D }], andintervalCountUtc(A, D, "hour")is8.Migration:
-
An interval whose
endwas the last day, or last unit, it covers now stops before it. Pass the next day or unit asend:intervalContainsDate("2024-01-01", addDate("2024-01-31", { days: 1 }), "2024-01-31")istrue. -
Code that undid the one-unit step, for example by adding a nanosecond to a piece from
intervalDifference*, must stop: pieces now end and start exactly at the cut. -
Code that tested
intervalAbuts*for a one-unit gap now tests for a shared endpoint. -
mapDatesInRangeandmapZonedDatesInRangestay end-inclusive and did not change. They enumerate the dates a range covers, soendis one of them;interval*bounds a span, soendis not in it. Mixing the two in one expression is where this bites:mapDatesInRange("2024-01-01", "2024-01-05", 1);// ["2024-01-01", "2024-01-02", "2024-01-03", "2024-01-04", "2024-01-05"] — 5 datesintervalCountDate("2024-01-01", "2024-01-05", "day"); // 4intervalContainsDate("2024-01-01", "2024-01-05", "2024-01-05"); // falsesplitIntervalByUnitDate("2024-01-01", "2024-01-05", "day", 1).length; // 4The same
start/endpair therefore yieldsn + 1from themap*functions andnfrom theinterval*ones. To read one set of bounds both ways, passaddDate(end, { days: 1 })to theinterval*call, orsubtractDate(end, { days: 1 })to themap*call.
- Which functions. Every variant (
-
727a3f4: Read options, unit names and locales the way Temporal and ECMA-402 read them, and remove the options no function reads (Story CORE-8).
Singular and plural unit names are the same unit everywhere. Temporal §13.17
GetTemporalUnitValuedOptionaccepts"day"and"days"alike. Many GMT functions accepted only one spelling. Every unit-taking function now accepts both: thestartOf*,endOf*andare*EqualByfunctions,diffDate,diffDateTime,diffTime,diffUtc,diffZoned,diffUnixand their*AsDurationforms, thegetLargest*DurationUnitfunctions, theparseUnitFrom*functions,durationAs,getDurationUnit,getZonedOffsetAs,spanWallClock,floorToZone,bucketRange,isValidZoneBucketUnitand theget*NowUnitfunctions.import { diffDate, startOfDate } from "@northguild/gmt/plain";import { diffZoned } from "@northguild/gmt/zoned";diffDate("2024-01-01", "2024-03-20", "day"); // 79diffZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-03-20T00:00:00+00:00[UTC]", "day"); // 79startOfDate("2024-03-15", "months"); // "2024-03-01"An options argument must be an object. Temporal’s
GetOptionsObjectthrows aTypeErrorfornull, a string, a number or a boolean. GMT read all of them as “no options”. The functions that take their own options object now return their sentinel, and the sixisValid*Rangevalidators returnfalsefor such aprops.options. The functions backed byIntl.DateTimeFormat(formatDate,formatTime,formatDateTime,formatDateRange,formatDateTimeRange, the…ToPartsfunctions,formatUtc,formatUnix,formatZonedDateTime,formatZonedRangeandformatZonedToParts) follow ECMA-402’sCoerceOptionsToObjectinstead:nullreturns the sentinel, and a string or number means the defaults. Theplain/formatters andformatZonedDateTimealready returned""fornull;formatUtc,formatUnix,formatZonedRangeandformatZonedToPartsread it as no options.formatDurationbuilds its own options, so it returns""for any non-object.import { addDate } from "@northguild/gmt/plain";import { durationAs, formatDuration } from "@northguild/gmt/duration";import { formatUnix } from "@northguild/gmt/unix";addDate("2024-03-10", { days: 5 }, null); // ""durationAs("P1DT2H30M", "hours", null); // nullformatUnix(0, "en-US", null); // ""formatDuration("PT1H", "en-US", null); // ""An explicit
undefinedis the same as an omitted argument, as Temporal’sGetOptiontreats it.mapDatesInRange,mapZonedDatesInRange,fromNanosecondsandfromNtpTimestampreturned their sentinel for it.import { mapDatesInRange } from "@northguild/gmt/plain";mapDatesInRange("2024-01-01", "2024-01-03", undefined); // ["2024-01-01", "2024-01-02", "2024-01-03"]Locales follow ECMA-402’s
CanonicalizeLocaleList. Every locale-taking function accepts astringor astring[], and a list uses its first supported tag.isThisUnitandisZonedThisUnitvalidate the locale for every unit, not only"week".getLocaleEraNames,getLocaleMeridiems,getLocaleMonthNamesandgetLocaleWeekdayNamesused to return[]for any list, even["en-US"]; a list now works. The 17 functions whose locale is required still return their sentinel for an empty list, rather than reading the host’s locale:getLocaleStartOfWeek,getLocaleEndOfWeek,getLocaleDayOfWeek,getLocaleWeekYear,getWeeksInLocaleWeekYear,getWeekOfMonth,getWeeksInMonth,isWeekend,getLocaleEraNames,getLocaleMeridiems,getLocaleMonthNames,getLocaleWeekdayNames,getLocaleZonedDayOfWeek,getLocaleZonedStartOfWeek,getLocaleZonedEndOfWeek,isZonedWeekendandformatTimeZoneName.import { formatDate, getLocaleStartOfWeek, isThisUnit } from "@northguild/gmt/plain";formatDate("2024-02-29", ["fr-FR", "en-US"]); // "29/02/2024"getLocaleStartOfWeek("2024-02-29", ["en-US", "fr-FR"]); // "2024-02-25"getLocaleStartOfWeek("2024-02-29", []); // ""isThisUnit("2024-03-15", "day", "en_US"); // falseAn invalid
weekStartsOnis invalid input. ThestartOf*,endOf*,are*EqualBy,parseUnitFrom*andparseWeekFrom*functions andgetWeekNumberreturn their sentinel for anything but"monday"or"sunday", such as"Monday"or1.import { areDatesEqualBy, startOfDate } from "@northguild/gmt/plain";startOfDate("2024-03-15", "week", { weekStartsOn: "Monday" as never }); // ""areDatesEqualBy("2024-03-15", "2024-03-15", "week", { weekStartsOn: 1 as never }); // falsesetZoned,setUnixandcycleZoneddefaultoffsetto"prefer", asTemporal.ZonedDateTime#withdoes. The default was"ignore", which re-resolved a time in a repeated hour to its first occurrence, so setting the minute of the second 1:30 a.m. moved the value an hour back.import { cycleZoned, setZoned } from "@northguild/gmt/zoned";setZoned("2024-11-03T01:30:00-05:00[America/New_York]", { minute: 45 }); // "2024-11-03T01:45:00-05:00[America/New_York]"cycleZoned("2024-11-03T01:30:00-05:00[America/New_York]", "minute", 15); // "2024-11-03T01:45:00-05:00[America/New_York]"formatRelativeUtc,formatRelativeUnix,formatRelativeZonedandformatRelativeDateTimepick units up to a year, with the thresholdsformatRelativeDateuses: a week from 7 days, a month from 28 and a year from 365. They stopped at days.formatRelativeTimeis unchanged, since a time distance is under a day.import { formatRelativeDateTime } from "@northguild/gmt/plain";import { formatRelativeUtc } from "@northguild/gmt/utc";import { formatRelativeZoned } from "@northguild/gmt/zoned";formatRelativeUtc("2026-01-15T14:30:45Z", "en-US", { reference: "2026-04-15T14:30:45Z" }); // "3 months ago"formatRelativeZoned("2021-01-01T00:00:00+00:00[UTC]", "en-US", { reference: "2024-01-01T00:00:00+00:00[UTC]" }); // "3 years ago"formatRelativeDateTime("2024-01-01T00:00:00", "en-US", { reference: "2024-01-11T00:00:00" }); // "last week"formatRelativeZonedandformatCalendarZonedvalidatereference. It must be omitted, a zoned or UTC string, or a finite epoch in milliseconds.true,nullor an array was converted to a number and rendered.closestDateTo,closestZonedToand thegetLargest*DurationUnitfunctions return""for invalid input.closestDateToandclosestZonedToreturnednull, unlike every other string-returning function.getLargestDateDurationUnit,getLargestDateTimeDurationUnitandgetLargestTimeDurationUnitreturned their default unit, so an invalid list looked like a real answer.import { closestDateTo, getLargestDateDurationUnit } from "@northguild/gmt/plain";closestDateTo("nope", ["2024-01-01"]); // ""getLargestDateDurationUnit(["hours"] as never); // ""getLargestDateDurationUnit(["day", "month"]); // "months"parseDateFromUtcand the otherparse*FromUtcfunctions take atimeZone, asparseTimeFromUtcalready did. Omitted, they read UTC fields as before.import { parseDateFromUtc, parseHourFromUtc } from "@northguild/gmt/utc";parseHourFromUtc("2024-03-15T14:30:00Z", { timeZone: "Asia/Tokyo" }); // "23"parseDateFromUtc("2024-03-15T20:30:00Z", { timeZone: "Asia/Tokyo" }); // "2024-03-16"startOfTimefloors below a second.startOfTime("12:34:56.999", "millisecond")returned"12:34:56.000". It now returns"12:34:56.999".Options that no function read are removed. Each was accepted and had no effect on the output, so the only change is that a call passing one stops type-checking.
offsetonaddZoned,subtractZoned,intervalFromDurationZonedandconvertPlainDateTimeToZoned. Construction from a date-time and exact-time arithmetic have no offset to reconcile.offsetanddisambiguationonsetUtc. UTC has no repeated or skipped wall-clock time.overflowonaddTime,subtractTime,intervalFromDurationTimeandcycleTime.Temporal.PlainTime#addtakes no options, since a time has no month to overflow.addTime,subtractTimeandintervalFromDurationTimetherefore take no options argument at all, andcycleTimekeeps{ round }.
Breaking changes
Section titled “Breaking changes”Function 1.15 1.16 Functions with their own options object addDate(meant no optionsv, d, null) "",null,falseor[]; omit the argument or pass{}formatUtc,formatUnix,formatZonedRange,formatZonedToPartsoptions = nullmeant no optionsthe sentinel; a string or number still means the defaults formatDuration(v, locale, "x") the defaults ""formatRelativeZoned,formatCalendarZonedwithreference: truerendered against epoch 1 ""isThisUnit,isZonedThisUnitlocale read only for "week"an invalid locale returns falsefor every unitweekStartsOnother than"monday"or"sunday"not checked the sentinel setZoned,setUnix,cycleZoned,offsetomitted"ignore":setZoned(gave"2024-11-03T 01:30:00-05:00 [America/ New_York]", { minute: 45 }) "…01:45:00-04:00[…]" "prefer":"…01:45:00-05:00; pass[…]" { offset: "ignore" }for the old resultformatRelativeUtc,formatRelativeUnix,formatRelativeZoned,formatRelativeDateTime"90 days ago","1,095 days ago""3 months ago","3 years ago"; passlargestUnit: "day"for the old textclosestDateTo,closestZonedToon invalid inputnull""getLargestDateDurationUnitand siblings on invalid inputthe default unit ""startOfTime("12:34:56.999", "millisecond") "12:34:56.000""12:34:56.999"addZoned(, likewisev, d, { disambiguation, offset }) subtractZoned,intervalFromDurationZoned,convertPlainDateTimeToZonedoffsetaccepted, no effectaddZoned(v, d, { disambiguation }) setUtc(v, fields, { overflow, disambiguation, offset }) accepted, no effect setUtc(v, fields, { overflow }) addTime(,v, d, { overflow }) subtractTime(v, d, { overflow }) accepted, no effect addTime(,v, d) subtractTime(v, d) intervalFromDurationTime(v, duration, anchor, { overflow }) accepted, no effect intervalFromDurationTime(v, duration, anchor) cycleTime(v, field, amount, { round, overflow }) overflowaccepted, no effectcycleTime(v, field, amount, { round }) -
727a3f4: List every import path explicitly, mark the package side-effect free, and state the Node versions it supports (Story CORE-8).
The
exportsmap names each subpath. It used wildcard patterns, which also resolved folders nobody documented, such as@northguild/gmt/plain/interval/validate, and a./regex/*pattern that matched nothing. It now lists the root, the twelve namespace paths (calendar,duration,instant,interval,plain,precision,regex,span,types,unix,utc,zoned) and each namespace’s category subpaths, such as@northguild/gmt/plain/intervalor@northguild/gmt/unix/convert: 71 entries in all. Any other path fails withERR_PACKAGE_PATH_NOT_EXPORTED.typesVersionsmirrors the map, so TypeScript withmoduleResolution: "node10"resolves the same 71 paths asnode16,nodenextandbundler.sideEffects: false. An audit of every source module found only pure constant construction at load time, so bundlers may drop the modules an application does not use. An import cycle through the internal barrel is also gone.Every namespace subpath except
typesre-exports the polyfill.Temporal,IntlandtoTemporalInstantare available from each of them, not only from the root and some namespaces, and they are the same objects everywhere.@northguild/gmt/typesis type-only — it has no runtime exports at all — so the polyfill is not among them; it exports theUnixUnittype.import { Temporal } from "@northguild/gmt/span";import type { UnixUnit } from "@northguild/gmt/types";const unit: UnixUnit = "seconds";Temporal.Instant.from("2024-01-01T00:00:00Z").epochMilliseconds; // 1704067200000enginesisnode >=22.16.0. Node 22.16.0 ships ICU 77.1, the oldest ICU the test suite’s locale and calendar expectations cover. CI runs the latest Node 22, 24 and 26.Breaking changes
Section titled “Breaking changes”1.15 1.16 import { … } from "@northguild/and other nested foldersgmt/ plain/ interval/ validate" ERR_PACKAGE_PATH_NOT_EXPORTED; import from@northguild/orgmt/ plain/ interval @northguild/gmt/ plain import { chopUtc } from "@northguild/gmt/ plain" not exported there; import { chopUtc } from "@northguild/gmt/ utc" Node below 22.16.0 outside engines; upgrade Node -
727a3f4: Add a
maxPiecesoption to the functions that build one array element per piece, so a large range returns[]instead of exhausting the heap (Story CORE-8).Which functions.
splitIntervalByUnitDate,splitIntervalByUnitDateTime,splitIntervalByUnitTime,splitIntervalByUnitUtc,splitIntervalByUnitUnix,splitIntervalByUnitZoned, the six matchingintervalDivideEqually*functions,mapDatesInRangeandmapZonedDatesInRange. Before, each built an array as long as the range asked for. Ten thousand years of days, or a divide into billions of pieces, ran out of memory or threw aRangeErrorfrom inside the engine.The option.
maxPiecesis a positive safe integer, and it defaults to1_000_000. A call that would return more pieces returns[], the functions’ existing invalid-input sentinel. A split stops as soon as piecemaxPieces + 1is due, so the answer comes back in bounded time. AmaxPiecesthat is not a positive safe integer also returns[].import { intervalDivideEquallyUnix, mapDatesInRange, splitIntervalByUnitDate } from "@northguild/gmt";splitIntervalByUnitDate("2024-01-01", "2024-01-10", "day", 2, { maxPieces: 4 }); // [] — 5 slicessplitIntervalByUnitDate("2024-01-01", "2024-01-10", "day", 2, { maxPieces: 5 }).length; // 5intervalDivideEquallyUnix(0, 90000000, 3, { maxPieces: 2 }); // []mapDatesInRange("0001-01-01", "9999-12-31", 1); // [] — 3,652,059 dates is over the defaultmapDatesInRange("2024-01-01", "4000-01-01", 1, { maxPieces: 2000000 }).length; // 721720splitIntervalByUnitTimeno longer loops forever. A step that carried past midnight wrapped back to the morning, so the split never reached its end. The last slice now ends atend.splitIntervalByUnitTime("20:00:00", "23:00:00", "hour", 5); // [{ start: "20:00:00", end: "23:00:00" }]bucketRangegives up quickly. It already returned[]over 10,000 buckets, but it counted them one at a time, which took up to a minute in zones with many offset changes. It now works out from the span when the range is certainly over the limit, and returns in under a second.Breaking changes
Section titled “Breaking changes”A call that used to return more than 1,000,000 pieces now returns
[]. The input was valid before and still is — only the output changed — so nothing throws and nothing warns. Each row is the boundary: one piece under the default cap still returns the array, one piece over returns[]. Every function in the row’s family behaves the same way.Call 1.15 1.16 (default maxPieces: 1_000_000)mapDatesInRange("2024-01-01", "4761-11-27", 1) 1,000,000 dates 1,000,000 dates mapDatesInRange("2024-01-01", "4761-11-28", 1) 1,000,001 dates []mapZonedDatesInRange(A, "4761-11-27T 00:00:00-05:00 [America/ New_York]", 1) 1,000,000 dates 1,000,000 dates mapZonedDatesInRange(A, "4761-11-28T 00:00:00-05:00 [America/ New_York]", 1) 1,000,001 dates []splitIntervalByUnitDate("2024-01-01", "4761-11-28", "day", 1) 1,000,000 pieces 1,000,000 pieces splitIntervalByUnitDate("2024-01-01", "4761-11-29", "day", 1) 1,000,001 pieces []splitIntervalByUnitUnix(0, 3_600_003_600_000, "hour", 1) 1,000,001 pieces []intervalDivideEquallyUtc("2024-01-01T 00:00:00Z", "2124-01-01T 00:00:00Z", 1000000) 1,000,000 pieces 1,000,000 pieces intervalDivideEquallyUtc("2024-01-01T 00:00:00Z", "2124-01-01T 00:00:00Z", 1000001) 1,000,001 pieces []intervalDivideEquallyTime("00:00:00", "23:59:59", 1000001) 1,000,001 pieces []splitIntervalByUnitTime("20:00:00", "23:00:00", "hour", 5) never returned [{ start: "20:00:00", end: "23:00:00" }]Ais"2024-01-01T00:00:00-05:00[America/New_York]". The same boundary applies tosplitIntervalByUnitDateTime,splitIntervalByUnitTime,splitIntervalByUnitUtc,splitIntervalByUnitZonedand to the other fourintervalDivideEqually*functions.Migration:
- A call that legitimately needs more than a million pieces passes its own cap:
mapDatesInRange("2024-01-01", "4761-11-28", 1, { maxPieces: 2_000_000 })returns the 1,000,001 dates again.maxPiecesmust be a positive safe integer; anything else is invalid input and returns[]. - Code that treated
[]as “the range is empty” must now also read it as “the range is too large”. These functions have one sentinel, so distinguish the two by checking the range yourself —intervalCountDate(start, end, "day")counts the pieces without building them. - Nothing became slower. A split stops as soon as piece
maxPieces + 1is due, so an over-cap call returns in bounded time instead of exhausting the heap. - The engine’s own array limit, 2^32 − 1 elements, still applies above any
maxPiecesyou set.
- A call that legitimately needs more than a million pieces passes its own cap:
-
e8c148a: Add the
instant/namespace: the instant-plus-offset pair, and explicit resolution of zoneless local wall times (Story CORE-4).GMT could represent an instant, and it could represent a zoned datetime. It had no primitive for the shape the world actually exchanges: an absolute instant plus the local UTC offset that was in force where the event happened. Neither field derives from the other — the instant orders events globally, the offset renders them as the human on the ground saw them — which is why GS1 EPCIS 2.0 requires both (
eventTimeandeventTimeZoneOffset), UN/EDIFACT DTM has qualifiers303/304for the pair, and DICOM appends&ZZXXto aDTvalue.import {classifyLocal,fromOffsetInstant,resolveLocal,toOffsetInstant,} from "@northguild/gmt";toOffsetInstant("2024-07-15T12:00:00-04:00[America/New_York]");// { instant: "2024-07-15T16:00:00Z", offset: "-04:00", timeZone: "America/New_York" }toOffsetInstant("2024-07-15T12:00:00-04:00");// { instant: "2024-07-15T16:00:00Z", offset: "-04:00" } — most feeds send no zonetoOffsetInstant("2024-07-15T16:00:00Z", "America/New_York");// { instant: "2024-07-15T16:00:00Z", offset: "-04:00", timeZone: "America/New_York" }fromOffsetInstant({ instant: "2024-07-15T16:00:00Z", offset: "-04:00" });// "2024-07-15T12:00:00-04:00"classifyLocal("2024-11-03T01:30:00", "America/New_York"); // "ambiguous"classifyLocal("2024-03-10T02:30:00", "America/New_York"); // "nonexistent"resolveLocal("2024-11-03T01:30:00", "America/New_York", { disambiguation: "later" });// "2024-11-03T06:30:00Z" — the same wall clock, an hour of real time later- An offset is not a zone.
-05:00does not identifyAmerica/New_York; it is every zone sitting at-05:00that day, and it says nothing about what that zone does next spring. Keep the zone for anything still to be scheduled and the offset for anything that already happened.timeZoneis optional because most feeds do not send one, and a string whose offset contradicts its own bracketed zone returnsnullrather than a guess about which half the sender meant. classifyLocalexists so realm code can refuse rather than guess. Ambiguous and nonexistent wall times are the single most common datetime bug there is — 01:30 happens twice on a fall-back day and never on a spring-forward one — and a demurrage clock or a medication window should not silently accept whichever of two instants an hour apart a default handed it. It returns"unique","ambiguous"or"nonexistent"before any policy is applied, reading the zone’s own transition table, so it is right for 30-minute shifts (Australia/Lord_Howe), quarter-hour offsets (Pacific/Chatham) and the calendar day Samoa deleted crossing the date line in 2011.resolveLocalreturns an instant, exactly;convertPlainDateTimeToZonedreturns a zoned string. Same underlying resolution and the same fourdisambiguationvalues, but different output and different precision —convertPlainDateTimeToZonedtruncates to milliseconds by default, so a nanosecond wall time survives one and not the other.resolveLocalhas nooffsetparameter, since that option is inert on this construction path.offsetis±HH:MM, except where the zone was not on a whole minute.Africa/Monroviaran at-00:44:30until 1972, andtoOffsetInstantreports it as±HH:MM:SSrather than rounding the pair thirty seconds away from the event it describes. Sub-second offsets are rejected — ISO 8601 permits them and Temporal parses them, but no zone and no standard that stores this pair has used one.- Annotations are read as RFC 9557 §3.3 and Temporal read them. An elective
[key=value]annotation, including[u-ca=...], is ignored, and an unknown critical[!key=value]annotation returnsnull, exactly asisValidInstantdecides. A string whose offset contradicts its bracketed zone still returnsnull. - Also exported: the
OffsetInstantandLocalTimeClassificationtypes, and theutcOffsetregex pattern fromregex/.
- An offset is not a zone.
-
727a3f4: Write calendar strings in the standard RFC 9557 form, the ISO date followed by
[u-ca=<id>], and name calendars by their CLDR and Temporal ids (Story CORE-8).GMT’s calendar strings carried the calendar’s own year, month and day digits: the Hebrew New Year 5785 was
"5785-01-01[u-ca=hebrew]". No standard defines that form. Temporal’sPlainDate#toString()always writes the ISO date, and RFC 9557 §3.3 saysu-canames the calendar a date is preferably shown in, not the calendar of its digits. Every standard parser, Temporal included, therefore read GMT’s strings as a different date without an error.;era=was not RFC 9557 syntax, and the zoned form put[u-ca=…]before the time zone, the reverse of RFC 9557 §4.1.import { addDate, convertDateToCalendar } from "@northguild/gmt/plain";import { convertZonedToCalendar } from "@northguild/gmt/zoned";convertDateToCalendar("2024-10-03", "hebrew"); // "2024-10-03[u-ca=hebrew]"convertDateToCalendar("2024-10-03", "islamicc"); // "2024-10-03[u-ca=islamic-civil]"convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "hebrew"); // "2024-10-03T14:30:45-04:00[America/New_York][u-ca=hebrew]"addDate("2024-10-03[u-ca=hebrew]", { months: 1 }); // "2024-11-02[u-ca=hebrew]"- Output is exactly Temporal’s.
convertDateToCalendarand every function that returns a calendar string writeTemporal.PlainDate#toString()orTemporal.ZonedDateTime#toString(). Onlyiso8601has no annotation;gregoryis written[u-ca=gregory]. A zoned string ends…[timeZone][u-ca=<id>]. - Calendar ids are the CLDR and Temporal ids, in strings and as function arguments alike:
iso8601,gregory,hebrew,islamic-civil,islamic-tbla,islamic-umalqura,japanese,buddhist,roc,persian,indian,ethiopic,ethioaaandcoptic. Temporal’s aliases and any letter case are accepted, and the canonical id is written (islamicc→islamic-civil,ethiopic-amete-alem→ethioaa,HEBREW→hebrew).chinese,dangi,islamicandislamic-rgsaare not supported. - Input is read as Temporal reads it. A critical
[!u-ca=…]is accepted, and the flag is not written back. Elective annotations such as[foo=bar]and a time zone annotation on a date are ignored. The firstu-canames the calendar. An unknown critical annotation, or a secondu-cawhen either is critical, is rejected. A calendar date-time such as"2024-10-03T14:30[u-ca=hebrew]"is read as its date. The part before the first[must still be GMT’s written shape, so basic format (20241003[u-ca=hebrew]), a space or lower-casetseparator, and an offset are rejected. - Different calendars follow Temporal’s
CalendarEqualscheck.diffDate,diffDateAsDuration,diffZoned,diffZonedAsDuration, theintervalCount*,intervalLength*,splitIntervalByUnit*andintervalOverlappingDays*functions, and the value-returning interval set operations inplain/andzoned/, return their sentinel for two different calendars. A bare ISO string isiso8601. Temporal’s ordering has no calendar check, sointervalsOverlap*,intervalContains*,intervalEngulfs*,intervalAbuts*,isValidDateIntervalandisValidCalendarZonedIntervalstill accept mixed calendars. relativeToindurationAs,normalizeDurationandcompareDurationsreads a calendar string as Temporal’sParseTemporalRelativeToStringdoes: zoned when it has a time zone annotation, otherwise a date.
import { diffDate, intervalsOverlapDate, isValidCalendarDate } from "@northguild/gmt/plain";import { durationAs } from "@northguild/gmt/duration";isValidCalendarDate("2024-10-03T14:30[u-ca=hebrew]"); // trueisValidCalendarDate("2024-10-03[foo=bar][u-ca=hebrew]"); // trueisValidCalendarDate("20241003[u-ca=hebrew]"); // falsediffDate("2024-10-03", "2024-11-03[u-ca=hebrew]", "days"); // nullintervalsOverlapDate("2024-10-03[u-ca=hebrew]", "2024-10-10", "2024-10-05", "2024-10-20"); // truedurationAs("P1M", "days", { relativeTo: "2024-02-10[!u-ca=hebrew]" }); // 30Breaking changes
Section titled “Breaking changes”Every calendar string changes. There is no converter from the old strings: no standard defines them, and an old string cannot be told apart from a valid RFC 9557 one.
Call 1.15 1.16 convertDateToCalendar("2024-10-03", "hebrew") "5785-01-01[u-ca=hebrew]" "2024-10-03[u-ca=hebrew]" convertDateToCalendar("2024-10-03", "japanese") "0006-10-03[u-ca=japanese;era=reiwa]" "2024-10-03[u-ca=japanese]" convertDateToCalendar("2024-10-03", "ethiopic") "2017-01-23[u-ca=ethiopic;era=ethiopic]" "2024-10-03[u-ca=ethiopic]" convertDateToCalendar("1000-01-01", "taiwan") "-911-01-01[u-ca=taiwan]" ""; with"roc":"1000-01-01[u-ca=roc]" convertDateToCalendar("+275760-09-13", "hebrew") "279517-10-11[u-ca=hebrew]" "+275760-09-13[u-ca=hebrew]" convertDateToCalendar("5785-01-01 [u-ca=hebrew]", "gregorian") "2024-10-03"""; with"iso8601":"5785-01-01"convertZonedToCalendar("2024-10-03T 14:30:45-04:00 [America/ New_York]", "hebrew") "5785-01-01T14:30:45-04:00 [u-ca=hebrew] [America/ New_York]" "2024-10-03T14:30:45-04:00 [America/ New_York] [u-ca=hebrew]" addDate("5784-06-15 [u-ca=hebrew]", { months: 1 }) "5784-07-15[u-ca=hebrew]" "5784-07-14, reading ISO 5784-06-15[u-ca=hebrew]" diffDate("2024-10-03", "2024-11-03 [u-ca=hebrew]", "days") -1373406, reading Hebrew year 2024nullCalendar ids renamed:
1.15 1.16 gregorianiso8601(orgregory, which writes[u-ca=gregory])taiwanrocislamic-tabularislamic-tblaethiopic-amete-alemethioaa(the old id is still accepted as Temporal’s alias)Migration:
- Regenerate every stored calendar string from its ISO date with
convertDateToCalendarorconvertZonedToCalendar. Do not parse the old strings. Most of them are also valid RFC 9557, so"5785-01-01[u-ca=hebrew]"is now read, silently, as ISO year 5785. Only four old shapes are rejected:;era=, an unsigned 5- or 6-digit year, a negative year without six digits (-911), and[u-ca=…]before the time zone. ;era=is gone, including the;era=japaneseinput alias.convertDateToCalendar("1800-01-01[u-ca=japanese;era=ce]", "iso8601")is"".- Replace the renamed ids in calls and stored annotations.
gregorian,taiwanandislamic-tabularreturn the sentinel. - Difference two dates in one calendar. Convert one side first with
convertDateToCalendar, then calldiffDate.
- Output is exactly Temporal’s.
-
358e91e: Add the
interval/namespace: half-open[start, end)interval algebra over instants: overlap, containment, intersect, clamp, merge, subtract, split and sum (Story CORE-6).Four realms need the same operation and none of them could express it: sum the parts of an interval that fall inside a set of allowed windows. Laytime counts only the hours a charter clause allows, driver hours split a duty period around mandatory rest, demurrage free time counts only working days, and a trading window counts only continuous-session time. Without one shared primitive, each realm reimplements intersection and they disagree at every boundary.
import {intervalsOverlap,mergeIntervals,subtractIntervals,sumIntervals,} from "@northguild/gmt";const shift = { start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" };intervalsOverlap(shift, { start: "2024-01-01T17:00:00Z", end: "2024-01-01T18:00:00Z" });// false — touching intervals share no instantsubtractIntervals(shift, [{ start: "2024-01-01T12:00:00Z", end: "2024-01-01T13:00:00Z" }]);// [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" },// { start: "2024-01-01T13:00:00Z", end: "2024-01-01T17:00:00Z" }]sumIntervals([{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T13:00:00Z" },{ start: "2024-01-01T12:00:00Z", end: "2024-01-01T17:00:00Z" },]); // "PT8H" — the overlap counts once- Half-open
[start, end), everywhere in the namespace. An instanttis inside whenstart ≤ t < end. That is SQL:2011’s closed-open application-timePERIOD, RFC 5545’s non-inclusiveDTENDand Dijkstra’s EWD831. Touching intervals do not overlap,intersectIntervalsreturnsnullfor them,mergeIntervalsjoins them, andsplitIntervalAtreturns pieces that share no instant. A container gated out at exactly 17:00 has not used another day. - Endpoints are instants. Each needs an offset (
Zor±HH:MM), may carry a[Zone]annotation, and may name a different zone from the other. They compare by epoch nanoseconds, as a TC39Temporal.Instantdoes. A leap second and an unknown critical annotation are rejected. Elective annotations and a[u-ca=…]calendar annotation are ignored, asTemporal.Instant.fromignores them, and the caller’s annotated string is echoed back. Where a realm needs local-calendar edges, build them withfloorToZoneorbucketRangefirst. - Outputs are the caller’s own strings, never re-serialised. When two strings spell the same instant, the first argument’s spelling wins (
from’s insubtractIntervals, the first occurrence insplitIntervalAtandmergeIntervals). No spec covers this tie, so it is a GMT rule, chosen because a rule based on position is deterministic without inventing a canonical spelling. start === endis a valid empty interval. It has a position but contains no instant:intervalContainsis alwaysfalsefor it.- It overlaps only an interval it lies strictly inside.
mergeIntervalsabsorbs it into a run it touches, and drops it otherwise.- Removing one changes nothing.
- An inverted interval (
startafterend) is invalid input, not silently swapped.
sumIntervalsis covered time. It measures the length of the union as an exact ISO 8601 duration with hours as the largest unit: exactlyTemporal.Instant.prototype.until(…, { largestUnit: "hour" }), since an instant has no calendar to define a day (PT49H30M, notP2DT1H30M). It sums asbigintnanoseconds, so it stays exact past 2^53 ns and across the whole instant range.sumIntervals([])isPT0S. A New York day across spring-forward isPT23H.- Also exported: the
Intervaltype ({ start: string; end: string }) andisValidInterval.mergeIntervals,subtractIntervalsandsplitIntervalAtreturn[]both as a legitimate result (a fully covered subtraction) and as the invalid-input sentinel, andisValidIntervaltells the two apart.
The older positional functions in
plain/,utc/,zoned/andunix/interval/move to the same half-open rule in this release, and theUtcvariants call these functions; that change and its migration are listed in their own entry. - Half-open
-
5f32094: Add the
precision/namespace: nanosecond instants asbigint, their JSON bridge, and explicit storage truncation (Story CORE-1).convertZonedToUnixand the rest ofunix/returnnumbermilliseconds, which cannot carry nanosecond timestamps — anumberholds integers exactly only to2^53 − 1≈ 9.0 × 10^15, and nanoseconds since the epoch passed that in April 1970. The new namespace works inbigintthroughout:import {toNanoseconds,fromNanoseconds,formatNanoseconds,parseNanoseconds,truncateNanoseconds,} from "@northguild/gmt";toNanoseconds("2024-03-10T12:00:00.123456789Z");// 1710072000123456789nfromNanoseconds(1710072000123456789n, "America/New_York");// "2024-03-10T08:00:00.123456789-04:00[America/New_York]"JSON.stringify({ observedAt: formatNanoseconds(1710072000123456789n) });// '{"observedAt":"1710072000123456789"}' — JSON.stringify throws on a raw bigintparseNanoseconds("1710072000123456789");// 1710072000123456789ntruncateNanoseconds(1710072000123456789n, "us");// 1710072000123456000n — what a PostgreSQL timestamptz column can actually holdtoNanosecondsaccepts any extended-format ISO 8601 instant string (offset or bracketed IANA zone). It rejects leap seconds and unknown critical annotations, and ignores a[u-ca=...]calendar annotation, asTemporal.Instant.fromdoes.fromNanosecondsreturns a UTC instant string, or a zoned string when given a time zone. Instant-to-local needs no disambiguation policy. Truncate first when writing to a store that holds less than nanoseconds, or the round-trip silently loses digits.truncateNanosecondsfloors toward negative infinity, so pre-1970 values truncate the same way post-1970 ones do:truncateNanoseconds(-1500n, "us")is-2000n, not-1000n.- Every function returns a sentinel (
"",0n) on invalid input and never throws, and accepts only values inside the rangeTemporal.Instantcan represent (±8_640_000_000_000_000_000_000n).0nis also the epoch itself, so validate first when the two must be told apart. formatNanoseconds/parseNanosecondsare the JSON bridge: abigintcannot go into a payload as-is, so the value crosses as a canonical decimal string. Embed it as a JSON string — unquoted it is a JSON number, andJSON.parserounds it back through a double to1710072000123456800.parseNanosecondstakes that string value (JSON.parse(payload).observedAt), not JSON text.- Leap-second-aware time scales (TAI, GPS) are deliberately out of scope — these are plain instant conversions.
Importable from the package root or from
@northguild/gmt/precision,@northguild/gmt/precision/convert,/precision/format,/precision/parse, and/precision/calculate. -
f9fb4f5: Fix zone-aware boundaries, counts and splits that went wrong around DST transitions and month ends.
Every fix follows TC39 Temporal. A boundary is a real instant in the zone, never a wall-clock time re-resolved after truncation. Repeated calendar steps are measured from the original anchor.
- Boundaries are always real.
startOfZoned,endOfZoned,startOfUnix,endOfUnix,getLocaleZonedStartOfWeek,getLocaleZonedEndOfWeek,startOfQuarterForZoned,startOfQuarterForUnix,endOfQuarterForZoned,endOfQuarterForUnixreturn the real start and end of the unit that contains the input: a start is never after the input and an end never before it. Before,startOfZonedcould place Pacific/Chatham’s hour 15 minutes after its input, andendOfZonedcould end New York’s repeated 1 a.m. hour before the input. disambiguationandoffsetare removed from those functions, andmapZonedHoursInDaytakes no options. Boundary methods in TC39 Temporal take no resolution options —startOfDay()has none — and passing them here, even at their documented defaults, used to bring the wrong answer back. See Breaking changes below.- A repeated local midnight is one day. When a fall-back repeats midnight on the same date (America/Havana, 3 November 2024), that date is one 25-hour day, matching
getHoursInZonedDay; its repeated first hour is still two hour buckets. A fall-back that re-enters the previous date (America/Goose_Bay, 7 November 2010) remains its own 59-minute bucket, because the date changed. areZonedEqualByandareUnixEqualBycompare those boundary instants, so the two passes of a repeated hour are no longer equal. Across two different zones,areZonedEqualBystill compares each value’s local unit.intervalCountZoned,intervalCountUnix,intervalCountUtccount the bucketsbucketRangewould return. A 20-minute Chatham range straddling 04:00 now counts 2 hours, not 1, and a span over Samoa’s deleted 30 December 2011 counts 2 days, not 3. Counting stops at 10,000 zone transitions and returnsnull;bucketRangeseparately stops at 10,000 buckets, so the two agree only within that list’s cap.startOfQuarterForZoned,startOfQuarterForUnix,startOfQuarterForUtcreset milliseconds, microseconds and nanoseconds.2024-05-15T12:34:56.789Znow starts its quarter at2024-04-01T00:00:00Z, not…00:00:00.789Z.getHoursInZonedDayreturns Temporal’shoursInDay, so a day whose midnight is skipped (America/Santiago, 8 September 2024) is 23 hours, not 24.mapZonedHoursInDaystops at the next local day instead of spilling into it. Both follow TC39’s date-labelled day (startOfDay()/hoursInDay), which differs from the boundary functions’ bucket only where a fall-back re-enters the previous date (America/Goose_Bay, 2010).splitIntervalByUnitDate,splitIntervalByUnitDateTime,splitIntervalByUnitZoned,splitIntervalByUnitUnix,splitIntervalByUnitUtcno longer drift at month ends: calendar units step from the anchor, so splitting from 31 January by month gives 29 February, 31 March, 30 April, and a yearly split from 29 February returns to 29 February in leap years. A step into a deleted local day is skipped rather than failing the whole split (Pacific/Apia by day now returns 29–31 December and 31 December–1 January). Hours and smaller step from the previous boundary, so very large amounts keep nanosecond precision.getDstTransitionsreports a transition that falls exactly at local midnight on 1 January (Asia/Singapore, 1982), returns a year with 20 transitions in full, and returns[]rather than a truncated list if its scan limit is ever exhausted.floorToZoneandbucketRangereturn""and[]rather than a plausible wrong boundary if the zone walker ever runs out of transitions.
getFiscalPeriod,roundZoned,roundUnix,parseRfc2822andparseHttpbehave as before. Their documentation now states how a 29 February fiscal anchor clamps, howroundbehaves in Chatham, and that impossible dates such as 31 February are rejected.Breaking changes
Section titled “Breaking changes”startOfZoned,endOfZoned,startOfQuarterForZoned,endOfQuarterForZoned,getLocaleZonedStartOfWeek,getLocaleZonedEndOfWeek,startOfUnix,endOfUnix,startOfQuarterForUnixandendOfQuarterForUnixno longer declaredisambiguationoroffset, andmapZonedHoursInDayno longer declares an options argument. A call that passes one stops type-checking. The output is the real boundary either way; a caller that relied ondisambiguation: "reject"returning""for an ambiguous boundary gets the boundary.1.15 1.16 startOfZoned(v, "hour", { disambiguation: "reject", offset: "prefer" }) startOfZoned(v, "hour") endOfZoned(v, "day", { weekStartsOn, fractionalSecondDigits, disambiguation, offset }) endOfZoned(v, "day", { weekStartsOn, fractionalSecondDigits }) startOfQuarterForZoned(, likewisev, { disambiguation, offset, fractionalSecondDigits }) endOfQuarterForZonedstartOfQuarterForZoned(v, { fractionalSecondDigits }) getLocaleZonedStartOfWeek(, likewisev, locale, { fractionalSecondDigits, disambiguation, offset }) …EndOfWeekgetLocaleZonedStartOfWeek(v, locale, { fractionalSecondDigits }) startOfUnix(, likewisev, unit, { epochUnit, timeZone, weekStartsOn, disambiguation, offset }) endOfUnixstartOfUnix(v, unit, { epochUnit, timeZone, weekStartsOn }) startOfQuarterForUnix(, likewisev, { epochUnit, timeZone, disambiguation, offset }) endOfQuarterForUnixstartOfQuarterForUnix(v, { epochUnit, timeZone }) mapZonedHoursInDay(anchor, { disambiguation, offset }) mapZonedHoursInDay(anchor) - Boundaries are always real.
-
727a3f4: Read annotations, time zone ids, SQL literals and leap seconds by their standards, and accept only the written shape each validator documents (Story CORE-8).
Elective annotations are accepted everywhere a Temporal string is. RFC 9557 §3.3 lets a receiver ignore an elective
[key=value]annotation and requires it to reject an unknown critical[!key=value]one, and Temporal’s ISO grammar does exactly that. GMT refused every annotation in some namespaces and read them loosely in others. Now:plain/validators and functions read elective annotations and a time zone annotation asTemporal.PlainDate.fromand its siblings do, and accept[u-ca=iso8601]. A non-ISO calendar is still refused outside the calendar functions.utc/,instant/,interval/,span/andprecision/read an instant asTemporal.Instant.fromdoes, which ignores any calendar annotation, critical or not.zoned/functions accept elective annotations and[u-ca=iso8601], and refuse a non-ISO calendar outside the calendar functions.- Every namespace rejects an unknown critical annotation.
isValidZonedRange, theplain/interval validators andtoOffsetInstantfollow the same rule.getWeekNumberaccepts an ISO-annotated date.import { isValidDateTime, getWeekNumber } from "@northguild/gmt/plain";import { isValidInterval } from "@northguild/gmt/interval";import { toOffsetInstant } from "@northguild/gmt/instant";import { isValidUtc } from "@northguild/gmt/utc";import { isValidZonedDateTime } from "@northguild/gmt/zoned";isValidDateTime("2024-01-01T10:00:00[foo=bar]"); // trueisValidDateTime("2024-01-01T10:00:00[!foo=bar]"); // falseisValidUtc("2024-01-01T00:00:00Z[u-ca=hebrew]"); // trueisValidZonedDateTime("2024-01-01T00:00:00+01:00[Europe/Paris][u-ca=iso8601]"); // trueisValidZonedDateTime("2024-01-01T00:00:00+01:00[Europe/Paris][u-ca=hebrew]"); // falseisValidInterval({ start: "2024-01-01T09:00:00Z[u-ca=hebrew]", end: "2024-01-01T17:00:00Z" }); // truetoOffsetInstant("2024-07-15T12:00:00-04:00[foo=bar]"); // { instant: "2024-07-15T16:00:00Z", offset: "-04:00" }getWeekNumber("2024-06-15[u-ca=iso8601]"); // 24Each validator accepts only its documented written shape. Temporal’s parser also reads the basic format, a space or lower-case
tseparator, a lower-casez, an hour without minutes, and a date with only a zone annotation.isValidZonedDateTime,isValidZonedRange,isValidInstant,isValidUtc,toNanoseconds,isValidSpan,toOffsetInstant,getTimeZoneOffset, theutcDateTimeandcalendarZonedDateTimeregexes and a zonedrelativeToaccepted some of these although GMT never writes them. They now accept only the extended form with an upper-caseTandZ, as the rest of GMT does.import { durationAs } from "@northguild/gmt/duration";import { isValidInstant } from "@northguild/gmt/precision";import { isValidZonedDateTime } from "@northguild/gmt/zoned";isValidZonedDateTime("2024-01-01 00:00:00+01:00[Europe/Paris]"); // falseisValidInstant("20240101T000000Z"); // falseisValidInstant("2024-01-01T00:00:00z"); // falsedurationAs("P1D", "hours", { relativeTo: "2024-03-10[America/New_York]" }); // nulldurationAs("P1D", "hours", { relativeTo: "2024-03-10T00:00:00-05:00[America/New_York]" }); // 23UTC offset ids are time zones. Temporal’s
TimeZoneIdentifieris an IANA name or a UTC offset without seconds.isValidTimeZoneand every zone argument rejected"+05:00". They now accept it, andtoOffsetInstantreturns the pair without atimeZonefor an offset zone, because an offset names no zone.import { toOffsetInstant } from "@northguild/gmt/instant";import { convertUtcToZoned } from "@northguild/gmt/utc";import { isValidTimeZone } from "@northguild/gmt/zoned";isValidTimeZone("+05:00"); // trueisValidTimeZone("+05:00:30"); // falseconvertUtcToZoned("2024-07-15T16:00:00Z", "+05:00"); // "2024-07-15T21:00:00+05:00[+05:00]"toOffsetInstant("2024-07-15T16:00:00Z", "+05:00"); // { instant: "2024-07-15T16:00:00Z", offset: "+05:00" }toOffsetInstantstill writes a zero offset as+00:00, neverZ, because EPCISeventTimeZoneOffsetrequires±HH:MM. Its documentation now says so.SQL date-times follow the SQL literal grammar. SQL-92 §5.3 requires seconds in a timestamp literal, and a four-digit year from 0001 to 9999. The
sqlDateTimeregex andparseSqlaccepted a value without seconds and years outside that range, andformatSqlwrote years outside it. They now takeYYYY-MM-DD HH:MM:SS, with an optional.and up to nine fraction digits, andformatSqlreturns""for a year it cannot write.import { formatSql, parseSql } from "@northguild/gmt/plain";import { sqlDateTime } from "@northguild/gmt/regex";sqlDateTime.test("2024-03-15 14:30"); // falseparseSql("2024-03-15 14:30:00.123456789"); // "2024-03-15T14:30:00.123456789"parseSql("0000-03-15 14:30:00"); // ""formatSql("+010000-01-01T00:00:00"); // ""isLeapSecondrecognises a second-60 field in a bare date-time or time. It stays a syntactic test, since GMT carries no IERS leap-second table, and matched only a second 60 followed by an offset,Zor an annotation. TheleapSecondregex is widened with it. Every validator still rejects second 60.import { isLeapSecond, isValidDateTime } from "@northguild/gmt/plain";isLeapSecond("2016-12-31T23:59:60"); // trueisLeapSecond("23:59:60"); // trueisValidDateTime("2016-12-31T23:59:60"); // falseSub-millisecond time ranges are ordered correctly.
isValidTimeRangeandisValidTimeIntervalcompared times to the millisecond, so an end one nanosecond before the start was accepted. They now compare withTemporal.PlainTime.compare.import { isValidTimeInterval } from "@northguild/gmt/plain";isValidTimeInterval("10:00:00.000000002", "10:00:00.000000001"); // falseBreaking changes
Section titled “Breaking changes”Input 1.15 1.16 "2024-01-01Tto a10:00:00 [foo=bar]" plain/functionrejected accepted, annotation ignored "2024-01-01Tto a00:00:00Z [u-ca=hebrew]" utc/functionrejected accepted, calendar ignored [!u-ca=hebrew]on an instant, for example toisValidUtcoraddUtcrejected accepted, calendar ignored "…to[u-ca=iso8601]" plain/andzoned/functionsrejected accepted isValidZonedDateTime(, and basic, lower-case"2024-01-01 00:00:00+01:00 [Europe/ Paris]") tand hour-only spellingstruefalseisValidUtc("2024-01-01T 00:00:00z") accepted falsedurationAs(…, { relativeTo: "2024-03-10 [America/ New_York]" }) a value null; pass a full zoned date-timeisValidTimeZone(, and"+05:00") "+05:00"as any zone argumentfalse, sentineltrue, acceptedsqlDateTime.test(,"2024-03-15 14:30") parseSqlof the samematched, parsed false,""formatSqlfor a year past 9999 or before 0001a string outside the SQL grammar ""isLeapSecond("2016-12-31T 23:59:60") falsetrueisValidTimeInterval("10:00:00.000000002", "10:00:00.000000001") truefalseMigration: write strings in GMT’s extended form (
T,Z, fullHH:MM:SS). Pass SQL values with seconds. CheckisValidTimeZone(zone) && !zone.startsWith("+") && !zone.startsWith("-")where only IANA zones are allowed. -
fb7a860: Add the
span/namespace: exact elapsed and wall-clock durations between two timestamps, as raw numbers (Story CORE-2).diffZonedanddiffUnixmeasure in calendar units and hand back a TemporalDuration. Profiling, tracing and telemetry want a number:import { spanMs, spanNs, spanWallClock } from "@northguild/gmt";spanMs("2024-03-10T12:00:00Z", "2024-03-10T12:00:01Z");// 1000spanMs("2024-03-10T12:00:00Z", "2024-03-10T12:00:00.123456789Z");// 123.456789 — fractional, like performance.now()spanNs("2024-03-10T12:00:00.123456789Z", "2024-03-10T12:00:00.123456790Z");// 1nBoth are signed, so
spanMs(b, a)is exactly-spanMs(a, b), and both measure exact elapsed time. That is a different question from calendar distance, and conflating the two is the most common span bug there is — a wall-clock day containing a DST transition is 23 or 25 real hours, or 24.5 inAustralia/Lord_Howe:const start = "2024-03-09T12:00:00-05:00[America/New_York]";const end = "2024-03-10T12:00:00-04:00[America/New_York]";spanMs(start, end);// 82800000 — 23 hours actually elapsedspanWallClock(start, end, "hours");// 24 — the clock face advanced a full dayspanMs/spanNsaccept anythingtoNanosecondsdoes: the extended RFC 9557 instant form, an offset or a bracketed IANA zone, no leap seconds, a[u-ca=...]calendar annotation ignored. The endpoints need not share a zone.spanWallClock(start, end, "days" | "hours")reads each endpoint’s own local wall clock, so it requires a bracketed IANA zone on both — and the two may differ, which is how a flight from New York to Berlin is 12 wall-clock hours and 7 elapsed ones. It truncates toward zero, and it is not a count of midnights crossed. The wall clock is read directly rather than via an instant, so no disambiguation policy applies: an offset-less local time that never occurred ("2024-03-10T02:30:00[America/New_York]") is measured as written rather than silently advanced past the DST gap.0and0nare valid spans, so invalid input returnsnullfrom all three rather than the zero the rest of the library would use.nulland notNaN, because it is the sentinel GMT already uses for every number-returning function and the only onestrictNullChecksforces a caller to handle — aNaNtypes as plainnumberand propagates silently through arithmetic. This is also whyspanNsis nottoNanoseconds(b) - toNanoseconds(a): those return0nfor both the epoch and a rejected string.spanMsreturnsnullpastNumber.MAX_SAFE_INTEGERmilliseconds (±285,000 years, which two instants at opposite ends ofTemporal.Instant’s range exceed). UsespanNsthere. A span is a duration, not an instant: it reaches twice the epoch-nanosecond range, so it is not afromNanosecondsinput.- Leap seconds are not counted. UTC repeats a second rather than numbering a 61st one, so a span across one is a second short of the physical elapsed time; against a smeared clock (Google, AWS, Meta) the error is up to a second spread over the smear window. Leap-second-exact spans need a TAI scale, which is not yet shipped.
Validators for both namespaces
Section titled “Validators for both namespaces”precision/andspan/were the only namespaces with novalidate/module, and inprecision/that was not cosmetic:0nis simultaneously the epoch and the invalid-input sentinel, and there was no public predicate to tell them apart.toNanoseconds’ own JSDoc suggestedisValidUtc, which gates on GMT’s stricter<date>T<time>Zshape and returnsfalsefor the offset and bracketed-zone stringstoNanosecondsaccepts — so following that advice discarded valid input.import {isValidInstant,isValidNanoseconds,isValidNanoPattern,isValidSpan,} from "@northguild/gmt";isValidInstant("1970-01-01T00:00:00Z"); // true — toNanoseconds returns 0n, the epochisValidInstant("garbage"); // false — toNanoseconds returns 0n, the sentinelisValidInstant("2024-03-10T12:00:00-04:00[America/New_York]"); // true — isValidUtc says falseisValidNanoPattern("0"); // true — parseNanoseconds returns 0n, the epochisValidNanoseconds(0n); // true; isValidNanoseconds(0) is false — a number cannot carry oneisValidSpan("2024-03-10T12:00:00Z", "2024-03-10T12:00:01Z"); // trueEach predicate accepts exactly what its partner parses, and
parseNanosecondsnow defers toisValidNanoPatternso the two cannot drift apart.isValidSpanis symmetric — a reversed pair is a negative span, not an invalid one — and is true for a pair whose span exceedsspanMs’s range, since that is a limit on the result rather than the inputs;spanNsstill returns the exactbigint.regex/gainsinstantLeapSecond(the wider leap-second grammar the full instant parser needs, alongside the existingleapSecond) andnanosecondDecimal.Importable from the package root or from
@northguild/gmt/span,@northguild/gmt/span/calculate,@northguild/gmt/span/validateand@northguild/gmt/precision/validate. -
727a3f4: Export
parseMillisecondFromUnixandparseMinuteFromUnixand three types their functions’ signatures already named, and add aminimalDaysoption togetLocaleWeekYearandgetWeeksInLocaleWeekYear(Story CORE-8).Two functions that shipped unreachable. Both were implemented, documented and tested, but
unix/parsenever re-exported them, and the package’sexportsmap blocks deep imports, so no path could reach them. Theirutc/andzoned/equivalents were always exported.import { parseMillisecondFromUnix, parseMinuteFromUnix } from "@northguild/gmt/unix";parseMillisecondFromUnix(1700000000123); // "123"parseMinuteFromUnix(1700000000000); // "13"Three types a signature named but nobody could import.
startOfTime,endOfTimeandisValidDateRangedeclared their unit and argument types without exporting them.StartOfTimeUnit,EndOfTimeUnitandIsValidDateRangePropsare now exported from@northguild/gmt/plainand the package root.import type { EndOfTimeUnit } from "@northguild/gmt/plain";const unit: EndOfTimeUnit = "minute";A locale’s week-numbering rule, stated by the caller. Week 1 is the week, starting on the locale’s first day of week, that holds at least
minimalDaysdays of January (UTS #35, Week Data). ECMA-402 no longer exposes that value:Intl.Locale.prototype.getWeekInforeturns onlyfirstDayandweekend(tc39/proposal-intl-locale-info#86). So it is now an option, an integer from 1 to 7.import { getLocaleWeekYear, getWeeksInLocaleWeekYear } from "@northguild/gmt";getLocaleWeekYear("2022-01-01", "en-US", { minimalDays: 1 }); // 2022 — January 1 is always in week 1getLocaleWeekYear("2022-01-01", "en-US"); // 2021 — the ISO 8601 default of 4getWeeksInLocaleWeekYear("2022-06-15", "en-US", { minimalDays: 1 }); // 53getLocaleWeekYear("2022-01-01", "en-US", { minimalDays: 0 }); // nullIn CLDR 48’s
weekDatathe world default is1, as inUS,CA,MX,JPandCN.4is set for a list of mostly European regions such asGB,DEandFR, where it matches GMT’s default. -
727a3f4: Give every
unix/function one epoch grammar, one{ epochUnit }option and a UTC default time zone (Story CORE-8).UTC is the default time zone everywhere in
unix/. About twenty functions read an omittedtimeZoneas the host’s zone, so the same call gave a different answer on another machine:addUnix,subtractUnix,setUnix,roundUnix,diffUnix,diffUnixAsDuration,isBetweenUnix,startOfUnix,endOfUnix,startOfQuarterForUnix,endOfQuarterForUnix,areUnixEqualBy, theconvertUnixToPlain*functions,parseDateFromUnix,parseTimeFromUnix,parseDayOfWeekFromUnix,parseUnitFromUnixandparseWeekFromUnix. They now use UTC, asformatUnixandformatRelativeUnixalready did. PasstimeZone: "local"to the formatters, or a zone id to any function, for another zone.One epoch grammar. An epoch is a safe integer, or a string of ASCII digits with an optional leading
-. Anything else returns the sentinel:"+1"," 1","1e3","1.0",1.5,NaN, abigint, and a value outside Temporal’s instant range. Before, some functions took digit strings and others did not, and the validators disagreed with the functions they guard.isValidUnixSecondsandisValidUnixMillisecondsnow accept exactly what the functions accept.import { addUnix, convertUnixToPlainDate, isValidUnixSeconds, parseHourFromUnix, sortUnix } from "@northguild/gmt/unix";parseHourFromUnix(1700000000000); // "22"convertUnixToPlainDate(1710460800, { epochUnit: "seconds" }); // "2024-03-15"addUnix("1700000000000", { days: 1 }); // 1700086400000addUnix("+1700000000000", { days: 1 }); // nullisValidUnixSeconds("1700000000"); // truesortUnix(["3", 1, "2"]); // [1, 2, 3]The converters take
{ epochUnit }.convertUnixToUtc,convertUnixToZoned,convertUtcToUnix,convertZonedToUnixandgetUnixNowtook the unit as a positional argument, unlike every otherunix/function. They now take an options object, andgetUnixNowreturnsnumber | null. Singular unit names are accepted inepochUnittoo, as Temporal §13.17 accepts them.import { convertUnixToUtc } from "@northguild/gmt/unix";import { convertUtcToUnix } from "@northguild/gmt/utc";convertUnixToUtc(1709164800, { epochUnit: "seconds" }); // "2024-02-29T00:00:00Z"convertUnixToUtc("1709164800", { epochUnit: "second" }); // "2024-02-29T00:00:00Z"convertUtcToUnix("2024-02-29T00:00:00Z", { epochUnit: "seconds" }); // 1709164800getUnixNowUnitalso accepts plural unit names.intervalLengthUnix,intervalCountUnixandsplitIntervalByUnitUnixtakeepochUnitandtimeZonelike the otherunix/intervalfunctions. They read milliseconds and the host’s zone only.import { intervalCountUnix, intervalLengthUnix } from "@northguild/gmt/unix";intervalLengthUnix(0, 172800, "days", { epochUnit: "seconds" }); // 2intervalCountUnix(0, 86400000, "day", { timeZone: "America/New_York" }); // 2An unknown time zone is invalid in the
unix/andutc/formatters.formatUnix,formatCalendarUnix,formatRelativeUnix,formatUtc,formatCalendarUtcandformatRelativeUtcrendered in UTC when the zone did not exist, as if it had been omitted. ECMA-402 throws aRangeErrorfor it, so they now return"". An omitted zone is still UTC, and"local"is the system zone.import { formatUnix } from "@northguild/gmt/unix";formatUnix(1700000000000, "en-US", { timeZone: "Not/AZone" }); // ""Nanosecond fields are three digits.
parseNanosecondFromUnixandparseUnitFromUnix(…, "nanosecond")returned nine digits. Temporal’snanosecondfield is 0–999, as every other GMT parser and getter writes it.import { parseNanosecondFromUnix } from "@northguild/gmt/unix";parseNanosecondFromUnix(1700000000123); // "000"Breaking changes
Section titled “Breaking changes”Function 1.15 1.16 convertUnixToUtc,convertUnixToZonedconvertUnixToUtc(,v, "seconds") convertUnixToZoned(v, zone, "seconds") convertUnixToUtc(,v, { epochUnit: "seconds" }) convertUnixToZoned(v, zone, { epochUnit: "seconds" }) convertUtcToUnix,convertZonedToUnixconvertUtcToUnix(v, "seconds") convertUtcToUnix(v, { epochUnit: "seconds" }) getUnixNowgetUnixNow(, returns"seconds") numbergetUnixNow(, returns{ epochUnit: "seconds" }) number | nullconvertUnixToPlainDate,…DateTime,…TimeconvertUnixToPlainDate(silently read milliseconds:1710460800, "seconds") "1970-01-20"in UTC""; pass{ epochUnit: "seconds" }The unix functions listed above, timeZoneomittedthe host’s zone "UTC"; passtimeZonefor another zoneintervalLengthUnix,intervalCountUnix,splitIntervalByUnitUnixhost zone, milliseconds only { epochUnit, timeZone }, default milliseconds and"UTC"formatUnix,formatCalendarUnix,formatRelativeUnix,formatUtc,formatCalendarUtc,formatRelativeUtcwith an unknowntimeZonerendered in UTC ""parseNanosecondFromUnix(1700000000000) "000000000""000"Epoch strings such as "+1","1e3"or" 1"accepted by some functions the sentinel A positional unit passed to the new signatures returns the sentinel rather than a wrong instant:
convertUnixToUtc(1709164800, "seconds" as never)is"". -
727a3f4: Validate
unix/epoch arguments and read rounding and comparison options the way Temporal reads them (Story CORE-8).epochUnitis validated. Fourteenunix/functions read anyepochUnitthey did not recognise, including a misspelling, as milliseconds. They areaddUnix,subtractUnix,diffUnix,diffUnixAsDuration,isBetweenUnix,roundUnix,setUnix,areUnixEqual,isAfterUnix,isBeforeUnix,intervalFromDurationUnix,intervalOverlappingDaysUnix,formatCalendarUnixandformatRelativeUnix. They now return their sentinel.A blank epoch string is not 1970.
parseYearFromUnixand the otherparse*FromUnixfunctions read""and whitespace as epoch 0. They now return"".sortUnix,minUnixandmaxUnixskip values that are not instants. A fraction such as1.5, or a number past Temporal’s range such as1e20, was sorted or returned as if it were an epoch.import { addUnix, parseYearFromUnix, sortUnix } from "@northguild/gmt/unix";addUnix(1700000000000, { days: 1 }, { epochUnit: "minutes" }); // nullparseYearFromUnix(" "); // ""sortUnix([3, 1.5, 1e20, 2]); // [2, 3]FormatCalendarUnixOptionsno longer declaresstyle,numeric,largestUnitorroundingMethod.formatCalendarUnixnever read them, so its output is unchanged; see Breaking changes below.Rounding options follow Temporal.
roundTime,roundDateTime,roundUtc,roundZonedandroundUnixaccept plural unit names insmallestUnit, as Temporal §13.17 does.roundDateandroundDateTimereturned the floor for aroundingModeoutside Temporal’s nine modes. They now return"". A fractionalroundingIncrementis truncated to an integer, as Temporal truncates it, instead of rejected.startOfDate(value, "day")returns the date, asendOfDate(value, "day")already did. It returned"".
import { roundDate, roundTime, startOfDate } from "@northguild/gmt/plain";roundTime("12:34:56", { smallestUnit: "hours" }); // "13:00:00"roundDate("2024-05-20", { smallestUnit: "month", roundingIncrement: 1.5 }); // "2024-06-01"roundDate("2024-05-20", { smallestUnit: "month", roundingMode: "bogus" as never }); // ""startOfDate("2024-02-29", "day"); // "2024-02-29"areUtcEqualByandareDateTimesEqualBycompare the buckets you name. WithfractionalSecondDigits, they compared the printed strings, so two different milliseconds printed with 0 digits looked equal. They now compare the start of eachunitbucket, and the option is removed.import { areUtcEqualBy } from "@northguild/gmt/utc";areUtcEqualBy("2024-05-15T10:20:30.123Z", "2024-05-15T10:20:30.999Z", "millisecond"); // falseTo compare at the precision the digits stood for, pass that coarser unit.
areUtcEqualBy("2024-05-15T10:20:30.123Z", "2024-05-15T10:20:30.999Z", "second"); // truegetLocaleZonedEndOfWeekprints the end to the nanosecond. It kept the whole-second default that the otherendOf*functions dropped in this release.import { getLocaleZonedEndOfWeek } from "@northguild/gmt/zoned";getLocaleZonedEndOfWeek("2024-03-13T10:00:00-04:00[America/New_York]", "en-US"); // "2024-03-16T23:59:59.999999999-04:00[America/New_York]"Compatibility: pass
{ fractionalSecondDigits: 0 }to keep the whole-second string.getLocaleZonedEndOfWeek("2024-03-13T10:00:00-04:00[America/New_York]", "en-US", { fractionalSecondDigits: 0 }); // "2024-03-16T23:59:59-04:00[America/New_York]"Breaking changes
Section titled “Breaking changes”1.15 1.16 formatCalendarUnix(v, locale, { reference, style, numeric, largestUnit, roundingMethod }) formatCalendarUnix(: the four members had no effectv, locale, { reference }) areUtcEqualBy(a, b, "millisecond", { fractionalSecondDigits: 0 }) areUtcEqualBy(a, b, "second") areDateTimesEqualBy(a, b, "millisecond", { fractionalSecondDigits: 0 }) areDateTimesEqualBy(a, b, "second")
Patch Changes
Section titled “Patch Changes”-
727a3f4: Fix three defaults that returned the wrong value (Story CORE-8). Each one has a documented option that restores the previous output.
endOf*printed a moment earlier than the end. An end is the next start minus one nanosecond, butendOfTime,endOfDateTime,endOfUtc,endOfZonedandendOfQuarterForZonedprinted only the digits the unit names, soendOfTime("12:34:56", "hour")returned"12:59:59": 999,999,999 nanoseconds before the real end. They now default to nanosecond precision, whichendOfQuarterForUtcalready used.endOfUtc("2024-03-15T14:30:45Z", "month"); // "2024-03-31T23:59:59.999999999Z"endOfUtc("2024-03-15T14:30:45Z", "month", { fractionalSecondDigits: 0 }); // "2024-03-31T23:59:59Z" — previous outputTo keep the previous string, pass the digits the unit names:
0forsecondand coarser,3formillisecond,6formicrosecond. ForendOfQuarterForZoned, always pass0.formatDateTimeToPartsandformatZonedToPartsdropped the time. Called with no field options, they returned only the date parts. For a date-time value, ECMA-402’sGetDateTimeFormat, as amended by Temporal, defaults year, month, day, hour, minute and second to"numeric", and adds a short time zone name for a zoned value. They now do the same.formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US");// month, day, year, hour, minute, second, dayPeriod, timeZoneName "EDT"formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US", { year: "numeric", month: "numeric", day: "numeric" });// month, day, year — previous outputgetLocaleWeekYearandgetWeeksInLocaleWeekYearanswered differently by Node version. They read a locale’sminimalDaysfrom the runtime. Node 22 still reported it, while Node 24 and later do not, sogetLocaleWeekYear("2022-01-01", "en-US")returned2022on one runtime and2021on another. The default is now the ISO 8601 value4on every runtime. Pass{ minimalDays: 1 }to keep the Node 22 result foren-USand other locales whose rule is1. -
358e91e: Fix non-ISO calendar arithmetic, differences and range limits that were wrong, empty or unparseable, so every supported calendar follows TC39 Temporal and the Intl Era and Month Code proposal across the whole representable range.
Several of these fixes change outputs that shipped. Each earlier output was wrong under the specification, so each change is a bug fix, not a new behaviour. The examples use this release’s RFC 9557 calendar strings, described in their own entry.
- Month and year differences at month ends are correct in every non-ISO calendar. A month counts only once the end date reaches the same day of the next month, as Temporal’s
NonISODateSurpassesspecifies.diffDateAsDuration("2024-08-31[u-ca=buddhist]", "2024-09-30[u-ca=buddhist]", "months")is"P30D", not"P1M". This changes results fromdiffDate,diffDateAsDuration,intervalLengthDate,intervalCountDate,diffZoned,diffZonedAsDuration,intervalLengthZonedandintervalCountZonedfor calendar-annotated input. The rounding options ofdiffDateanddiffDateAsDurationnow round from that correct difference. - Hebrew year differences across a leap month return a value. A difference in years from an Adar I date in a leap year used to return
nullor"".diffDateAsDuration("2024-02-24[u-ca=hebrew]", "2025-03-15[u-ca=hebrew]", "years")is"P1Y". - Calendar dates at both range limits parse, and arithmetic works there.
isValidCalendarDate("+275760-09-13[u-ca=hebrew]")istrue.addDate,subtractDate,diffDate*and the duration functions work near the first and last dates in buddhist, hebrew, the Islamic calendars, persian and indian. - Buddhist is proleptic. Its year is the ISO year plus 543 with the same month and day for every date, so month arithmetic before 1582-10-15 follows the proleptic Gregorian calendar:
addDate("1000-01-31[u-ca=buddhist]", { months: 1 })is"1000-02-28[u-ca=buddhist]". - Hebrew years ≤ 0 and Indian dates before ISO year 1 are correct. Their fields were a day off, threw, or returned the sentinel, which put arithmetic on those dates a day off too.
- Zoned values at the minimum instant in zones behind UTC are accepted.
convertZonedToCalendar("-271821-04-19T12:00:00[Etc/GMT+12]", "hebrew")is"-271821-04-19T12:00:00-12:00[Etc/GMT+12][u-ca=hebrew]". With an explicit-12:00offset, Temporal checks that local date against the day range and rejects it, so that form still returns"". - A calendar-annotated
relativeToworks near the range limits indurationAs,normalizeDurationandcompareDurations.
Each correction checks the installed Temporal polyfill and ICU once and stays inactive where they are already right, so no output changes when the upstream fixes ship.
- Month and year differences at month ends are correct in every non-ISO calendar. A month counts only once the end date reaches the same day of the next month, as Temporal’s
-
727a3f4: The 1844 date-line crossings are found.
Asia/Manila,Pacific/Guam,Pacific/Saipan,Pacific/KosraeandPacific/Palaumoved to the Asian side of the date line by skipping 1844-12-31, but the Temporal polyfill only searches for time zone transitions from 1847-01-01 on, so GMT missed that change. Every fix returns what native Temporal (Chrome 153) returns.getDstTransitions(zone, 1845)lists the crossing. It used to return[].getDstTransitions("Asia/Manila", 1845)is[{ instant: "1844-12-31T15:56:08Z", offsetBefore: "-15:56:08", offsetAfter: "+08:03:52" }]. 1844 stays[]: the crossing is local 1845-01-01 00:00, so it belongs to 1845.- Weeks across the crossing start on Monday 1844-12-30.
startOfZoned,endOfZoned,floorToZoneandareZonedEqualByby week were a day off.floorToZone("1845-01-02T03:56:08Z", "week", "Asia/Manila")is"1844-12-30T15:56:08Z", not"1844-12-29T15:56:08Z", and 1844-12-30 and 1845-01-02 are now in the same week.startOfUnix,areUnixEqualByandgetLocaleZonedStartOfWeekare corrected with them. - 1844-12-30 is 24 hours long.
getHoursInZonedDay("1844-12-30T12:00:00-15:56[Asia/Manila]")is24, not479340.06444444443.roundZonedandroundUnixto a day now round its noon up to the crossing,1845-01-01T00:00:00+08:04[Asia/Manila], instead of down to 1844-12-30. - The skipped day is not counted.
intervalCountZonedfrom 1844-12-01 to 1845-02-01 by day is61, not62(intervalCountUnixover the same span agrees), andintervalOverlappingDaysZonedfrom 1844-12-29 noon to 1845-01-01 noon is3, not4. - Business days skip it.
addZonedBusinessDays("1844-12-27T12:00:00-15:56[Asia/Manila]", 2)is"1845-01-01T12:00:00+08:04[Asia/Manila]", not a date in 1899.
The correction runs only for instants before 1847-01-01 (and local dates on or before it) in a named zone; every later value takes the same path as before. It is removed once a polyfill release containing js-temporal/temporal-polyfill#372 is the dependency floor.
-
727a3f4: Correct about 70 JSDoc
@exampleresults that disagreed with what the function returns (Story CORE-8).Every public function’s examples were executed against the build and compared with their documented result. They also feed the reference site and the playground’s default inputs. The wrong ones fell into a few classes:
- Invalid locales. Twelve locale-aware functions documented their sentinel for
"not-a-locale". That tag is well-formed BCP 47, so ECMA-402 falls back instead of throwing, and the functions return a real value. The examples now use a malformed tag. - Microseconds and nanoseconds. The
parseMicrosecondFrom*andparseNanosecondFrom*examples documented"123"for"…45.123". That fraction is 123 milliseconds, so both fields are"000". - Zone-dependent Unix parsers. The
unix/parseexamples were written in a local zone. They now document the UTC fields. - CLDR wording. Range, date-time and parts examples now match CLDR 42 and later, including the narrow no-break space (U+202F) before
AM/PM. - Arithmetic and transcription errors. Among others:
roundUtc,roundUnix,minZonedacross a DST change,convertZonedToUnix,intervalIntersectionUnix, andareUnixEqual, whoseepochUnitapplies to both values. TheformatCalendarUtcandformatCalendarZonedexamples referenced an undefined variable.
The rest of the review corrected the prose around those examples too:
- Parity claims and option tables.
formatCalendarUnixclaimed to mirrorformatCalendarand listed four options it never read.isZonedBusinessDayand its add and subtract functions claimed parity withisBusinessDaythat no longer held. - Ranges and defaults.
normalizeDuration’sroundingIncrementandlargestUnit: "auto"rules, and theunixSecondsandunixMillisecondsregex ranges. - Sources. Wrong section numbers for Temporal, ECMA-402 and the RFCs, and documented behaviour the docs had not stated: RFC 5905’s all-zero NTP timestamp also means an unknown time, only .NET ticks of
Kind == Utcname an instant, and a bracketed zone on an instant string is not checked.
No function’s behaviour changed in this entry.
- Invalid locales. Twelve locale-aware functions documented their sentinel for
-
358e91e: Fix results that were wrong, empty or thrown at the edges of the representable range: the last nanosecond of a day, the first and last instant, and zones ahead of or behind UTC there.
Temporal represents instants from
-271821-04-20T00:00:00Zto+275760-09-13T00:00:00Z. Every fix returns what the TC39 specification returns for the same input.intervalAbuts*andintervalXorAll*no longer step past an edge. They used to add one unit to an interval’s end, which wraps aPlainTimeto midnight and throws at the last instant. The half-open rule in this release removes the step altogether, sointervalAbutsTime,intervalAbutsDate,intervalAbutsDateTime,intervalAbutsUtc,intervalAbutsZoned, andintervalXorAll*for all six families return the exact answer there.intervalXorAllTime([{ start: "22:00:00", end: "23:59:59.999999999" }])returns that interval, not[].intervalDifference*keeps A whole when B lies entirely before it. All six families used to start the remaining piece one unit after B’s end, inside the gap.intervalDifferenceDate("2024-01-10", "2024-01-20", "2024-01-01", "2024-01-05")is[{ start: "2024-01-10", end: "2024-01-20" }].- Ends of units in the earliest month exist. Several functions returned the sentinel because the unit’s start lies before the range, although its end does not:
endOfDate,endOfDateTime,endOfUtc,endOfZonedandendOfUnixfor week, month, quarter and year, plusroundDate,roundDateTime,intervalCountDate,intervalCountDateTimeandgetLocaleZonedEndOfWeek.endOfDate("-271821-04-19", "month")is"-271821-04-30". endOfDateandendOfDateTimeend a Sunday-first week on Saturday. For a Sunday input, the week used to end on the previous Saturday.endOfDate("2024-03-10", "week", { weekStartsOn: "sunday" })is"2024-03-16".- Zone boundaries at the last instant keep the right offset.
startOfZoned,startOfQuarterForZoned,floorToZone,startOfUnix,intervalCountZoned,intervalCountUnixandgetLocaleZonedStartOfWeekdropped a transition there, so boundaries in daylight-saving zones came out an hour off. - Zoned values near the last instant work in zones ahead of UTC.
isValidZonedDateTime("+275760-09-13T10:00:00+10:00[Australia/Sydney]")is nowtrue, and one nanosecond later is stillfalse. Everyzoned/function that parses, adds, rounds or finds a start of day accepts these values, as do the differences and totals built on them:diffZoned,diffUnix,diffUtc, their*AsDurationforms,intervalLengthZoned,intervalLengthUnix,intervalLengthUtc,durationAs,normalizeDuration,compareDurationsandformatRelative{Zoned,Utc,Unix}. For example,durationAs("PT49H", "days", { relativeTo: "+275760-09-10T05:00:00+10:00[Australia/Sydney]" })is now2.0416666666666665, notnull. The same differences also work at the first instant in zones behind UTC. - Daylight-saving transitions in the last weeks of the range are found.
America/Santiago’s day on+275760-09-07is 23 hours:getHoursInZonedDayreturns23, notnull.getDstTransitions,mapZonedHoursInDay,roundZonedandroundUnixto a day, andintervalCountZonedare corrected with it. UTCnear the last instant behaves like+00:00. A rounded difference or total whose window passes the limit now returns the sentinel, as the specification requires.intervalLengthUtc("+275760-09-10T23:00:00Z", "+275760-09-13T00:00:00Z", "days")isnull.unix/intervalfunctions accept only whole, safe epochs. A fractional epoch, one pastNumber.MAX_SAFE_INTEGER, or""now returns the sentinel, as does any other value outside theunix/epoch grammar.intervalXorUnix(0, 1, 0.5, 2)used to return a negative piece, and""was read as epoch 0.isValidUnixRangeandisValidUnixIntervalreject the same values.- The critical calendar flag is read like the plain one.
[!u-ca=hebrew]used to pass a gate that refused[u-ca=hebrew], and the value was read in the wrong calendar.spanNs,spanMs,toNanoseconds,isValidInstantandisValidIntervalnow ignore both spellings, since an instant has no calendar, and the zoned validators refuse both.
The zoned corrections run only when the installed Temporal polyfill throws near a limit, so no other input changes. They are removed once a polyfill release fixes those limits.
-
727a3f4: Return the sentinel for arguments that are hostile to inspection, not just hostile to
ToString(Story CORE-8).What was wrong. 221 of the 551 exports threw when an argument resisted being looked at. A revoked
Proxythrows onget,ownKeysandArray.isArray; an object with a throwing getter throws when a rest-spread enumerates it. Those operations sat in the guards above each function’stry, so the guard meant to reject invalid input raised instead.import { addDate, formatUnix } from "@northguild/gmt";const { proxy, revoke } = Proxy.revocable({}, {});revoke();addDate("2024-01-01", proxy);// "" — was: TypeError: Cannot perform 'ownKeys' on a proxy that has been revokedformatUnix(0, "en-US", { get length() { throw new Error("boom"); } });// "" — was: Error: boomEvery affected export now evaluates its whole body inside the
trywhosecatchalready returned its sentinel, so a guard cannot raise. Valid input is unaffected: all 36,348 tests pass unchanged.Why it was invisible. The no-throw harness fed each export a list of eleven hostile values, and a list only finds what someone thought to put on it. It now also passes a proxy that throws on every trap, a revoked proxy, and an object with a throwing getter — values hostile to any access rather than to one named operation.
-
727a3f4: Make the RFC 5322, HTTP-date and RFC 3339 parsers and formatters follow their grammars exactly (Story CORE-8).
parseRfc2822accepts what a receiver must accept. It took only the strict form GMT’s own formatter writes. RFC 5322 §3.3 also allows folding whitespace, comments, any letter case and a 4-or-more-digit year. §4 says a receiver MUST accept the obsolete syntax too: two- and three-digit years, and the military and North American zone names. Unknown zone names read as-0000, meaning no offset information.import { parseRfc2822 } from "@northguild/gmt/zoned";parseRfc2822("fri,15 Mar 24 14:30 -0400 (EDT)"); // "2024-03-15T14:30:00-04:00[-04:00]"parseRfc2822("Fri, 15 Mar 2024 14:30:00 CEST"); // "2024-03-15T14:30:00+00:00[+00:00]"Comments are read in one linear pass. A deeply nested comment used to take quadratic time: 4 seconds for 100 KB.
parseHttpaccepts all three HTTP-date forms. RFC 9110 §5.6.7 says a recipient MUST acceptrfc850-dateandasctime-dateas well asIMF-fixdate. OnlyIMF-fixdatewas accepted.import { parseHttp } from "@northguild/gmt/utc";parseHttp("Sunday, 06-Nov-94 08:49:37 GMT"); // "1994-11-06T08:49:37Z"parseHttp("Sun Nov 6 08:49:37 1994"); // "1994-11-06T08:49:37Z"A day name that contradicts the date is rejected. RFC 5322 §3.3 requires the day of week to match the date. Both parsers ignored it, so
"Sat, 15 Mar 2024"parsed as a Friday. They now return"".parseHttpapplies the rule to all three HTTP-date forms,asctime-dateincluded. That form writes the day name with no comma after it, so it is the one most likely to be read as decoration — it is not. 6 November 1994 was a Sunday, so all three of these return"", and only the Sunday spellings parse:parseRfc2822("Sat, 15 Mar 2024 14:30:00 -0400"); // ""parseHttp("Sat, 15 Mar 2024 14:30:00 GMT"); // "" — IMF-fixdateparseHttp("Monday, 06-Nov-94 08:49:37 GMT"); // "" — rfc850-dateparseHttp("Mon Nov 6 08:49:37 1994"); // "" — asctime-dateparseHttp("Sun Nov 6 08:49:37 1994"); // "1994-11-06T08:49:37Z"Accepting a mismatch would mean choosing which of the two fields to believe, and RFC 9110 gives no rule for that. Rejecting is the only reading that never invents a date.
Compatibility: remove the day name. The date alone then decides the result. For
parseHttp, parse the string as RFC 5322 and convert it to UTC.parseRfc2822("15 Mar 2024 14:30:00 -0400"); // "2024-03-15T14:30:00-04:00[-04:00]"convertZonedToUtc(parseRfc2822("15 Mar 2024 14:30:00 GMT")); // "2024-03-15T14:30:00Z"Formatters stop writing strings outside their grammar.
formatRfc2822andformatHttpwrote years before 0000 as"00-1", andformatHttpwrote years past 9999.formatRfc2822wrote an offset with seconds, such as Monrovia’s −00:44:30 in 1969, as"-0044.5".formatRfc3339rounded a sub-minute offset to the minute, which names a different instant, and wrote years past 9999 in expanded form. All three now return""for a year their grammar cannot express, andformatRfc2822does the same for an offset with seconds.formatRfc3339writes such a value as the same instant at+00:00.formatRfc3339("1969-12-31T23:15:30-00:45[Africa/Monrovia]"); // "1970-01-01T00:00:00+00:00"formatRfc3339("+010000-01-01T00:00:00+00:00[UTC]"); // ""formatHttp("-000001-06-15T12:00:00Z"); // ""formatRfc2822("-000001-06-15T12:00:00+00:00[UTC]"); // ""Compatibility: for the value itself, use Temporal’s own serialisation.
Temporal.ZonedDateTime#toString({ timeZoneName: "never" })gives the earlierformatRfc3339string, andTemporal.Instant#toString()orTemporal.ZonedDateTime#toString()gives a string for any year.Temporal.ZonedDateTime.from("1969-12-31T23:15:30-00:45[Africa/Monrovia]").toString({ timeZoneName: "never" }); // "1969-12-31T23:15:30-00:45"The
rfc2822DateTimeandhttpDateregexes stay strict: they match only the form GMT writes. Therfc3339DateTimeregex now rejects an offset outside-23:59…+23:59, as RFC 3339 §5.6 requires.import { rfc3339DateTime } from "@northguild/gmt/regex";rfc3339DateTime.test("2024-03-15T14:30:00+24:00"); // false -
727a3f4: Format dates and times the way ECMA-402, as amended by Temporal, formats Temporal values (Story CORE-8).
The text formatters took their options through the polyfill’s
toLocaleString, which rebuilds them fromresolvedOptions()and loses some on the way. They now apply Temporal’sGetDateTimeFormatandAdjustDateTimeStyleFormatover the runtime’s ownIntl.DateTimeFormat, so each text result equals its…ToPartsresult joined. The affected functions areformatDate,formatTime,formatDateTime,formatDateRange,formatDateTimeRange,formatUtc,formatUnix,formatZonedDateTime,formatZonedRangeand the three…ToPartsfunctions. The implementation was checked against a native-Temporal browser in 55,080 comparisons.Requested widths are kept. Some locales and calendars lost a width, so
ja-JPwith the Japanese calendar andmonth: "long"gave"R6/2", andzh-CNgave"2024/2". AlongorfulltimeStylealso replaced a shorterdateStyle.import { formatDate, formatDateTime, formatTime } from "@northguild/gmt/plain";formatDate("2024-02-03", "ja-JP-u-ca-japanese", { year: "numeric", month: "long" }); // "令和6年2月"formatDate("2024-02-03", "ja-JP-u-ca-japanese", { year: "numeric", month: "numeric" }); // "R6/2"eraandtimeZoneNamecount as the fields they are. Temporal treats neither as a date or time field, so it adds the value’s default fields.eraalone dropped the time from a date-time.timeZoneNamealone returned"", and a plain value has no zone to name, so it is now left out.formatDateTime("2024-02-03T14:30:45", "en-US", { era: "long" }); // "2/3/2024 Anno Domini, 2:30:45 PM"formatDate("2024-02-03", "en-US", { timeZoneName: "long" }); // "2/3/2024"formatTime("14:30:45", "en-US", { era: "long" }); // "2:30:45 PM"A style the type cannot show returns the sentinel. A
timeStylebesidedateStyleon aPlainDatewas ignored, as was adateStyleon aPlainTime.formatDateToPartswith time options leaked a UTC midnight and a"UTC"zone name, and along/fulltimeStyleadded a"UTC"zone name toformatDateTimeToPartsandformatCalendar. Plain values now show no zone, and a style for fields the type does not have returns""or[].formatDate("2024-02-03", "en-US", { dateStyle: "short", timeStyle: "short" }); // ""formatDate("2024-02-03", "en-US", { dateStyle: "short" }); // "2/3/24"formatTime("14:30:45", "en-US", { timeStyle: "short" }); // "2:30 PM"A zoned value is formatted in its own zone.
formatZonedToPartshonoured atimeZoneoption and rendered the instant in that zone, andformatZonedRangesilently overrode it. Both now return their sentinel for atimeZoneoption, asformatZonedDateTimedoes.import { formatUtc, formatZonedToParts } from "@northguild/gmt";formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US", { timeZone: "Asia/Tokyo" }); // []formatUtc("2024-02-03T19:30:45Z", "en-US", { timeZone: "Asia/Tokyo", includeTimeZoneName: true }); // "2/4/2024, 4:30:45 AM GMT+9"Compatibility: each function’s JSDoc names the call that keeps its earlier text. Pass the fields the old text showed, such as the numeric fields for
"R6/2"ordateStylealone for the styled date. To render an instant in another zone, useformatUtcwith itstimeZoneoption. For the parts a plain date used to leak, callformatZonedToPartson the value at midnight UTC. -
727a3f4: Stop 62 functions throwing on a missing or wrong-typed argument (Story CORE-8). Each now returns its documented invalid-input result.
GMT’s contract is that invalid input returns
"",null,falseor[]and never throws. These functions broke it with aTypeErrororRangeErrorfrom inside the function:addDate,subtractDateand the otheradd*/subtract*functions, given anulldurationroundDate,roundTimeand the otherround*functions, with no optionsmin*,max*,sort*,closestDateToandclosestZonedTo, given something that is not an arraygetLargestDateDurationUnit,getLargestDateTimeDurationUnitandgetLargestTimeDurationUnit, givennullor a non-array, which now return""- the ten
formatRelative*andformatCalendar*functions, givenoptions = null - the six
isValid*Rangevalidators, givennullorundefined
import { addDate, cycleDate, isValidDateRange, minDate, minUnix, roundTime } from "@northguild/gmt";addDate("2024-01-01", null); // ""roundTime("12:34:56"); // ""minDate("2024-01-01"); // nullisValidDateRange(null); // falseoptions = nullin the relative and calendar formatters returns"", since Temporal’sGetOptionsObjectrejects it. This release applies the same rule to every function that takes an options object.cycle*amounts.cycleDate,cycleDateTime,cycleTimeandcycleZonedreadnull,"",[]andtrueas an amount of0and returned the value unchanged. They now return"".cycleDate("2024-12-15", "month", null); // ""minUnixandmaxUnixon long arrays. They spread the array into one call, so around 200,000 values overflowed the stack. They now scan the array.minUnix(Array.from({ length: 200000 }, (_, i) => i * 1000)); // 0A new test feeds invalid values to every exported function in every argument position and checks that it returns its declared sentinel. No valid input changes output in this entry.
-
727a3f4: Tighten input checks for leap seconds, time zone names, calendar annotations and date shapes, so every function accepts the same strings its validator accepts (Story CORE-8).
Leap seconds are rejected in every spelling. GMT rejects
:60, as Temporal does not represent it, but the check matched only an uppercaseTwith extended digits. A lowercaset, a space separator or the basic format (20161231 235960Z) got through, and everyzoned/function silently read the second as:59.getTimeZoneOffsetlooked up the offset at the clamped instant, and arelativeTostring was never checked at all. All of them now return their sentinel, andisLeapSecondand theleapSecondregex recognise every spelling.import { addZoned, getTimeZoneOffset, isValidZonedDateTime } from "@northguild/gmt/zoned";isValidZonedDateTime("2016-12-31t23:59:60+00:00[UTC]"); // falseaddZoned("2016-12-31 23:59:60+00:00[UTC]", { seconds: 1 }); // ""getTimeZoneOffset("UTC", "2016-12-31T23:59:60Z"); // ""Compatibility: to read a leap second as
:59the way earlier releases did, let Temporal clamp it, or pass the:59instant yourself.Temporal.ZonedDateTime.from("2016-12-31 23:59:60+00:00[UTC]").toString(); // "2016-12-31T23:59:59+00:00[UTC]"getTimeZoneOffset("UTC", "2016-12-31T23:59:60Z".replace(":60", ":59")); // "+00:00"The
instantLeapSecondregex is now anchored. It used to match inside an annotation value, soisValidInstant, thespan*functions andtoOffsetInstantrejected a valid instant such as"2024-01-01T00:00:00Z[x=T123460Z]".Single-component IANA names are time zones.
timeZoneLike, and soisValidTimeZoneand every zone argument, required a/in any name exceptUTCandGMT. It rejected 42 IANA names such asJapan,ZuluandEST5EDT, andformatUtcandformatUnixrendered those zones as UTC. The pattern now follows Temporal’sTimeZoneIdentifiergrammar and is case-insensitive: an IANA name, or a UTC offset such as+05:00, which this release also accepts as a zone. Any other name starting with+or-is rejected.import { formatUtc, isValidTimeZone } from "@northguild/gmt";isValidTimeZone("Japan"); // trueisValidTimeZone("utc"); // trueformatUtc("2024-07-15T16:00:00Z", "en-US", { timeZone: "Japan", hour: "numeric", minute: "2-digit" }); // "1:00 AM"Compatibility: to keep the slash rule, also require
timeZone.includes("/"), or"UTC"/"GMT".toOffsetInstantnow returns the zone in IANA casing on both paths. Earlier releases echoed the argument’s casing, so pass an IANA-cased id to get the same string back.isValidZonedRangechecks calendar annotations as the rest ofzoned/does. It accepted any[u-ca=…]annotation, which thezoned/functions behind it then refused. It now accepts[u-ca=iso8601]and returnsfalsefor any other calendar. Calendar ids and calendar-annotated strings themselves are described in this release’s RFC 9557 entry.import { isValidZonedRange } from "@northguild/gmt/zoned";isValidZonedRange({ value1: "2024-01-01T00:00:00+00:00[UTC][u-ca=hebrew]", value2: "2024-02-01T00:00:00+00:00[UTC]" }); // falseisValidZonedRange({ value1: "2024-01-01T00:00:00+00:00[UTC][u-ca=iso8601]", value2: "2024-02-01T00:00:00+00:00[UTC]" }); // trueCompatibility: to check a range of calendar-annotated zoned strings, validate each value with
isValidCalendarZonedDateTime.isLeapYearandgetWeekNumbervalidate before they parse. They read date-times, zoned strings and other shapes loosely as a date. They now take aPlainDateonly.import { getWeekNumber, isLeapYear } from "@northguild/gmt/plain";isLeapYear("2024-03-15T10:00"); // falsegetWeekNumber("2024-03-15T10:00"); // nullgetWeekNumber("2024-03-15T10:00".slice(0, 10)); // 11Compatibility: pass the date part alone, or use
Temporal.PlainDate.from(value).inLeapYearand.weekOfYear.Regexes.
year,plainDate,plainDateTime,sqlDateTimeandutcDateTimeaccepted the year-000000, which Temporal’s grammar forbids. They now reject it.import { year } from "@northguild/gmt/regex";year.test("-000000"); // false -
358e91e: Fix locale week data on Node 26.
Node 26 (V8 14) removed the
Intl.Locale#weekInfoaccessor in favour of the Intl Locale Info proposal’sgetWeekInfo()method. GMT read only the accessor, so on Node 26 every locale silently fell back to ISO defaults: weeks started on Monday, weekends were Saturday and Sunday, and week-year rules used ISO’s minimal days.The functions affected on Node 26 were
getLocaleStartOfWeek,getLocaleEndOfWeek,getLocaleDayOfWeek,getLocaleWeekYear,getWeeksInLocaleWeekYear,getWeekOfMonth,getWeeksInMonth,getLocaleWeekdayNames,isWeekend,isThisUnitand their zoned twins. For example,en-USweeks started on Monday instead of Sunday, andar-SAweekends were Saturday and Sunday instead of Friday and Saturday.GMT now calls
getWeekInfo()when the runtime has it and falls back toweekInfootherwise, so results are the same on Node 22, 24 and 26. -
727a3f4: Fix lengths, rounding and differences in months or years measured from the 29th, 30th or 31st (Story CORE-8).
Which functions.
intervalLengthDate,intervalLengthDateTime,intervalLengthUtc,intervalLengthZoned,intervalLengthUnix,formatRelativeDate,formatRelativeDateTime,normalizeDuration, and thediff*functions that carry a time component —diffDateTime,diffUtc,diffUnixanddiffZoned— given asmallestUnitof months or years.diffDateis not affected: two dates have no time component, so the bracket always closes on a date it already reaches.What was wrong. A month has no fixed length, so measuring one means bracketing the span between two dates a month apart. Temporal checks that the answer actually falls inside that bracket and moves it along when it does not.
@js-temporal/polyfill0.5.1 skips that check, so any measurement from the 29th, 30th or 31st — the days where adding a month has to clamp — could be taken against the wrong pair of dates.import { diffDateTime, intervalLengthDateTime, normalizeDuration } from "@northguild/gmt";diffDateTime("2024-01-31T00:00:00", "2024-02-29T12:00:00", ["months"], { smallestUnit: "months", roundingMode: "floor" });// { months: 1 } — was { months: 0 }, a whole month shortnormalizeDuration("P30DT12H", { smallestUnit: "month", roundingMode: "floor", relativeTo: "2024-01-30" });// "P1M" — was "PT0S"intervalLengthDateTime("2024-01-31T00:00:00", "2024-02-29T12:00:00", "month");// 1.0161290322580645 — was 1.0172413793103448Differences without a
smallestUnitwere always right, and so was every whole part: only a measurement that had to round, or report a fraction, was affected.Rounding exactly on a boundary. Separately,
ceiltreated a span that lands exactly on a whole month as needing another one —P60Dfrom2024-01-31rounded toP3Minstead ofP2M. A span that is already a whole number of months now stays as it is, in every calendar.How it is fixed. GMT already owns the TC39 algorithm, for the non-ISO calendars the polyfill also gets wrong; these operations now take that path. Every one of 24,916 scanned cases matches the Temporal built into Chrome 153 exactly. The workaround is behind a probe (compat defect
D11) and stops running by itself once a polyfill release carries the upstream fix — the answers do not change when it does. -
727a3f4: Stop routing ISO
PlainDatedifferences through the D11 nudge-window workaround (Story CORE-8).diffDateanddiffDateAsDurationwith asmallestUnitof months or years took GMT’s own spec path when the start day was the 29th or later. That path exists for a polyfill defect the operation cannot reach: the nudge window only misses its target when the target sits strictly between the window bounds by a sub-day amount, and twoPlainDates have no time component, so the bound always lands on a date the window already reaches. Measured over about 1.96 million rows against the raw polyfill, in both directions and across every rounding mode and increment, the two paths never disagreed.Answers are unchanged. What goes away is exposure: that path carries GMT’s own exact-boundary rounding behaviour, and routing ISO through it widened a defect’s reach for no corrected result. The workaround stays where the defect is real —
Duration#total,Duration#round, anduntil/sincewith a time component. -
358e91e: Correct the positional interval documentation’s cross-references and tiling notes.
intervalSplitAtDate,intervalSplitAtDateTimeandintervalSplitAtTimenamed adivideEquallyfunction that does not exist. They now nameintervalDivideEquallyDate,intervalDivideEquallyDateTimeandintervalDivideEquallyTime.intervalSplitAt*,splitIntervalByUnit*andintervalDivideEqually*say that each piece’sendis the next piece’sstart, so the pieces partition the interval under the half-open rule.
The boundary behaviour of every positional interval function is described in the half-open intervals entry of this release.
-
727a3f4: Return exact answers at Temporal’s range limits and for very large or very precise values (Story CORE-8).
Answers that exist at the edge of the range. Temporal represents dates from
-271821-04-19to+275760-09-13. Several functions built a boundary they did not need, such as the start of the next year or the 1st of a month before the first date, and returned their sentinel when that boundary fell outside the range. The affected functions wereroundDate,roundDateTime,bucketRange, thesplitIntervalByUnit*functions,mapDatesInRange,mapZonedDatesInRange,getWeekOfMonth,getWeeksInMonth,getWeeksInYear,getLocaleWeekYearandgetWeeksInLocaleWeekYear. TheintervalCount*functions also returnednullat the minimum. Each now builds a boundary only when the answer needs it, and returns the answer.import { bucketRange, getWeekOfMonth, intervalCountZoned, roundDate } from "@northguild/gmt";roundDate("+275760-06-15", { smallestUnit: "year", roundingMode: "floor" }); // "+275760-01-01"roundDate("+275760-06-15", { smallestUnit: "year", roundingMode: "ceil" }); // "" — +275761-01-01 is out of rangegetWeekOfMonth("-271821-04-30", "en-US"); // 5intervalCountZoned("-271821-04-20T00:00:00+00:00[UTC]", "-271821-04-20T01:00:00+00:00[UTC]", "week"); // 1bucketRange("+275760-09-12T23:00:00Z", "+275760-09-13T00:00:00Z", "day", "America/New_York"); // ["+275760-09-12T04:00:00Z"]Equal pieces are equal. The
intervalDivideEqually*functions computed boundaries in floating point, so pieces differed by nanoseconds and the last one could end up to 66 microseconds past the range. Boundaries are now exact integer division of the span in nanoseconds, rounded half up.import { intervalDivideEquallyUtc } from "@northguild/gmt/utc";intervalDivideEquallyUtc("2024-01-01T00:00:00Z", "2024-01-01T00:00:01Z", 3).map((piece) => piece.end);// ["2024-01-01T00:00:00.333333333Z", "2024-01-01T00:00:00.666666667Z", "2024-01-01T00:00:01Z"]formatDurationshows sub-second parts exactly. It rounded milliseconds, microseconds and nanoseconds to three digits of a second. A duration of one nanosecond printed as"0 seconds", and seconds past 2^53 printed a larger number than the input.import { formatDuration, parseDuration } from "@northguild/gmt/duration";formatDuration("PT0.000000001S", "en-US"); // "0.000000001 seconds"formatDuration("PT1.123456789S", "en-US"); // "1.123456789 seconds"Compatibility: round the duration to milliseconds first to keep three digits.
formatDuration(parseDuration("PT1.123456789S", { smallestUnit: "millisecond" }), "en-US"); // "1.123 seconds"Large month spans in non-ISO calendars no longer crash the process. The polyfill adds and counts non-ISO months one at a time and caches every step. A few million months, which is in range, ran the heap out of memory and aborted the process, and no
trycould catch it. GMT now computes spans of 1,200 months or more in whole years from Temporal’s own calendar data. This work-around is inactive for smaller spans, andpnpm compatreports when a polyfill release makes it unnecessary.import { addDate } from "@northguild/gmt/plain";addDate("2024-01-15[u-ca=persian]", { months: 3000000 }); // "+252023-12-27[u-ca=persian]"Smaller corrections.
fromFileTimeandtoFileTimetreat a value at or above 2^63 as out of range, as Windows’FileTimeToSystemTimedoes. They used to decode it as a date as far out as the year 60056. Compatibility:fromNanoseconds((value - 116444736000000000n) * 100n)decodes the raw unsigned value.businessDaysBetweenreturns0, not-0.intervalFromDurationTimereturnsnullfor a duration of 24 hours or more, or a negative duration that wraps past midnight, as its docs said. It used to return a span of the wrong length, such as a zero-length span for"PT24H".
import { fromFileTime, fromNanoseconds } from "@northguild/gmt/precision";import { intervalFromDurationTime } from "@northguild/gmt/plain";fromFileTime(9223372036854775808n); // ""fromNanoseconds((18446744073709551615n - 116444736000000000n) * 100n); // "+060056-05-28T05:36:10.9551615Z"intervalFromDurationTime("10:00:00", "PT24H", "start"); // null -
358e91e: Document the
year,monthanddaypatterns, and correct a wrongfractionalSecondexample.year,monthanddayhad no JSDoc, so editors showed nothing on hover. They now carry a description and examples like every other pattern in the regex namespace. Themillisecondalias gains examples too.The
fractionalSecondJSDoc saidfractionalSecond.test("0")returnsfalse. It returnstrue, since"0"is one digit. The example now shows a 10-digit input, which the pattern does reject. -
fc97a9d: Name the standard behind each roll convention, and correct three wrong JSDoc examples.
RollConvention,rollDateandisValidRollConventionsaidmodifiedFollowingwith the end-of-month rule was “the common convention for interest-rate instruments”, sourced to a vendor daycount page. That sourced a market habit, not the definition. The docs now cite the text that actually governs the conventions:following,modifiedFollowingandprecedingare ISDA 2006 Definitions §4.12(a)(i)–(iii),modifiedPreceding— which §4.12(a) does not define — is FpML’sBusinessDayConventionEnumMODPRECEDING, andnoneis what OpenGamma Strata callsNO_ADJUST. No TC39, ECMA or RFC standard governs any of them, and the camelCase spelling is GMT’s — the standard fixes the behaviour, not the identifier.endOfMonthis now labelled plainly as GMT’s own, because it is neither an ISDA convention nor the industry “EOM rule” a reader is likely to assume it is. That rule is a schedule rule — hold every date in a schedule to its month’s last day once the anchor is one — andendOfMonthis the per-date primitive you build it from, by testing the anchor for month-end yourself and applying it to the unadjusted target date.Three
@examplelines asserted results the functions do not return:// formatRelativeUtc: the old example had no `reference`, so its output moved with the clockformatRelativeUtc("2026-01-15T14:30:45Z", "en-US", { reference: "2026-04-15T14:30:45Z" }); // "3 months ago"// roundZoned: New York is -04:00 in June, not -05:00, and 12:34:56 rounds down to 12:30roundZoned("2024-06-15T12:34:56-04:00[America/New_York]", { smallestUnit: "minute", roundingIncrement: 15 }); // "2024-06-15T12:30:00-04:00[America/New_York]"The docs site runs every
@examplelive, so a wrong one is visible on the reference page as well as on hover. -
358e91e: Fix
halfEveninroundDateandroundDateTime, which rounded ties the wrong way.Both functions aliased
halfEventohalfExpandfor date units, so an exact tie rounded away from the unit start instead of towards the even multiple of the increment.roundDate("2024-06-16", { smallestUnit: "month", roundingMode: "halfEven" })returned"2024-07-01"; June 16 is 15 days into a 30-day month, an exact tie, so half-even rounds to"2024-06-01". The same applied toroundDateTimeon"year","month"and"week".The rounding grid is anchored at the unit containing the value: that unit’s start is multiple 0 and the next start is multiple 1, so the even multiple at a tie is the current start. Values above and below the tie are unaffected, and every other rounding mode is unchanged. Both JSDoc blocks now state the anchor. Time units in
roundDateTimewere already correct — they round through Temporal. -
727a3f4: Follow Temporal’s zoned arithmetic and difference algorithms across DST changes (Story CORE-8).
addZoned,subtractZonedandintervalFromDurationZonedkeep exact time exact. TC39 Temporal §6.5.5 AddZonedDateTime adds a duration’s date part on the wall clock and its time part in exact time. With adisambiguationother than"compatible", these functions re-resolved the final wall-clock time. Adding 10 minutes in a repeated hour could then land 50 minutes earlier.disambiguationnow applies only to the wall-clock time the date part lands on: when a fall-back repeats that time, and when a spring-forward skips it. A date step into a skipped hour used to move forward whateverdisambiguationsaid. A time-only duration ignores it.import { addZoned, setZoned } from "@northguild/gmt/zoned";addZoned("2024-11-03T01:30:00-05:00[America/New_York]", { minutes: 10 }, { disambiguation: "earlier" });// "2024-11-03T01:40:00-05:00[America/New_York]"addZoned("2024-03-09T02:30:00-05:00[America/New_York]", { days: 1 }, { disambiguation: "earlier" });// "2024-03-10T01:30:00-05:00[America/New_York]"addZoned("2024-03-09T02:30:00-05:00[America/New_York]", { days: 1 }, { disambiguation: "reject" }); // ""Compatibility: to get the earlier value, re-resolve the result’s wall-clock time with
setZoned.setZoned(addZoned("2024-11-03T01:30:00-05:00[America/New_York]", { minutes: 10 }), { hour: 1, minute: 40, second: 0 }, { disambiguation: "earlier", offset: "ignore" });// "2024-11-03T01:40:00-04:00[America/New_York]"diffZoned,diffZonedAsDurationandintervalLengthZonedcount calendar units on the wall clock. They converted both values to UTC first, so a 23-hour local day was 0 days. §6.5.6 DifferenceZonedDateTime measures days, weeks, months and years on the wall clock of the shared time zone. For values in two different zones, a calendar unit has no single wall clock to count on, and Temporal throws. These functions now return their sentinel instead. Hours and smaller units are exact time, as before, and work across zones.import { diffZoned, diffZonedAsDuration } from "@northguild/gmt/zoned";diffZoned("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]", "days"); // 1diffZonedAsDuration("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-11T12:00:00-04:00[America/New_York]", "days"); // "P2D"diffZoned("2024-01-01T00:00:00-05:00[America/New_York]", "2024-01-03T00:00:00+01:00[Europe/Paris]", "days"); // nullCompatibility: difference the UTC instants to get the UTC-clock value. For
intervalLengthZonedacross two zones, convert both ends to one zone first withconvertZonedToZoned.diffUtc(convertZonedToUtc("2024-03-09T12:00:00-05:00[America/New_York]"), convertZonedToUtc("2024-03-10T12:00:00-04:00[America/New_York]"), "days"); // 0diffUtcAsDuration(convertZonedToUtc("2024-03-09T12:00:00-05:00[America/New_York]"), convertZonedToUtc("2024-03-11T12:00:00-04:00[America/New_York]"), "days"); // "P1DT23H"intervalOverlappingDaysZonedandintervalOverlappingDaysUnixcount the local dates an overlap touches. They took the calendar difference of the overlap’s two endpoint dates and added one. A day a zone deleted was counted, like Samoa’s 30 December 2011, and a fall-back that sent the clock back into the previous date could give 0. They now count the distinct local dates the overlap touches.import { intervalOverlappingDaysUnix } from "@northguild/gmt/unix";intervalOverlappingDaysUnix(1289098830000, 1289100600000, 1289098830000, 1289100600000, { timeZone: "America/Goose_Bay" }); // 2Compatibility: for the earlier number, take the difference of the endpoint dates in the first interval’s zone and add one.
diffDate(convertUnixToPlainDate(1289098830000, { timeZone: "America/Goose_Bay" }), convertUnixToPlainDate(1289100600000, { timeZone: "America/Goose_Bay" }), "days") + 1; // 0
© 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.