Changelog 1.18
Release notes of @northguild/gmt 1.18.0, newest first, built from packages/gmt/CHANGELOG.md. Back to Changelog.
@northguild/gmt
Section titled “@northguild/gmt”1.18.0
Section titled “1.18.0”Released 2026-10-03
Minor Changes
Section titled “Minor Changes”-
5a79155:
isInDaylightSavingandhasDaylightSavingnow read daylight time from a zone’s own clock changes, andhasDaylightSavingtakes a reference instant inoptions.at(Story CORE-77).getDstTransitions,startOfZonedandgetHoursInZonedDaynow find two clock changes that fall less than 14 days apart.Before, both functions compared a zone’s 15 January and 15 July offsets, and
hasDaylightSavingdid so for the year 2024 only. A zone that moved its standard time during a year then read as being in daylight time afterwards:Europe/Istanbulhas stayed at+03:00since 2016, and December 2016 read as daylight time.import { getDstTransitions, hasDaylightSaving, isInDaylightSaving } from "@northguild/gmt";isInDaylightSaving("2015-07-01T12:00:00+03:00[Europe/Istanbul]"); // true — the clocks went back on 2015-11-08isInDaylightSaving("2016-12-01T12:00:00+03:00[Europe/Istanbul]"); // false — was trueisInDaylightSaving("2019-07-15T12:00:00+01:00[Europe/Dublin]"); // trueisInDaylightSaving("2024-01-15T12:00:00+11:00[Australia/Sydney]"); // true — southern summerhasDaylightSaving("Australia/Sydney", { at: "2024-06-15T12:00:00Z" }); // true — winter; the next period begins in OctoberhasDaylightSaving("Europe/Istanbul", { at: "2015-06-15T12:00:00Z" }); // truehasDaylightSaving("Europe/Istanbul", { at: "2016-06-15T12:00:00Z" }); // falsehasDaylightSaving("America/Sao_Paulo", { at: "2018-06-15T12:00:00Z" }); // truehasDaylightSaving("America/Sao_Paulo", { at: "2019-06-15T12:00:00Z" }); // false — the last period ended 2019-02-17getDstTransitions("America/Boa_Vista", 2000).length; // 3 — was 1- The rule is GMT’s own definition, not the tz database’s daylight flag. No JavaScript API exposes that flag, and it cannot be worked out from offsets. GMT holds no zone data: it reads the zone’s offset changes from the runtime.
- The rule. Daylight time runs from a forward change of a zone’s clocks to the backward change that undoes it. A backward change undoes the most recent forward change of the same size not yet undone, if it comes less than 365 days after it. An instant is in daylight time when it is at or after such a forward change and before its backward change.
- A forward change never undone, or undone 365 days or more later, is a change of standard time.
Europe/Istanbulis on standard time from its last advance in March 2016. - The higher of two alternating offsets is the daylight one, as in the tz database’s rearguard form.
Europe/Dublinis in daylight time in summer, andAfrica/Casablancain its months at+01:00. The database’s main form names Dublin’s winter and Casablanca’s Ramadan weeks as daylight time. - Read as standard time, because the offsets do not show otherwise:
- the last summer before a zone kept its daylight offset for good. The tz database dates Istanbul’s switch 2016-09-07, with no clock change, so GMT reads March to September 2016 as standard time;
- a daylight period held 365 days or longer (
America/Santiago, 2014 to 2016); - a daylight period that began, ended or was interrupted by a move of standard time, so the clocks went back by another amount or not at all (
America/Kentucky/Monticello2000,Asia/Tomsk2002,Asia/Jerusalem1948); - a daylight period whose end is past the last instant Temporal can represent.
- Read as daylight time: a move of standard time reversed by the same amount less than 365 days later (
America/Metlakatla, 2018 to 2019). hasDaylightSaving(timeZone, { at })answers for a reference instant. It istruewhen the zone is in daylight time atat, or a daylight period begins less than 365 days after it. So a zone in its winter istrue, and a zone that has stopped changing its clocks isfalse.atis an ISO 8601 instant string:Z, an offset, or a zoned string. A bracketed zone onatdoes not choose the zone that is judged;timeZonedoes.- Pass
atfor an answer that does not depend on the day the code runs. Without it the reference is the current instant. An invalidat, such as the date"2024-01-15", returnsfalse. - The answer can change when the runtime’s time zone data does. An answer for a past instant changes when that data learns that a zone stopped changing its clocks.
- Calls cost more. On Node 24,
isInDaylightSavingtakes 0.2 to 0.6 ms a call where 1.17 took 0.05 ms, andhasDaylightSaving0.4 to 1.1 ms where 1.17 took 0.03 ms. Each call searches the zone’s clock changes, up to 365 days either side, and GMT keeps no cache. Cache the result yourself if you call either in a loop. - A function that walks a zone’s clock changes costs two to three times more per change crossed. GMT’s search reads the zone every 5 days where the polyfill read it every 14. On Node 24,
getDstTransitions("America/New_York", 2024)takes 0.9 ms where 1.17 took 0.4 ms, andintervalCountZonedby day over 30 years ofAmerica/New_Yorktakes 24 ms where 1.17 took 8 ms. A span that crosses no clock change, or one or two, costs what it did. - Two clock changes less than 14 days apart are now found.
America/Boa_Vista,America/NoronhaandAmerica/Recifewent forward on 8 October 2000 and back on 15 October. The Temporal polyfill GMT runs on steps through a zone 14 days at a time and missed both changes.getDstTransitionsnow lists them, and a day beside them has the right start and length.
Breaking changes
Section titled “Breaking changes”isInDaylightSaving:Call 1.17 1.18 isInDaylightSaving("2016-12-01T 12:00:00+03:00 [Europe/ Istanbul]") truefalseisInDaylightSaving("2016-07-01T 12:00:00+03:00 [Europe/ Istanbul]") truefalseisInDaylightSaving("2011-07-01T 12:00:00+04:00 [Europe/ Moscow]") truefalseisInDaylightSaving("2018-12-01T 12:00:00+09:00 [Asia/ Pyongyang]") truefalseisInDaylightSaving("2016-07-01T 12:00:00-04:00 [America/ Caracas]") truefalseisInDaylightSaving("1996-07-01T 12:00:00+06:30 [Asia/ Colombo]") truefalseisInDaylightSaving("2019-12-01T 12:00:00+01:00 [Africa/ Casablanca]") falsetrueisInDaylightSaving("+275760-09-12T 20:00:00-04:00 [America/ New_York]") truefalsehasDaylightSaving. 1.17 took no options and compared January with July 2024:1.17 call 1.17 1.18 call 1.18 hasDaylightSaving("Africa/ Casablanca") falsehasDaylightSaving("Africa/ Casablanca", { at: "2024-06-15T 12:00:00Z" }) truehasDaylightSaving("America/ Sao_Paulo") falsehasDaylightSaving("America/ Sao_Paulo", { at: "2018-06-15T 12:00:00Z" }) truehasDaylightSaving("America/ Asuncion") truehasDaylightSaving("America/ Asuncion", { at: "2026-06-15T 12:00:00Z" }) falseTwo clock changes less than 14 days apart:
Call 1.17 1.18 getDstTransitions("America/ Boa_Vista", 2000) one change, 2000-02-27T03:00:00Z three: that one, 2000-10-08Tand04:00:00Z 2000-10-15T03:00:00Z startOfZoned("2000-10-08T 01:00:00-03:00 [America/ Boa_Vista]", "day") "2000-10-07T23:00:00-04:00 [America/ Boa_Vista]" "2000-10-08T01:00:00-03:00 [America/ Boa_Vista]" getHoursInZonedDay("2000-10-08T 12:00:00-03:00 [America/ Boa_Vista]") null23getHoursInZonedDay("2000-10-08T 12:00:00-01:00 [America/ Noronha]") -888123Unchanged: a zone that changes its clocks twice a year reads as before, in both hemispheres. So does a zone that has never changed its clocks, a fixed offset and
UTC.Migration:
hasDaylightSaving(timeZone)now answers for the current instant, not for 2024. Pass{ at }wherever the result is stored, compared or tested. To ask about 2024, pass an instant in 2024.- A stored
isInDaylightSavingresult for a zone that moved its standard time can be wrong under the new rule. Recompute it. - For where a zone’s offset changes, use
getDstTransitions(timeZone, year). It lists every change and classifies none of them. For the offset itself, usegetZonedOffset.
-
96d3372: Add
cutoffAt,cutoffSchedule,isPastCutoffandtimeToCutoffto thetransport/namespace, and the@northguild/gmt/transport/comparesubpath (Story TRAN-10).A logistics deadline is not a fixed timestamp. It counts back from an event — a vessel’s departure, a container’s loading, an arrival — in the local time of the place that enforces it, and it moves when that event moves. An ocean booking carries a stack of them: documentation, VGM, gate-in, customs.
import { cutoffAt, cutoffSchedule, isPastCutoff, timeToCutoff } from "@northguild/gmt";// A vessel sails Friday 14 June 2024 at 18:00 in Amsterdam. "Two days before, 17:00":cutoffAt("2024-06-14T16:00:00Z", "P2D", { timeZone: "Europe/Amsterdam", atLocalTime: "17:00" });// "2024-06-12T17:00:00+02:00[Europe/Amsterdam]" — not 48 hours, which keeps 18:00cutoffSchedule("2024-06-14T16:00:00Z", [{ name: "gate-in", offset: "P1D" },{ name: "document", offset: "P2D", atLocalTime: "17:00" },{ name: "VGM", offset: "P1D", atLocalTime: "10:00" },], { timeZone: "Europe/Amsterdam" });// [ { name: "document", at: "2024-06-12T17:00:00+02:00[Europe/Amsterdam]" },// { name: "VGM", at: "2024-06-13T10:00:00+02:00[Europe/Amsterdam]" },// { name: "gate-in", at: "2024-06-13T18:00:00+02:00[Europe/Amsterdam]" } ]// 96 hours before an arrival is exact elapsed time, across New York's fall-back.cutoffAt("2024-11-05T17:00:00Z", "PT96H", { timeZone: "America/New_York" });// "2024-11-01T13:00:00-04:00[America/New_York]"isPastCutoff("2024-06-12T16:00:00Z", "2024-06-12T17:00:00+02:00[Europe/Amsterdam]"); // truetimeToCutoff("2024-06-12T16:00:00Z", "2024-06-12T17:00:00+02:00[Europe/Amsterdam]"); // "-PT1H"atLocalTimepins the time of day. With it, the offset’s exact part (hours and smaller) comes off the anchor’s instant, its calendar part (years, months, weeks, days) off that local date, and the cut-off isatLocalTimeon the day it lands on. The exact part comes off first, so it can change the day. Without it, the offset is taken off as Temporal’sZonedDateTime#subtracttakes it:P2Dkeeps the anchor’s wall clock andPT96His 96 elapsed hours.- The anchor is the caller’s event. Loading, departure and arrival are different instants, and
cutoffAtnever guesses which one a rule means. The anchor is exact — an instant or a zoned string, whose bracket never supplies the zone — andtimeZone, an IANA identifier or a fixed offset, is the local frame. The functions are pure: a rescheduled departure is a new call. - Closures roll the way the caller says. With a
BusinessCalendar, a cut-off on a weekend or holiday moves byroll, asrollDatemoves it. Every industry answers this differently and no standard picks one, so there is no default:calendarwithoutroll, orrollwithoutcalendar, returns"". The rolled day keeps the cut-off’s local time of day, andcalendar.timeZoneis not read.cutoffAtdoes not check that the cut-off comes before the anchor. - A skipped hour is refused. Every local wall time a cut-off lands on takes the first pass of a repeated hour, as RFC 5545 §3.3.5 reads it, and returns
""for an hour the clock skipped or a day the zone deleted, rather than shifting the deadline. cutoffScheduleis all or nothing. It sorts the stack by instant, keeps the given order for ties, and returns[]if any entry fails.- The window closes at the cut-off.
isPastCutoffistruefrom the cut-off instant on.timeToCutoffis exact hours,PT0Sat the cut-off and negative after it. Both return their sentinel forcutoffAt’s"". - Also exported: the
CutoffOptions,Cutoff,CutoffTimeandCutoffScheduleOptionstypes.
-
5a79155: Add
scheduleDeviation,classifyPunctuality,punctualityRate,bestAvailable,estimateDriftandnextDepartureto thetransport/namespace (Story TRAN-57). Every function that reads a moment now reads a zoned string for a zone with a sub-minute offset as the instant Temporal wrote it for, and an offset written with seconds must match its zone exactly.Every mode publishes a plan and records what happened, and measures the gap the same way. Only the tolerance differs, and the tolerance is the caller’s. The other shared problem is that one field often holds four kinds of time — planned, estimated, requested and actual — and an estimate shown as an actual is the standard tracking-dashboard error.
import { bestAvailable, classifyPunctuality, estimateDrift, nextDeparture, punctualityRate, scheduleDeviation } from "@northguild/gmt";scheduleDeviation("2024-06-15T10:00:00Z", "2024-06-15T10:14:00Z"); // "PT14M"scheduleDeviation("2024-06-15T10:00:00Z", "2024-06-15T09:55:00Z"); // "-PT5M" — five minutes earlyscheduleDeviation("2024-11-03T01:30:00-04:00[America/New_York]", "2024-11-03T01:30:00-05:00[America/New_York]");// "PT1H" — the same wall time, an hour later across the fall-back nightclassifyPunctuality("2024-06-15T10:00:00Z", "2024-06-15T10:14:59Z", { late: "PT15M" }); // "onTime"classifyPunctuality("2024-06-15T10:00:00Z", "2024-06-15T10:15:00Z", { late: "PT15M" }); // "late"classifyPunctuality("2024-06-15T10:00:00Z", "2024-06-15T09:49:00Z", { late: "PT15M", early: "PT10M" }); // "early"punctualityRate([{ planned: "2024-06-15T10:00:00Z", actual: "2024-06-15T10:05:00Z" },{ planned: "2024-06-15T10:00:00Z", actual: "2024-06-15T10:14:00Z" },{ planned: "2024-06-15T10:00:00Z", actual: "2024-06-15T10:16:00Z" },{ planned: "2024-06-15T10:00:00Z", actual: "2024-06-15T09:57:00Z" },], { late: "PT15M" });// { onTime: 3, total: 4, rate: 0.75 }bestAvailable([{ classifier: "ACT", at: "2024-06-15T12:52:00Z", recordedAt: "2024-06-15T12:53:00Z" },{ classifier: "EST", at: "2024-06-15T13:05:00Z", recordedAt: "2024-06-15T14:00:00Z" },]);// { at: "2024-06-15T12:52:00Z", classifier: "ACT" } — an estimate recorded later never replaces an actualestimateDrift([{ classifier: "EST", at: "2024-06-20T08:00:00Z", recordedAt: "2024-06-01T00:00:00Z" },{ classifier: "EST", at: "2024-06-20T12:00:00Z", recordedAt: "2024-06-05T00:00:00Z" },{ classifier: "EST", at: "2024-06-20T17:00:00Z", recordedAt: "2024-06-10T00:00:00Z" },], { tolerance: "PT8H" });// { first: "2024-06-20T08:00:00Z", last: "2024-06-20T17:00:00Z", drift: "PT9H", revisions: 3, exceedsTolerance: true }const timetable = ["2024-06-15T08:00:00Z", "2024-06-15T09:30:00Z", "2024-06-15T11:00:00Z"];nextDeparture("2024-06-15T09:00:00Z", timetable, { minimumConnection: "PT45M" }); // "2024-06-15T11:00:00Z"nextDeparture("2024-06-15T06:05:00+02:00", { headway: "PT20M", from: "2024-06-15T06:00:00+02:00", to: "2024-06-15T09:00:00+02:00" });// "2024-06-15T06:20:00+02:00"- A deviation is exact elapsed time.
scheduleDeviationreturnsactualminusplannedwith hours as the largest unit: positive when late, negative when early,PT48Hrather thanP2D. A delay across a fall-back night isPT1H, never thePT0SorPT2Ha wall-clock subtraction gives. Both times are an instant or a zoned string, and the zone they are written in does not matter. - “On time” needs a stated tolerance. GMT has no default.
PunctualityToleranceis{ late, early? }as ISO 8601 durations of exact time: a day is 24 hours, and years, months, weeks or a negative value returnnull. A 15-minute tolerance, a 60/120-minute pair and a day-based one are all the same call with different numbers. - Both edges belong to the outside. Exactly
lateis late, and exactly-earlyis early. Withoutearly, every early arrival is on time.classifyPunctualityreturnsnullon invalid input, asclassifyLocaldoes. - A rate is a count under one tolerance.
punctualityRatereads the tolerance once and judges every pair under it. Only"onTime"counts, so with anearlytolerance an early arrival is not on time.rateis not rounded. An empty list, or any invalid pair, returnsnull— never a rate over the rest. - The class travels with the value.
TimestampEventrecords aclassifier(PLN,EST,REQorACT, DCSA’s vocabulary), the momentatand when it wasrecordedAt.bestAvailablepicks anACTwhenever one exists, elsePLN, elseREQ, elseEST, and the newest-recorded within that class. The order is GMT’s and is fixed: DCSA’s Port Call standard defines the classes and an estimated, requested, planned, then actual pattern, not a rule for choosing among them. It returns the class with the value, and echoesatexactly as written. - Drift needs two estimates.
estimateDriftreads only theESTrecords, in recording order, and reports the last minus the first. It returnsnullwith fewer than two, since one estimate has no drift. Withtolerance,exceedsToleranceistruewhen the drift in either direction is greater than it; exactly the tolerance isfalse. nextDepartureis timetable lookup, not routing. It returns the first departure at or afterafterplusminimumConnection(default"PT0S"); one exactly at that threshold is made. A list entry is returned exactly as written, so it can go straight intoscheduleDeliveryas a leg’sdeparture. Every moment must carry its offset: a wall time without one returns"", because in a repeated fall-back hour it names two departures.- A headway window is half-open.
{ headway, from, to }has the shape of a GTFSfrequencies.txtrow. Departures arefromplus whole headways in exact time, up to but never atto, and are computed fromfromrather than stepped. The result is written the wayfromwas written. - Also exported: the
TimestampClass,TimestampEvent,PunctualityTolerance,Punctuality,PlannedActual,OnTimeRate,ClassifiedTimestamp,EstimateDriftOptions,DriftReport,HeadwayandNextDepartureOptionstypes.
A zoned string names one instant in every reader
Section titled “A zoned string names one instant in every reader”Temporal.ZonedDateTime.prototype.toStringwrites a zone’s offset rounded to the minute.Africa/Monroviastood at −00:44:30 until 1972, so Temporal writes it-00:45.Temporal.ZonedDateTime.fromreads that string back to the same instant (TC39ToTemporalZonedDateTimematches a minute-precision offset by minutes), butTemporal.Instant.fromtakes-00:45literally and lands 30 seconds late. GMT writes zoned strings and reads them back as instants, so a deviation, a span or a cut-off measured from one of its own strings was up to 30 seconds off in such a zone. Every instant reader now follows the zoned reading.import { etaAtZone, isValidZonedDateTime, scheduleDeviation, toNanoseconds } from "@northguild/gmt";const written = etaAtZone("1960-01-01T01:04:30Z", "Africa/Monrovia");// "1960-01-01T00:20:00-00:45[Africa/Monrovia]" — Temporal rounds -00:44:30 to the minutescheduleDeviation("1960-01-01T01:04:30Z", written); // "PT0S" — was "PT30S"toNanoseconds(written); // -315615330000000000n, which is 01:04:30ZtoNanoseconds("1960-01-01T00:20:00-00:45"); // -315615300000000000n — no zone, so the offset is exactisValidZonedDateTime("1960-01-01T00:20:00-00:45[Africa/Monrovia]"); // true — the rounded offsetisValidZonedDateTime("1960-01-01T00:20:00-00:44:30[Africa/Monrovia]"); // true — the exact offsetisValidZonedDateTime("1960-01-01T00:20:00-00:45:00[Africa/Monrovia]"); // false — seconds must be exact- The rule. When a string has a bracketed zone and an offset written to the minute, and that offset is the zone’s real offset at that wall time rounded to the minute, the instant is the one the zone gives. Every other string keeps its written offset: one without a bracket, a
Zinstant, an offset written with seconds, and a bracket whose zone does not exist or does not fit the offset. - Only zones with a sub-minute offset are affected. These are historical offsets: local mean time, and zones such as
Africa/Monroviabefore 1972. A string in a zone whose offset is a whole number of minutes reads exactly as before. - An instant reader still does not validate the bracket.
toNanoseconds("2024-06-15T10:00:00Z[Not/AZone]")is still the instant theZnames. A bracket never supplies the zone a result is rendered in:timeZoneandtargetZonedo. - Every string Temporal writes for an instant in range is now valid. At the first seconds of the range, the rounded offset alone can read as just outside it:
-271821-04-19T23:58:45-00:01[Europe/London]is the first instant, at London’s local mean time of −00:01:15. - An offset written with seconds must be the zone’s offset exactly, as TC39
ToTemporalZonedDateTimerequires. The Temporal polyfill GMT runs on matched it by minutes, so-00:45:00[Africa/Monrovia]was accepted as a zoned string. GMT now corrects that in every function that reads a zoned string. - A wall time repeated inside a sub-minute offset change reads as its first pass, as it does in
Temporal.ZonedDateTime.from.Pacific/Niuemoved from −11:19:40 to −11:20:00 at the end of 15 October 1952, so 23:59:40 to 23:59:59 happened twice, and both passes are written-11:20. Write the offset with seconds (-11:20:00) to name the second pass. - A zoned read still refuses a local date of −271821-04-19, as
Temporal.ZonedDateTime.fromdoes. A zone west of Greenwich shows that date for the first hours of the instant range.isValidInstantand the other instant readers accept such a string;transitTime,toOffsetInstant,isValidZonedDateTimeand thezoned/functions return their sentinel. Pass that instant inZform.
Breaking changes
Section titled “Breaking changes”Mis1960-01-01T00:20:00-00:45[Africa/Monrovia], a string Temporal writes for1960-01-01T01:04:30Z.Sis the same wall time with the offset written-00:45:00.Call 1.17 1.18 toNanoseconds(, likewiseM) toFileTime,toDotNetTicks,toNtpTimestamp,toExcelSerial,toPgMicroseconds-315615300000000000n(01:05:00Z)-315615330000000000n(01:04:30Z)spanNs(, likewise"1960-01-01T 01:04:30Z", M) spanMs30000000000n0nisValidInterval(, likewise every{ start: "1960-01-01T 01:04:45Z", end: M }) interval/function:mergeIntervals,intersectIntervals,subtractIntervals,splitIntervalAt,sumIntervals,intervalContains,intervalsOverlaptrue(endread as01:05:00Z)false(endis01:04:30Z, beforestart)etaAtZone(, likewiseM, "UTC") dwellTime,floorToZone,bucketRangeandgetTimeZoneOffset, which read the same instant"1960-01-01T01:05:00+00:00 [UTC]" "1960-01-01T01:04:30+00:00 [UTC]" freeTimeExpiry(, likewise"1960-01-01T 23:15:15-00:45 [Africa/ Monrovia]", 1, { basis: "calendar", timeZone: "UTC", firstDay: "eventDay" }) chargeableDaysanddemurrageClock, which read their events the same wayfreeTimeStart: "1960-01-02"freeTimeStart: "1960-01-01"isValidInstant(, likewise"-271821-04-19T 23:58:45-00:01 [Europe/ London]") isValidSpanfalsetrueisValidZonedDateTime(S) truefalsetransitTime(, likewiseS, "PT1H") toOffsetInstant,dwellTimewithouttargetZone, and everyzoned/function"1960-01-01T01:20:00-00:45 [Africa/ Monrovia]" ""(each function’s own sentinel)durationAs(, likewise"P1D", "hours", { relativeTo: S }) normalizeDurationandcompareDurations24nullconvertZonedToUtc("1952-10-15T 23:59:59-11:20:00 [Pacific/ Niue]") "1952-10-16T(the first pass)11:19:39Z" "1952-10-16T(the second pass, which11:19:59Z" -11:20:00names)Unchanged: a string without a bracket, a
Zinstant, and any string in a zone whose offset is a whole number of minutes.toOffsetInstant(M),transitTime(M, …)and thezoned/functions already readMthrough its zone.Migration:
- A stored instant computed from a zoned string in a sub-minute-offset zone moves by up to 30 seconds, to the instant Temporal wrote the string for. Recompute it. To keep the old reading, drop the bracket:
toNanoseconds("1960-01-01T00:20:00-00:45")reads the offset as written. - A zoned string whose offset has seconds that are not the zone’s is now invalid. Write the zone’s exact offset (
-00:44:30[Africa/Monrovia]) or the minute-rounded one Temporal writes (-00:45[Africa/Monrovia]).
- A deviation is exact elapsed time.
-
9067590: Read two adjacent single quotes in a parse pattern as one literal quote, wherever they appear.
parseDateWithPattern,parseTimeWithPatternandparseDateTimeWithPatternfollow the Unicode UTS #35 date format pattern rules for literal text. UTS #35 gives''one meaning, a literal', inside and outside quoted text. These functions applied it only inside quoted text such as'o''clock', and read''anywhere else as nothing at all. A pattern such as"MMM d, ''yy"now reads"Mar 15, '24".Breaking changes
Section titled “Breaking changes”A pattern with
''outside quoted text now needs a'in the value at that position.Call 1.17 1.18 parseDateWithPattern("2024'01'15", "yyyy''MM''dd") """2024-01-15"parseDateWithPattern("20240115", "yyyy''MM''dd") "2024-01-15"""parseTimeWithPattern("14'30", "HH''mm") """14:30:00"parseTimeWithPattern("1430", "HH''mm") "14:30:00"""parseDateTimeWithPattern("2024-01-15'14:30:00", "yyyy-MM-dd''HH:mm:ss") """2024-01-15T14:30:00" parseDateTimeWithPattern("2024-01-1514:30:00", "yyyy-MM-dd''HH:mm:ss") "2024-01-15T14:30:00" ""parseDateWithPattern("''2024-01-15", "''''yyyy-MM-dd") """2024-01-15"parseDateWithPattern("'2024-01-15", "''''yyyy-MM-dd") "2024-01-15"""Four quotes in a row are two literal quotes, not one. Quoted text is unchanged:
'at'still readsat,'o''clock'still readso'clock, and a quote that never closes still makes the pattern malformed.To keep fields adjacent with nothing between them, remove the
''from the pattern:"yyyyMMdd"reads"20240115". -
9067590: Accept
timeZone: "local"for the system time zone in theutcreaders and converters, as theutcformatters and everyunixfunction already do.Before,
"local"returned the empty result (""ornull) from these functions, whileformatUtc,formatCalendarUtc,formatRelativeUtcand the matchingunixfunctions read it as the system zone. Everyutcfunction that takes atimeZoneoption now reads it the same way: omitted is UTC,"local"is the system time zone, and an IANA name or a UTC offset is that zone.This applies to
parseDateFromUtc,parseTimeFromUtc,parseYearFromUtc,parseMonthFromUtc,parseWeekFromUtc,parseDayFromUtc,parseDayOfWeekFromUtc,parseHourFromUtc,parseMinuteFromUtc,parseSecondFromUtc,parseMillisecondFromUtc,parseMicrosecondFromUtc,parseNanosecondFromUtc,parseUnitFromUtc,convertUtcToPlainDate,convertUtcToPlainTimeandconvertUtcToPlainDateTime.import { convertUtcToPlainDate, parseHourFromUtc } from "@northguild/gmt";// On a machine whose time zone is Asia/Tokyo (UTC+9)parseHourFromUtc("2024-01-30T20:30:45Z"); // "20", unchanged: an omitted zone is UTCparseHourFromUtc("2024-01-30T20:30:45Z", { timeZone: "Asia/Tokyo" }); // "05", unchangedparseHourFromUtc("2024-01-30T20:30:45Z", { timeZone: "local" }); // "05" — was ""convertUtcToPlainDate("2024-01-30T20:30:45Z", { timeZone: "local" }); // "2024-01-31" — was ""Unchanged: an omitted
timeZonestill reads UTC, never the system zone, and an unknown zone still returns the empty result.convertUtcToZonedtakes its zone as a required argument and still accepts only an IANA name or a UTC offset, asconvertUnixToZoneddoes. -
2c069f5: Add operating hours to
calendar/:recurringWindows,operatingIntervals,isOpenAt,nextOpenAt,nextCloseAt,operatingTimeBetweenandaddOperatingTime(Story CORE-55).A business day answers “is Thursday a working day”. A terminal gate, a support desk, a customs office or a night curfew asks more: is it open now, how many open hours have passed, and when does an SLA measured in open hours fall due. One
OperatingScheduleanswers all of them: a zone, windows of local wall time for each ISO weekday, holiday dates, and dated overrides.import { addOperatingTime, nextOpenAt, operatingIntervals, operatingTimeBetween, recurringWindows } from "@northguild/gmt";const nineToFive = [{ from: "09:00", to: "17:00" }];const desk = {timeZone: "America/New_York",weekly: { 1: nineToFive, 2: nineToFive, 3: nineToFive, 4: nineToFive, 5: nineToFive },holidays: ["2024-07-04"],overrides: [{ date: "2024-07-05", windows: [{ from: "10:00", to: "12:00" }] }],};operatingIntervals(desk, { start: "2024-07-04T04:00:00Z", end: "2024-07-06T04:00:00Z" });// [{ start: "2024-07-05T14:00:00Z", end: "2024-07-05T16:00:00Z" }] — holiday closed, Friday overriddennextOpenAt("2024-06-15T16:00:00Z", desk); // "2024-06-17T13:00:00Z" — Saturday noon to Monday 09:00 localoperatingTimeBetween("2024-06-14T20:00:00Z", "2024-06-17T14:00:00Z", desk); // "PT2H"addOperatingTime("2024-06-14T20:00:00Z", "PT8H", desk); // "2024-06-17T20:00:00Z" — Monday 16:00 localaddOperatingTime("2024-06-14T20:00:00Z", "PT8H", desk, { within: "P1D" }); // ""recurringWindows({ 6: [{ from: "23:00", to: "06:00" }] },{ start: "2024-11-02T00:00:00Z", end: "2024-11-04T00:00:00Z" },"America/New_York",);// [{ start: "2024-11-03T03:00:00Z", end: "2024-11-03T11:00:00Z" }] — 8 hours across the fall-back night- Windows are half-open local wall time. A
toat or before itsfromwraps past midnight (23:00–06:00is a night,00:00–00:00a whole day). A window belongs to the date it starts on, so a Friday holiday or override removes or replaces a Friday-night window and a Saturday one does not. Windows that overlap or touch are merged. - Every window edge goes through
resolveLocal.disambiguationdefaults to"compatible": an edge in a repeated fall-back hour takes the earlier instant, and one in a skipped spring-forward hour moves forward by the gap."earlier"and"later"pick the other instant."reject"returns the sentinel when a window with an ambiguous or nonexistent edge could change the answer, and ignores one that cannot. Every function takes the option. - Dates are the zone’s real local dates. Holidays and overrides are ISO dates in the schedule’s zone. A
BusinessCalendarcan be passed asholidays; itsholidaysare read and itsweekendis not. An override wins over a holiday, andwindows: []closes a date. A date the zone deleted has no windows, and a date the clock re-enters after a fall-back is walked once. - Open time is exact elapsed time.
operatingTimeBetweensums the open intervals inside[start, end)with hours as the largest unit, the same numbersumIntervalsgives for their intersections with the range.addOperatingTimeis its inverse: the earliest instant at which that much open time has passed. Its duration is hours and smaller; a duration with days, weeks, months or years returns"", becauseP1Dof open time could mean 24 open hours or one working day. - Searches have a stated horizon.
nextOpenAt,nextCloseAtandaddOperatingTimesearch up towithinafter the input (default"P1Y", added in the schedule’s zone). An answer exactly at the horizon counts; past it they return"".nextOpenAtreturns the input when it is already open, andnextCloseAtreturns the input when it is already closed. - Walks are bounded. A range spanning more than 10,000 local dates (about 27 years) from its start’s date, or a search that would go that far past its input, returns the sentinel, never a truncated answer. A search answers as soon as its answer is certain, and a horizon past Temporal’s last instant stops there.
- Also exported: the
OperatingSchedule,LocalWindow,OperatingOverrideandIsoWeekdaytypes under/types. The subpath@northguild/gmt/calendar/hoursjoins the package exports.
- Windows are half-open local wall time. A
-
9067590: Read each option once per call, convert it once, and read inherited options in every formatter that passes its options to
Intl.DateTimeFormat.One read per option. 56 functions read an option twice or more: once to check it or to choose its default, and again to use it. An options object whose property is a getter could answer a different value each time, so the value that was checked was not the value that was used. ECMA-402 and the Temporal specification read an option with one
Get(GetOption), and every function that takes anoptionsobject now does the same.import { getZonedNow } from "@northguild/gmt";let reads = 0;const options = {get smallestUnit() {reads += 1;return reads === 1 ? ("minute" as const) : undefined;},};// With the clock at 2024-02-29T00:00:00ZgetZonedNow("UTC", options); // "2024-02-29T00:00+00:00[UTC]" — was "2024-02-29T00:00:00+00:00[UTC]"reads; // 1 — was 2One conversion per option.
GetOptionalso converts the value it read once: to a string, or to a number forfractionalSecondDigits. Twelve functions asked an option given as an object for its value twice, once to check it and once to use it, so the object could answer"long"to the check and"narrow"to the formatter. They now ask once and use that answer throughout.Inherited options. ECMA-402 reads an option with
Get, which follows the prototype chain, so an option an object inherits is an option. Five functions copied only the options an object holds itself and ignored the rest. They now read each option asIntl.DateTimeFormatdoes.A plain options object whose values are strings, numbers and booleans gives the same result as before.
Breaking changes
Section titled “Breaking changes”An inherited option is now read. Each call below passes
Object.create({ dateStyle: "full" })asoptions.Call 1.17 1.18 formatUtc("2024-03-15T 20:00:00Z", "en-US", options) "3/15/2024, 8:00:00 PM""Friday, March 15, 2024"formatUnix(1710532800000, "en-US", options) "3/15/2024, 8:00:00 PM""Friday, March 15, 2024"formatZonedDateTime("2024-03-15T 20:00:00+00:00 [UTC]", "en-US", options) "3/15/2024""Friday, March 15, 2024"formatZonedRange("2024-03-15T 20:00:00+00:00 [UTC]", "2024-03-17T 20:00:00+00:00 [UTC]", "en-US", options) "3/15/2024 - 3/17/2024""Friday, March 15 - Sunday, March 17, 2024"formatZonedToParts("2024-03-15T 20:00:00+00:00 [UTC]", "en-US", options) The parts of "3/15/2024": month, day and yearThe parts of "Friday, March 15, 2024": weekday, month, day and yearTo keep the 1.17 result, pass an object that does not inherit the option, for example
{}orObject.create(null). The other seven formatters (formatDate,formatDateRange,formatDateTime,formatDateTimeRange,formatDateToParts,formatDateTimeToParts,formatTime) already read inherited options and are unchanged.An option given as an object is now converted once. In the calls below
monthis an object whosetoStringreturns"long"the first time and"narrow"after that, andlateris one that returns"later"and then"earlier".Call 1.17 1.18 formatDate(, likewise"2024-03-15", "en-US", { month, day: "numeric" }) formatDateTime,formatUtcandformatUnixfor the same day"M 15""March 15"formatDateRange(, likewise"2024-03-15", "2024-03-17", "en-US", { month, day: "numeric" }) formatDateTimeRange"M 15 - 17""March 15 - 17"formatDateToParts(, likewise"2024-03-15", "en-US", { month, day: "numeric" }) formatDateTimeToPartsA month part of "M"A month part of "March"formatTime(, where"20:05:00", "en-US", { hour, minute: "2-digit" }) hourreturns"2-digit"and then"numeric""8:05 PM""08:05 PM"formatTime("20:05:00", "en-US", { timeStyle: new String( "long") }) "8:05:00 PM UTC""8:05:00 PM"formatDateTime("2024-03-15T 20:05:00", "en-US", { timeStyle: new String( "full") }) "8:05:00 PM Coordinated Universal Time""8:05:00 PM"addZoned("2024-11-02T 01:30:00-04:00 [America/ New_York]", { days: 1 }, { disambiguation: later }) "2024-11-03T01:30:00-04:00 [America/ New_York]" "2024-11-03T01:30:00-05:00 [America/ New_York]" subtractZoned("2024-11-04T 01:30:00-05:00 [America/ New_York]", { days: 1 }, { disambiguation: later }) "2024-11-03T01:30:00-04:00 [America/ New_York]" "2024-11-03T01:30:00-05:00 [America/ New_York]" intervalFromDurationZoned("2024-11-02T 01:30:00-04:00 [America/ New_York]", "P1D", "start", { disambiguation: later }) An endof"2024-11-03T01:30:00-04:00 [America/ New_York]" An endof"2024-11-03T01:30:00-05:00 [America/ New_York]" TypeScript rejects an object where each of these options expects a string, so only untyped callers and casts are affected. Pass the string itself and the result is the same in both versions.
-
9067590: Return
""from theformatRelative*functions for alargestUnittheir type does not list.Each function lists the units its values have:
formatRelativeDatethe date units,formatRelativeTimethe time units, and the other four all seven. The type already rejected any other unit, but at run timeformatRelativeDatewrote a date distance in hours andformatRelativeTimeaccepted"day". Temporal throwsRangeErrorfor a unit outside the units of the type:Temporal.PlainDate.prototype.untilrejectslargestUnit: "hour", andTemporal.PlainTime.prototype.untilrejects"day". The functions now follow that rule and return"".One rule here is GMT’s own and stricter than Temporal: a
largestUnitthat is not a string returns"". Temporal converts any value to a string first, so it accepts["day"]and an object whosetoStringreturns"day". GMT takes string inputs, and its other functions that check a unit (roundDate,roundDateTime,roundUtc,roundZoned,startOfDate,durationAs,areDatesEqualBy) already reject a value that is not a string, so theformatRelative*functions now do too.Function largestUnitaccepts, singular or pluralformatRelativeDate"day","week","month","year"formatRelativeTime"second","minute","hour"formatRelativeDateTime,formatRelativeUtc,formatRelativeUnix,formatRelativeZoned"second","minute","hour","day","week","month","year"A listed unit, singular or plural, formats as before. An omitted
largestUnit, or one passed asundefined, still picks the unit from the distance.Breaking changes
Section titled “Breaking changes”Call 1.17 1.18 formatRelativeDate(, likewise"2024-01-03", "en-US", { reference: "2024-01-01", largestUnit: "hour" }) "hours""in 48 hours"""The same call with "minute"or"minutes""in 2,880 minutes"""The same call with "second"or"seconds""in 172,800 seconds"""formatRelativeTime(, likewise"05:00", "en-US", { reference: "00:00", largestUnit: "day" }) "days""today"""Any of the six functions with a largestUnitthat is not a string, such as["day"]or an object whosetoStringreturns"day"(GMT’s rule; Temporal accepts these)The value was converted to a string and formatted, for example "in 2 days"""TypeScript already rejected each of these calls, so only untyped callers and
as nevercasts are affected.To write a date distance in a time unit, give both dates a time and call
formatRelativeDateTime:import { formatRelativeDateTime } from "@northguild/gmt";formatRelativeDateTime("2024-01-03T00:00:00", "en-US", {reference: "2024-01-01T00:00:00",largestUnit: "hour",}); // "in 48 hours" -
511b394: Add
crossingTimeandscheduleDeliveryto thetransport/namespace (Story TRAN-9).A crossing — a canal transit, a strait passage, a border queue — is logged as two instants and read on the clock of whoever runs it. A multi-leg move — truck, ship, rail — is one departure, a duration per leg and a handling time at each handoff, and the handoffs are where a naive ETA loses an hour. Every leg boundary here is an exact instant; local time is rendered only at the edges.
import { crossingTime, scheduleDelivery } from "@northguild/gmt";crossingTime("2024-03-10T05:00:00Z", "2024-03-10T12:00:00Z", "America/New_York");// { duration: "PT7H", enter: "2024-03-10T00:00:00-05:00[America/New_York]",// exit: "2024-03-10T08:00:00-04:00[America/New_York]" } — seven hours across the spring-forwardconst legs = [{ departure: "2024-06-14T08:00:00", duration: "PT6H", timeZone: "Asia/Shanghai", dwellAfter: "PT12H", mode: "truck" },{ departure: "2024-06-15T10:00:00+08:00[Asia/Shanghai]", duration: "PT336H", timeZone: "America/Los_Angeles", dwellAfter: "PT48H", mode: "ship" },{ duration: "PT70H", timeZone: "America/Chicago", mode: "rail" },];scheduleDelivery(legs, { startTimeZone: "Asia/Shanghai" });// { eta: "2024-07-03T19:00:00-05:00[America/Chicago]", legTimes: [// { arrival: "2024-06-14T06:00:00Z", localArrival: "2024-06-14T14:00:00+08:00[Asia/Shanghai]", dwellAfter: "PT12H", mode: "truck" },// { arrival: "2024-06-29T02:00:00Z", localArrival: "2024-06-28T19:00:00-07:00[America/Los_Angeles]", dwellAfter: "PT48H", mode: "ship" },// { arrival: "2024-07-04T00:00:00Z", localArrival: "2024-07-03T19:00:00-05:00[America/Chicago]", dwellAfter: "PT0S", mode: "rail" } ] }scheduleDelivery([legs[0], { ...legs[1], departure: "2024-06-14T20:00:00+08:00[Asia/Shanghai]" }], { startTimeZone: "Asia/Shanghai" });// null — the sailing leaves inside the truck leg's 12-hour dwell: a missed connectioncrossingTimemeasures, it does not count days. It returns the exact elapsed duration, hours as the largest unit, and the entry and exit rendered intargetZone, an IANA identifier or a fixed offset.targetZoneis always the rendering zone; a bracketed zone on the input never is. A crossing that needs a day count is a dwell — usedwellTime. An exit before the entry returnsnull; a zero-length crossing isPT0S.dwellAfteris the minimum connect time. A leg leaves at its owndeparture, or, when it has none, at the previous arrival plus the previous leg’sdwellAfter. A scheduled departure earlier than that — inside the dwell or before the arrival — is a missed connection and returnsnull; equal passes, so a zero-slack connection is feasible.dwellAfteris echoed as written,"PT0S"when omitted. The last leg’s dwell is validated and echoed but never added to an instant, so it cannot turn a representable ETA intonull.- Departures must be exact, with two wall-time exceptions. An instant (
Zor an offset) or a zoned string, whose bracketed zone must be real and agree with its offset. Schedules are published as local wall times, so a zoneless first departure is read instartTimeZone, and a zoneless later-leg departure is read in the previous leg’s owntimeZone— leg N−1’s destination is exactly leg N’s departure zone. Zoneless without one of these returnsnull; the missed-connection check still applies after resolution. - Wall times resolve as
"compatible". An ambiguous wall time — a fall-back hour the clock ran through twice — resolves to the earlier instant; a skipped one resolves to the later instant. Write the offset to pick the other pass of a repeated hour. At a hub, a printed timetable never says which pass it means, so on any leg but the first a repeated hour takes the earliest pass at or after the previous arrival plus its dwell; when neither is that late, the connection is missed. - Durations follow
transitTime. Time units are elapsed time, a day is 24 hours, and years, months and weeks returnnull. A negative leg returnsnull: a leg cannot arrive before it departs. A single-leg schedule is exactlytransitTimecomposed withetaAtZone. - Tags are opaque.
mode,originanddestinationare echoed onto eachLegTime, and absent when not supplied, so a caller can join results to its own records. GMT never resolves a code to a zone;timeZoneis the caller’s fact. An empty legs array returns{ eta: "", legTimes: [] }. - Also exported: the
Crossing,Leg,LegTime,ScheduleDeliveryOptionsandDeliveryScheduletypes.
-
9067590: Remove the
DurationUnittype from the public exports.No public function takes or returns
DurationUnit. It only typed two private lookup tables insideformatDuration, so it now lives there.Breaking changes
Section titled “Breaking changes”Import 1.17 1.18 import type { DurationUnit } from "@northguild/, likewise fromgmt" @northguild/gmt/ types The union "years" | "months" | "weeks" | "days" | "hours" | "minutes" | "seconds"Not exported For the unit keys a function accepts, import the type its signature names:
DateDurationUnit,TimeDurationUnitorDateTimeDurationUnit.DateTimeDurationUnitis a wider union thanDurationUnitwas, so code that needs exactly the seven keys above declares that union itself.
Patch Changes
Section titled “Patch Changes”-
9067590: Keep the millisecond default of
getZonedNowwhensmallestUnitis passed asundefined, and read no option butsmallestUnit.Before,
{ smallestUnit: undefined }replaced the default, and the string was written with as many fractional digits as the clock reading needed: none on a whole second. An option whose value isundefinedis now read as absent, asGetOptionreads it in ECMA-402 and in the Temporal specification, so the documented default applies.import { getZonedNow } from "@northguild/gmt";// With the clock at 2024-02-29T00:00:00ZgetZonedNow("UTC"); // "2024-02-29T00:00:00.000+00:00[UTC]"getZonedNow("UTC", { smallestUnit: undefined }); // "2024-02-29T00:00:00.000+00:00[UTC]" — was "2024-02-29T00:00:00+00:00[UTC]"getZonedNow("UTC", { smallestUnit: "second" }); // "2024-02-29T00:00:00+00:00[UTC]", unchangedBefore, the whole options object also went to Temporal’s
toString, so a key the function does not document changed the string. TypeScript rejects these keys; a JavaScript caller, or an object built elsewhere and passed through, could still carry them. Now onlysmallestUnitis read. The string always has the offset and the bracketed time zone, and units smaller thansmallestUnitare always truncated, as the documentation says.// With the clock at 2024-02-29T00:00:00.999Zconst rounding = { smallestUnit: "second", roundingMode: "ceil" };getZonedNow("UTC", rounding as never); // "2024-02-29T00:00:00+00:00[UTC]" — was "2024-02-29T00:00:01+00:00[UTC]"getZonedNow("UTC", { timeZoneName: "never" } as never); // "2024-02-29T00:00:00.999+00:00[UTC]" — was "2024-02-29T00:00:00.999+00:00"getZonedNow("UTC", { offset: "never" } as never); // "2024-02-29T00:00:00.999+00:00[UTC]" — was "2024-02-29T00:00:00.999[UTC]"getZonedNow("UTC", { roundingMode: "bogus" } as never); // "2024-02-29T00:00:00.999+00:00[UTC]" — was ""Unchanged: a call with no options, with
{}, or with anysmallestUnitfrom"minute"to"nanosecond". AsmallestUnitoutside that range still returns"". -
9067590: Accept
timeStyle: "long"in the type offormatCalendarUtc,formatCalendarUnixandformatCalendarZoned, not only at run time.timeStyleis thetimeStyleofIntl.DateTimeFormat, which takes"short","medium","long"and"full". The three functions formatted"long"when called from JavaScript but rejected it in TypeScript.import { formatCalendarUtc } from "@northguild/gmt";formatCalendarUtc("2024-03-16T18:30:00Z", "en-US", {reference: "2024-03-15T13:00:00Z",timeStyle: "long",}); // "tomorrow at 6:30:00 PM UTC" — was a type errorNo output changes.
formatCalendaris unchanged: a plain date-time has no time zone, so its type offers"short"and"medium"only. -
9067590: Stop
splitIntervalByUnitUnixreturning empty or repeated pieces when the step is finer than the epoch unit, and always end the last piece ofsplitIntervalByUnitZonedat theendyou passed.A step finer than the epoch unit. Boundaries are floored to whole seconds or milliseconds, so several finer steps used to floor to the same value and come back as empty pieces. Such a split now returns one piece per epoch unit, and
maxPiecescounts those pieces rather than the finer steps.import { splitIntervalByUnitUnix } from "@northguild/gmt";splitIntervalByUnitUnix(0, 2, "millisecond", 500, { epochUnit: "seconds" });// was [{ start: 0, end: 0 }, { start: 0, end: 1 }, { start: 1, end: 1 }, { start: 1, end: 2 }]// now [{ start: 0, end: 1 }, { start: 1, end: 2 }]splitIntervalByUnitUnix(0, 1, "microsecond", 500);// was [{ start: 0, end: 0 }, { start: 0, end: 1 }]// now [{ start: 0, end: 1 }]splitIntervalByUnitUnix(0, 2000, "millisecond", 1, { epochUnit: "seconds" }).length;// was 0 (2,000,000 steps passed the default limit), now 2000A step of one epoch unit or more is unchanged.
startandendin different zones. When the last step landed exactly onend,splitIntervalByUnitZonedwrote that last boundary instart’s zone. It now returns theendargument in its own zone, as it already did when the last step passedend.import { splitIntervalByUnitZoned } from "@northguild/gmt";splitIntervalByUnitZoned("2024-01-01T00:00:00-05:00[America/New_York]","2024-01-01T11:00:00+00:00[Europe/London]","hour",3,).at(-1)?.end;// was "2024-01-01T06:00:00-05:00[America/New_York]" — the same instant// now "2024-01-01T11:00:00+00:00[Europe/London]"The same holds when
endis another spelling ofstart’s zone, such as[+00:00]against[UTC]: the lastendis the argument as you wrote it.splitIntervalByUnitZoned("2024-01-01T00:00:00+00:00[UTC]","2024-01-01T06:00:00+00:00[+00:00]","hour",3,).at(-1)?.end;// was "2024-01-01T06:00:00+00:00[UTC]"// now "2024-01-01T06:00:00+00:00[+00:00]" -
9067590: Accept plural unit names in the type of the
largestUnitoption of theformatRelative*functions, not only at run time.formatRelativeUnixalready typedlargestUnitas singular or plural. The other five functions accepted"hours"when called from JavaScript but rejected it in TypeScript. Their types now accept the plural of every unit they already listed:Function largestUnitnow also acceptsformatRelativeUtc,formatRelativeZoned,formatRelativeDateTime"years","months","weeks","days","hours","minutes","seconds"formatRelativeDate"years","months","weeks","days"formatRelativeTime"hours","minutes","seconds"import { formatRelativeUtc } from "@northguild/gmt";const reference = "2024-03-17T12:00:00Z";formatRelativeUtc("2024-03-17T10:00:00Z", "en-US", { reference, largestUnit: "hour" }); // "2 hours ago", unchangedformatRelativeUtc("2024-03-17T10:00:00Z", "en-US", { reference, largestUnit: "hours" }); // "2 hours ago" — was a type errorNo output changes: a plural names the same unit as its singular, as it does in
Intl.RelativeTimeFormatand Temporal. -
9067590: Return
""from theformatRelative*functions for aroundingMethodthat is not"floor","ceil"or"round".Before, the value was used as the name of a
Mathfunction. Any nameMathhas was accepted, so"abs","trunc","sign","random"and inherited keys such as"constructor"produced a wrong phrase instead of the empty string that invalid input returns. The method is now matched against the three listed values only.This applies to
formatRelativeDate,formatRelativeTime,formatRelativeDateTime,formatRelativeZoned,formatRelativeUtcandformatRelativeUnix.import { formatRelativeUtc } from "@northguild/gmt";const options = {reference: "2024-03-17T12:00:00Z",largestUnit: "hour",numeric: "always",} as const;// 10:30 is 1.5 hours before the referenceformatRelativeUtc("2024-03-17T10:30:00Z", "en-US", options); // "1 hour ago" (−1.5 rounds to −1), unchangedformatRelativeUtc("2024-03-17T10:30:00Z", "en-US", { ...options, roundingMethod: "floor" }); // "2 hours ago", unchangedformatRelativeUtc("2024-03-17T10:30:00Z", "en-US", { ...options, roundingMethod: "abs" as never }); // "" — was "in 1.5 hours"formatRelativeUtc("2024-03-17T10:30:00Z", "en-US", { ...options, roundingMethod: "trunc" as never }); // "" — was "1 hour ago"formatRelativeUtc("2024-03-17T10:30:00Z", "en-US", { ...options, roundingMethod: undefined }); // "1 hour ago", the default, unchangedUnchanged:
"floor","ceil","round", an omittedroundingMethod, androundingMethod: undefined, which is read as omitted and takes the default"round".
© 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.