@northguild/gmt 1.14.2 → 1.16.0

package/dist/calendar/calculate/getQuarter.js

@@ -0,0 +1,64 @@
+import { zonelessCalendarDate } from "../../internal/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
+/** Months in a quarter. */
+const MONTHS_PER_QUARTER = 3;
+/** Months in a year. */
+const MONTHS_PER_YEAR = 12;
+/**
+ * Return the quarter `value` falls in, as a year and a quarter number.
+ *
+ * - `quarter` is 1–4. With no options these are the calendar quarters: Q1 is January to
+ *   March, and `year` is the calendar year.
+ * - `fiscalYearStartMonth` (1–12, default 1) moves the year's first month. A date before it
+ *   belongs to the previous fiscal year, so `getQuarter("2024-03-31", { fiscalYearStartMonth:
+ *   4 })` is Q4 of 2023.
+ * - **`year` is the calendar year the fiscal year starts in**, matching the NRF retail
+ *   convention `getFiscalPeriod` uses. Organisations that label a fiscal year by the calendar
+ *   year it *ends* in — the US federal government's October-start FY2025 begins in October
+ *   2024 — should add one.
+ * - `value` must be zoneless — an ISO date or datetime, as `isValidIsoDateLike` accepts. See
+ *   `getIsoWeekDate` for why a moment is not accepted here.
+ * - Returns null on invalid input, including a `fiscalYearStartMonth` that is not an integer
+ *   from 1 to 12.
+ *
+ * @param value zoneless ISO 8601 date or datetime string (e.g. "2024-06-15")
+ * @param optionsArg optional: fiscalYearStartMonth (1-12, default 1)
+ * @returns { year, quarter }, or null on invalid input
+ *
+ * @example getQuarter("2024-06-15") // { year: 2024, quarter: 2 }
+ * @example getQuarter("2024-10-01") // { year: 2024, quarter: 4 }
+ * @example getQuarter("2024-06-15", { fiscalYearStartMonth: 1 }) // { year: 2024, quarter: 2 } (the default, stated)
+ * @example getQuarter("2024-04-01", { fiscalYearStartMonth: 4 }) // { year: 2024, quarter: 1 }
+ * @example getQuarter("2024-03-31", { fiscalYearStartMonth: 4 }) // { year: 2023, quarter: 4 } (the previous fiscal year)
+ * @example getQuarter("2024-06-15", { fiscalYearStartMonth: 13 }) // null
+ * @example getQuarter("2024-06-15T12:00:00Z") // null (a moment, not a calendar date)
+ * @example getQuarter("invalid") // null
+ */
+export function getQuarter(value, optionsArg) {
+    try {
+        if (!isOptionsArgument(optionsArg)) {
+            return null;
+        }
+        const fiscalYearStartMonth = optionsArg?.fiscalYearStartMonth === undefined
+            ? 1
+            : optionsArg.fiscalYearStartMonth;
+        if (!Number.isInteger(fiscalYearStartMonth) ||
+            fiscalYearStartMonth < 1 ||
+            fiscalYearStartMonth > MONTHS_PER_YEAR) {
+            return null;
+        }
+        const date = zonelessCalendarDate(value);
+        if (!date)
+            return null;
+        const monthsIntoYear = (date.month - fiscalYearStartMonth + MONTHS_PER_YEAR) % MONTHS_PER_YEAR;
+        return {
+            year: date.month < fiscalYearStartMonth ? date.year - 1 : date.year,
+            quarter: Math.floor(monthsIntoYear / MONTHS_PER_QUARTER) + 1,
+        };
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}

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

@@ -0,0 +1,6 @@
+export * from "./bucketRange.js";
+export * from "./floorToZone.js";
+export * from "./getFiscalPeriod.js";
+export * from "./getIsoWeekDate.js";
+export * from "./getOrdinalDate.js";
+export * from "./getQuarter.js";

package/dist/calendar/calculate/index.js

@@ -0,0 +1,6 @@
+export * from "./bucketRange.js";
+export * from "./floorToZone.js";
+export * from "./getFiscalPeriod.js";
+export * from "./getIsoWeekDate.js";
+export * from "./getOrdinalDate.js";
+export * from "./getQuarter.js";

package/dist/calendar/index.d.ts

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

package/dist/calendar/index.js

@@ -0,0 +1,5 @@
+// Re-export the Temporal polyfill (`Temporal`, `Intl`, `toTemporalInstant`) so every namespace subpath offers it
+export * from "@js-temporal/polyfill";
+export * from "./business/index.js";
+export * from "./calculate/index.js";
+export * from "./validate/index.js";

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

@@ -0,0 +1,4 @@
+export * from "./isValidBusinessCalendar.js";
+export * from "./isValidFiscalPattern.js";
+export * from "./isValidRollConvention.js";
+export * from "./isValidZoneBucketUnit.js";

package/dist/calendar/validate/index.js

@@ -0,0 +1,4 @@
+export * from "./isValidBusinessCalendar.js";
+export * from "./isValidFiscalPattern.js";
+export * from "./isValidRollConvention.js";
+export * from "./isValidZoneBucketUnit.js";

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

@@ -0,0 +1,31 @@
+import type { BusinessCalendar } from "../../types/index.js";
+/**
+ * Return true when `calendar` is a `BusinessCalendar` the business-day functions accept.
+ *
+ * - `weekend` must be an array of ISO weekday integers, 1 (Monday) through 7 (Sunday).
+ *   Duplicates are ignored and `[]` is valid — a calendar with no weekly closure.
+ * - All seven weekdays being weekend is **invalid**: such a calendar has no business day, so
+ *   `nextBusinessDay` and every other walk would have nothing to walk to.
+ * - `holidays` must be an array of ISO PlainDate strings. `[]` is valid. A datetime, a leap
+ *   second or a date that does not exist is not.
+ * - `timeZone` must be a valid IANA identifier. It records which locality the calendar
+ *   describes; the business-day functions never read it, because they work on local dates.
+ * - Returns `false` for non-objects, `null` and arrays.
+ * - Use it to tell a legitimate result from `mergeCalendars` apart from its invalid-input
+ *   sentinel, which is also `null`, and to tell a misconfigured calendar apart from a bad date
+ *   when a business-day function returns `""`.
+ *
+ * @param calendar candidate value of any type
+ * @returns boolean indicating whether every business-day function accepts it
+ *
+ * @example isValidBusinessCalendar({ weekend: [6, 7], holidays: [], timeZone: "UTC" }) // true
+ * @example isValidBusinessCalendar({ weekend: [5, 6], holidays: ["2024-07-04"], timeZone: "Asia/Riyadh" }) // true — Friday–Saturday
+ * @example isValidBusinessCalendar({ weekend: [], holidays: [], timeZone: "UTC" }) // true — no weekly closure
+ * @example isValidBusinessCalendar({ weekend: [1, 2, 3, 4, 5, 6, 7], holidays: [], timeZone: "UTC" }) // false — no business day left
+ * @example isValidBusinessCalendar({ weekend: [6, 8], holidays: [], timeZone: "UTC" }) // false — 8 is not an ISO weekday
+ * @example isValidBusinessCalendar({ weekend: [6, 7], holidays: ["2024-02-30"], timeZone: "UTC" }) // false — that date does not exist
+ * @example isValidBusinessCalendar({ weekend: [6, 7], holidays: ["2024-07-04T00:00:00"], timeZone: "UTC" }) // false — a datetime, not a date
+ * @example isValidBusinessCalendar({ weekend: [6, 7], holidays: [], timeZone: "Invalid/Zone" }) // false
+ * @example isValidBusinessCalendar(null) // false
+ */
+export declare function isValidBusinessCalendar(calendar: unknown): calendar is BusinessCalendar;

package/dist/calendar/validate/isValidBusinessCalendar.js

@@ -0,0 +1,40 @@
+import { parseBusinessCalendar } from "../../internal/businessCalendar.js";
+/**
+ * Return true when `calendar` is a `BusinessCalendar` the business-day functions accept.
+ *
+ * - `weekend` must be an array of ISO weekday integers, 1 (Monday) through 7 (Sunday).
+ *   Duplicates are ignored and `[]` is valid — a calendar with no weekly closure.
+ * - All seven weekdays being weekend is **invalid**: such a calendar has no business day, so
+ *   `nextBusinessDay` and every other walk would have nothing to walk to.
+ * - `holidays` must be an array of ISO PlainDate strings. `[]` is valid. A datetime, a leap
+ *   second or a date that does not exist is not.
+ * - `timeZone` must be a valid IANA identifier. It records which locality the calendar
+ *   describes; the business-day functions never read it, because they work on local dates.
+ * - Returns `false` for non-objects, `null` and arrays.
+ * - Use it to tell a legitimate result from `mergeCalendars` apart from its invalid-input
+ *   sentinel, which is also `null`, and to tell a misconfigured calendar apart from a bad date
+ *   when a business-day function returns `""`.
+ *
+ * @param calendar candidate value of any type
+ * @returns boolean indicating whether every business-day function accepts it
+ *
+ * @example isValidBusinessCalendar({ weekend: [6, 7], holidays: [], timeZone: "UTC" }) // true
+ * @example isValidBusinessCalendar({ weekend: [5, 6], holidays: ["2024-07-04"], timeZone: "Asia/Riyadh" }) // true — Friday–Saturday
+ * @example isValidBusinessCalendar({ weekend: [], holidays: [], timeZone: "UTC" }) // true — no weekly closure
+ * @example isValidBusinessCalendar({ weekend: [1, 2, 3, 4, 5, 6, 7], holidays: [], timeZone: "UTC" }) // false — no business day left
+ * @example isValidBusinessCalendar({ weekend: [6, 8], holidays: [], timeZone: "UTC" }) // false — 8 is not an ISO weekday
+ * @example isValidBusinessCalendar({ weekend: [6, 7], holidays: ["2024-02-30"], timeZone: "UTC" }) // false — that date does not exist
+ * @example isValidBusinessCalendar({ weekend: [6, 7], holidays: ["2024-07-04T00:00:00"], timeZone: "UTC" }) // false — a datetime, not a date
+ * @example isValidBusinessCalendar({ weekend: [6, 7], holidays: [], timeZone: "Invalid/Zone" }) // false
+ * @example isValidBusinessCalendar(null) // false
+ */
+export function isValidBusinessCalendar(calendar) {
+    try {
+        return parseBusinessCalendar(calendar) !== null;
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return false;
+    }
+}

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

@@ -0,0 +1,25 @@
+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".
+ * - 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.
+ *
+ * @param pattern candidate value of any type
+ * @returns boolean indicating validity
+ *
+ * @example isValidFiscalPattern("4-5-4") // true (the NRF retail calendar)
+ * @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("454") // false
+ * @example isValidFiscalPattern("invalid") // false
+ * @example isValidFiscalPattern(454) // false
+ * @example isValidFiscalPattern(null) // false
+ */
+export declare function isValidFiscalPattern(pattern: unknown): pattern is FiscalPattern;

package/dist/calendar/validate/isValidFiscalPattern.js

@@ -0,0 +1,29 @@
+/**
+ * Return true when `pattern` is a valid FiscalPattern.
+ *
+ * - Valid patterns are: "4-5-4" (the NRF retail calendar), "4-4-5", "5-4-4".
+ * - 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.
+ *
+ * @param pattern candidate value of any type
+ * @returns boolean indicating validity
+ *
+ * @example isValidFiscalPattern("4-5-4") // true (the NRF retail calendar)
+ * @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("454") // false
+ * @example isValidFiscalPattern("invalid") // false
+ * @example isValidFiscalPattern(454) // false
+ * @example isValidFiscalPattern(null) // false
+ */
+export function isValidFiscalPattern(pattern) {
+    if (typeof pattern !== "string") {
+        return false;
+    }
+    return pattern === "4-5-4" || pattern === "4-4-5" || pattern === "5-4-4";
+}

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

@@ -0,0 +1,28 @@
+import type { RollConvention } from "../../types/index.js";
+/**
+ * Return true when `convention` is a `RollConvention` that `rollDate` implements.
+ *
+ * - Valid conventions are `"following"`, `"modifiedFollowing"`, `"preceding"`,
+ *   `"modifiedPreceding"`, `"endOfMonth"` and `"none"`. The first three are the conventions
+ *   [ISDA 2006 Definitions §4.12(a)](https://www.isda.org/a/smMDE/Blackline-2000-v-2006-ISDA-Definitions.pdf)
+ *   defines in (i)–(iii); `"modifiedPreceding"` is FpML's `BusinessDayConventionEnum`
+ *   `MODPRECEDING`, which §4.12(a) does not define; `"none"` is Strata's `NO_ADJUST`; and
+ *   `"endOfMonth"` is GMT's own. The camelCase spelling
+ *   is GMT's — no standard fixes the identifiers, only the behaviour.
+ * - Matching is exact: case, spacing and abbreviations are not normalised.
+ * - Accepts any input type and returns false for non-string values.
+ * - `rollDate` returns `""` for a convention it does not recognise — the same sentinel it
+ *   returns for a bad date or calendar. Check the convention here to tell a misconfigured
+ *   contract term apart from bad data.
+ *
+ * @param convention candidate value of any type
+ * @returns boolean indicating validity
+ *
+ * @example isValidRollConvention("modifiedFollowing") // true
+ * @example isValidRollConvention("endOfMonth") // true
+ * @example isValidRollConvention("none") // true
+ * @example isValidRollConvention("Following") // false (case is exact)
+ * @example isValidRollConvention("nearest") // false (not implemented)
+ * @example isValidRollConvention(null) // false
+ */
+export declare function isValidRollConvention(convention: unknown): convention is RollConvention;

package/dist/calendar/validate/isValidRollConvention.js

@@ -0,0 +1,38 @@
+const ROLL_CONVENTIONS = [
+    "following",
+    "modifiedFollowing",
+    "preceding",
+    "modifiedPreceding",
+    "endOfMonth",
+    "none",
+];
+/**
+ * Return true when `convention` is a `RollConvention` that `rollDate` implements.
+ *
+ * - Valid conventions are `"following"`, `"modifiedFollowing"`, `"preceding"`,
+ *   `"modifiedPreceding"`, `"endOfMonth"` and `"none"`. The first three are the conventions
+ *   [ISDA 2006 Definitions §4.12(a)](https://www.isda.org/a/smMDE/Blackline-2000-v-2006-ISDA-Definitions.pdf)
+ *   defines in (i)–(iii); `"modifiedPreceding"` is FpML's `BusinessDayConventionEnum`
+ *   `MODPRECEDING`, which §4.12(a) does not define; `"none"` is Strata's `NO_ADJUST`; and
+ *   `"endOfMonth"` is GMT's own. The camelCase spelling
+ *   is GMT's — no standard fixes the identifiers, only the behaviour.
+ * - Matching is exact: case, spacing and abbreviations are not normalised.
+ * - Accepts any input type and returns false for non-string values.
+ * - `rollDate` returns `""` for a convention it does not recognise — the same sentinel it
+ *   returns for a bad date or calendar. Check the convention here to tell a misconfigured
+ *   contract term apart from bad data.
+ *
+ * @param convention candidate value of any type
+ * @returns boolean indicating validity
+ *
+ * @example isValidRollConvention("modifiedFollowing") // true
+ * @example isValidRollConvention("endOfMonth") // true
+ * @example isValidRollConvention("none") // true
+ * @example isValidRollConvention("Following") // false (case is exact)
+ * @example isValidRollConvention("nearest") // false (not implemented)
+ * @example isValidRollConvention(null) // false
+ */
+export function isValidRollConvention(convention) {
+    return (typeof convention === "string" &&
+        ROLL_CONVENTIONS.includes(convention));
+}

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

@@ -0,0 +1,31 @@
+import type { Temporal } from "@js-temporal/polyfill";
+import type { ZoneBucketUnit } from "../../types/index.js";
+/**
+ * Return true when `unit` is a valid ZoneBucketUnit.
+ *
+ * - Valid units are: "hour", "day", "week", "month", singular or plural (`"days"`), as Temporal
+ *   §13.17 names a unit either way and `floorToZone`/`bucketRange` accept both.
+ * - Accepts any input type and returns false for non-string values.
+ * - Uses type assertion to narrow the type.
+ * - Narrower than `isValidDateTimeUnit` on purpose: these are the boundaries a calendar in a
+ *   zone actually has. Sub-hour units need no zone, and "year" is left out because the
+ *   calendar and fiscal year questions are `getQuarter`'s and `getFiscalPeriod`'s.
+ * - `floorToZone` returns "" and `bucketRange` returns [] for a unit they do not recognise —
+ *   the same sentinels they return for an unusable instant. Check the unit here to tell a
+ *   misconfigured rollup apart from a bad timestamp.
+ *
+ * @param unit candidate value of any type
+ * @returns boolean indicating validity
+ *
+ * @example isValidZoneBucketUnit("hour") // true
+ * @example isValidZoneBucketUnit("day") // true
+ * @example isValidZoneBucketUnit("week") // true
+ * @example isValidZoneBucketUnit("month") // true
+ * @example isValidZoneBucketUnit("year") // false (a calendar year is getQuarter's question)
+ * @example isValidZoneBucketUnit("minute") // false (a sub-hour boundary needs no zone)
+ * @example isValidZoneBucketUnit("days") // true (plural name)
+ * @example isValidZoneBucketUnit("years") // false
+ * @example isValidZoneBucketUnit(1) // false
+ * @example isValidZoneBucketUnit(null) // false
+ */
+export declare function isValidZoneBucketUnit(unit: unknown): unit is Temporal.SmallestUnit<ZoneBucketUnit>;

package/dist/calendar/validate/isValidZoneBucketUnit.js

@@ -0,0 +1,39 @@
+import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
+/**
+ * Return true when `unit` is a valid ZoneBucketUnit.
+ *
+ * - Valid units are: "hour", "day", "week", "month", singular or plural (`"days"`), as Temporal
+ *   §13.17 names a unit either way and `floorToZone`/`bucketRange` accept both.
+ * - Accepts any input type and returns false for non-string values.
+ * - Uses type assertion to narrow the type.
+ * - Narrower than `isValidDateTimeUnit` on purpose: these are the boundaries a calendar in a
+ *   zone actually has. Sub-hour units need no zone, and "year" is left out because the
+ *   calendar and fiscal year questions are `getQuarter`'s and `getFiscalPeriod`'s.
+ * - `floorToZone` returns "" and `bucketRange` returns [] for a unit they do not recognise —
+ *   the same sentinels they return for an unusable instant. Check the unit here to tell a
+ *   misconfigured rollup apart from a bad timestamp.
+ *
+ * @param unit candidate value of any type
+ * @returns boolean indicating validity
+ *
+ * @example isValidZoneBucketUnit("hour") // true
+ * @example isValidZoneBucketUnit("day") // true
+ * @example isValidZoneBucketUnit("week") // true
+ * @example isValidZoneBucketUnit("month") // true
+ * @example isValidZoneBucketUnit("year") // false (a calendar year is getQuarter's question)
+ * @example isValidZoneBucketUnit("minute") // false (a sub-hour boundary needs no zone)
+ * @example isValidZoneBucketUnit("days") // true (plural name)
+ * @example isValidZoneBucketUnit("years") // false
+ * @example isValidZoneBucketUnit(1) // false
+ * @example isValidZoneBucketUnit(null) // false
+ */
+export function isValidZoneBucketUnit(unit) {
+    if (typeof unit !== "string") {
+        return false;
+    }
+    const singular = resolveDateTimeUnit(unit);
+    return (singular === "hour" ||
+        singular === "day" ||
+        singular === "week" ||
+        singular === "month");
+}

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

@@ -1,3 +1,4 @@
+import { Temporal } from "@js-temporal/polyfill";
 import type { DateTimeDurationUnit, DurationRelativeTo } from "../../types/index.js";
 /**
  * Express an ISO 8601 duration as a single fractional total in one unit.
@@ -16,10 +17,28 @@ import type { DateTimeDurationUnit, DurationRelativeTo } from "../../types/index
  *   calendar quantity to Temporal regardless of what it is being measured from.
  * - `relativeTo` changes the answer for non-calendar units too when it names a zoned instant:
  *   a day spanning a DST spring-forward transition totals 23 hours, not 24.
+ * - A zoned `relativeTo` string resolves its wall time with disambiguation "compatible" and
+ *   offset "reject", as Temporal does: an ambiguous wall time takes the earlier instant, a
+ *   nonexistent one the later instant, and an offset that does not match the zone returns null.
+ *   Pass an explicit offset to pick the other reading of an ambiguous wall time.
+ * - A `relativeTo` string is ISO 8601 extended format before its first `[`:
+ *   a date, a date-time, or with a time zone annotation a zoned date-time (`<date>T<time>`, then
+ *   nothing, `Z` or `±HH:MM`). Basic format (`"20240101"`), a space or lower-case `t` separator, a
+ *   lower-case `z`, a UTC offset without a zone and a zoned date without a time are invalid.
+ * - A `relativeTo` string takes a calendar in RFC 9557 form, as `convertDateToCalendar` and
+ *   `convertZonedToCalendar` write it: ISO digits and a `[u-ca=<id>]` annotation, after the zone
+ *   for a zoned string (`"2024-02-24[u-ca=hebrew]"`, `"2024-02-24T00:00:00-05:00[America/New_York][u-ca=hebrew]"`).
+ *   The annotations are read as Temporal reads them: the critical flag and the id's letter case
+ *   are accepted, elective unknown annotations are ignored, the first `u-ca` names the calendar,
+ *   and a string with a time zone annotation is zoned. An unknown critical annotation, a critical
+ *   duplicate calendar, a calendar before the zone, an unsupported calendar and a leap second in
+ *   any spelling return null.
+ *   Compatibility: before 1.16.0 the digits were read as the calendar's own year, month and day.
+ * - `unit` accepts the plural or singular name (`"hours"` or `"hour"`), as Temporal does.
  * - Returns null on a non-duration `value`, an invalid `unit`, or an invalid `relativeTo`.
  *
  * @param value ISO 8601 duration string
- * @param unit DateTimeDurationUnit to total into ("years" | "months" | "weeks" | "days" | "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds")
+ * @param unit DateTimeDurationUnit to total into ("years" | "months" | "weeks" | "days" | "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds", or the singular name)
  * @param options optional: { relativeTo } — anchor date/instant, required for any calendar unit
  * @returns the fractional total in `unit`, or null on invalid input
  *
@@ -29,10 +48,15 @@ import type { DateTimeDurationUnit, DurationRelativeTo } from "../../types/index
  * @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: "5784-06-15[u-ca=hebrew]" }) // 385 (Hebrew leap year — relativeTo accepts GMT's calendar-annotated PlainDate string, not Temporal's own ISO-digit u-ca convention)
+ * @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)
  */
-export declare function durationAs(value: string, unit: DateTimeDurationUnit, options?: {
+export declare function durationAs(value: string, unit: DateTimeDurationUnit | Temporal.DateTimeUnit, options?: {
     relativeTo?: DurationRelativeTo;
 }): number | null;

package/dist/duration/calculate/durationAs.js

@@ -1,7 +1,9 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { resolveDurationRelativeTo } from "../../internal/index.js";
+import { durationTotal, resolveDurationRelativeTo } from "../../internal/index.js";
 import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
 import { isValidDuration } from "../validate/isValidDuration.js";
+import { resolveDurationUnit } from "../../internal/resolveDurationUnit.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Express an ISO 8601 duration as a single fractional total in one unit.
  *
@@ -19,10 +21,28 @@ import { isValidDuration } from "../validate/isValidDuration.js";
  *   calendar quantity to Temporal regardless of what it is being measured from.
  * - `relativeTo` changes the answer for non-calendar units too when it names a zoned instant:
  *   a day spanning a DST spring-forward transition totals 23 hours, not 24.
+ * - A zoned `relativeTo` string resolves its wall time with disambiguation "compatible" and
+ *   offset "reject", as Temporal does: an ambiguous wall time takes the earlier instant, a
+ *   nonexistent one the later instant, and an offset that does not match the zone returns null.
+ *   Pass an explicit offset to pick the other reading of an ambiguous wall time.
+ * - A `relativeTo` string is ISO 8601 extended format before its first `[`:
+ *   a date, a date-time, or with a time zone annotation a zoned date-time (`<date>T<time>`, then
+ *   nothing, `Z` or `±HH:MM`). Basic format (`"20240101"`), a space or lower-case `t` separator, a
+ *   lower-case `z`, a UTC offset without a zone and a zoned date without a time are invalid.
+ * - A `relativeTo` string takes a calendar in RFC 9557 form, as `convertDateToCalendar` and
+ *   `convertZonedToCalendar` write it: ISO digits and a `[u-ca=<id>]` annotation, after the zone
+ *   for a zoned string (`"2024-02-24[u-ca=hebrew]"`, `"2024-02-24T00:00:00-05:00[America/New_York][u-ca=hebrew]"`).
+ *   The annotations are read as Temporal reads them: the critical flag and the id's letter case
+ *   are accepted, elective unknown annotations are ignored, the first `u-ca` names the calendar,
+ *   and a string with a time zone annotation is zoned. An unknown critical annotation, a critical
+ *   duplicate calendar, a calendar before the zone, an unsupported calendar and a leap second in
+ *   any spelling return null.
+ *   Compatibility: before 1.16.0 the digits were read as the calendar's own year, month and day.
+ * - `unit` accepts the plural or singular name (`"hours"` or `"hour"`), as Temporal does.
  * - Returns null on a non-duration `value`, an invalid `unit`, or an invalid `relativeTo`.
  *
  * @param value ISO 8601 duration string
- * @param unit DateTimeDurationUnit to total into ("years" | "months" | "weeks" | "days" | "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds")
+ * @param unit DateTimeDurationUnit to total into ("years" | "months" | "weeks" | "days" | "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds", or the singular name)
  * @param options optional: { relativeTo } — anchor date/instant, required for any calendar unit
  * @returns the fractional total in `unit`, or null on invalid input
  *
@@ -32,19 +52,25 @@ import { isValidDuration } from "../validate/isValidDuration.js";
  * @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: "5784-06-15[u-ca=hebrew]" }) // 385 (Hebrew leap year — relativeTo accepts GMT's calendar-annotated PlainDate string, not Temporal's own ISO-digit u-ca convention)
+ * @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)
  */
 export function durationAs(value, unit, options) {
-    if (!isValidDuration(value) || !isValidDateTimeDurationUnit(unit)) {
+    if (!isOptionsArgument(options)) {
+        return null;
+    }
+    const resolvedUnit = resolveDurationUnit(unit);
+    if (!isValidDuration(value) || !isValidDateTimeDurationUnit(resolvedUnit)) {
         return null;
     }
     try {
-        return Temporal.Duration.from(value).total({
-            unit,
-            relativeTo: resolveDurationRelativeTo(options?.relativeTo),
-        });
+        return durationTotal(Temporal.Duration.from(value), resolvedUnit, resolveDurationRelativeTo(options?.relativeTo));
     }
     catch {
         return null;

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

@@ -1,3 +1,4 @@
+import { Temporal } from "@js-temporal/polyfill";
 import type { DateTimeDurationUnit } from "../../types/index.js";
 /**
  * Read a single component out of an ISO 8601 duration string.
@@ -12,11 +13,12 @@ import type { DateTimeDurationUnit } from "../../types/index.js";
  *   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
  *   for each nonzero component of "-P1DT2H", not just the leading one.
+ * - `unit` accepts the plural or singular name (`"hours"` or `"hour"`), as Temporal does.
  * - Returns null when `value` is not a valid duration string or `unit` is not a valid
  *   DateTimeDurationUnit.
  *
  * @param value ISO 8601 duration string
- * @param unit DateTimeDurationUnit to read ("years" | "months" | "weeks" | "days" | "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds")
+ * @param unit DateTimeDurationUnit to read ("years" | "months" | "weeks" | "days" | "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds", or the singular name)
  * @returns the component's value, or null on invalid input
  *
  * @example getDurationUnit("P1DT2H30M", "hours") // 2
@@ -26,6 +28,7 @@ import type { DateTimeDurationUnit } from "../../types/index.js";
  * @example getDurationUnit("P1M", "months") // 1 (no relativeTo needed to read a field)
  * @example getDurationUnit("PT0S", "days") // 0
  * @example getDurationUnit("not a duration", "hours") // null
+ * @example getDurationUnit("P1DT2H30M", "hour") // 2 (singular unit name)
  * @example getDurationUnit("P1D", "fortnights") // null
  */
-export declare function getDurationUnit(value: string, unit: DateTimeDurationUnit): number | null;
+export declare function getDurationUnit(value: string, unit: DateTimeDurationUnit | Temporal.DateTimeUnit): number | null;

package/dist/duration/calculate/getDurationUnit.js

@@ -1,6 +1,7 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
 import { isValidDuration } from "../validate/isValidDuration.js";
+import { resolveDurationUnit } from "../../internal/resolveDurationUnit.js";
 /**
  * Read a single component out of an ISO 8601 duration string.
  *
@@ -14,11 +15,12 @@ import { isValidDuration } from "../validate/isValidDuration.js";
  *   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
  *   for each nonzero component of "-P1DT2H", not just the leading one.
+ * - `unit` accepts the plural or singular name (`"hours"` or `"hour"`), as Temporal does.
  * - Returns null when `value` is not a valid duration string or `unit` is not a valid
  *   DateTimeDurationUnit.
  *
  * @param value ISO 8601 duration string
- * @param unit DateTimeDurationUnit to read ("years" | "months" | "weeks" | "days" | "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds")
+ * @param unit DateTimeDurationUnit to read ("years" | "months" | "weeks" | "days" | "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds", or the singular name)
  * @returns the component's value, or null on invalid input
  *
  * @example getDurationUnit("P1DT2H30M", "hours") // 2
@@ -28,14 +30,16 @@ import { isValidDuration } from "../validate/isValidDuration.js";
  * @example getDurationUnit("P1M", "months") // 1 (no relativeTo needed to read a field)
  * @example getDurationUnit("PT0S", "days") // 0
  * @example getDurationUnit("not a duration", "hours") // null
+ * @example getDurationUnit("P1DT2H30M", "hour") // 2 (singular unit name)
  * @example getDurationUnit("P1D", "fortnights") // null
  */
 export function getDurationUnit(value, unit) {
-    if (!isValidDuration(value) || !isValidDateTimeDurationUnit(unit)) {
+    const resolvedUnit = resolveDurationUnit(unit);
+    if (!isValidDuration(value) || !isValidDateTimeDurationUnit(resolvedUnit)) {
         return null;
     }
     try {
-        return Temporal.Duration.from(value)[unit];
+        return Temporal.Duration.from(value)[resolvedUnit];
     }
     catch {
         return null;

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

@@ -6,7 +6,8 @@ import type { DurationRelativeTo } from "../../types/index.js";
  * - 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; without it, returns null. Note the asymmetry with `addDuration`/`subtractDuration`
+ *   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`
  *   (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.
@@ -14,6 +15,23 @@ import type { DurationRelativeTo } from "../../types/index.js";
  *   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.
+ *   Pass an explicit offset to pick the other reading of an ambiguous wall time.
+ * - A `relativeTo` string is ISO 8601 extended format before its first `[`:
+ *   a date, a date-time, or with a time zone annotation a zoned date-time (`<date>T<time>`, then
+ *   nothing, `Z` or `±HH:MM`). Basic format (`"20240101"`), a space or lower-case `t` separator, a
+ *   lower-case `z`, a UTC offset without a zone and a zoned date without a time are invalid.
+ * - A `relativeTo` string takes a calendar in RFC 9557 form, as `convertDateToCalendar` and
+ *   `convertZonedToCalendar` write it: ISO digits and a `[u-ca=<id>]` annotation, after the zone
+ *   for a zoned string (`"2024-02-24[u-ca=hebrew]"`, `"2024-02-24T00:00:00-05:00[America/New_York][u-ca=hebrew]"`).
+ *   The annotations are read as Temporal reads them: the critical flag and the id's letter case
+ *   are accepted, elective unknown annotations are ignored, the first `u-ca` names the calendar,
+ *   and a string with a time zone annotation is zoned. An unknown critical annotation, a critical
+ *   duplicate calendar, a calendar before the zone, an unsupported calendar and a leap second in
+ *   any spelling return null.
+ *   Compatibility: before 1.16.0 the digits were read as the calendar's own year, month and day.
  * - Returns null if either operand is not a valid ISO 8601 duration string, or `relativeTo`
  *   is invalid.
  *
@@ -28,9 +46,14 @@ import type { DurationRelativeTo } from "../../types/index.js";
  * @example compareDurations("P1M", "P30D") // null (calendar unit needs relativeTo)
  * @example compareDurations("P1M", "P30D", { relativeTo: "2024-01-01" }) // 1
  * @example compareDurations("P1M", "P30D", { relativeTo: "2024-02-01" }) // -1
+ * @example compareDurations("P1M", "P30D", { relativeTo: "2024-02-01 00:00" }) // null (space separator)
  * @example compareDurations("P1D", "PT24H", { relativeTo: "2024-03-10T00:00:00-05:00[America/New_York]" }) // -1 (spring-forward)
+ * @example compareDurations("P1Y", "P1Y") // 0
+ * @example compareDurations("P1D", "PT24H", { relativeTo: "2024-11-03T01:30[America/New_York]" }) // 1
  * @example compareDurations("not a duration", "PT1H") // null
- * @example compareDurations("P1M", "P30D", { relativeTo: "5785-04-15[u-ca=hebrew]" }) // -1 (Tevet, a 29-day Hebrew month — relativeTo accepts GMT's calendar-annotated PlainDate string, not Temporal's own ISO-digit u-ca convention)
+ * @example compareDurations("P1M", "P30D", { relativeTo: "2025-01-15[u-ca=hebrew]" }) // -1 (Tevet 5785, a 29-day Hebrew month)
+ * @example compareDurations("P1M", "P30D", { relativeTo: "2024-02-10[!u-ca=hebrew]" }) // 0 (1 Adar I 5784, a 30-day month; the critical flag is accepted)
+ * @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?: {
     relativeTo?: DurationRelativeTo;