@northguild/gmt 1.17.0 → 1.19.0

package/dist/calendar/hours/recurringWindows.d.ts

@@ -0,0 +1,68 @@
+import type { Disambiguation, Interval, OperatingSchedule } from "../../types/index.js";
+/**
+ * Return the instants a weekly pattern of local windows is open inside `range`, read in
+ * `timeZone`: the primitive under operating hours, curfews and recurring crew windows.
+ *
+ * - `weekly` maps ISO weekdays (1 = Monday … 7 = Sunday) to `LocalWindow`s of wall time. A
+ *   window whose `to` is at or before its `from` wraps past midnight and belongs to the date it
+ *   starts on: `{ from: "23:00", to: "06:00" }` under 5 is Friday 23:00 to Saturday 06:00, and
+ *   `{ from: "00:00", to: "00:00" }` is the whole day. No holidays or overrides; see
+ *   `operatingIntervals` for those.
+ * - Each window edge is a local wall time resolved with `resolveLocal`. An edge in a skipped
+ *   spring-forward hour is shifted by the gap: forward, or back when it is read `"earlier"` (TC39
+ *   DisambiguatePossibleEpochNanoseconds), so in a zone that skips midnight a date's early
+ *   window can open on the previous local date, before the date's own first instant; it still
+ *   belongs to its own date.
+ * - A window "reaches the range" for `"reject"` when the widest span it could cover (its `from`
+ *   read `"earlier"`, its `to` read `"later"`) overlaps `range`. A rejected window elsewhere
+ *   does not matter.
+ * - Windows are elapsed time between their resolved edges, so the wall-clock length is not the
+ *   real one on transition nights: in New York, 23:00–06:00 is 8 hours across the fall-back
+ *   night and 6 across the spring-forward one, and 00:00–00:00 is 25 and 23 hours.
+ * - A window whose edges resolve to an empty or inverted span on a transition night — only a
+ *   window shorter than the gap it straddles — is empty that day and left out.
+ * - The result is clipped to `range` (half-open), sorted, and merged where windows overlap or
+ *   touch, so a run of whole-day windows is one interval. Endpoints are UTC instants ending in
+ *   `Z`, except a clipped edge, which is `range`'s own string.
+ * - Local dates follow the zone's real days: a date the zone deleted (`Pacific/Apia` skipped
+ *   2011-12-30) has no windows, and a date re-entered after a fall-back is counted once.
+ * - `[]` is both a legitimate result (closed throughout, or an empty `range`) and the sentinel.
+ * - Returns `[]` when `weekly` has a key other than `"1"`–`"7"` or a malformed window, when
+ *   `range` is not a valid `Interval`, when `timeZone` is invalid, when `disambiguation` is not
+ *   one of the four values, and when the range spans more than 10,000 local dates (about 27
+ *   years) counted from the date `range.start` falls on, rather than a truncated list.
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the first instant Temporal supports
+ *   (`-271821-04-20T00:00:00Z`), for an offset west of UTC, this returns `[]`. An offset to the
+ *   minute has no such limit.
+ *
+ * @param weekly windows by ISO weekday, `{ 1: [{ from: "09:00", to: "17:00" }], … }`
+ * @param range `{ start, end }` record of ISO 8601 instant strings to expand the pattern inside
+ * @param timeZone IANA name or UTC offset the windows are read in: a time zone identifier
+ *   (`+05:30`, `+0530`, `-08`) or a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
+ * @param optionsArg How a window edge on a clock change is resolved
+ * @returns sorted, merged `{ start, end }` records of the open instants, or [] on invalid input
+ *
+ * @example recurringWindows({ 1: [{ from: "09:00", to: "17:00" }] }, { start: "2024-06-10T00:00:00Z", end: "2024-06-11T00:00:00Z" }, "America/New_York") // [{ start: "2024-06-10T13:00:00Z", end: "2024-06-10T21:00:00Z" }]
+ * @example recurringWindows({ 5: [{ from: "23:00", to: "06:00" }] }, { start: "2024-06-14T00:00:00Z", end: "2024-06-16T00:00:00Z" }, "UTC") // [{ start: "2024-06-14T23:00:00Z", end: "2024-06-15T06:00:00Z" }] — Friday night into Saturday
+ * @example 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
+ * @example recurringWindows({ 7: [{ from: "02:30", to: "04:00" }] }, { start: "2024-03-10T00:00:00Z", end: "2024-03-11T00:00:00Z" }, "America/New_York") // [{ start: "2024-03-10T07:30:00Z", end: "2024-03-10T08:00:00Z" }] — 02:30 does not exist; "compatible" reads it as 03:30
+ * @example recurringWindows({ 7: [{ from: "02:30", to: "04:00" }] }, { start: "2024-03-10T00:00:00Z", end: "2024-03-11T00:00:00Z" }, "America/New_York", { disambiguation: "reject" }) // []
+ * @example recurringWindows({ 1: [{ from: "00:00", to: "00:00" }], 2: [{ from: "00:00", to: "00:00" }] }, { start: "2024-06-10T00:00:00Z", end: "2024-06-13T00:00:00Z" }, "UTC") // [{ start: "2024-06-10T00:00:00Z", end: "2024-06-12T00:00:00Z" }] — touching days merge
+ * @example recurringWindows({ 8: [{ from: "09:00", to: "17:00" }] }, { start: "2024-06-10T00:00:00Z", end: "2024-06-11T00:00:00Z" }, "UTC") // [] — not an ISO weekday
+ * @example recurringWindows({ 1: [{ from: "9am", to: "17:00" }] }, { start: "2024-06-10T00:00:00Z", end: "2024-06-11T00:00:00Z" }, "UTC") // [] — malformed window
+ * @example recurringWindows({ 1: [{ from: "09:00", to: "17:00" }] }, { start: "2024-06-10T00:00:00Z", end: "2024-06-11T00:00:00Z" }, "Invalid/Zone") // []
+ * @example recurringWindows({ 4: [{ from: "08:00", to: "17:00" }] }, { start: "1970-01-01T00:00:00Z", end: "1970-01-02T00:00:00Z" }, "-00:44:30") // [{ start: "1970-01-01T08:44:30Z", end: "1970-01-01T17:44:30Z" }]
+ */
+export declare function recurringWindows(weekly: OperatingSchedule["weekly"], range: Interval, timeZone: string, optionsArg?: {
+    /**
+     * How a window edge in a repeated or skipped local hour becomes an instant, as `resolveLocal`
+     * resolves it. `"compatible"` takes the earlier instant of a repeated fall-back hour and the
+     * later one of a skipped spring-forward hour, and `"earlier"` and `"later"` take that side in
+     * both cases. `"reject"` returns `[]` when a window with such an edge reaches the range.
+     *
+     * @defaultValue `"compatible"`, Temporal's default.
+     */
+    disambiguation?: Disambiguation;
+}): Interval[];

package/dist/calendar/hours/recurringWindows.js

@@ -0,0 +1,88 @@
+import { parseIntervalNanoseconds, zoneFrame } from "../../internal/index.js";
+import { parseScheduleDisambiguation, parseWeeklyPattern, scheduleRunsWithin, } from "../../internal/operatingSchedule.js";
+/**
+ * Return the instants a weekly pattern of local windows is open inside `range`, read in
+ * `timeZone`: the primitive under operating hours, curfews and recurring crew windows.
+ *
+ * - `weekly` maps ISO weekdays (1 = Monday … 7 = Sunday) to `LocalWindow`s of wall time. A
+ *   window whose `to` is at or before its `from` wraps past midnight and belongs to the date it
+ *   starts on: `{ from: "23:00", to: "06:00" }` under 5 is Friday 23:00 to Saturday 06:00, and
+ *   `{ from: "00:00", to: "00:00" }` is the whole day. No holidays or overrides; see
+ *   `operatingIntervals` for those.
+ * - Each window edge is a local wall time resolved with `resolveLocal`. An edge in a skipped
+ *   spring-forward hour is shifted by the gap: forward, or back when it is read `"earlier"` (TC39
+ *   DisambiguatePossibleEpochNanoseconds), so in a zone that skips midnight a date's early
+ *   window can open on the previous local date, before the date's own first instant; it still
+ *   belongs to its own date.
+ * - A window "reaches the range" for `"reject"` when the widest span it could cover (its `from`
+ *   read `"earlier"`, its `to` read `"later"`) overlaps `range`. A rejected window elsewhere
+ *   does not matter.
+ * - Windows are elapsed time between their resolved edges, so the wall-clock length is not the
+ *   real one on transition nights: in New York, 23:00–06:00 is 8 hours across the fall-back
+ *   night and 6 across the spring-forward one, and 00:00–00:00 is 25 and 23 hours.
+ * - A window whose edges resolve to an empty or inverted span on a transition night — only a
+ *   window shorter than the gap it straddles — is empty that day and left out.
+ * - The result is clipped to `range` (half-open), sorted, and merged where windows overlap or
+ *   touch, so a run of whole-day windows is one interval. Endpoints are UTC instants ending in
+ *   `Z`, except a clipped edge, which is `range`'s own string.
+ * - Local dates follow the zone's real days: a date the zone deleted (`Pacific/Apia` skipped
+ *   2011-12-30) has no windows, and a date re-entered after a fall-back is counted once.
+ * - `[]` is both a legitimate result (closed throughout, or an empty `range`) and the sentinel.
+ * - Returns `[]` when `weekly` has a key other than `"1"`–`"7"` or a malformed window, when
+ *   `range` is not a valid `Interval`, when `timeZone` is invalid, when `disambiguation` is not
+ *   one of the four values, and when the range spans more than 10,000 local dates (about 27
+ *   years) counted from the date `range.start` falls on, rather than a truncated list.
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the first instant Temporal supports
+ *   (`-271821-04-20T00:00:00Z`), for an offset west of UTC, this returns `[]`. An offset to the
+ *   minute has no such limit.
+ *
+ * @param weekly windows by ISO weekday, `{ 1: [{ from: "09:00", to: "17:00" }], … }`
+ * @param range `{ start, end }` record of ISO 8601 instant strings to expand the pattern inside
+ * @param timeZone IANA name or UTC offset the windows are read in: a time zone identifier
+ *   (`+05:30`, `+0530`, `-08`) or a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
+ * @param optionsArg How a window edge on a clock change is resolved
+ * @returns sorted, merged `{ start, end }` records of the open instants, or [] on invalid input
+ *
+ * @example recurringWindows({ 1: [{ from: "09:00", to: "17:00" }] }, { start: "2024-06-10T00:00:00Z", end: "2024-06-11T00:00:00Z" }, "America/New_York") // [{ start: "2024-06-10T13:00:00Z", end: "2024-06-10T21:00:00Z" }]
+ * @example recurringWindows({ 5: [{ from: "23:00", to: "06:00" }] }, { start: "2024-06-14T00:00:00Z", end: "2024-06-16T00:00:00Z" }, "UTC") // [{ start: "2024-06-14T23:00:00Z", end: "2024-06-15T06:00:00Z" }] — Friday night into Saturday
+ * @example 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
+ * @example recurringWindows({ 7: [{ from: "02:30", to: "04:00" }] }, { start: "2024-03-10T00:00:00Z", end: "2024-03-11T00:00:00Z" }, "America/New_York") // [{ start: "2024-03-10T07:30:00Z", end: "2024-03-10T08:00:00Z" }] — 02:30 does not exist; "compatible" reads it as 03:30
+ * @example recurringWindows({ 7: [{ from: "02:30", to: "04:00" }] }, { start: "2024-03-10T00:00:00Z", end: "2024-03-11T00:00:00Z" }, "America/New_York", { disambiguation: "reject" }) // []
+ * @example recurringWindows({ 1: [{ from: "00:00", to: "00:00" }], 2: [{ from: "00:00", to: "00:00" }] }, { start: "2024-06-10T00:00:00Z", end: "2024-06-13T00:00:00Z" }, "UTC") // [{ start: "2024-06-10T00:00:00Z", end: "2024-06-12T00:00:00Z" }] — touching days merge
+ * @example recurringWindows({ 8: [{ from: "09:00", to: "17:00" }] }, { start: "2024-06-10T00:00:00Z", end: "2024-06-11T00:00:00Z" }, "UTC") // [] — not an ISO weekday
+ * @example recurringWindows({ 1: [{ from: "9am", to: "17:00" }] }, { start: "2024-06-10T00:00:00Z", end: "2024-06-11T00:00:00Z" }, "UTC") // [] — malformed window
+ * @example recurringWindows({ 1: [{ from: "09:00", to: "17:00" }] }, { start: "2024-06-10T00:00:00Z", end: "2024-06-11T00:00:00Z" }, "Invalid/Zone") // []
+ * @example recurringWindows({ 4: [{ from: "08:00", to: "17:00" }] }, { start: "1970-01-01T00:00:00Z", end: "1970-01-02T00:00:00Z" }, "-00:44:30") // [{ start: "1970-01-01T08:44:30Z", end: "1970-01-01T17:44:30Z" }]
+ */
+export function recurringWindows(weekly, range, timeZone, optionsArg) {
+    try {
+        const disambiguation = parseScheduleDisambiguation(optionsArg);
+        const weeklyWindows = parseWeeklyPattern(weekly);
+        const bounds = parseIntervalNanoseconds(range);
+        const frame = zoneFrame(timeZone);
+        if (disambiguation === null ||
+            weeklyWindows === null ||
+            bounds === null ||
+            typeof timeZone !== "string" ||
+            frame === null) {
+            return [];
+        }
+        const runs = scheduleRunsWithin({
+            timeZone,
+            frame,
+            weekly: weeklyWindows,
+            holidays: new Set(),
+            overrides: new Map(),
+        }, bounds, disambiguation);
+        return runs === null
+            ? []
+            : runs.map((run) => ({ start: run.startText, end: run.endText }));
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return [];
+    }
+}

package/dist/calendar/index.d.ts

@@ -1,4 +1,5 @@
 export * from "@js-temporal/polyfill";
 export * from "./business/index.js";
 export * from "./calculate/index.js";
+export * from "./hours/index.js";
 export * from "./validate/index.js";

package/dist/calendar/index.js

@@ -2,4 +2,5 @@
 export * from "@js-temporal/polyfill";
 export * from "./business/index.js";
 export * from "./calculate/index.js";
+export * from "./hours/index.js";
 export * from "./validate/index.js";

package/dist/duration/calculate/durationFromUnits.d.ts

@@ -0,0 +1,47 @@
+import type { DateTimeDurationUnit } from "../../types/index.js";
+/**
+ * Write an amount given as a unit object, such as `{ minutes: 15 }`, as an ISO 8601 duration
+ * string.
+ *
+ * - Uses Temporal.Duration.from to read the fields, then .toString() to write them.
+ * - Which function to use: `durationFromUnits` turns a unit object into the duration string that
+ *   the other duration functions take. `totalUnits` totals a unit object of exact units in one
+ *   call. `totalDuration` totals a duration string.
+ * - Takes all ten units, from years down to nanoseconds: writing a year, a month or a week needs
+ *   no date to measure from. To total a calendar amount, pass the result to `totalDuration` with
+ *   `relativeTo`.
+ * - Years down to minutes are written as given, and nothing is carried into a larger unit:
+ *   `{ minutes: 90 }` is "PT90M". `normalizeDuration` with `largestUnit` carries it.
+ * - Seconds, milliseconds, microseconds and nanoseconds are written together as one decimal
+ *   number of seconds, as Temporal's `Duration.prototype.toString` writes them:
+ *   `{ milliseconds: 1500 }` is "PT1.5S". Reading that string back gives 1 second and 500
+ *   milliseconds.
+ * - A zero amount is "PT0S", the one spelling Temporal writes for every zero duration.
+ * - Every key is a unit name in the plural, and every amount is a whole finite number. All
+ *   nonzero amounts share one sign, as Temporal requires of a duration. A unit set to `undefined`
+ *   is absent, as Temporal reads it.
+ * - An unknown key returns "", even beside a valid one. Temporal on its own ignores an unknown
+ *   key, so a misspelt `{ minutes: 15, hour: 1 }` would be written "PT15M" with no warning.
+ * - Returns "" on an object with no unit, a non-object `units` (a duration string included), an
+ *   invalid amount, or an amount past Temporal's duration range.
+ *
+ * @param units Partial<Record<DateTimeDurationUnit, number>> object holding the amount to write
+ * @returns ISO 8601 duration string, or "" on invalid input
+ *
+ * @example durationFromUnits({ minutes: 15 }) // "PT15M"
+ * @example durationFromUnits({ days: 1, hours: 12 }) // "P1DT12H"
+ * @example durationFromUnits({ minutes: 90 }) // "PT90M" (not carried into hours)
+ * @example durationFromUnits({ years: 1, months: 2 }) // "P1Y2M"
+ * @example durationFromUnits({ weeks: 1 }) // "P1W"
+ * @example durationFromUnits({ milliseconds: 1500 }) // "PT1.5S"
+ * @example durationFromUnits({ seconds: 59, milliseconds: 1500 }) // "PT60.5S" (one decimal number of seconds)
+ * @example durationFromUnits({ minutes: 15, hours: undefined }) // "PT15M" (an undefined unit is absent)
+ * @example durationFromUnits({ minutes: -15 }) // "-PT15M"
+ * @example durationFromUnits({ minutes: 0 }) // "PT0S"
+ * @example durationFromUnits({ minutes: 15, hour: 1 }) // "" (unknown key "hour")
+ * @example durationFromUnits({ minutes: 1.5 }) // "" (fractional amount)
+ * @example durationFromUnits({ hours: 1, minutes: -30 }) // "" (mixed signs)
+ * @example durationFromUnits({}) // ""
+ * @example durationFromUnits("PT15M") // "" (already a duration string)
+ */
+export declare function durationFromUnits(units: Partial<Record<DateTimeDurationUnit, number>>): string;

package/dist/duration/calculate/durationFromUnits.js

@@ -0,0 +1,67 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { readDurationUnits } from "../../internal/index.js";
+import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
+/**
+ * Write an amount given as a unit object, such as `{ minutes: 15 }`, as an ISO 8601 duration
+ * string.
+ *
+ * - Uses Temporal.Duration.from to read the fields, then .toString() to write them.
+ * - Which function to use: `durationFromUnits` turns a unit object into the duration string that
+ *   the other duration functions take. `totalUnits` totals a unit object of exact units in one
+ *   call. `totalDuration` totals a duration string.
+ * - Takes all ten units, from years down to nanoseconds: writing a year, a month or a week needs
+ *   no date to measure from. To total a calendar amount, pass the result to `totalDuration` with
+ *   `relativeTo`.
+ * - Years down to minutes are written as given, and nothing is carried into a larger unit:
+ *   `{ minutes: 90 }` is "PT90M". `normalizeDuration` with `largestUnit` carries it.
+ * - Seconds, milliseconds, microseconds and nanoseconds are written together as one decimal
+ *   number of seconds, as Temporal's `Duration.prototype.toString` writes them:
+ *   `{ milliseconds: 1500 }` is "PT1.5S". Reading that string back gives 1 second and 500
+ *   milliseconds.
+ * - A zero amount is "PT0S", the one spelling Temporal writes for every zero duration.
+ * - Every key is a unit name in the plural, and every amount is a whole finite number. All
+ *   nonzero amounts share one sign, as Temporal requires of a duration. A unit set to `undefined`
+ *   is absent, as Temporal reads it.
+ * - An unknown key returns "", even beside a valid one. Temporal on its own ignores an unknown
+ *   key, so a misspelt `{ minutes: 15, hour: 1 }` would be written "PT15M" with no warning.
+ * - Returns "" on an object with no unit, a non-object `units` (a duration string included), an
+ *   invalid amount, or an amount past Temporal's duration range.
+ *
+ * @param units Partial<Record<DateTimeDurationUnit, number>> object holding the amount to write
+ * @returns ISO 8601 duration string, or "" on invalid input
+ *
+ * @example durationFromUnits({ minutes: 15 }) // "PT15M"
+ * @example durationFromUnits({ days: 1, hours: 12 }) // "P1DT12H"
+ * @example durationFromUnits({ minutes: 90 }) // "PT90M" (not carried into hours)
+ * @example durationFromUnits({ years: 1, months: 2 }) // "P1Y2M"
+ * @example durationFromUnits({ weeks: 1 }) // "P1W"
+ * @example durationFromUnits({ milliseconds: 1500 }) // "PT1.5S"
+ * @example durationFromUnits({ seconds: 59, milliseconds: 1500 }) // "PT60.5S" (one decimal number of seconds)
+ * @example durationFromUnits({ minutes: 15, hours: undefined }) // "PT15M" (an undefined unit is absent)
+ * @example durationFromUnits({ minutes: -15 }) // "-PT15M"
+ * @example durationFromUnits({ minutes: 0 }) // "PT0S"
+ * @example durationFromUnits({ minutes: 15, hour: 1 }) // "" (unknown key "hour")
+ * @example durationFromUnits({ minutes: 1.5 }) // "" (fractional amount)
+ * @example durationFromUnits({ hours: 1, minutes: -30 }) // "" (mixed signs)
+ * @example durationFromUnits({}) // ""
+ * @example durationFromUnits("PT15M") // "" (already a duration string)
+ */
+export function durationFromUnits(units) {
+    try {
+        const amounts = readDurationUnits(units, isValidDateTimeDurationUnit);
+        if (amounts === null) {
+            return "";
+        }
+        try {
+            return Temporal.Duration.from(amounts).toString();
+        }
+        catch {
+            return "";
+        }
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
+}

package/dist/duration/calculate/getDurationUnit.d.ts

@@ -5,10 +5,10 @@ import type { DateTimeDurationUnit } from "../../types/index.js";
  *
  * - Uses Temporal.Duration.from and reads the named field directly — this is the value as
  *   *stored*, not a converted total: getDurationUnit("PT90M", "hours") is 0, because "PT90M"
- *   holds 90 in its minutes field and nothing in its hours field. Use `durationAs` for a
+ *   holds 90 in its minutes field and nothing in its hours field. Use `totalDuration` for a
  *   converted total.
  * - Never needs `relativeTo`: reading a field is not a unit conversion, so calendar units
- *   (years/months/weeks) work here even though they require an anchor in `durationAs`.
+ *   (years/months/weeks) work here even though they require an anchor in `totalDuration`.
  * - Temporal balances fractional units at parse time, so getDurationUnit("PT1.5H", "minutes")
  *   is 30 — the input's own precision, not the caller's spelling of it, decides the fields.
  * - A negative duration stores *every* field as negative, so this returns a negative number

package/dist/duration/calculate/getDurationUnit.js

@@ -7,10 +7,10 @@ import { resolveDurationUnit } from "../../internal/resolveDurationUnit.js";
  *
  * - Uses Temporal.Duration.from and reads the named field directly — this is the value as
  *   *stored*, not a converted total: getDurationUnit("PT90M", "hours") is 0, because "PT90M"
- *   holds 90 in its minutes field and nothing in its hours field. Use `durationAs` for a
+ *   holds 90 in its minutes field and nothing in its hours field. Use `totalDuration` for a
  *   converted total.
  * - Never needs `relativeTo`: reading a field is not a unit conversion, so calendar units
- *   (years/months/weeks) work here even though they require an anchor in `durationAs`.
+ *   (years/months/weeks) work here even though they require an anchor in `totalDuration`.
  * - Temporal balances fractional units at parse time, so getDurationUnit("PT1.5H", "minutes")
  *   is 30 — the input's own precision, not the caller's spelling of it, decides the fields.
  * - A negative duration stores *every* field as negative, so this returns a negative number

package/dist/duration/calculate/index.d.ts

@@ -1,7 +1,9 @@
 export * from "./absDuration.js";
 export * from "./addDuration.js";
-export * from "./durationAs.js";
+export * from "./durationFromUnits.js";
 export * from "./getDurationSign.js";
 export * from "./getDurationUnit.js";
 export * from "./negateDuration.js";
 export * from "./subtractDuration.js";
+export * from "./totalDuration.js";
+export * from "./totalUnits.js";

package/dist/duration/calculate/index.js

@@ -1,7 +1,9 @@
 export * from "./absDuration.js";
 export * from "./addDuration.js";
-export * from "./durationAs.js";
+export * from "./durationFromUnits.js";
 export * from "./getDurationSign.js";
 export * from "./getDurationUnit.js";
 export * from "./negateDuration.js";
 export * from "./subtractDuration.js";
+export * from "./totalDuration.js";
+export * from "./totalUnits.js";

package/dist/duration/calculate/negateDuration.d.ts

@@ -3,7 +3,7 @@
  *
  * - Uses Temporal.Duration.from and .negated, then .toString() to re-emit.
  * - Negating is a pure sign flip on every component, so it never needs `relativeTo` —
- *   calendar-unit durations round-trip through it fine, unlike `addDuration`/`durationAs`.
+ *   calendar-unit durations round-trip through it fine, unlike `addDuration`/`totalDuration`.
  * - A zero-length duration has no sign to flip and comes back as "PT0S", the canonical
  *   spelling Temporal emits for every zero duration (so "P0D" also renders "PT0S").
  * - Returns "" when `value` is not a valid ISO 8601 duration string.

package/dist/duration/calculate/negateDuration.js

@@ -5,7 +5,7 @@ import { isValidDuration } from "../validate/isValidDuration.js";
  *
  * - Uses Temporal.Duration.from and .negated, then .toString() to re-emit.
  * - Negating is a pure sign flip on every component, so it never needs `relativeTo` —
- *   calendar-unit durations round-trip through it fine, unlike `addDuration`/`durationAs`.
+ *   calendar-unit durations round-trip through it fine, unlike `addDuration`/`totalDuration`.
  * - A zero-length duration has no sign to flip and comes back as "PT0S", the canonical
  *   spelling Temporal emits for every zero duration (so "P0D" also renders "PT0S").
  * - Returns "" when `value` is not a valid ISO 8601 duration string.

package/dist/duration/calculate/totalDuration.d.ts

@@ -0,0 +1,73 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { DateTimeDurationUnit, DurationRelativeTo } from "../../types/index.js";
+/**
+ * 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
+ *   totalDuration("P1DT2H30M", "hours") is 26.5, not the 2 that `getDurationUnit` reads.
+ * - Which function to use: `totalDuration` takes an ISO 8601 duration string. `totalUnits` takes
+ *   a unit object of exact units, such as `{ minutes: 15 }`. `durationFromUnits` turns a unit
+ *   object into the duration string this function takes. To total a calendar amount written as a
+ *   unit object, such as `{ months: 1 }`, pass the result of `durationFromUnits` here with
+ *   `relativeTo`.
+ * - The result is fractional, not rounded: totalDuration("P1DT2H30M", "days") is
+ *   1.1041666666666667. Round it yourself, or reach for `normalizeDuration` instead. It is a
+ *   JavaScript number, so a total past 2^53 is the nearest double.
+ * - The calendar-unit rule of `relativeTo` is the same one `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 totalDuration("P1DT2H30M", "weeks") is still null — a week is a
+ *   calendar quantity to Temporal regardless of what it is being measured from.
+ * - A zoned `relativeTo` string resolves its wall time with disambiguation "compatible" and
+ *   offset "reject", as Temporal does: an ambiguous wall time takes the earlier instant, a
+ *   nonexistent one the later instant, and an offset that does not match the zone returns null.
+ *   Pass an explicit offset to pick the other reading of an ambiguous wall time.
+ * - A `relativeTo` string is ISO 8601 extended format before its first `[`:
+ *   a date, a date-time, or with a time zone annotation a zoned date-time (`<date>T<time>`, then
+ *   nothing, `Z` or `±HH:MM`). Basic format (`"20240101"`), a space or lower-case `t` separator, a
+ *   lower-case `z`, a UTC offset without a zone and a zoned date without a time are invalid.
+ * - A `relativeTo` string takes a calendar in RFC 9557 form, as `convertDateToCalendar` and
+ *   `convertZonedToCalendar` write it: ISO digits and a `[u-ca=<id>]` annotation, after the zone
+ *   for a zoned string (`"2024-02-24[u-ca=hebrew]"`, `"2024-02-24T00:00:00-05:00[America/New_York][u-ca=hebrew]"`).
+ *   The annotations are read as Temporal reads them: the critical flag and the id's letter case
+ *   are accepted, elective unknown annotations are ignored, the first `u-ca` names the calendar,
+ *   and a string with a time zone annotation is zoned. An unknown critical annotation, a critical
+ *   duplicate calendar, a calendar before the zone, an unsupported calendar and a leap second in
+ *   any spelling return null.
+ *   Compatibility: before 1.16.0 the digits were read as the calendar's own year, month and day.
+ * - `unit` accepts the plural or singular name (`"hours"` or `"hour"`), as Temporal does.
+ * - Returns null on a non-duration `value`, an invalid `unit`, or an invalid `relativeTo`.
+ *
+ * @param value ISO 8601 duration string
+ * @param unit DateTimeDurationUnit to total into ("years" | "months" | "weeks" | "days" | "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds", or the singular name)
+ * @param options The anchor calendar units are measured from
+ * @returns the fractional total in `unit`, or null on invalid input
+ *
+ * @example totalDuration("P1DT2H30M", "hours") // 26.5
+ * @example totalDuration("P1DT2H30M", "minutes") // 1590
+ * @example totalDuration("PT36H", "days") // 1.5
+ * @example totalDuration("-PT90M", "hours") // -1.5
+ * @example totalDuration("P1M", "days") // null (calendar unit needs relativeTo)
+ * @example totalDuration("P1M", "days", { relativeTo: "2024-02-01" }) // 29
+ * @example totalDuration("P1M", "days", { relativeTo: "20240201" }) // null (basic format)
+ * @example totalDuration("P1D", "hours", { relativeTo: "2024-03-10T00:00:00-05:00[America/New_York]" }) // 23 (spring-forward)
+ * @example totalDuration("P1D", "hours", { relativeTo: "2024-11-03T01:30[America/New_York]" }) // 25
+ * @example totalDuration("P1DT2H30M", "minute") // 1590 (singular unit name)
+ * @example totalDuration("not a duration", "hours") // null
+ * @example totalDuration("P1Y", "days", { relativeTo: "2024-02-24[u-ca=hebrew]" }) // 385 (Hebrew leap year 5784)
+ * @example totalDuration("P1M", "days", { relativeTo: "2024-02-10[!u-ca=hebrew]" }) // 30 (1 Adar I 5784; the critical flag is accepted)
+ * @example totalDuration("P1M", "days", { relativeTo: "2024-02-10T00:00:00[u-ca=hebrew]" }) // 30 (a date-time without a zone reads as its date, as Temporal reads relativeTo)
+ */
+export declare function totalDuration(value: string, unit: DateTimeDurationUnit | Temporal.DateTimeUnit, options?: {
+    /**
+     * The date or zoned date-time the duration is measured from. It is required whenever a year,
+     * month or week is involved, as the `unit` asked for or as a nonzero field of the duration.
+     * With a zoned value, days follow that zone's clock changes, so a day spanning a
+     * spring-forward transition totals 23 hours.
+     *
+     * @defaultValue None. Days are 24 hours, and a duration or `unit` that involves a year, month
+     * or week returns `null`.
+     */
+    relativeTo?: DurationRelativeTo;
+}): number | null;

package/dist/duration/calculate/{durationAs.js → totalDuration.js}

@@ -8,19 +8,21 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * 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.
+ *   totalDuration("P1DT2H30M", "hours") is 26.5, not the 2 that `getDurationUnit` reads.
+ * - Which function to use: `totalDuration` takes an ISO 8601 duration string. `totalUnits` takes
+ *   a unit object of exact units, such as `{ minutes: 15 }`. `durationFromUnits` turns a unit
+ *   object into the duration string this function takes. To total a calendar amount written as a
+ *   unit object, such as `{ months: 1 }`, pass the result of `durationFromUnits` here with
+ *   `relativeTo`.
+ * - The result is fractional, not rounded: totalDuration("P1DT2H30M", "days") is
+ *   1.1041666666666667. Round it yourself, or reach for `normalizeDuration` instead. It is a
+ *   JavaScript number, so a total past 2^53 is the nearest double.
+ * - The calendar-unit rule of `relativeTo` is the same one `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
+ *   no calendar component, yet totalDuration("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.
  * - A zoned `relativeTo` string resolves its wall time with disambiguation "compatible" and
  *   offset "reject", as Temporal does: an ambiguous wall time takes the earlier instant, a
  *   nonexistent one the later instant, and an offset that does not match the zone returns null.
@@ -43,25 +45,25 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *
  * @param value ISO 8601 duration string
  * @param unit DateTimeDurationUnit to total into ("years" | "months" | "weeks" | "days" | "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds", or the singular name)
- * @param options optional: { relativeTo } — anchor date/instant, required for any calendar unit
+ * @param options The anchor calendar units are measured from
  * @returns the fractional total in `unit`, or null on invalid input
  *
- * @example durationAs("P1DT2H30M", "hours") // 26.5
- * @example durationAs("P1DT2H30M", "minutes") // 1590
- * @example durationAs("PT36H", "days") // 1.5
- * @example durationAs("-PT90M", "hours") // -1.5
- * @example durationAs("P1M", "days") // null (calendar unit needs relativeTo)
- * @example durationAs("P1M", "days", { relativeTo: "2024-02-01" }) // 29
- * @example durationAs("P1M", "days", { relativeTo: "20240201" }) // null (basic format)
- * @example durationAs("P1D", "hours", { relativeTo: "2024-03-10T00:00:00-05:00[America/New_York]" }) // 23 (spring-forward)
- * @example durationAs("P1D", "hours", { relativeTo: "2024-11-03T01:30[America/New_York]" }) // 25
- * @example durationAs("P1DT2H30M", "minute") // 1590 (singular unit name)
- * @example durationAs("not a duration", "hours") // null
- * @example durationAs("P1Y", "days", { relativeTo: "2024-02-24[u-ca=hebrew]" }) // 385 (Hebrew leap year 5784)
- * @example durationAs("P1M", "days", { relativeTo: "2024-02-10[!u-ca=hebrew]" }) // 30 (1 Adar I 5784; the critical flag is accepted)
- * @example durationAs("P1M", "days", { relativeTo: "2024-02-10T00:00:00[u-ca=hebrew]" }) // 30 (a date-time without a zone reads as its date, as Temporal reads relativeTo)
+ * @example totalDuration("P1DT2H30M", "hours") // 26.5
+ * @example totalDuration("P1DT2H30M", "minutes") // 1590
+ * @example totalDuration("PT36H", "days") // 1.5
+ * @example totalDuration("-PT90M", "hours") // -1.5
+ * @example totalDuration("P1M", "days") // null (calendar unit needs relativeTo)
+ * @example totalDuration("P1M", "days", { relativeTo: "2024-02-01" }) // 29
+ * @example totalDuration("P1M", "days", { relativeTo: "20240201" }) // null (basic format)
+ * @example totalDuration("P1D", "hours", { relativeTo: "2024-03-10T00:00:00-05:00[America/New_York]" }) // 23 (spring-forward)
+ * @example totalDuration("P1D", "hours", { relativeTo: "2024-11-03T01:30[America/New_York]" }) // 25
+ * @example totalDuration("P1DT2H30M", "minute") // 1590 (singular unit name)
+ * @example totalDuration("not a duration", "hours") // null
+ * @example totalDuration("P1Y", "days", { relativeTo: "2024-02-24[u-ca=hebrew]" }) // 385 (Hebrew leap year 5784)
+ * @example totalDuration("P1M", "days", { relativeTo: "2024-02-10[!u-ca=hebrew]" }) // 30 (1 Adar I 5784; the critical flag is accepted)
+ * @example totalDuration("P1M", "days", { relativeTo: "2024-02-10T00:00:00[u-ca=hebrew]" }) // 30 (a date-time without a zone reads as its date, as Temporal reads relativeTo)
  */
-export function durationAs(value, unit, options) {
+export function totalDuration(value, unit, options) {
     if (!isOptionsArgument(options)) {
         return null;
     }

package/dist/duration/calculate/totalUnits.d.ts

@@ -0,0 +1,49 @@
+import type { ExactDurationUnit, TimeUnit } from "../../types/index.js";
+/**
+ * Express an amount written as a unit object, such as `{ minutes: 15 }`, as a single fractional
+ * total in one unit.
+ *
+ * - Uses Temporal.Duration.from and .total: every field is converted, so
+ *   totalUnits({ days: 1, hours: 12 }, "seconds") is 129600.
+ * - Which function to use: `totalUnits` takes a unit object. `totalDuration` takes an ISO 8601
+ *   duration string (`"PT15M"`). `durationFromUnits` turns a unit object into the duration string
+ *   that the other duration functions take.
+ * - Takes exact units only: days, hours, minutes, seconds, milliseconds, microseconds and
+ *   nanoseconds. A day is 24 hours, as Temporal's `Duration.prototype.total` reads a day when it
+ *   has no `relativeTo`. For a day in a time zone, which can be 23 or 25 hours across a clock
+ *   change, use `totalDuration` with a zoned `relativeTo`.
+ * - A year, a month or a week returns null, as a key and as `unit`: Temporal gives them no length
+ *   without a date to measure from. Write a week as `{ days: 7 }`. For a calendar amount, build
+ *   the string with `durationFromUnits` and pass it to `totalDuration` with `relativeTo`.
+ * - The result is fractional, not rounded: totalUnits({ hours: 36 }, "days") is 1.5. It is a
+ *   JavaScript number, so a total past 2^53 is the nearest double.
+ * - Every key is a unit name in the plural, and every amount is a whole finite number. All
+ *   nonzero amounts share one sign, as Temporal requires of a duration. A unit set to `undefined`
+ *   is absent, as Temporal reads it.
+ * - An unknown key returns null, even beside a valid one. Temporal on its own ignores an unknown
+ *   key, so a misspelt `{ minutes: 15, hour: 1 }` would total 900 with no warning.
+ * - `unit` accepts the plural or singular name (`"seconds"` or `"second"`), as Temporal does.
+ * - Returns null on an object with no unit, a non-object `units` (a duration string included), an
+ *   invalid amount, an amount past Temporal's duration range, or an invalid `unit`.
+ *
+ * @param units Partial<Record<ExactDurationUnit, number>> object holding the amount to total
+ * @param unit ExactDurationUnit to total into ("days" | "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds", or the singular name)
+ * @returns the fractional total in `unit`, or null on invalid input
+ *
+ * @example totalUnits({ minutes: 15 }, "seconds") // 900
+ * @example totalUnits({ days: 30 }, "seconds") // 2592000
+ * @example totalUnits({ days: 1, hours: 12 }, "seconds") // 129600
+ * @example totalUnits({ hours: 36 }, "days") // 1.5
+ * @example totalUnits({ minutes: -90 }, "hours") // -1.5
+ * @example totalUnits({ seconds: 10 }, "millisecond") // 10000 (singular unit name)
+ * @example totalUnits({ minutes: 0 }, "seconds") // 0
+ * @example totalUnits({ minutes: 15, hours: undefined }, "seconds") // 900 (an undefined unit is absent)
+ * @example totalUnits({ weeks: 1 }, "days") // null (a week has no exact length; write { days: 7 })
+ * @example totalUnits({ days: 7 }, "weeks") // null (a week has no exact length)
+ * @example totalUnits({ minutes: 15, hour: 1 }, "seconds") // null (unknown key "hour")
+ * @example totalUnits({ minutes: 1.5 }, "seconds") // null (fractional amount)
+ * @example totalUnits({ hours: 1, minutes: -30 }, "seconds") // null (mixed signs)
+ * @example totalUnits({}, "seconds") // null
+ * @example totalUnits("PT15M", "seconds") // null (a duration string goes to totalDuration)
+ */
+export declare function totalUnits(units: Partial<Record<ExactDurationUnit, number>>, unit: ExactDurationUnit | "day" | TimeUnit): number | null;