@northguild/gmt 1.14.2

package/skills/durations/SKILL.md

@@ -0,0 +1,418 @@
+---
+name: durations
+description: >
+  Parse, validate, combine, rebalance, and format ISO 8601 duration strings
+  (e.g. "P1DT2H30M"). Use isValidDuration to check a duration string is
+  well-formed, parseDuration to normalize one and optionally control its output
+  precision/rounding via smallestUnit, fractionalSecondDigits, and roundingMode,
+  addDuration / subtractDuration to combine two duration strings,
+  normalizeDuration to roll small units into larger ones (e.g. 90 minutes into 1
+  hour 30 minutes) via largestUnit/smallestUnit/
+  roundingIncrement/roundingMode/relativeTo, getDurationUnit to read one stored
+  component, durationAs to total a duration into a single unit, negateDuration /
+  absDuration to flip or drop its sign, getDurationSign to test whether it is
+  negative/zero/positive, compareDurations to order two durations by length, and
+  formatDuration to render a duration as a human-readable, locale-aware string
+  (e.g. "1 day, 2 hours, and 30 minutes").
+sources:
+  - 'northguild/gmt:packages/gmt/src/duration/index.ts'
+  - 'northguild/gmt:packages/gmt/src/duration/calculate/getDurationUnit.ts'
+  - 'northguild/gmt:packages/gmt/src/duration/calculate/durationAs.ts'
+  - 'northguild/gmt:packages/gmt/src/duration/calculate/negateDuration.ts'
+  - 'northguild/gmt:packages/gmt/src/duration/calculate/absDuration.ts'
+  - 'northguild/gmt:packages/gmt/src/duration/calculate/getDurationSign.ts'
+  - 'northguild/gmt:packages/gmt/src/duration/compare/compareDurations.ts'
+  - 'northguild/gmt:packages/gmt/src/plain/calculate/diffDateAsDuration.ts'
+  - 'northguild/gmt:packages/gmt/src/plain/calculate/diffDateTimeAsDuration.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/calculate/diffZonedAsDuration.ts'
+  - 'northguild/gmt:packages/gmt/src/unix/calculate/diffUnixAsDuration.ts'
+  - 'northguild/gmt:packages/gmt/src/utc/calculate/diffUtcAsDuration.ts'
+metadata:
+  type: core
+  library: '@northguild/gmt'
+  library_version: '1.14.2'
+---
+
+# Durations
+
+Use this skill when you need to parse, validate, re-normalize, or format ISO 8601 duration strings — distinct from date/time arithmetic, which takes a `{ unit: number }` object rather than a duration string. See the `calculate-dates` skill for `add*`/`subtract*`/`diff*`.
+
+## Setup
+
+```ts
+import {
+  absDuration,
+  addDuration,
+  compareDurations,
+  durationAs,
+  formatDuration,
+  getDurationSign,
+  getDurationUnit,
+  isValidDuration,
+  negateDuration,
+  normalizeDuration,
+  parseDuration,
+  subtractDuration,
+} from "@northguild/gmt";
+```
+
+## Core Patterns
+
+### Validate an ISO 8601 duration string
+
+```ts
+const valid = isValidDuration("P1DT2H30M"); // true
+const invalid = isValidDuration("not a duration"); // false
+const empty = isValidDuration(""); // false
+```
+
+### Parse and re-normalize a duration string
+
+```ts
+const result = parseDuration("P1DT2H30M"); // "P1DT2H30M"
+const invalid = parseDuration("not a duration"); // ""
+```
+
+### Round a duration's output precision
+
+```ts
+// smallestUnit rounds down to whole units of the given granularity
+const rounded = parseDuration("PT1.5S", { smallestUnit: "second" }); // "PT1S"
+
+// fractionalSecondDigits pads/truncates the fractional-seconds component
+const padded = parseDuration("PT1.5S", { fractionalSecondDigits: 3 }); // "PT1.500S"
+
+// roundingMode controls how rounding is performed (default halfExpand)
+const truncated = parseDuration("PT1.9S", {
+  smallestUnit: "second",
+  roundingMode: "trunc",
+}); // "PT1S"
+```
+
+### Combine two duration strings
+
+```ts
+const combined = addDuration("P1D", "PT2H"); // "P1DT2H"
+const remainder = subtractDuration("P1D", "PT2H"); // "PT22H"
+const negative = subtractDuration("PT1H", "PT2H"); // "-PT1H"
+```
+
+### Roll small units into larger ones
+
+```ts
+// largestUnit promotes into a bigger unit
+const promoted = normalizeDuration("PT90M", { largestUnit: "hour" }); // "PT1H30M"
+
+// smallestUnit rounds off sub-unit precision, no largestUnit required
+const rounded = normalizeDuration("PT90M30S", { smallestUnit: "minute" }); // "PT91M"
+
+// no options defaults to largestUnit: "auto" — reformats without promoting
+const reformatted = normalizeDuration("PT90M"); // "PT90M" (unchanged)
+
+// calendar units (year/month/week) need relativeTo as a reference point
+const noRef = normalizeDuration("P45D", { largestUnit: "month" }); // ""
+const withRef = normalizeDuration("P45D", {
+  largestUnit: "month",
+  relativeTo: "2024-01-01",
+}); // "P1M14D"
+```
+
+### Read one component out of a duration
+
+`getDurationUnit` returns the component **as stored**, not a converted total.
+
+```ts
+const hours = getDurationUnit("P1DT2H30M", "hours"); // 2
+const minutes = getDurationUnit("P1DT2H30M", "minutes"); // 30
+
+// "PT90M" stores 90 in its minutes field and nothing in its hours field
+const noHours = getDurationUnit("PT90M", "hours"); // 0
+
+// a negative duration stores every field as negative
+const negative = getDurationUnit("-P1DT2H", "hours"); // -2
+
+// reading a field is not a unit conversion, so calendar units need no relativeTo
+const months = getDurationUnit("P1M", "months"); // 1
+
+const invalid = getDurationUnit("not a duration", "hours"); // null
+```
+
+### Total a duration into a single unit
+
+`durationAs` converts the whole duration and returns a fractional number.
+
+```ts
+const asHours = durationAs("P1DT2H30M", "hours"); // 26.5
+const asMinutes = durationAs("P1DT2H30M", "minutes"); // 1590
+const asDays = durationAs("PT36H", "days"); // 1.5 — fractional, not rounded
+
+// calendar units need a relativeTo anchor, in either direction
+const noAnchor = durationAs("P1M", "days"); // null
+const feb = durationAs("P1M", "days", { relativeTo: "2024-02-01" }); // 29
+const jan = durationAs("P1M", "days", { relativeTo: "2024-01-01" }); // 31
+
+// a zoned anchor resolves real elapsed time across a DST transition
+const springForward = durationAs("P1D", "hours", {
+  relativeTo: "2024-03-10T00:00:00-05:00[America/New_York]",
+}); // 23
+```
+
+### Flip, drop, or test a duration's sign
+
+```ts
+const negated = negateDuration("P1DT2H"); // "-P1DT2H"
+const backAgain = negateDuration("-P1DT2H"); // "P1DT2H"
+const positive = absDuration("-P1DT2H"); // "P1DT2H"
+
+const sign = getDurationSign("-P1DT2H"); // -1
+const zero = getDurationSign("PT0S"); // 0
+const invalid = getDurationSign("not a duration"); // null
+
+// all three are pure sign operations — calendar units work, no relativeTo needed
+const negatedMonth = negateDuration("P1Y2M"); // "-P1Y2M"
+```
+
+### Compare two durations by length
+
+```ts
+const longer = compareDurations("PT1H", "PT30M"); // 1
+const shorter = compareDurations("PT30M", "PT1H"); // -1
+
+// equal by length, not by spelling
+const equal = compareDurations("PT60M", "PT1H"); // 0
+
+// unlike addDuration, Temporal.Duration.compare DOES take relativeTo, so
+// calendar-unit durations are comparable — the anchor decides the answer
+const noAnchor = compareDurations("P1M", "P30D"); // null
+const fromJan = compareDurations("P1M", "P30D", { relativeTo: "2024-01-01" }); // 1
+const fromFeb = compareDurations("P1M", "P30D", { relativeTo: "2024-02-01" }); // -1
+```
+
+### Render a duration as human-readable text
+
+```ts
+const long = formatDuration("P1DT2H30M", "en-US");
+// "1 day, 2 hours, and 30 minutes"
+
+const short = formatDuration("P1DT2H30M", "en-US", { style: "short" });
+// "1 day, 2 hr, & 30 min"
+
+const narrow = formatDuration("P1DT2H30M", "en-US", { style: "narrow" });
+// "1d, 2h, & 30m"
+
+// zero-valued components are omitted by default
+const noZeros = formatDuration("P1DT0H30M", "en-US"); // "1 day and 30 minutes"
+const withZeros = formatDuration("P1DT0H30M", "en-US", { zero: true });
+// "0 years, 0 months, 0 weeks, 1 day, 0 hours, 30 minutes, and 0 seconds"
+
+// a zero-length duration always renders "0 seconds"
+const zero = formatDuration("PT0S", "en-US"); // "0 seconds"
+```
+
+### Bridge a diff into an ISO duration string
+
+`diffDate`/`diffDateTime`/`diffZoned`/`diffUnix`/`diffUtc` return a single-unit number (or a `Record<Unit, number>` for an array of units). Their `*AsDuration` siblings return an ISO 8601 duration string instead — the same string shape every other function in this skill consumes/produces.
+
+```ts
+import { diffDateAsDuration, diffZonedAsDuration } from "@northguild/gmt";
+
+const span = diffDateAsDuration("2024-03-10", "2024-04-05", "days"); // "P26D"
+
+const negative = diffDateAsDuration("2024-04-05", "2024-03-10", "days"); // "-P26D"
+
+const zoned = diffZonedAsDuration(
+  "2024-03-09T12:00:00-05:00[America/New_York]",
+  "2024-03-11T12:00:00-04:00[America/New_York]",
+  "days",
+); // "P1DT23H" — real elapsed time across a DST spring-forward transition
+```
+
+Feed the result straight into a `duration` namespace function, e.g. `formatDuration(diffDateAsDuration(a, b, "days"), "en-US")`.
+
+## Common Mistakes
+
+### HIGH Confusing duration strings with unit objects
+
+Wrong:
+
+```ts
+import { addDate } from "@northguild/gmt";
+
+// addDate takes a { unit: number } object, not an ISO duration string
+const result = addDate("2024-03-15", "P5D");
+```
+
+Correct:
+
+```ts
+import { addDate } from "@northguild/gmt";
+
+const result = addDate("2024-03-15", { days: 5 }); // "2024-03-20"
+```
+
+Source: packages/gmt/src/plain/calculate/addDate.ts — accepts `Partial<Record<DateDurationUnit, number>>`, not a duration string
+
+### MEDIUM Not validating before parsing
+
+Wrong:
+
+```ts
+const result = parseDuration(userInput);
+// assume result is a valid duration string
+useDuration(result);
+```
+
+Correct:
+
+```ts
+import { isValidDuration, parseDuration } from "@northguild/gmt";
+
+if (!isValidDuration(userInput)) {
+  throw new Error("Invalid duration");
+}
+const result = parseDuration(userInput);
+```
+
+Source: packages/gmt/src/duration/parse/parseDuration.ts — returns `""` on invalid input rather than throwing
+
+### MEDIUM Expecting a best-effort answer for calendar units without relativeTo
+
+`"P1M"` has no fixed length, so nothing in this namespace will guess one for you. Every function that has to *measure* a duration returns its sentinel (`""` for strings, `null` for numbers) when a year/month/week is involved and no `relativeTo` anchor was supplied — it does not fall back to a nominal 30-day month.
+
+Wrong:
+
+```ts
+import { addDuration, compareDurations, durationAs } from "@northguild/gmt";
+
+const combined = addDuration("P1Y", "P1M"); // ""
+const asDays = durationAs("P1M", "days"); // null — not 30
+const ordered = compareDurations("P1M", "P30D"); // null
+```
+
+Correct: supply `relativeTo` wherever the function accepts one. Note the three tiers, which differ by what Temporal itself allows:
+
+```ts
+import {
+  absDuration,
+  compareDurations,
+  durationAs,
+  getDurationSign,
+  getDurationUnit,
+  negateDuration,
+  normalizeDuration,
+} from "@northguild/gmt";
+
+// 1. Takes relativeTo — pass it and calendar units work
+durationAs("P1M", "days", { relativeTo: "2024-02-01" }); // 29
+compareDurations("P1M", "P30D", { relativeTo: "2024-01-01" }); // 1
+normalizeDuration("P45D", { largestUnit: "month", relativeTo: "2024-01-01" }); // "P1M14D"
+
+// 2. Never needs relativeTo — reads a stored field or flips a sign, no measuring
+getDurationUnit("P1M", "months"); // 1
+getDurationSign("-P1Y"); // -1
+negateDuration("P1Y2M"); // "-P1Y2M"
+absDuration("-P1Y2M"); // "P1Y2M"
+
+// 3. Has no relativeTo option at all — use addDate/subtractDate with a unit object
+addDuration("P1Y", "P1M"); // "" — no way to make this work
+```
+
+`durationAs`'s rule cuts in both directions, and the requested-unit half bites even on day/time-only input:
+
+```ts
+durationAs("PT36H", "weeks"); // null — a week is a calendar quantity to Temporal
+durationAs("P1M", "hours"); // null — the input's month component needs an anchor
+```
+
+The anchor decides the answer rather than merely unblocking it: `compareDurations("P1M", "P30D", { relativeTo: "2024-01-01" })` is `1` (January is 31 days) while the same call anchored to `"2024-02-01"` is `-1` (February 2024 is 29). It matters for non-calendar units too when the anchor names a zoned instant — `durationAs("P1D", "hours", { relativeTo: "2024-03-10T00:00:00-05:00[America/New_York]" })` is `23`, not `24`, because that day spans a DST spring-forward.
+
+Source: packages/gmt/src/duration/calculate/addDuration.ts (`Temporal.Duration.prototype.add`/`.subtract` have no `relativeTo` option, so calendar-unit operands throw and result in `""`), packages/gmt/src/duration/calculate/durationAs.ts and packages/gmt/src/duration/compare/compareDurations.ts (`.total()` and `Temporal.Duration.compare` both accept `relativeTo` and require it for calendar units)
+
+`relativeTo` also accepts a GMT calendar-annotated `PlainDate` string (E5, e.g. `"5784-06-15[u-ca=hebrew]"`, as produced by `convertDateToCalendar`) — not Temporal's own differently-shaped `[u-ca=...]` convention. `durationAs`, `compareDurations`, and `normalizeDuration` all resolve it the same way:
+
+```ts
+durationAs("P1Y", "days", { relativeTo: "5784-06-15[u-ca=hebrew]" }); // 385, not the 366 a Gregorian P1Y would total — a Hebrew leap year
+```
+
+### HIGH Reading a component with getDurationUnit when you wanted a total
+
+`getDurationUnit` reads the named field **as stored**; `durationAs` converts the whole duration. They disagree whenever the duration isn't already spelled in the unit you're asking for, and `getDurationUnit`'s wrong answer is a plausible-looking `0` rather than an error.
+
+Wrong:
+
+```ts
+import { getDurationUnit } from "@northguild/gmt";
+
+// "PT90M" holds 90 in its minutes field and nothing in its hours field
+const hours = getDurationUnit("PT90M", "hours"); // 0, not 1.5
+```
+
+Correct:
+
+```ts
+import { durationAs, getDurationUnit } from "@northguild/gmt";
+
+const total = durationAs("PT90M", "hours"); // 1.5 — the whole duration in hours
+const stored = getDurationUnit("P1DT2H30M", "hours"); // 2 — the hours component itself
+```
+
+`durationAs` returns a fractional total and never rounds — `durationAs("P1DT2H30M", "days")` is `1.1041666666666667`. If you want a rebalanced duration *string* rather than a number, reach for `normalizeDuration("PT90M", { largestUnit: "hour" })` instead.
+
+Source: packages/gmt/src/duration/calculate/getDurationUnit.ts (reads `Temporal.Duration`'s field directly) vs. packages/gmt/src/duration/calculate/durationAs.ts (wraps `Temporal.Duration.prototype.total`)
+
+### MEDIUM Assuming `normalizeDuration`'s default is always `relativeTo`-free
+
+Wrong:
+
+```ts
+import { normalizeDuration } from "@northguild/gmt";
+
+// input already has a month component — the "auto" default does NOT
+// exempt calendar-unit inputs, this still throws internally and returns ""
+const result = normalizeDuration("P1M"); // ""
+```
+
+Correct: pass `relativeTo` whenever a calendar unit (year/month/week) is involved — either as an explicit `largestUnit`, or because the input duration itself already has a nonzero year/month/week component, even under the default `{ largestUnit: "auto" }`.
+
+```ts
+import { normalizeDuration } from "@northguild/gmt";
+
+const result = normalizeDuration("P1M", {
+  largestUnit: "day",
+  relativeTo: "2024-01-01",
+}); // "P31D"
+```
+
+Source: packages/gmt/src/duration/normalize/normalizeDuration.ts — `Temporal.Duration.prototype.round` requires `relativeTo` for any week-or-larger unit, whether requested via `largestUnit` or already present in the duration being rounded
+
+### MEDIUM Expecting `formatDuration` to match native `Intl.DurationFormat` output exactly
+
+`formatDuration` does not use `Intl.DurationFormat` — that constructor is absent entirely on Node 20/22 (only ships natively on Node 24+), and GMT does not carry a polyfill dependency for it. Instead, `formatDuration` builds its output from `Intl.NumberFormat({ style: "unit" })` per component plus `Intl.ListFormat` for joining — both universally available, so behavior is identical across all supported Node versions, but output is not guaranteed byte-for-byte identical to what native `Intl.DurationFormat` would produce (e.g. no `"digital"` `01:30:00`-style output is supported).
+
+Source: packages/gmt/src/duration/format/formatDuration.ts
+
+### MEDIUM Passing an array of units to a `*AsDuration` bridge function
+
+Wrong:
+
+```ts
+import { diffDateAsDuration } from "@northguild/gmt";
+
+// diffDate accepts unit | unit[], but diffDateAsDuration only accepts a
+// single unit — an array here fails validation and returns ""
+const result = diffDateAsDuration("2024-03-10", "2024-04-05", ["days"]); // ""
+```
+
+Correct: pass a single unit. It only sets the resulting duration's `largestUnit` — an ISO duration string already expresses a full multi-unit breakdown (e.g. `"P1DT23H"`) without needing an array of requested units the way `diffDate`'s `Record<Unit, number>` return shape does.
+
+```ts
+import { diffDateAsDuration } from "@northguild/gmt";
+
+const result = diffDateAsDuration("2024-03-10", "2024-04-05", "days"); // "P26D"
+```
+
+Source: packages/gmt/src/plain/calculate/diffDateAsDuration.ts (and its `diffDateTimeAsDuration`/`diffZonedAsDuration`/`diffUnixAsDuration`/`diffUtcAsDuration` siblings) — signature takes `unit: DateDurationUnit`, not `unit: DateDurationUnit | DateDurationUnit[]` like their counterparts
+
+## References
+
+- [Temporal.Duration](https://tc39.es/proposal-temporal/docs/duration.html)