@northguild/gmt 1.18.0 → 1.20.0

package/dist/calendar/validate/isValidFiscalPattern.d.ts

@@ -2,21 +2,21 @@ import type { FiscalPattern } from "../../types/index.js";
 /**
  * Return true when `pattern` is a valid FiscalPattern.
  *
- * - Valid patterns are: "4-5-4" (the NRF retail calendar), "4-4-5", "5-4-4".
+ * - Valid patterns are: "4-5-4", "4-4-5", "5-4-4". One published 4-5-4 example is the NRF
+ *   retail calendar (US).
  * - Accepts any input type and returns false for non-string values.
  * - Uses type assertion to narrow the type.
- * - `getFiscalPeriod` returns null for a pattern it does not recognise — the same sentinel it
- *   returns for a date it cannot place. Check the pattern here to tell a misconfigured
- *   calendar apart from an unusable date: a pattern read from config, an env var or a form is
- *   a bare string until something narrows it.
+ * - A pattern read from config, an env var or a form is a bare string until something narrows
+ *   it. Narrow it here; to check a whole calendar before `getFiscalPeriod`, whose null also
+ *   means an invalid date, use `isValidFiscalCalendar`.
  *
  * @param pattern candidate value of any type
  * @returns boolean indicating validity
  *
- * @example isValidFiscalPattern("4-5-4") // true (the NRF retail calendar)
+ * @example isValidFiscalPattern("4-5-4") // true
  * @example isValidFiscalPattern("4-4-5") // true
  * @example isValidFiscalPattern("5-4-4") // true
- * @example isValidFiscalPattern("4-5-5") // false (the shape a 53-week year's last quarter takes, not a pattern)
+ * @example isValidFiscalPattern("4-5-5") // false (a 53-week year's last quarter under `"lastPeriod"`, not a pattern)
  * @example isValidFiscalPattern("454") // false
  * @example isValidFiscalPattern("invalid") // false
  * @example isValidFiscalPattern(454) // false

package/dist/calendar/validate/isValidFiscalPattern.js

@@ -1,21 +1,21 @@
 /**
  * Return true when `pattern` is a valid FiscalPattern.
  *
- * - Valid patterns are: "4-5-4" (the NRF retail calendar), "4-4-5", "5-4-4".
+ * - Valid patterns are: "4-5-4", "4-4-5", "5-4-4". One published 4-5-4 example is the NRF
+ *   retail calendar (US).
  * - Accepts any input type and returns false for non-string values.
  * - Uses type assertion to narrow the type.
- * - `getFiscalPeriod` returns null for a pattern it does not recognise — the same sentinel it
- *   returns for a date it cannot place. Check the pattern here to tell a misconfigured
- *   calendar apart from an unusable date: a pattern read from config, an env var or a form is
- *   a bare string until something narrows it.
+ * - A pattern read from config, an env var or a form is a bare string until something narrows
+ *   it. Narrow it here; to check a whole calendar before `getFiscalPeriod`, whose null also
+ *   means an invalid date, use `isValidFiscalCalendar`.
  *
  * @param pattern candidate value of any type
  * @returns boolean indicating validity
  *
- * @example isValidFiscalPattern("4-5-4") // true (the NRF retail calendar)
+ * @example isValidFiscalPattern("4-5-4") // true
  * @example isValidFiscalPattern("4-4-5") // true
  * @example isValidFiscalPattern("5-4-4") // true
- * @example isValidFiscalPattern("4-5-5") // false (the shape a 53-week year's last quarter takes, not a pattern)
+ * @example isValidFiscalPattern("4-5-5") // false (a 53-week year's last quarter under `"lastPeriod"`, not a pattern)
  * @example isValidFiscalPattern("454") // false
  * @example isValidFiscalPattern("invalid") // false
  * @example isValidFiscalPattern(454) // false

package/dist/calendar/validate/isValidFiscalYearLabel.d.ts

@@ -0,0 +1,20 @@
+import type { FiscalYearLabel } from "../../types/index.js";
+/**
+ * Return true when `value` is a valid FiscalYearLabel: the rule that picks the calendar year
+ * naming a fiscal year.
+ *
+ * - Valid values are `"startYear"`, `"endYear"` and `"majorityYear"`.
+ * - Accepts any input type and returns false for non-string values.
+ * - Use it to narrow a value read from config, an env var or a form before building a
+ *   `FiscalCalendar` or passing `getQuarter` its options.
+ *
+ * @param value candidate value of any type
+ * @returns boolean indicating validity
+ *
+ * @example isValidFiscalYearLabel("startYear") // true
+ * @example isValidFiscalYearLabel("endYear") // true
+ * @example isValidFiscalYearLabel("majorityYear") // true
+ * @example isValidFiscalYearLabel("fiscalYear") // false
+ * @example isValidFiscalYearLabel(null) // false
+ */
+export declare function isValidFiscalYearLabel(value: unknown): value is FiscalYearLabel;

package/dist/calendar/validate/isValidFiscalYearLabel.js

@@ -0,0 +1,24 @@
+/**
+ * Return true when `value` is a valid FiscalYearLabel: the rule that picks the calendar year
+ * naming a fiscal year.
+ *
+ * - Valid values are `"startYear"`, `"endYear"` and `"majorityYear"`.
+ * - Accepts any input type and returns false for non-string values.
+ * - Use it to narrow a value read from config, an env var or a form before building a
+ *   `FiscalCalendar` or passing `getQuarter` its options.
+ *
+ * @param value candidate value of any type
+ * @returns boolean indicating validity
+ *
+ * @example isValidFiscalYearLabel("startYear") // true
+ * @example isValidFiscalYearLabel("endYear") // true
+ * @example isValidFiscalYearLabel("majorityYear") // true
+ * @example isValidFiscalYearLabel("fiscalYear") // false
+ * @example isValidFiscalYearLabel(null) // false
+ */
+export function isValidFiscalYearLabel(value) {
+    if (typeof value !== "string") {
+        return false;
+    }
+    return (value === "startYear" || value === "endYear" || value === "majorityYear");
+}

package/dist/calendar/validate/isValidRollConvention.js

@@ -1,11 +1,4 @@
-const ROLL_CONVENTIONS = [
-    "following",
-    "modifiedFollowing",
-    "preceding",
-    "modifiedPreceding",
-    "endOfMonth",
-    "none",
-];
+import { isRollConventionName } from "../../internal/inputChecks.js";
 /**
  * Return true when `convention` is a `RollConvention` that `rollDate` implements.
  *
@@ -33,6 +26,5 @@ const ROLL_CONVENTIONS = [
  * @example isValidRollConvention(null) // false
  */
 export function isValidRollConvention(convention) {
-    return (typeof convention === "string" &&
-        ROLL_CONVENTIONS.includes(convention));
+    return isRollConventionName(convention);
 }

package/dist/calendar/validate/isValidZoneBucketUnit.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "../../internal/temporal.js";
 import type { ZoneBucketUnit } from "../../types/index.js";
 /**
  * Return true when `unit` is a valid ZoneBucketUnit.

package/dist/duration/calculate/absDuration.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { isValidDuration } from "../validate/isValidDuration.js";
 /**
  * Return the absolute value of an ISO 8601 duration string.

package/dist/duration/calculate/addDuration.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { isValidDuration } from "../validate/isValidDuration.js";
 /**
  * Combine two ISO 8601 duration strings by addition.

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 "../../internal/temporal.js";
+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/getDurationSign.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { isValidDuration } from "../validate/isValidDuration.js";
 /**
  * Report whether an ISO 8601 duration is negative, zero-length, or positive.

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

@@ -1,14 +1,14 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import type { DateTimeDurationUnit } from "../../types/index.js";
 /**
  * Read a single component out of an ISO 8601 duration string.
  *
  * - 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

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
 import { isValidDuration } from "../validate/isValidDuration.js";
 import { resolveDurationUnit } from "../../internal/resolveDurationUnit.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

@@ -1,11 +1,11 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { isValidDuration } from "../validate/isValidDuration.js";
 /**
  * Flip the sign of an ISO 8601 duration string.
  *
  * - 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/subtractDuration.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { isValidDuration } from "../validate/isValidDuration.js";
 /**
  * Combine two ISO 8601 duration strings by subtraction.

package/dist/duration/calculate/{durationAs.d.ts → totalDuration.d.ts}

@@ -1,17 +1,23 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 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
- *   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.
+ *   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.
  * - 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
@@ -23,7 +29,7 @@ import type { DateTimeDurationUnit, DurationRelativeTo } from "../../types/index
  *   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]"`).
+ *   for a zoned string (`"2024-02-24[u-ca=hebrew]"`, `"2024-02-24T00:00:00+02:00[Asia/Jerusalem][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
@@ -38,22 +44,22 @@ import type { DateTimeDurationUnit, DurationRelativeTo } from "../../types/index
  * @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-31T00:00:00+00:00[Europe/London]" }) // 23 (spring-forward)
+ * @example totalDuration("P1D", "hours", { relativeTo: "2024-04-07T02:30[Australia/Sydney]" }) // 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 durationAs(value: string, unit: DateTimeDurationUnit | Temporal.DateTimeUnit, options?: {
+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.

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

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { durationTotal, resolveDurationRelativeTo } from "../../internal/index.js";
 import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
 import { isValidDuration } from "../validate/isValidDuration.js";
@@ -8,14 +8,20 @@ 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.
+ *   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.
  * - 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
@@ -27,7 +33,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   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]"`).
+ *   for a zoned string (`"2024-02-24[u-ca=hebrew]"`, `"2024-02-24T00:00:00+02:00[Asia/Jerusalem][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
@@ -42,22 +48,22 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @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-31T00:00:00+00:00[Europe/London]" }) // 23 (spring-forward)
+ * @example totalDuration("P1D", "hours", { relativeTo: "2024-04-07T02:30[Australia/Sydney]" }) // 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;