Changelog 1.13
Release notes of @northguild/gmt 1.13.0, newest first, built from packages/gmt/CHANGELOG.md. Back to Changelog.
@burglekitt/gmt
Section titled “@burglekitt/gmt”
In memoriam: @burglekitt. These releases were published under the retired @burglekitt npm scope. The package continues as @northguild/gmt from 1.14.2; install @northguild/gmt.
1.13.0
Section titled “1.13.0”Released 2026-08-22
Minor Changes
Section titled “Minor Changes”-
b8e13a9: Add calendar quantity getters:
getDaysInMonth,getDaysInYear,getDayOfYear,getWeeksInYear,getWeeksInMonth,getWeekOfMonth(Story J3).All six take a
PlainDateISO string and returnnumber | null.getDaysInMonth,getDaysInYear, andgetDayOfYearwrap Temporal’s owndaysInMonth/daysInYear/dayOfYear.getWeeksInYearreports the ISO week-numbering year’s total week count (52 or 53), resolved fromvalue’s ownyearOfWeekrather than its calendar year, since late-December/early-January dates can belong to a different ISO week-year than their calendar year.getWeeksInMonthandgetWeekOfMonthare locale-aware — they size and index a month’s calendar-grid rows usinglocale’s first day of week, matching date-fns’sgetWeekOfMonthconvention (the row containing the 1st of the month counts as row 1, even when partial). They live inplain/calculate/, notplain/get/, per the rule J0b established:get/namespaces are current-moment accessors only, and these take a date value. -
5b9ed2b: Add duration introspection and comparison:
getDurationUnit,durationAs,negateDuration,absDuration,compareDurations,getDurationSign(Story J8).getDurationUnitreads a single component as stored (getDurationUnit("PT90M", "hours")is0— the minutes field holds 90, not a converted total);durationAstotals the whole duration into one unit instead (durationAs("PT90M", "hours")is1.5).negateDuration/absDurationflip or drop the sign;getDurationSignreports-1/0/1. Newduration/compare/module holdscompareDurations, wrappingTemporal.Duration.compare.durationAsandcompareDurationsfollow therelativeTopattern already documented fornormalizeDuration(A3): any calendar unit (years/months/weeks) on either side requiresrelativeTo, returning the sentinel (null) without it — this applies even when the requested unit is the only calendar-shaped one, e.g.durationAs("PT36H", "weeks")isnull. Worth noting the asymmetry withaddDuration/subtractDuration(A2):Temporal.Duration.comparedoes acceptrelativeTo, socompareDurationscan order calendar-unit durations in casesaddDurationcannot combine.negateDuration,absDuration, andgetDurationSignare pure sign operations and never needrelativeTo, even on calendar-unit durations.Updated
packages/gmt/README.md,packages/gmt/src/duration/README.md, and thedurationsskill (new Core Patterns plus two Common Mistakes entries extending the existingrelativeToguidance). -
75ce713: Add field setters:
setDate,setDateTime,setTime,setZoned,setUnix,setUtc(Story J1).Each takes a partial fields object and wraps
Temporal.*.prototype.with(), resolving every supplied field in a single atomic overflow pass — the safe alternative to composingadd*calls field-by-field, which resolves each field’s overflow independently and can silently diverge on multi-field updates (e.g. setting month-then-day vs. day-then-month on the same target).All six take
overflow(“constrain” (default) | “reject”).setZoned,setUnix, andsetUtcadditionally takedisambiguationandoffset(default"ignore", same rule as thestartOfZonedfamily — seedocs/dst-disambiguation.md) for DST gap/overlap control;setUtc’sdisambiguation/offsetare accepted for signature consistency but are permanently inert, since"UTC"has no DST transitions.An empty fields object is a no-op on all six.
-
f8af3ec: Add
formatCalendar,formatCalendarZoned,formatCalendarUnix,formatCalendarUtc(Story J15) — Story Group J complete.Moment’s
.calendar(): a relative day label plus time-of-day, e.g."Tomorrow at 2:30 PM". This is distinct from the existingformatRelative*family, which renders an elapsed-time phrase (“in 1 day”) and never includes a clock time — Group I’s notes over-generalized Luxon’stoRelativeCalendarparity claim to Moment’s.calendar(), which this story corrects.Within
±6days ofreference(default “now”), renders<day label> <connector> <time>— “today”/“tomorrow”/“yesterday” near the boundary, “in N days”/“N days ago” further out, viaIntl.RelativeTimeFormat. Beyond that, falls back to an absolutedateStyle: "long"+timeStylestring with no relative wording, matching Moment’ssameElsebehavior.The day label and time are joined using the locale’s own connector — read from
Intl.DateTimeFormat’s combineddateStyle+timeStylepart sequence for the same instant, never a hardcoded"at". This is the go/no-go decision the story required before implementation: a verifiedIntl-only route with no hardcoded English, covering all 17MustTestLocalesincluding a locale (ru-RU) whose combined date+time pattern fuses a date-side suffix onto the connector literal, which the newinternal/joinDateTimeConnector.tshelper detects and strips.timeStyle: "full"is available on the zoned/unix/utc variants (a real IANA zone) but not on plainformatCalendar— a plain value has no real timezone, so"full"’stimeZoneNamewould misrepresent the internal UTC anchor as a fact about the input.Updated
packages/gmt/README.md,plain/README.md,zoned/README.md,unix/README.md,utc/README.md, and theformat-date-timeskill (new Core Pattern + a Common Mistakes entry distinguishingformatCalendarfromformatRelativeDateTime). -
de8e944: Add
formatDateToParts,formatDateTimeToParts,formatZonedToParts(Story J12).Each returns the locale-ordered
Array<{ type, value }>parts behindformatDate/formatDateTime/formatZonedDateTime’s finished strings, mirroring those functions’(value, locale?, options?)signature exactly.formatZonedToPartsalso emitstimeZoneNameparts whenoptions.timeZoneNameis set. All three return[]on invalid input.This is GMT’s sanctioned substitute for a token formatter (Luxon
toFormat, date-fnsformat), which remains deliberately excluded (roadmap Decision 1): a token pattern like"MM/dd/yyyy"hard-codes US field order and ships it to every locale.formatToPartsgives the caller full control over presentation while the locale keeps control of field order — iterate the returned array instead of reassembling parts in a fixed order. -
4917f26: Add interval length and partitioning:
intervalLength*,intervalDivideEqually*,intervalSplitAt*,mergeIntervals*,intervalXorAll*acrossDate/DateTime/Time/Zoned/Unix/Utc(Story J9).intervalLength*isintervalCount*’s exact-duration counterpart — it answers “how long is this interval” as a real, possibly fractional number viaTemporal.Duration.prototype.total, rather than “how manyunitboundaries does it touch”. The same interval from23:59to00:01is2day boundaries viaintervalCountDateTimebut~0.0014days viaintervalLengthDateTime. Zoned/Unix/Utc variants are DST-aware the same wayintervalCount*is.intervalDivideEqually*splits an interval intonequal-length sub-intervals;intervalSplitAt*splits at arbitrary (unsorted, out-of-range-safe) points instead of by count.PlainDaterounds internal boundaries to the nearest whole day since it has no fractional-day representation; every other variant is exact, computed from total elapsed nanoseconds —intervalDivideEquallyZonedsplits DST-crossing intervals by real elapsed time, not local clock time.mergeIntervals*andintervalXorAll*are the list-form generalizations of the existing pairwiseintervalUnion*(B5) andintervalXor*(B7) — each takes a single array of{ start, end }records instead of two flat intervals.intervalXorAll*is implemented as a coverage sweep and reduces to the pairwiseintervalXor*result for exactly two intervals.Updated
packages/gmt/README.md, all four namespace READMEs (plain/zoned/unix/utc), and theinterval-opsskill (new Core Patterns plus two Common Mistakes entries, including the requiredintervalLengthvsintervalCountdistinction). -
1d4f7ab: Add named machine-format format/parse pairs:
formatRfc2822/parseRfc2822(zoned),formatHttp/parseHttp(utc),formatSql/parseSql(plain),formatRfc3339/parseRfc3339(zoned) (Story J13).These are fixed, non-locale-adaptive grammars — RFC 5322 and RFC 7231 mandate English weekday/month abbreviations regardless of locale, by specification — so none of the eight take a
localeargument, unlike GMT’sIntl-backed formatters.""on invalid input for every function.formatRfc2822/parseRfc2822— RFC 5322 (RFC 2822) emailDate:header format, e.g."Fri, 15 Mar 2024 14:30:00 -0400". Parsing accepts a 1- or 2-digit day and RFC 5322’s obsolete named zones (GMT,UT, and the eight North American zones); formatting always emits a zero-padded, numeric offset.formatHttp/parseHttp— RFC 7231 IMF-fixdate, e.g."Fri, 15 Mar 2024 14:30:00 GMT", forLast-Modified/Date/Expiresheaders. Strict 2-digit fields and a literalGMTonly; the obsolete RFC 850/asctime HTTP-date forms are a documented limitation, not accepted.formatSql/parseSql— ANSI SQL / ODBC datetime literal, e.g."2024-03-15 14:30:00", forDATETIME/TIMESTAMPcolumns without a time zone. SQL’s offset-carryingTIMESTAMPTZliteral is out of scope.formatRfc3339/parseRfc3339— strict RFC 3339. This is not a passthrough on GMT’s existing ISO output: GMT’s own zoned strings always carry a bracketed IANA zone annotation (...+00:00[UTC]) that RFC 3339 does not permit, soformatRfc3339strips it. A parallelutc/unixwrapper was deliberately not added —Temporal.Instant.prototype.toString()is already fully RFC 3339 compliant with no bracket to strip, so a wrapper there would be a pure passthrough.
-
1bb2556: Add now-relative predicates:
isRelativeDay,isThisUnit,isPast,isFuture, and their zoned counterpartsisZonedRelativeDay,isZonedThisUnit,isZonedPast,isZonedFuture(Story J6).isRelativeDay(value, offsetDays)subsumesisToday/isYesterday/isTomorrow(offsetDays: 0/-1/1, or any other integer offset);isThisUnit(value, unit, locale?)subsumesisThisWeek/isThisMonth/isThisYear. Per Decision 5 incontext/roadmap/issues/J.md, GMT ships one parameterized function per axis rather than date-fns’s eleven near-duplicate named functions.isPast/isFuturestay separate — genuinely distinct before/after-now predicates, not one more value on an enumerable axis.The plain functions compare against
getToday()and so depend on the system clock and system timeZone — the same call can return a different answer on hosts in different timeZones at the same instant. The zoned variants resolve “today”/“now” in the value’s own timeZone instead, making them deterministic regardless of the host machine’s timeZone;isZonedPast/isZonedFutureadditionally compare the exact instant rather than just the calendar day, since aZonedDateTimecarries a full time-of-day where aPlainDatedoes not. -
1852f00: Add offset and DST-instant accessors:
getZonedOffset,getZonedOffsetAs,getTimeZoneOffset,formatTimeZoneName,isInDaylightSaving(Story J10).GMT could construct and manipulate zoned values but couldn’t report their UTC offset —
getZonedOffset(value)returns it as a±HH:MMstring;getZonedOffsetAs(value, unit)reads it as a number in"minutes"or"nanoseconds"(following J8’sgetDurationUnit(value, unit)precedent, replacing what would otherwise be agetZonedOffsetMinutes/getZonedOffsetNanosecondspair).getTimeZoneOffset(timeZone, instant)looks up a zone’s offset at an arbitrary instant without needing an existing zoned value in hand.formatTimeZoneName(timeZone, locale, options?)returns a zone’s localized display name across all sixIntl.DateTimeFormatOptionstimeZoneNamestyles.isInDaylightSaving(value)is the third DST-related function in the roadmap and answers a distinct question from the other two:hasDaylightSaving(timeZone)asks whether a zone observes DST at all (zone-level, no instant),getDstTransitions(timeZone, year)asks where a zone’s transitions fall (enumerates instants), andisInDaylightSaving(value)asks whether this particular instant is currently in DST.docs/dst-disambiguation.mdnow documents all four (includingdisambiguation/offset, the orthogonal construction-time concern) as one table.Both
getZonedOffset/getZonedOffsetAslive inzoned/parse/, notzoned/get/— per J0b’s rule, they take a date value rather than reporting on now or a bare timezone.getTimeZoneOffsetstays inzoned/get/alongsidegetDstTransitions, since neither argument is a value being described, both are coordinates for a zone-level lookup.Updated
packages/gmt/README.md,packages/gmt/src/zoned/README.md,docs/dst-disambiguation.md, and thezoned-date-opsskill. -
865a2ea: Add plain range formatting:
formatDateRange,formatDateTimeRange(Story J14).Plain counterparts of the existing
zoned/format/formatZonedRange— same(start, end, locale?, options?)parameter order andIntl.DateTimeFormatOptionsshape, but wrappingTemporal.PlainDate/Temporal.PlainDateTimedirectly since there’s no timezone to reconcile between endpoints. Both useIntl.DateTimeFormat.prototype.formatRangeunder the hood, so the locale elides shared fields betweenstartandend("February 3 – 5, 2024"for same-month,"November 3, 2024 – February 10, 2025"once the year differs) instead of the caller having to format both ends and join them by hand. Returns""when either endpoint is invalid; a reversed range (endbeforestart) still formats rather than throwing or auto-correcting.Updated
packages/gmt/README.md,packages/gmt/src/plain/README.md, and theformat-date-timeskill. -
c522327: Add same-unit comparison:
areDatesEqualBy,areDateTimesEqualBy,areZonedEqualBy,areUnixEqualBy,areUtcEqualBy(Story J5).Each function answers “are these two values equal at a given calendar unit?” —
areDatesEqualBy(a, b, "month")replaces the pattern of manually truncating both values before comparing. Per Decision 5 incontext/roadmap/issues/J.md, GMT ships one parameterized function per namespace rather than date-fns’s twelveisSameXfunctions; each function’s JSDoc carries the full date-fns mapping table.Semantics, decided explicitly: equality is measured by comparing the start-of-unit boundary for each value, so a unit implicitly requires every coarser unit above it to match too —
areDatesEqualBy("2023-03-15", "2024-03-15", "month")isfalse, nottrue, because “same month” means the same month and year. This matches date-fns’sisSameMonth/isSameWeek/etc. and Luxon’sdt.hasSame(other, unit)(verified against date-fns’s source), not a bare “same month-of-year across any year” comparison.areZonedEqualBycompares each value’s own local calendar fields in its own time zone, not the underlying instant or time zone identifier — two zoned values representing the same instant can land on different local calendar days depending on their zone, and vice versa. -
82dfe27: Add token-pattern-based parsing:
parseDateWithPattern,parseDateTimeWithPattern,parseTimeWithPattern(Story J11).Each decodes a string against a caller-supplied token pattern (e.g.
"MM/dd/yyyy","dd-MMM-yyyy h:mm a") and returns the matching ISOPlainDate/PlainDateTime/PlainTimestring, or""on no match, a malformed pattern, or a shape-valid-but-not-real date/time ("02/31/2024"against"MM/dd/yyyy"still fails — the regex only proves shape,Temporal.*.from(..., { overflow: "reject" })proves it’s real).This is a decoding tool for a known, fixed producer format — a CSV column, a legacy API field, a partially-typed form value — not a display formatter. GMT still has no token-pattern formatter: hard-coding a field order like
"MM/dd/yyyy"for output would ship US field ordering to every locale (roadmap Decision 1). UseformatDate/formatDateTime/formatDateToPartsfor locale-correct display; use these new functions only to consume input whose shape you don’t control.Supports numeric tokens (
yyyy/yy/MM/M/dd/d/HH/H/hh/h/mm/m/ss/s/SSS), locale-aware name tokens (MMMM/MMM/EEEE/EEE/a/GGGG/GG, defaulting to"en-US"whenlocaleis omitted), and literal text via automatic literal characters or'single quotes'.parseDateWithPattern/parseTimeWithPatterneach reject the other’s tokens (returning"");parseDateTimeWithPatternaccepts the full combined set. -
1d9b625: Add week-numbering year getters:
getWeekYear,getLocaleWeekYear,getWeeksInLocaleWeekYear(Story J4).getWeekYearreports the ISO 8601 week-numbering year a date belongs to (viaTemporal.PlainDate.yearOfWeek), which can differ from the calendar year — 2024-12-30 is a Monday in ISO week 1 of 2025, not 2024. Pair it with the existingweekOfYearForDate/getWeekNumberwhenever bucketing by week number, since a week number alone is ambiguous across a year boundary.getLocaleWeekYearandgetWeeksInLocaleWeekYearare the locale-relative equivalents, resolved fromlocale’s first day of week and minimal-days-in-first-week (Intl.Locale.prototype.weekInfo) instead of the fixed ISO rule (Monday-start, 4 minimal days). The two can disagree on the same date near a year boundary — e.g. en-US always counts Jan 1 as week 1, while ISO-style locales do not.All three take a
PlainDateISO string and returnnumber | null. They live inplain/calculate/, notplain/get/, per the rule J0b established. -
d6a5780: Add weekday navigation:
nextWeekday,previousWeekday(Story J7).Each function finds the next/previous occurrence of a given ISO day of week (1 = Monday … 7 = Sunday, matching
getDayOfWeek/parseDayOfWeekFromDate) on or after/before a date. Per Decision 5 incontext/roadmap/issues/J.md, GMT ships two parameterized functions rather than date-fns’s sixteennextMonday…previousSundayfunctions; each function’s JSDoc carries the full date-fns mapping table.options.inclusive(defaultfalse) controls what happens when the input already falls on the target day:falseadvances/retreats a full week, matching date-fns’s behavior;truereturns the input as-is. This default is easy to get surprised by —nextWeekday("2024-03-15", 5)on a date that is already a Friday returns the following Friday, not the input — so it’s called out explicitly in both functions’ JSDoc and thecompare-datesskill’s Common Mistakes.date-fns’s
lastDayOfMonthis not a gap this pair fills — it’s already covered by GMT’s existingendOfDate(value, "month"). -
5a33ffd: Move
getLocaleDayOfWeek,getLocaleZonedDayOfWeek, andgetHoursInZonedDayfrom theget/namespace tocalculate/(Story J0b):plain/get/getLocaleDayOfWeek.ts→plain/calculate/getLocaleDayOfWeek.tszoned/get/getLocaleZonedDayOfWeek.ts→zoned/calculate/getLocaleZonedDayOfWeek.tszoned/get/getHoursInZonedDay.ts→zoned/calculate/getHoursInZonedDay.ts
get/namespaces are now current-moment accessors only (no argument, or timezone only, reporting a value for now); any function taking a date value belongs incalculate/. Function names, signatures, and behavior are unchanged.Technically breaking for deep-subpath consumers. Root imports (
from "@northguild/gmt") are unaffected. But anyone importing from@northguild/gmt/plain/getor@northguild/gmt/zoned/getloses these symbols — switch those imports to@northguild/gmt/plain/calculateand@northguild/gmt/zoned/calculaterespectively.
© 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.