@northguild/gmt 1.18.0 → 1.19.0

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/{durationAs.d.ts → totalDuration.d.ts}

@@ -4,14 +4,20 @@ import type { DateTimeDurationUnit, DurationRelativeTo } from "../../types/index
  * 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
@@ -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-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 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}

@@ -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
@@ -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-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;

package/dist/duration/calculate/totalUnits.js

@@ -0,0 +1,73 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { durationTotal, readDurationUnits } from "../../internal/index.js";
+import { resolveDurationUnit } from "../../internal/resolveDurationUnit.js";
+import { isValidTimeDurationUnit } from "../../plain/validate/index.js";
+/** Whether `unit` has an exact length: `"days"` (24 hours with no anchor) or a time unit. */
+const isExactDurationUnit = (unit) => unit === "days" || isValidTimeDurationUnit(unit);
+/**
+ * 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 function totalUnits(units, unit) {
+    try {
+        const resolvedUnit = resolveDurationUnit(unit);
+        const amounts = readDurationUnits(units, isExactDurationUnit);
+        if (!isExactDurationUnit(resolvedUnit) || amounts === null) {
+            return null;
+        }
+        try {
+            return durationTotal(Temporal.Duration.from(amounts), resolvedUnit);
+        }
+        catch {
+            return null;
+        }
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}

package/dist/duration/compare/compareDurations.d.ts

@@ -9,7 +9,7 @@ import type { DurationRelativeTo } from "../../types/index.js";
  *   Temporal checks identity first. Note the asymmetry with `addDuration`/`subtractDuration`
  *   (A2): Temporal.Duration.compare *does* accept `relativeTo`, while .add/.subtract do not,
  *   so calendar-unit durations are comparable here even though they cannot be combined there.
- *   `durationAs` and `normalizeDuration` (A3) carry the same relativeTo rule as this function.
+ *   `totalDuration` and `normalizeDuration` (A3) carry the same relativeTo rule as this function.
  * - The anchor genuinely decides the answer rather than merely unblocking it: "P1M" is longer
  *   than "P30D" relative to January (31 days) and shorter relative to February 2024 (29).
  * - A zoned `relativeTo` string resolves its wall time with disambiguation "compatible" and

package/dist/duration/compare/compareDurations.js

@@ -11,7 +11,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   Temporal checks identity first. Note the asymmetry with `addDuration`/`subtractDuration`
  *   (A2): Temporal.Duration.compare *does* accept `relativeTo`, while .add/.subtract do not,
  *   so calendar-unit durations are comparable here even though they cannot be combined there.
- *   `durationAs` and `normalizeDuration` (A3) carry the same relativeTo rule as this function.
+ *   `totalDuration` and `normalizeDuration` (A3) carry the same relativeTo rule as this function.
  * - The anchor genuinely decides the answer rather than merely unblocking it: "P1M" is longer
  *   than "P30D" relative to January (31 days) and shorter relative to February 2024 (29).
  * - A zoned `relativeTo` string resolves its wall time with disambiguation "compatible" and

package/dist/duty/calculate/dutyDayFor.d.ts

@@ -0,0 +1,38 @@
+import type { DutyDay, Interval } from "../../types/index.js";
+/**
+ * Return the operator-designated day an instant falls in: from the most recent `dayStartTime`
+ * in `timeZone` at or before the instant, up to (not including) the next one.
+ *
+ * The day an hours-of-work rule counts is the operator's, not the local midnight where the
+ * person happens to be, so the reference zone and the start time are both the caller's and
+ * neither has a default.
+ *
+ * - A `dayStartTime` that a clock change skips or repeats is resolved under `day.disambiguation`,
+ *   the CORE-4 policy in `resolveLocal`. The default, `"compatible"`, reads a skipped time after
+ *   the gap (02:30 on New York's spring-forward day is 03:30) and a repeated one at its first
+ *   pass. The day that holds the change is then shorter or longer by the change: 23 or 25 hours
+ *   across a one-hour change, 24.5 across Lord Howe's 30-minute fall-back, 21 across Casey's
+ *   three-hour jump. `"reject"` returns `null` for
+ *   a day that starts or ends at such a time.
+ * - The instant is read in `timeZone` whatever offset or zone it is written with, so a log whose
+ *   entries cross zones still falls into the reference zone's days.
+ * - A date whose start resolves onto the next date's start opens no day: the date
+ *   `Pacific/Apia` deleted in 2011 is part of no operator day.
+ * - Returns `null` when `instant` is not an ISO 8601 instant string, when `day` is not an object
+ *   with a valid `timeZone` and a `dayStartTime` that `isValidTime` accepts, and when the day or
+ *   the next one starts outside Temporal's instant range.
+ *
+ * @param instant ISO 8601 instant string to place
+ * @param day the reference zone and the local time each day starts at
+ * @returns `{ start, end }` of the day as UTC instants ending in "Z", or null on invalid input
+ *
+ * @example dutyDayFor("2024-01-01T08:59:00Z", { timeZone: "America/New_York", dayStartTime: "04:00" }) // { start: "2023-12-31T09:00:00Z", end: "2024-01-01T09:00:00Z" } — 03:59 local is the previous day
+ * @example dutyDayFor("2024-01-01T09:00:00Z", { timeZone: "America/New_York", dayStartTime: "04:00" }) // { start: "2024-01-01T09:00:00Z", end: "2024-01-02T09:00:00Z" }
+ * @example dutyDayFor("2024-03-10T12:00:00Z", { timeZone: "America/New_York", dayStartTime: "02:30" }) // { start: "2024-03-10T07:30:00Z", end: "2024-03-11T06:30:00Z" } — 02:30 is skipped, read as 03:30; 23 hours
+ * @example dutyDayFor("2024-11-03T12:00:00Z", { timeZone: "America/New_York", dayStartTime: "01:30" }) // { start: "2024-11-03T05:30:00Z", end: "2024-11-04T06:30:00Z" } — 01:30 is repeated, the first pass starts it; 25 hours
+ * @example dutyDayFor("2024-11-03T12:00:00Z", { timeZone: "America/New_York", dayStartTime: "01:30", disambiguation: "later" }) // { start: "2024-11-03T06:30:00Z", end: "2024-11-04T06:30:00Z" } — the second pass; 24 hours
+ * @example dutyDayFor("2024-11-03T12:00:00Z", { timeZone: "America/New_York", dayStartTime: "01:30", disambiguation: "reject" }) // null — the day starts at a repeated time
+ * @example dutyDayFor("2024-01-01T12:00:00Z", { timeZone: "UTC" }) // null — no dayStartTime
+ * @example dutyDayFor("2024-01-01T12:00:00Z", { timeZone: "Invalid/Zone", dayStartTime: "04:00" }) // null
+ */
+export declare function dutyDayFor(instant: string, day: DutyDay): Interval | null;

package/dist/duty/calculate/dutyDayFor.js

@@ -0,0 +1,71 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isObject, parseInstantNanoseconds, zoneFrame } from "../../internal/index.js";
+import { operatorDayScale, parseDayStartTime, } from "../../internal/dutyPeriods.js";
+import { parseScheduleDisambiguation } from "../../internal/operatingSchedule.js";
+/**
+ * Return the operator-designated day an instant falls in: from the most recent `dayStartTime`
+ * in `timeZone` at or before the instant, up to (not including) the next one.
+ *
+ * The day an hours-of-work rule counts is the operator's, not the local midnight where the
+ * person happens to be, so the reference zone and the start time are both the caller's and
+ * neither has a default.
+ *
+ * - A `dayStartTime` that a clock change skips or repeats is resolved under `day.disambiguation`,
+ *   the CORE-4 policy in `resolveLocal`. The default, `"compatible"`, reads a skipped time after
+ *   the gap (02:30 on New York's spring-forward day is 03:30) and a repeated one at its first
+ *   pass. The day that holds the change is then shorter or longer by the change: 23 or 25 hours
+ *   across a one-hour change, 24.5 across Lord Howe's 30-minute fall-back, 21 across Casey's
+ *   three-hour jump. `"reject"` returns `null` for
+ *   a day that starts or ends at such a time.
+ * - The instant is read in `timeZone` whatever offset or zone it is written with, so a log whose
+ *   entries cross zones still falls into the reference zone's days.
+ * - A date whose start resolves onto the next date's start opens no day: the date
+ *   `Pacific/Apia` deleted in 2011 is part of no operator day.
+ * - Returns `null` when `instant` is not an ISO 8601 instant string, when `day` is not an object
+ *   with a valid `timeZone` and a `dayStartTime` that `isValidTime` accepts, and when the day or
+ *   the next one starts outside Temporal's instant range.
+ *
+ * @param instant ISO 8601 instant string to place
+ * @param day the reference zone and the local time each day starts at
+ * @returns `{ start, end }` of the day as UTC instants ending in "Z", or null on invalid input
+ *
+ * @example dutyDayFor("2024-01-01T08:59:00Z", { timeZone: "America/New_York", dayStartTime: "04:00" }) // { start: "2023-12-31T09:00:00Z", end: "2024-01-01T09:00:00Z" } — 03:59 local is the previous day
+ * @example dutyDayFor("2024-01-01T09:00:00Z", { timeZone: "America/New_York", dayStartTime: "04:00" }) // { start: "2024-01-01T09:00:00Z", end: "2024-01-02T09:00:00Z" }
+ * @example dutyDayFor("2024-03-10T12:00:00Z", { timeZone: "America/New_York", dayStartTime: "02:30" }) // { start: "2024-03-10T07:30:00Z", end: "2024-03-11T06:30:00Z" } — 02:30 is skipped, read as 03:30; 23 hours
+ * @example dutyDayFor("2024-11-03T12:00:00Z", { timeZone: "America/New_York", dayStartTime: "01:30" }) // { start: "2024-11-03T05:30:00Z", end: "2024-11-04T06:30:00Z" } — 01:30 is repeated, the first pass starts it; 25 hours
+ * @example dutyDayFor("2024-11-03T12:00:00Z", { timeZone: "America/New_York", dayStartTime: "01:30", disambiguation: "later" }) // { start: "2024-11-03T06:30:00Z", end: "2024-11-04T06:30:00Z" } — the second pass; 24 hours
+ * @example dutyDayFor("2024-11-03T12:00:00Z", { timeZone: "America/New_York", dayStartTime: "01:30", disambiguation: "reject" }) // null — the day starts at a repeated time
+ * @example dutyDayFor("2024-01-01T12:00:00Z", { timeZone: "UTC" }) // null — no dayStartTime
+ * @example dutyDayFor("2024-01-01T12:00:00Z", { timeZone: "Invalid/Zone", dayStartTime: "04:00" }) // null
+ */
+export function dutyDayFor(instant, day) {
+    try {
+        if (typeof instant !== "string" || !isObject(day)) {
+            return null;
+        }
+        const { timeZone, dayStartTime } = day;
+        const disambiguation = parseScheduleDisambiguation(day);
+        const at = parseInstantNanoseconds(instant);
+        const frame = zoneFrame(timeZone);
+        const time = parseDayStartTime(dayStartTime);
+        if (at === null ||
+            frame === null ||
+            time === null ||
+            disambiguation === null) {
+            return null;
+        }
+        const span = operatorDayScale(frame, time, disambiguation).containing(at);
+        if (span === null) {
+            return null;
+        }
+        return {
+            start: Temporal.Instant.fromEpochNanoseconds(span.start).toString(),
+            end: Temporal.Instant.fromEpochNanoseconds(span.end).toString(),
+        };
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}

package/dist/duty/calculate/dutyTotals.d.ts

@@ -0,0 +1,24 @@
+import type { DutyEntry, Interval } from "../../types/index.js";
+/**
+ * Return the time a duty log spends in any of `statuses` inside a window, as an exact ISO 8601
+ * duration.
+ *
+ * - The interval algebra of CORE-6: the entries in `statuses` are merged, each run is cut to
+ *   `window` (half-open), and what is left is summed. An entry that crosses the window's edge
+ *   counts only its part inside.
+ * - Hours are the largest unit, as `sumIntervals` writes it: `"PT49H30M"`, never days.
+ * - `[]` as `statuses`, an empty log or an empty window gives `"PT0S"`.
+ * - Returns `""` when the log fails `isValidDutyLog`, when `window` is not a valid `Interval`, and
+ *   when `statuses` is not an array of strings.
+ *
+ * @param log the duty log, ordered and non-overlapping
+ * @param window `{ start, end }` record of ISO 8601 instant strings to total inside
+ * @param statuses the statuses whose time is totalled
+ * @returns ISO 8601 duration string, or "" on invalid input
+ *
+ * @example dutyTotals([{ status: "driving", start: "2024-01-01T10:00:00Z", end: "2024-01-01T15:00:00Z" }, { status: "onDuty", start: "2024-01-01T15:00:00Z", end: "2024-01-01T17:00:00Z" }, { status: "driving", start: "2024-01-01T17:00:00Z", end: "2024-01-01T20:00:00Z" }], { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, ["driving"]) // "PT8H"
+ * @example dutyTotals([{ status: "driving", start: "2024-01-01T10:00:00Z", end: "2024-01-01T15:00:00Z" }], { start: "2024-01-01T12:00:00Z", end: "2024-01-01T18:00:00Z" }, ["driving"]) // "PT3H" — cut at the window
+ * @example dutyTotals([], { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, ["driving"]) // "PT0S"
+ * @example dutyTotals([{ status: "driving", start: "2024-01-01T15:00:00Z", end: "2024-01-01T10:00:00Z" }], { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, ["driving"]) // "" — inverted entry
+ */
+export declare function dutyTotals(log: DutyEntry[], window: Interval, statuses: string[]): string;

package/dist/duty/calculate/dutyTotals.js

@@ -0,0 +1,41 @@
+import { formatHourDuration, parseIntervalNanoseconds } from "../../internal/index.js";
+import { parseDutyLog } from "../../internal/dutyLog.js";
+import { readStatusList, timeIn } from "../../internal/dutyEngine.js";
+/**
+ * Return the time a duty log spends in any of `statuses` inside a window, as an exact ISO 8601
+ * duration.
+ *
+ * - The interval algebra of CORE-6: the entries in `statuses` are merged, each run is cut to
+ *   `window` (half-open), and what is left is summed. An entry that crosses the window's edge
+ *   counts only its part inside.
+ * - Hours are the largest unit, as `sumIntervals` writes it: `"PT49H30M"`, never days.
+ * - `[]` as `statuses`, an empty log or an empty window gives `"PT0S"`.
+ * - Returns `""` when the log fails `isValidDutyLog`, when `window` is not a valid `Interval`, and
+ *   when `statuses` is not an array of strings.
+ *
+ * @param log the duty log, ordered and non-overlapping
+ * @param window `{ start, end }` record of ISO 8601 instant strings to total inside
+ * @param statuses the statuses whose time is totalled
+ * @returns ISO 8601 duration string, or "" on invalid input
+ *
+ * @example dutyTotals([{ status: "driving", start: "2024-01-01T10:00:00Z", end: "2024-01-01T15:00:00Z" }, { status: "onDuty", start: "2024-01-01T15:00:00Z", end: "2024-01-01T17:00:00Z" }, { status: "driving", start: "2024-01-01T17:00:00Z", end: "2024-01-01T20:00:00Z" }], { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, ["driving"]) // "PT8H"
+ * @example dutyTotals([{ status: "driving", start: "2024-01-01T10:00:00Z", end: "2024-01-01T15:00:00Z" }], { start: "2024-01-01T12:00:00Z", end: "2024-01-01T18:00:00Z" }, ["driving"]) // "PT3H" — cut at the window
+ * @example dutyTotals([], { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, ["driving"]) // "PT0S"
+ * @example dutyTotals([{ status: "driving", start: "2024-01-01T15:00:00Z", end: "2024-01-01T10:00:00Z" }], { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, ["driving"]) // "" — inverted entry
+ */
+export function dutyTotals(log, window, statuses) {
+    try {
+        const entries = parseDutyLog(log);
+        const bounds = parseIntervalNanoseconds(window);
+        const counted = readStatusList(statuses);
+        if (entries === null || bounds === null || counted === null) {
+            return "";
+        }
+        return formatHourDuration(timeIn(entries, counted, bounds.start, bounds.end));
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
+}