@northguild/gmt 1.17.0 → 1.19.0

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

@@ -5,16 +5,13 @@ import type { DurationRelativeTo } from "../../types/index.js";
  * - Uses Temporal.Duration.compare: -1 when `a` is shorter, 0 when equal, 1 when `a` is longer.
  * - Equality is by length, not by spelling — "PT60M" and "PT1H" compare 0, as do "P1D" and
  *   "PT24H" absent a `relativeTo`.
- * - `relativeTo` is required whenever a calendar unit (year/month/week) appears on either
- *   side and the two durations differ; without it, returns null. Field-identical durations
- *   compare 0 without it ("P1Y" vs "P1Y"), since Temporal checks identity first. Note the asymmetry with `addDuration`/`subtractDuration`
+ * - Field-identical durations compare 0 without a `relativeTo` ("P1Y" vs "P1Y"), since
+ *   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).
- * - It matters for non-calendar units too when it names a zoned instant — across a DST
- *   spring-forward, "P1D" is 23 real hours and so compares shorter than "PT24H".
  * - 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.
@@ -37,7 +34,7 @@ import type { DurationRelativeTo } from "../../types/index.js";
  *
  * @param a ISO 8601 duration string
  * @param b ISO 8601 duration string
- * @param options optional: { relativeTo } — anchor date/instant, required when either side has a calendar unit
+ * @param options The anchor calendar units are measured from
  * @returns -1, 0, or 1, or null on invalid input
  *
  * @example compareDurations("PT1H", "PT30M") // 1
@@ -56,5 +53,14 @@ import type { DurationRelativeTo } from "../../types/index.js";
  * @example compareDurations("P1M", "P30D", { relativeTo: "2024-02-10T00:00:00[u-ca=hebrew]" }) // 0 (a date-time without a zone reads as its date, as Temporal reads relativeTo)
  */
 export declare function compareDurations(a: string, b: string, options?: {
+    /**
+     * The date or zoned date-time both durations are measured from. It is required when either
+     * side has a year, month or week and the two differ. With a zoned value, days follow that
+     * zone's clock changes, so across a spring-forward transition `"P1D"` is 23 hours and
+     * compares shorter than `"PT24H"`.
+     *
+     * @defaultValue None. Days are 24 hours, and two different durations of which one has a
+     * year, month or week return `null`.
+     */
     relativeTo?: DurationRelativeTo;
 }): number | null;

package/dist/duration/compare/compareDurations.js

@@ -7,16 +7,13 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Uses Temporal.Duration.compare: -1 when `a` is shorter, 0 when equal, 1 when `a` is longer.
  * - Equality is by length, not by spelling — "PT60M" and "PT1H" compare 0, as do "P1D" and
  *   "PT24H" absent a `relativeTo`.
- * - `relativeTo` is required whenever a calendar unit (year/month/week) appears on either
- *   side and the two durations differ; without it, returns null. Field-identical durations
- *   compare 0 without it ("P1Y" vs "P1Y"), since Temporal checks identity first. Note the asymmetry with `addDuration`/`subtractDuration`
+ * - Field-identical durations compare 0 without a `relativeTo` ("P1Y" vs "P1Y"), since
+ *   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).
- * - It matters for non-calendar units too when it names a zoned instant — across a DST
- *   spring-forward, "P1D" is 23 real hours and so compares shorter than "PT24H".
  * - 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.
@@ -39,7 +36,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *
  * @param a ISO 8601 duration string
  * @param b ISO 8601 duration string
- * @param options optional: { relativeTo } — anchor date/instant, required when either side has a calendar unit
+ * @param options The anchor calendar units are measured from
  * @returns -1, 0, or 1, or null on invalid input
  *
  * @example compareDurations("PT1H", "PT30M") // 1

package/dist/duration/format/formatDuration.d.ts

@@ -1,5 +1,19 @@
+/** How `formatDuration` writes unit names, and whether it writes zero components. */
 export interface FormatDurationOptions {
+    /**
+     * The length of each unit name, as the `unitDisplay` of `Intl.NumberFormat`: `"long"` ("90
+     * minutes"), `"short"` ("90 min") or `"narrow"` ("90m"). The components are joined as a long list
+     * ("1 day, 2 hours, and 30 minutes") for `"long"` and as a short list otherwise.
+     *
+     * @defaultValue `"long"`
+     */
     style?: "long" | "short" | "narrow";
+    /**
+     * Whether components that are zero are written. `false` leaves them out, so `"P1DT0H30M"`
+     * reads "1 day and 30 minutes"; `true` writes every unit from years to seconds.
+     *
+     * @defaultValue `false`
+     */
     zero?: boolean;
 }
 /**
@@ -16,10 +30,8 @@ export interface FormatDurationOptions {
  * - To render fewer fraction digits, round the string first with parseDuration, e.g.
  *   { smallestUnit: "millisecond", roundingMode: "halfExpand" } for the 3-digit output this
  *   function produced before (parseDuration's default roundingMode "trunc" drops the digits).
- * - By default, zero-valued components are omitted (e.g. "P1DT0H30M" -> "1 day and 30
- *   minutes"). Pass { zero: true } to include them.
  * - A zero-length duration (e.g. "PT0S") always renders its seconds component
- *   ("0 seconds") even with the default zero-omitting behavior, since omitting
+ *   ("0 seconds") even when zero components are left out, since omitting
  *   every component would otherwise produce "".
  * - Negative durations render each component with a leading "-" (Temporal stores
  *   every field of a negative duration as a negative number).
@@ -27,7 +39,7 @@ export interface FormatDurationOptions {
  *
  * @param value ISO 8601 duration string
  * @param locale BCP 47 locale tag, passed to Intl.NumberFormat/Intl.ListFormat; system default if omitted, or a preference list of tags (ECMA-402)
- * @param options optional: { style: "long" | "short" | "narrow" (default "long"), zero: boolean (default false) }
+ * @param options How unit names are written, and whether zero components are shown
  * @returns human-readable rendering of the duration, or "" on invalid input
  *
  * @example formatDuration("P1DT2H30M", "en-US") // "1 day, 2 hours, and 30 minutes"

package/dist/duration/format/formatDuration.js

@@ -1,5 +1,6 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 const UNIT_TO_INTL = {
     years: "year",
     months: "month",
@@ -58,10 +59,8 @@ function exactSeconds(duration) {
  * - To render fewer fraction digits, round the string first with parseDuration, e.g.
  *   { smallestUnit: "millisecond", roundingMode: "halfExpand" } for the 3-digit output this
  *   function produced before (parseDuration's default roundingMode "trunc" drops the digits).
- * - By default, zero-valued components are omitted (e.g. "P1DT0H30M" -> "1 day and 30
- *   minutes"). Pass { zero: true } to include them.
  * - A zero-length duration (e.g. "PT0S") always renders its seconds component
- *   ("0 seconds") even with the default zero-omitting behavior, since omitting
+ *   ("0 seconds") even when zero components are left out, since omitting
  *   every component would otherwise produce "".
  * - Negative durations render each component with a leading "-" (Temporal stores
  *   every field of a negative duration as a negative number).
@@ -69,7 +68,7 @@ function exactSeconds(duration) {
  *
  * @param value ISO 8601 duration string
  * @param locale BCP 47 locale tag, passed to Intl.NumberFormat/Intl.ListFormat; system default if omitted, or a preference list of tags (ECMA-402)
- * @param options optional: { style: "long" | "short" | "narrow" (default "long"), zero: boolean (default false) }
+ * @param options How unit names are written, and whether zero components are shown
  * @returns human-readable rendering of the duration, or "" on invalid input
  *
  * @example formatDuration("P1DT2H30M", "en-US") // "1 day, 2 hours, and 30 minutes"
@@ -94,7 +93,7 @@ export function formatDuration(value, locale, options = {}) {
     }
     try {
         const duration = Temporal.Duration.from(value);
-        const style = options.style === undefined ? "long" : options.style;
+        const style = optionOrDefault(options.style, "long");
         const includeZero = options.zero ?? false;
         const amounts = {
             years: duration.years,

package/dist/duration/normalize/normalizeDuration.d.ts

@@ -4,19 +4,9 @@ import type { DurationRelativeTo } from "../../types/index.js";
  * Roll an ISO 8601 duration string's small units into larger ones.
  *
  * - Uses Temporal.Duration.from and .round to rebalance, then .toString() to re-emit.
- * - Defaults to { largestUnit: "auto" }, which resolves to the larger of smallestUnit and the
- *   duration's own largest non-zero unit, then balances up to it. Units are promoted only up to
- *   a unit already present: "PT90M" stays "PT90M", but "P1DT25H" becomes "P2DT1H" and "PT1H90M"
- *   becomes "PT2H30M". Pass an explicit largestUnit to promote further.
- * - relativeTo is required whenever a calendar unit (year/month/week) is involved,
- *   either as the requested largestUnit or because the input duration already has a
- *   nonzero year/month/week component (this applies even under the "auto" default).
- *   Without relativeTo in either case, returns "".
- * - roundingIncrement must evenly divide, and be less than, 24 for hour, 60 for minute/second
- *   and 1000 for millisecond/microsecond/nanosecond (so 60 and 24 themselves are rejected).
- *   For year/month/week/day it has no maximum, but an increment above 1 is rejected unless
- *   largestUnit is that same unit ("auto" resolves to the largest unit present). An invalid
- *   increment returns "".
+ * - With no options, units are promoted only up to a unit already present: "PT90M" stays
+ *   "PT90M", but "P1DT25H" becomes "P2DT1H" and "PT1H90M" becomes "PT2H30M". Pass an explicit
+ *   largestUnit to promote further.
  * - 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 "". Pass an
@@ -38,7 +28,7 @@ import type { DurationRelativeTo } from "../../types/index.js";
  *   invalid relativeTo.
  *
  * @param value ISO 8601 duration string
- * @param options optional: { largestUnit, smallestUnit, roundingIncrement, roundingMode, relativeTo } per Temporal's Duration.round options
+ * @param options The units to balance between, the rounding, and the anchor for calendar units, as Temporal's Duration.round takes them
  * @returns rebalanced ISO 8601 duration string, or "" on invalid input
  *
  * @example normalizeDuration("PT90M", { largestUnit: "hour" }) // "PT1H30M"
@@ -55,9 +45,44 @@ import type { DurationRelativeTo } from "../../types/index.js";
  * @example normalizeDuration("P45D", { largestUnit: "month", relativeTo: "2024-02-10T00:00:00[u-ca=hebrew]" }) // "P1M15D" (a date-time without a zone reads as its date, as Temporal reads relativeTo)
  */
 export declare function normalizeDuration(value: string, options?: {
+    /**
+     * The largest unit the result may carry; smaller units are rolled up into it. `"auto"` is
+     * the larger of `smallestUnit` and the duration's own largest nonzero unit, so nothing is
+     * promoted past a unit already present.
+     *
+     * @defaultValue `"auto"`
+     */
     largestUnit?: Temporal.LargestUnit<Temporal.DateTimeUnit>;
+    /**
+     * The smallest unit the result may carry; anything smaller is rounded into it.
+     *
+     * @defaultValue `"nanosecond"`, Temporal's default.
+     */
     smallestUnit?: Temporal.SmallestUnit<Temporal.DateTimeUnit>;
+    /**
+     * The step `smallestUnit` is rounded to. It must evenly divide, and be less than, 24 for
+     * hour, 60 for minute and second, and 1000 for the sub-second units. For year, month, week
+     * and day it has no maximum, but an increment above 1 is rejected unless `largestUnit` is
+     * that same unit; an invalid increment returns `""`.
+     *
+     * @defaultValue `1`, Temporal's default.
+     */
     roundingIncrement?: number;
+    /**
+     * Which way a value between two steps goes when `smallestUnit` or `roundingIncrement` rounds
+     * the duration. `"halfExpand"` rounds to the nearest step, a half going away from zero, and
+     * `"trunc"` rounds toward zero.
+     *
+     * @defaultValue `"halfExpand"`, Temporal's default.
+     */
     roundingMode?: Temporal.RoundingMode;
+    /**
+     * The date or zoned date-time the duration is measured from. It is required whenever a year,
+     * month or week is involved, as `largestUnit` or `smallestUnit` or as a nonzero field of the
+     * duration, even under the `"auto"` default.
+     *
+     * @defaultValue None. Days are 24 hours, and a duration or unit that involves a year, month
+     * or week returns `""`.
+     */
     relativeTo?: DurationRelativeTo;
 }): string;

package/dist/duration/normalize/normalizeDuration.js

@@ -1,23 +1,14 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { durationRound, resolveDurationRelativeTo } from "../../internal/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 /**
  * Roll an ISO 8601 duration string's small units into larger ones.
  *
  * - Uses Temporal.Duration.from and .round to rebalance, then .toString() to re-emit.
- * - Defaults to { largestUnit: "auto" }, which resolves to the larger of smallestUnit and the
- *   duration's own largest non-zero unit, then balances up to it. Units are promoted only up to
- *   a unit already present: "PT90M" stays "PT90M", but "P1DT25H" becomes "P2DT1H" and "PT1H90M"
- *   becomes "PT2H30M". Pass an explicit largestUnit to promote further.
- * - relativeTo is required whenever a calendar unit (year/month/week) is involved,
- *   either as the requested largestUnit or because the input duration already has a
- *   nonzero year/month/week component (this applies even under the "auto" default).
- *   Without relativeTo in either case, returns "".
- * - roundingIncrement must evenly divide, and be less than, 24 for hour, 60 for minute/second
- *   and 1000 for millisecond/microsecond/nanosecond (so 60 and 24 themselves are rejected).
- *   For year/month/week/day it has no maximum, but an increment above 1 is rejected unless
- *   largestUnit is that same unit ("auto" resolves to the largest unit present). An invalid
- *   increment returns "".
+ * - With no options, units are promoted only up to a unit already present: "PT90M" stays
+ *   "PT90M", but "P1DT25H" becomes "P2DT1H" and "PT1H90M" becomes "PT2H30M". Pass an explicit
+ *   largestUnit to promote further.
  * - 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 "". Pass an
@@ -39,7 +30,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   invalid relativeTo.
  *
  * @param value ISO 8601 duration string
- * @param options optional: { largestUnit, smallestUnit, roundingIncrement, roundingMode, relativeTo } per Temporal's Duration.round options
+ * @param options The units to balance between, the rounding, and the anchor for calendar units, as Temporal's Duration.round takes them
  * @returns rebalanced ISO 8601 duration string, or "" on invalid input
  *
  * @example normalizeDuration("PT90M", { largestUnit: "hour" }) // "PT1H30M"
@@ -65,7 +56,7 @@ export function normalizeDuration(value, options) {
     try {
         const duration = Temporal.Duration.from(value);
         return durationRound(duration, {
-            largestUnit: options?.largestUnit === undefined ? "auto" : options.largestUnit,
+            largestUnit: optionOrDefault(options?.largestUnit, "auto"),
             smallestUnit: options?.smallestUnit,
             roundingIncrement: options?.roundingIncrement,
             roundingMode: options?.roundingMode,

package/dist/duration/parse/parseDuration.d.ts

@@ -3,12 +3,10 @@ import { Temporal } from "@js-temporal/polyfill";
  * Parse and re-normalize an ISO 8601 duration string.
  *
  * - Uses Temporal.Duration.from to parse, then .toString() to re-emit.
- * - `smallestUnit`, `fractionalSecondDigits`, and `roundingMode` control the precision/rounding
- *   of the re-emitted string, per Temporal's ToStringPrecisionOptions.
  * - Returns "" for invalid input.
  *
  * @param value ISO 8601 duration string
- * @param options optional: smallestUnit ("second" | "millisecond" | "microsecond" | "nanosecond" — "minute"/"hour" are rejected by Temporal, resulting in ""), fractionalSecondDigits ("auto" | 0-9, ignored when smallestUnit is also set), roundingMode
+ * @param options The precision of the string written back, as Temporal's ToStringPrecisionOptions
  * @returns re-normalized ISO 8601 duration string, or "" on invalid input
  *
  * @example parseDuration("P1DT2H30M") // "P1DT2H30M"
@@ -18,7 +16,27 @@ import { Temporal } from "@js-temporal/polyfill";
  * @example parseDuration("invalid") // ""
  */
 export declare function parseDuration(value: string, options?: {
+    /**
+     * The smallest unit written in the string: `"second"`, `"millisecond"`, `"microsecond"` or
+     * `"nanosecond"`. It sets how many fractional-second digits appear and takes precedence over
+     * `fractionalSecondDigits`. `"minute"` returns `""`, as `Temporal.Duration` refuses it.
+     *
+     * @defaultValue None. The precision comes from `fractionalSecondDigits`.
+     */
     smallestUnit?: Temporal.ToStringPrecisionOptions["smallestUnit"];
+    /**
+     * The number of fractional-second digits written: `0` to `9` writes exactly that many, and
+     * `"auto"` writes as many as the duration needs, with no trailing zeros. It has no effect when
+     * `smallestUnit` is given.
+     *
+     * @defaultValue `"auto"`, Temporal's default.
+     */
     fractionalSecondDigits?: Temporal.ToStringPrecisionOptions["fractionalSecondDigits"];
+    /**
+     * How the duration is rounded when the precision asked for drops digits. `"trunc"` cuts them
+     * off; `"halfExpand"` rounds to the nearest value, a half going away from zero.
+     *
+     * @defaultValue `"trunc"`, Temporal's default.
+     */
     roundingMode?: Temporal.ToStringPrecisionOptions["roundingMode"];
 }): string;

package/dist/duration/parse/parseDuration.js

@@ -4,12 +4,10 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * Parse and re-normalize an ISO 8601 duration string.
  *
  * - Uses Temporal.Duration.from to parse, then .toString() to re-emit.
- * - `smallestUnit`, `fractionalSecondDigits`, and `roundingMode` control the precision/rounding
- *   of the re-emitted string, per Temporal's ToStringPrecisionOptions.
  * - Returns "" for invalid input.
  *
  * @param value ISO 8601 duration string
- * @param options optional: smallestUnit ("second" | "millisecond" | "microsecond" | "nanosecond" — "minute"/"hour" are rejected by Temporal, resulting in ""), fractionalSecondDigits ("auto" | 0-9, ignored when smallestUnit is also set), roundingMode
+ * @param options The precision of the string written back, as Temporal's ToStringPrecisionOptions
  * @returns re-normalized ISO 8601 duration string, or "" on invalid input
  *
  * @example parseDuration("P1DT2H30M") // "P1DT2H30M"

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 "";
+    }
+}