Skip to content
@northguild/gmt

durationAs

Playground

call
result 

Signature

Section titled “Signature”
durationAs(value: string, unit: DateTimeDurationUnit, options?: { relativeTo?: DurationRelativeTo; }): number
import { durationAs } from "@northguild/gmt/duration/calculate";

Express an ISO 8601 duration as a single fractional total in one unit.

  • Uses Temporal.Duration.from and .total — the whole duration is converted, so durationAs(“P1DT2H30M”, “hours”) is 26.5, not the 2 that getDurationUnit reads.
  • The result is fractional, not rounded: durationAs(“P1DT2H30M”, “days”) is 1.1041666666666667. Round it yourself, or reach for normalizeDuration instead.
  • relativeTo is required whenever a calendar unit (year/month/week) is involved, in either direction — as the requested unit, or because the input duration already has a nonzero year/month/week component. Without it, returns null. This is the same documented gap normalizeDuration (A3) carries; addDuration/subtractDuration (A2) have it worse still, since Temporal gives them no relativeTo option at all.
  • The requested-unit half of that rule bites even on day/time-only input: “P1DT2H30M” has no calendar component, yet durationAs(“P1DT2H30M”, “weeks”) is still null — a week is a calendar quantity to Temporal regardless of what it is being measured from.
  • relativeTo changes the answer for non-calendar units too when it names a zoned instant: a day spanning a DST spring-forward transition totals 23 hours, not 24.
  • Returns null on a non-duration value, an invalid unit, or an invalid relativeTo.

Parameters

Section titled “Parameters”
Parameter Type Description
value string ISO 8601 duration string
unit DateTimeDurationUnit DateTimeDurationUnit to total into (“years” | “months” | “weeks” | “days” | “hours” | “minutes” | “seconds” | “milliseconds” | “microseconds” | “nanoseconds”)

Options

Section titled “Options”

options

Option Type Default
relativeTo? DurationRelativeTo —

Returns

Section titled “Returns”

the fractional total in unit, or null on invalid input

Section titled “Related types”

Examples

Section titled “Examples”
durationAs("P1DT2H30M", "hours") // 26.5
durationAs("P1DT2H30M", "minutes") // 1590
durationAs("PT36H", "days") // 1.5
durationAs("-PT90M", "hours") // -1.5
durationAs("P1M", "days") // null (calendar unit needs relativeTo)
durationAs("P1M", "days", { relativeTo: "2024-02-01" }) // 29
durationAs("P1D", "hours", { relativeTo: "2024-03-10T00:00:00-05:00[America/New_York]" }) // 23 (spring-forward)
durationAs("not a duration", "hours") // null
durationAs("P1Y", "days", { relativeTo: "5784-06-15[u-ca=hebrew]" }) // 385 (Hebrew leap year — relativeTo accepts GMT's calendar-annotated PlainDate string, not Temporal's own ISO-digit u-ca convention)

Source

Section titled “Source”

duration/calculate/durationAs.ts