@northguild/gmt 1.18.0 → 1.20.0

package/dist/duration/calculate/totalUnits.js

@@ -0,0 +1,73 @@
+import { Temporal } from "../../internal/temporal.js";
+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
@@ -22,7 +22,7 @@ import type { DurationRelativeTo } from "../../types/index.js";
  *   lower-case `z`, a UTC offset without a zone and a zoned date without a time are invalid.
  * - A `relativeTo` string takes a calendar in RFC 9557 form, as `convertDateToCalendar` and
  *   `convertZonedToCalendar` write it: ISO digits and a `[u-ca=<id>]` annotation, after the zone
- *   for a zoned string (`"2024-02-24[u-ca=hebrew]"`, `"2024-02-24T00:00:00-05:00[America/New_York][u-ca=hebrew]"`).
+ *   for a zoned string (`"2024-02-24[u-ca=hebrew]"`, `"2024-02-24T00:00:00+02:00[Asia/Jerusalem][u-ca=hebrew]"`).
  *   The annotations are read as Temporal reads them: the critical flag and the id's letter case
  *   are accepted, elective unknown annotations are ignored, the first `u-ca` names the calendar,
  *   and a string with a time zone annotation is zoned. An unknown critical annotation, a critical
@@ -44,9 +44,9 @@ import type { DurationRelativeTo } from "../../types/index.js";
  * @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("P1D", "PT24H", { relativeTo: "2024-03-31T00:00:00+00:00[Europe/London]" }) // -1 (spring-forward)
  * @example compareDurations("P1Y", "P1Y") // 0
- * @example compareDurations("P1D", "PT24H", { relativeTo: "2024-11-03T01:30[America/New_York]" }) // 1
+ * @example compareDurations("P1D", "PT24H", { relativeTo: "2024-04-07T02:30[Australia/Sydney]" }) // 1
  * @example compareDurations("not a duration", "PT1H") // null
  * @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)

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
@@ -24,7 +24,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   lower-case `z`, a UTC offset without a zone and a zoned date without a time are invalid.
  * - A `relativeTo` string takes a calendar in RFC 9557 form, as `convertDateToCalendar` and
  *   `convertZonedToCalendar` write it: ISO digits and a `[u-ca=<id>]` annotation, after the zone
- *   for a zoned string (`"2024-02-24[u-ca=hebrew]"`, `"2024-02-24T00:00:00-05:00[America/New_York][u-ca=hebrew]"`).
+ *   for a zoned string (`"2024-02-24[u-ca=hebrew]"`, `"2024-02-24T00:00:00+02:00[Asia/Jerusalem][u-ca=hebrew]"`).
  *   The annotations are read as Temporal reads them: the critical flag and the id's letter case
  *   are accepted, elective unknown annotations are ignored, the first `u-ca` names the calendar,
  *   and a string with a time zone annotation is zoned. An unknown critical annotation, a critical
@@ -46,9 +46,9 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @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("P1D", "PT24H", { relativeTo: "2024-03-31T00:00:00+00:00[Europe/London]" }) // -1 (spring-forward)
  * @example compareDurations("P1Y", "P1Y") // 0
- * @example compareDurations("P1D", "PT24H", { relativeTo: "2024-11-03T01:30[America/New_York]" }) // 1
+ * @example compareDurations("P1D", "PT24H", { relativeTo: "2024-04-07T02:30[Australia/Sydney]" }) // 1
  * @example compareDurations("not a duration", "PT1H") // null
  * @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)

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

@@ -42,16 +42,16 @@ export interface FormatDurationOptions {
  * @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"
- * @example formatDuration("PT90M", "en-US", { style: "short" }) // "90 min"
- * @example formatDuration("PT90M", "en-US", { style: "narrow" }) // "90m"
- * @example formatDuration("P1DT0H30M", "en-US") // "1 day and 30 minutes"
- * @example formatDuration("PT0S", "en-US") // "0 seconds"
- * @example formatDuration("-P1DT2H", "en-US") // "-1 day and -2 hours"
+ * @example formatDuration("P1DT2H30M", "en-GB") // "1 day, 2 hours and 30 minutes"
+ * @example formatDuration("PT90M", "ja-JP", { style: "short" }) // "90 分"
+ * @example formatDuration("PT90M", "hi-IN", { style: "narrow" }) // "90 मि"
+ * @example formatDuration("P1DT0H30M", "pt-BR") // "1 dia e 30 minutos"
+ * @example formatDuration("PT0S", "en-GB") // "0 seconds"
+ * @example formatDuration("-P1DT2H", "pt-BR") // "-1 dia e -2 horas"
  * @example formatDuration("P1DT2H30M", "de-DE") // "1 Tag, 2 Stunden und 30 Minuten"
- * @example formatDuration("PT0.000000001S", "en-US") // "0.000000001 seconds"
- * @example formatDuration("PT1.123456789S", "en-US") // "1.123456789 seconds"
- * @example formatDuration(parseDuration("PT1.123456789S", { smallestUnit: "millisecond" }), "en-US") // "1.123 seconds"
+ * @example formatDuration("PT0.000000001S", "hi-IN") // "0.000000001 सेकंड"
+ * @example formatDuration("PT1.123456789S", "ja-JP") // "1.123456789 秒"
+ * @example formatDuration(parseDuration("PT1.123456789S", { smallestUnit: "millisecond" }), "en-GB") // "1.123 seconds"
  * @example formatDuration("invalid") // ""
  * @example formatDuration("P1DT2H30M", ["es-ES", "en-US"]) // "1 día, 2 horas y 30 minutos"
  */

package/dist/duration/format/formatDuration.js

@@ -1,4 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { cachedFormatter } from "../../internal/formatterCache.js";
+import { Temporal } from "../../internal/temporal.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 import { optionOrDefault } from "../../internal/optionOrDefault.js";
 const UNIT_TO_INTL = {
@@ -71,16 +72,16 @@ function exactSeconds(duration) {
  * @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"
- * @example formatDuration("PT90M", "en-US", { style: "short" }) // "90 min"
- * @example formatDuration("PT90M", "en-US", { style: "narrow" }) // "90m"
- * @example formatDuration("P1DT0H30M", "en-US") // "1 day and 30 minutes"
- * @example formatDuration("PT0S", "en-US") // "0 seconds"
- * @example formatDuration("-P1DT2H", "en-US") // "-1 day and -2 hours"
+ * @example formatDuration("P1DT2H30M", "en-GB") // "1 day, 2 hours and 30 minutes"
+ * @example formatDuration("PT90M", "ja-JP", { style: "short" }) // "90 分"
+ * @example formatDuration("PT90M", "hi-IN", { style: "narrow" }) // "90 मि"
+ * @example formatDuration("P1DT0H30M", "pt-BR") // "1 dia e 30 minutos"
+ * @example formatDuration("PT0S", "en-GB") // "0 seconds"
+ * @example formatDuration("-P1DT2H", "pt-BR") // "-1 dia e -2 horas"
  * @example formatDuration("P1DT2H30M", "de-DE") // "1 Tag, 2 Stunden und 30 Minuten"
- * @example formatDuration("PT0.000000001S", "en-US") // "0.000000001 seconds"
- * @example formatDuration("PT1.123456789S", "en-US") // "1.123456789 seconds"
- * @example formatDuration(parseDuration("PT1.123456789S", { smallestUnit: "millisecond" }), "en-US") // "1.123 seconds"
+ * @example formatDuration("PT0.000000001S", "hi-IN") // "0.000000001 सेकंड"
+ * @example formatDuration("PT1.123456789S", "ja-JP") // "1.123456789 秒"
+ * @example formatDuration(parseDuration("PT1.123456789S", { smallestUnit: "millisecond" }), "en-GB") // "1.123 seconds"
  * @example formatDuration("invalid") // ""
  * @example formatDuration("P1DT2H30M", ["es-ES", "en-US"]) // "1 día, 2 horas y 30 minutos"
  */
@@ -104,20 +105,20 @@ export function formatDuration(value, locale, options = {}) {
             minutes: duration.minutes,
             seconds: exactSeconds(duration),
         };
-        const parts = UNITS_IN_ORDER.filter((unit) => includeZero || !isZeroAmount(amounts[unit])).map((unit) => new Intl.NumberFormat(locale, {
+        const parts = UNITS_IN_ORDER.filter((unit) => includeZero || !isZeroAmount(amounts[unit])).map((unit) => cachedFormatter("NumberFormat", locale, {
             style: "unit",
             unit: UNIT_TO_INTL[unit],
             unitDisplay: style,
             maximumFractionDigits: 9,
         }).format(amounts[unit]));
         if (parts.length === 0) {
-            parts.push(new Intl.NumberFormat(locale, {
+            parts.push(cachedFormatter("NumberFormat", locale, {
                 style: "unit",
                 unit: "second",
                 unitDisplay: style,
             }).format(0));
         }
-        return new Intl.ListFormat(locale, {
+        return cachedFormatter("ListFormat", locale, {
             style: style === "long" ? "long" : "short",
             type: "conjunction",
         }).format(parts);

package/dist/duration/index.d.ts

@@ -1,4 +1,4 @@
-export * from "@js-temporal/polyfill";
+export { Intl, Temporal, toTemporalInstant } from "../internal/temporal.js";
 export * from "./calculate/index.js";
 export * from "./compare/index.js";
 export * from "./format/index.js";

package/dist/duration/index.js

@@ -1,5 +1,5 @@
-// Re-export the Temporal polyfill (`Temporal`, `Intl`, `toTemporalInstant`) so every namespace subpath offers it
-export * from "@js-temporal/polyfill";
+// Re-export `Temporal`, `Intl` and `toTemporalInstant` from the internal seam so every namespace subpath offers them
+export { Intl, Temporal, toTemporalInstant } from "../internal/temporal.js";
 export * from "./calculate/index.js";
 export * from "./compare/index.js";
 export * from "./format/index.js";

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

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import type { DurationRelativeTo } from "../../types/index.js";
 /**
  * Roll an ISO 8601 duration string's small units into larger ones.
@@ -17,7 +17,7 @@ import type { DurationRelativeTo } from "../../types/index.js";
  *   lower-case `z`, a UTC offset without a zone and a zoned date without a time are invalid.
  * - A `relativeTo` string takes a calendar in RFC 9557 form, as `convertDateToCalendar` and
  *   `convertZonedToCalendar` write it: ISO digits and a `[u-ca=<id>]` annotation, after the zone
- *   for a zoned string (`"2024-02-24[u-ca=hebrew]"`, `"2024-02-24T00:00:00-05:00[America/New_York][u-ca=hebrew]"`).
+ *   for a zoned string (`"2024-02-24[u-ca=hebrew]"`, `"2024-02-24T00:00:00+02:00[Asia/Jerusalem][u-ca=hebrew]"`).
  *   The annotations are read as Temporal reads them: the critical flag and the id's letter case
  *   are accepted, elective unknown annotations are ignored, the first `u-ca` names the calendar,
  *   and a string with a time zone annotation is zoned. An unknown critical annotation, a critical
@@ -38,7 +38,7 @@ import type { DurationRelativeTo } from "../../types/index.js";
  * @example normalizeDuration("P45D", { largestUnit: "month", relativeTo: "20240101" }) // "" (basic format)
  * @example normalizeDuration("P1DT25H") // "P2DT1H"
  * @example normalizeDuration("PT2H", { smallestUnit: "minute", roundingIncrement: 60 }) // ""
- * @example normalizeDuration("PT25H", { largestUnit: "day", relativeTo: "2024-11-03T01:30[America/New_York]" }) // "P1D"
+ * @example normalizeDuration("PT25H", { largestUnit: "day", relativeTo: "2024-04-07T02:30[Australia/Sydney]" }) // "P1D"
  * @example normalizeDuration("invalid") // ""
  * @example normalizeDuration("P400D", { largestUnit: "year", relativeTo: "2024-02-24[u-ca=hebrew]" }) // "P1Y15D" (Hebrew leap year 5784)
  * @example normalizeDuration("P45D", { largestUnit: "month", relativeTo: "2024-02-10[!u-ca=hebrew]" }) // "P1M15D" (1 Adar I 5784; the critical flag is accepted)

package/dist/duration/normalize/normalizeDuration.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { durationRound, resolveDurationRelativeTo } from "../../internal/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 import { optionOrDefault } from "../../internal/optionOrDefault.js";
@@ -19,7 +19,7 @@ import { optionOrDefault } from "../../internal/optionOrDefault.js";
  *   lower-case `z`, a UTC offset without a zone and a zoned date without a time are invalid.
  * - A `relativeTo` string takes a calendar in RFC 9557 form, as `convertDateToCalendar` and
  *   `convertZonedToCalendar` write it: ISO digits and a `[u-ca=<id>]` annotation, after the zone
- *   for a zoned string (`"2024-02-24[u-ca=hebrew]"`, `"2024-02-24T00:00:00-05:00[America/New_York][u-ca=hebrew]"`).
+ *   for a zoned string (`"2024-02-24[u-ca=hebrew]"`, `"2024-02-24T00:00:00+02:00[Asia/Jerusalem][u-ca=hebrew]"`).
  *   The annotations are read as Temporal reads them: the critical flag and the id's letter case
  *   are accepted, elective unknown annotations are ignored, the first `u-ca` names the calendar,
  *   and a string with a time zone annotation is zoned. An unknown critical annotation, a critical
@@ -40,7 +40,7 @@ import { optionOrDefault } from "../../internal/optionOrDefault.js";
  * @example normalizeDuration("P45D", { largestUnit: "month", relativeTo: "20240101" }) // "" (basic format)
  * @example normalizeDuration("P1DT25H") // "P2DT1H"
  * @example normalizeDuration("PT2H", { smallestUnit: "minute", roundingIncrement: 60 }) // ""
- * @example normalizeDuration("PT25H", { largestUnit: "day", relativeTo: "2024-11-03T01:30[America/New_York]" }) // "P1D"
+ * @example normalizeDuration("PT25H", { largestUnit: "day", relativeTo: "2024-04-07T02:30[Australia/Sydney]" }) // "P1D"
  * @example normalizeDuration("invalid") // ""
  * @example normalizeDuration("P400D", { largestUnit: "year", relativeTo: "2024-02-24[u-ca=hebrew]" }) // "P1Y15D" (Hebrew leap year 5784)
  * @example normalizeDuration("P45D", { largestUnit: "month", relativeTo: "2024-02-10[!u-ca=hebrew]" }) // "P1M15D" (1 Adar I 5784; the critical flag is accepted)

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

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 /**
  * Parse and re-normalize an ISO 8601 duration string.
  *

package/dist/duration/parse/parseDuration.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Parse and re-normalize an ISO 8601 duration string.

package/dist/duration/validate/isValidDuration.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { isDurationString } from "../../internal/inputChecks.js";
 /**
  * Return true if `value` is a valid ISO 8601 duration string.
  *
@@ -15,14 +15,5 @@ import { Temporal } from "@js-temporal/polyfill";
  * @example isValidDuration("") // false
  */
 export function isValidDuration(value) {
-    if (typeof value !== "string") {
-        return false;
-    }
-    try {
-        Temporal.Duration.from(value);
-        return true;
-    }
-    catch {
-        return false;
-    }
+    return isDurationString(value);
 }

package/dist/gnss/convert/gnssToUtc.d.ts

@@ -0,0 +1,24 @@
+import type { GnssSystem } from "../../types/gnss.js";
+/**
+ * Convert a satellite system's time-scale string to a UTC instant string.
+ *
+ * - Reads `YYYY-MM-DDTHH:MM:SS[.fraction] <token>` with the system's RINEX token. Any other token
+ *   returns "".
+ * - A continuous scale has no second 60; `GLO` has one exactly when UTC does.
+ * - During an inserted leap second the result is `…T23:59:60Z`. Only this realm's functions read
+ *   that string back; other GMT functions reject a second of 60.
+ * - "" before the system's epoch and on invalid input.
+ *
+ * @param system satellite time scale: "GPS", "GAL", "BDT", "QZS", "GLO" or "IRN"
+ * @param value the system's time-scale string
+ * @returns ISO 8601 UTC instant string (`Z`), or "" on invalid input or before the system's epoch
+ *
+ * @example gnssToUtc("GPS", "2017-01-01T00:00:17 GPS") // "2016-12-31T23:59:60Z"
+ * @example gnssToUtc("GPS", "2038-11-21T00:00:00 GPS") // "2038-11-20T23:59:42Z"
+ * @example gnssToUtc("BDT", "2024-01-01T00:00:04 BDT") // "2024-01-01T00:00:00Z"
+ * @example gnssToUtc("GAL", "1999-08-22T00:00:00 GAL") // "1999-08-21T23:59:47Z"
+ * @example gnssToUtc("GLO", "2016-12-31T23:59:60 GLO") // "2016-12-31T23:59:60Z"
+ * @example gnssToUtc("GLO", "2017-12-31T23:59:60 GLO") // "" — no leap second that day
+ * @example gnssToUtc("GPS", "2024-01-01T00:00:18 GAL") // "" — wrong token
+ */
+export declare function gnssToUtc(system: GnssSystem, value: string): string;

package/dist/gnss/convert/gnssToUtc.js

@@ -0,0 +1,39 @@
+import { formatUtcReading, isGnssSystem, parseTimeScaleString, utcOfScaleLabel, } from "../../internal/index.js";
+/**
+ * Convert a satellite system's time-scale string to a UTC instant string.
+ *
+ * - Reads `YYYY-MM-DDTHH:MM:SS[.fraction] <token>` with the system's RINEX token. Any other token
+ *   returns "".
+ * - A continuous scale has no second 60; `GLO` has one exactly when UTC does.
+ * - During an inserted leap second the result is `…T23:59:60Z`. Only this realm's functions read
+ *   that string back; other GMT functions reject a second of 60.
+ * - "" before the system's epoch and on invalid input.
+ *
+ * @param system satellite time scale: "GPS", "GAL", "BDT", "QZS", "GLO" or "IRN"
+ * @param value the system's time-scale string
+ * @returns ISO 8601 UTC instant string (`Z`), or "" on invalid input or before the system's epoch
+ *
+ * @example gnssToUtc("GPS", "2017-01-01T00:00:17 GPS") // "2016-12-31T23:59:60Z"
+ * @example gnssToUtc("GPS", "2038-11-21T00:00:00 GPS") // "2038-11-20T23:59:42Z"
+ * @example gnssToUtc("BDT", "2024-01-01T00:00:04 BDT") // "2024-01-01T00:00:00Z"
+ * @example gnssToUtc("GAL", "1999-08-22T00:00:00 GAL") // "1999-08-21T23:59:47Z"
+ * @example gnssToUtc("GLO", "2016-12-31T23:59:60 GLO") // "2016-12-31T23:59:60Z"
+ * @example gnssToUtc("GLO", "2017-12-31T23:59:60 GLO") // "" — no leap second that day
+ * @example gnssToUtc("GPS", "2024-01-01T00:00:18 GAL") // "" — wrong token
+ */
+export function gnssToUtc(system, value) {
+    try {
+        if (!isGnssSystem(system)) {
+            return "";
+        }
+        const label = parseTimeScaleString(value, system);
+        if (label === null) {
+            return "";
+        }
+        const reading = utcOfScaleLabel(system, label);
+        return reading === null ? "" : formatUtcReading(reading);
+    }
+    catch {
+        return "";
+    }
+}

package/dist/gnss/convert/gnssWeekToUtc.d.ts

@@ -0,0 +1,53 @@
+import type { GnssWeekCounter, RolloverEra } from "../../types/gnss.js";
+/**
+ * Convert a week number and time of week, as a receiver reports them, to a UTC instant string.
+ *
+ * - Name the counter the week came from: GPS and QZSS LNAV wrap every 1024 weeks (about 19.6
+ *   years), their CNAV every 8192, Galileo every 4096, BeiDou every 8192, NavIC LNAV every 1024
+ *   and L1NV every 8192.
+ * - A week number alone cannot say which pass it is, so `rolloverEra` is required: an integer (era
+ *   0 starts at the system's epoch); `"rolling"` for the pass within half a counter period of today,
+ *   or era 0, when the week would otherwise fall before the system's epoch; or `{ notBefore }` for
+ *   the earliest pass at or after an instant you state, as a receiver that resolves weeks against
+ *   its firmware build date does. An instant exactly at `notBefore` counts, and a `notBefore`
+ *   before the counter's epoch gives era 0.
+ *   Receivers that report a stale week need an integer or a pivot.
+ * - `timeOfWeekSeconds` is seconds of week and may have a fraction; it is rounded to the nearest
+ *   nanosecond, and a value that rounds to 604 800 s returns "". Convert a coarser broadcast count
+ *   first (NavIC L5/S: TOWC × 12; NavIC L1: ITOW × 7200 + TOI × 18, per the NavIC ICDs). Both
+ *   counts name the start of the next subframe (L5/S) or 18-second frame (L1), so the last one of
+ *   a week (TOWC 50400; ITOW 83 with TOI 400) gives 604 800 s. That value is TOW 0 of the next
+ *   week: pass `week + 1` and 0. When `week` is the counter's last (1023 or 8191), pass week 0,
+ *   with `rolloverEra + 1` for an integer era or the same `"rolling"` or `{ notBefore }`.
+ * - A week time inside an inserted leap second returns `…T23:59:60Z`. Only this realm's functions
+ *   read that string back; other GMT functions reject a second of 60.
+ * - GLONASS has no week counter, so it is not a counter here.
+ * - A RINEX navigation-file week is a continuous count, not a broadcast week: read it with
+ *   `rinexWeekToUtc`. A RINEX NavIC week given to `"IRN-L1NV"` would be 1024 weeks off.
+ * - "" when `week`, `timeOfWeekSeconds` or `rolloverEra` is out of range (a `notBefore` that is not an
+ *   instant, or is an unlisted second 60, included), for a result past year 9999, and on invalid input.
+ *
+ * @param counter the week counter: "GPS-LNAV", "GPS-CNAV", "GAL", "BDT", "QZS-LNAV", "QZS-CNAV", "IRN-LNAV" or "IRN-L1NV"
+ * @param week week number as the counter shows it, 0 to the counter's modulus − 1
+ * @param timeOfWeekSeconds seconds since the start of the week, 0 up to but not including 604 800, rounded to the nearest nanosecond; a value that rounds to 604 800 s returns ""
+ * @param rolloverEra the counter's pass: an integer from 0, "rolling" (within half a counter period of today, or era 0, when the week would otherwise fall before the system's epoch), or `{ notBefore }` with an ISO 8601 UTC instant
+ * @returns ISO 8601 UTC instant string (`Z`), or "" on invalid input
+ *
+ * @example gnssWeekToUtc("GPS-LNAV", 100, 0, 0) // "1981-12-05T23:59:59Z"
+ * @example gnssWeekToUtc("GPS-LNAV", 100, 0, 1) // "2001-07-21T23:59:47Z"
+ * @example gnssWeekToUtc("GPS-LNAV", 0, 0, 3) // "2038-11-20T23:59:42Z" — the third LNAV rollover
+ * @example gnssWeekToUtc("GPS-CNAV", 2295, 86418, 0) // "2024-01-01T00:00:00Z"
+ * @example gnssWeekToUtc("BDT", 939, 86404, 0) // "2024-01-01T00:00:00Z"
+ * @example gnssWeekToUtc("GPS-LNAV", 906, 17, 1) // "2016-12-31T23:59:60Z"
+ * @example gnssWeekToUtc("GPS-LNAV", 0, 0, 2) // "2019-04-06T23:59:42Z" — the second LNAV rollover
+ * @example gnssWeekToUtc("GPS-LNAV", 1020, 0, { notBefore: "2019-01-01T00:00:00Z" }) // "2019-03-09T23:59:42Z"
+ * @example gnssWeekToUtc("GPS-LNAV", 1020, 0, { notBefore: "2019-04-07T00:00:00Z" }) // "2038-10-23T23:59:42Z" — after the 2019 rollover
+ * @example gnssWeekToUtc("GPS-LNAV", 0, 0, { notBefore: "2019-04-06T23:59:42Z" }) // "2019-04-06T23:59:42Z" — equal counts
+ * @example gnssWeekToUtc("GAL", 100, 0, { notBefore: "1999-01-01T00:00:00Z" }) // "2001-07-21T23:59:47Z" — before Galileo's epoch: era 0
+ * @example gnssWeekToUtc("GPS-LNAV", 1024, 0, 2) // "" — an LNAV week stops at 1023
+ * @example gnssWeekToUtc("IRN-LNAV", 247, 50399 * 12, 1) // "2024-01-06T23:59:30Z" — TOWC 50399
+ * @example gnssWeekToUtc("IRN-LNAV", 247, 50400 * 12, 1) // "" — TOWC 50400 is 604 800 s, not a time of week
+ * @example gnssWeekToUtc("IRN-LNAV", 248, 0, 1) // "2024-01-06T23:59:42Z" — TOWC 50400 of week 247
+ * @example gnssWeekToUtc("IRN-LNAV", 0, 0, 2) // "2038-11-20T23:59:42Z" — TOWC 50400 of week 1023, era 1
+ */
+export declare function gnssWeekToUtc(counter: GnssWeekCounter, week: number, timeOfWeekSeconds: number, rolloverEra: RolloverEra): string;

package/dist/gnss/convert/gnssWeekToUtc.js

@@ -0,0 +1,80 @@
+import { formatUtcReading, GNSS_WEEK_COUNTERS, isGnssWeekCounter, labelOfWeek, resolveRolloverEra, timeOfWeekNanoseconds, utcOfScaleLabel, weekNumber, } from "../../internal/index.js";
+/**
+ * Convert a week number and time of week, as a receiver reports them, to a UTC instant string.
+ *
+ * - Name the counter the week came from: GPS and QZSS LNAV wrap every 1024 weeks (about 19.6
+ *   years), their CNAV every 8192, Galileo every 4096, BeiDou every 8192, NavIC LNAV every 1024
+ *   and L1NV every 8192.
+ * - A week number alone cannot say which pass it is, so `rolloverEra` is required: an integer (era
+ *   0 starts at the system's epoch); `"rolling"` for the pass within half a counter period of today,
+ *   or era 0, when the week would otherwise fall before the system's epoch; or `{ notBefore }` for
+ *   the earliest pass at or after an instant you state, as a receiver that resolves weeks against
+ *   its firmware build date does. An instant exactly at `notBefore` counts, and a `notBefore`
+ *   before the counter's epoch gives era 0.
+ *   Receivers that report a stale week need an integer or a pivot.
+ * - `timeOfWeekSeconds` is seconds of week and may have a fraction; it is rounded to the nearest
+ *   nanosecond, and a value that rounds to 604 800 s returns "". Convert a coarser broadcast count
+ *   first (NavIC L5/S: TOWC × 12; NavIC L1: ITOW × 7200 + TOI × 18, per the NavIC ICDs). Both
+ *   counts name the start of the next subframe (L5/S) or 18-second frame (L1), so the last one of
+ *   a week (TOWC 50400; ITOW 83 with TOI 400) gives 604 800 s. That value is TOW 0 of the next
+ *   week: pass `week + 1` and 0. When `week` is the counter's last (1023 or 8191), pass week 0,
+ *   with `rolloverEra + 1` for an integer era or the same `"rolling"` or `{ notBefore }`.
+ * - A week time inside an inserted leap second returns `…T23:59:60Z`. Only this realm's functions
+ *   read that string back; other GMT functions reject a second of 60.
+ * - GLONASS has no week counter, so it is not a counter here.
+ * - A RINEX navigation-file week is a continuous count, not a broadcast week: read it with
+ *   `rinexWeekToUtc`. A RINEX NavIC week given to `"IRN-L1NV"` would be 1024 weeks off.
+ * - "" when `week`, `timeOfWeekSeconds` or `rolloverEra` is out of range (a `notBefore` that is not an
+ *   instant, or is an unlisted second 60, included), for a result past year 9999, and on invalid input.
+ *
+ * @param counter the week counter: "GPS-LNAV", "GPS-CNAV", "GAL", "BDT", "QZS-LNAV", "QZS-CNAV", "IRN-LNAV" or "IRN-L1NV"
+ * @param week week number as the counter shows it, 0 to the counter's modulus − 1
+ * @param timeOfWeekSeconds seconds since the start of the week, 0 up to but not including 604 800, rounded to the nearest nanosecond; a value that rounds to 604 800 s returns ""
+ * @param rolloverEra the counter's pass: an integer from 0, "rolling" (within half a counter period of today, or era 0, when the week would otherwise fall before the system's epoch), or `{ notBefore }` with an ISO 8601 UTC instant
+ * @returns ISO 8601 UTC instant string (`Z`), or "" on invalid input
+ *
+ * @example gnssWeekToUtc("GPS-LNAV", 100, 0, 0) // "1981-12-05T23:59:59Z"
+ * @example gnssWeekToUtc("GPS-LNAV", 100, 0, 1) // "2001-07-21T23:59:47Z"
+ * @example gnssWeekToUtc("GPS-LNAV", 0, 0, 3) // "2038-11-20T23:59:42Z" — the third LNAV rollover
+ * @example gnssWeekToUtc("GPS-CNAV", 2295, 86418, 0) // "2024-01-01T00:00:00Z"
+ * @example gnssWeekToUtc("BDT", 939, 86404, 0) // "2024-01-01T00:00:00Z"
+ * @example gnssWeekToUtc("GPS-LNAV", 906, 17, 1) // "2016-12-31T23:59:60Z"
+ * @example gnssWeekToUtc("GPS-LNAV", 0, 0, 2) // "2019-04-06T23:59:42Z" — the second LNAV rollover
+ * @example gnssWeekToUtc("GPS-LNAV", 1020, 0, { notBefore: "2019-01-01T00:00:00Z" }) // "2019-03-09T23:59:42Z"
+ * @example gnssWeekToUtc("GPS-LNAV", 1020, 0, { notBefore: "2019-04-07T00:00:00Z" }) // "2038-10-23T23:59:42Z" — after the 2019 rollover
+ * @example gnssWeekToUtc("GPS-LNAV", 0, 0, { notBefore: "2019-04-06T23:59:42Z" }) // "2019-04-06T23:59:42Z" — equal counts
+ * @example gnssWeekToUtc("GAL", 100, 0, { notBefore: "1999-01-01T00:00:00Z" }) // "2001-07-21T23:59:47Z" — before Galileo's epoch: era 0
+ * @example gnssWeekToUtc("GPS-LNAV", 1024, 0, 2) // "" — an LNAV week stops at 1023
+ * @example gnssWeekToUtc("IRN-LNAV", 247, 50399 * 12, 1) // "2024-01-06T23:59:30Z" — TOWC 50399
+ * @example gnssWeekToUtc("IRN-LNAV", 247, 50400 * 12, 1) // "" — TOWC 50400 is 604 800 s, not a time of week
+ * @example gnssWeekToUtc("IRN-LNAV", 248, 0, 1) // "2024-01-06T23:59:42Z" — TOWC 50400 of week 247
+ * @example gnssWeekToUtc("IRN-LNAV", 0, 0, 2) // "2038-11-20T23:59:42Z" — TOWC 50400 of week 1023, era 1
+ */
+export function gnssWeekToUtc(counter, week, timeOfWeekSeconds, rolloverEra) {
+    try {
+        if (!isGnssWeekCounter(counter)) {
+            return "";
+        }
+        const { system, modulus } = GNSS_WEEK_COUNTERS[counter];
+        const counterWeek = weekNumber(week);
+        if (counterWeek === null || counterWeek >= modulus) {
+            return "";
+        }
+        const timeOfWeek = timeOfWeekNanoseconds(timeOfWeekSeconds);
+        if (timeOfWeek === null) {
+            return "";
+        }
+        const era = resolveRolloverEra(counter, counterWeek, timeOfWeek, rolloverEra);
+        if (era === null) {
+            return "";
+        }
+        const reading = utcOfScaleLabel(system, {
+            labelNanoseconds: labelOfWeek(counter, counterWeek, timeOfWeek, era),
+            secondSixty: false,
+        });
+        return reading === null ? "" : formatUtcReading(reading);
+    }
+    catch {
+        return "";
+    }
+}

package/dist/gnss/convert/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./gnssToUtc.js";
+export * from "./gnssWeekToUtc.js";
+export * from "./rinexWeekToUtc.js";
+export * from "./utcToGnss.js";
+export * from "./utcToGnssWeek.js";
+export * from "./utcToRinexWeek.js";

package/dist/gnss/convert/index.js

@@ -0,0 +1,6 @@
+export * from "./gnssToUtc.js";
+export * from "./gnssWeekToUtc.js";
+export * from "./rinexWeekToUtc.js";
+export * from "./utcToGnss.js";
+export * from "./utcToGnssWeek.js";
+export * from "./utcToRinexWeek.js";

package/dist/gnss/convert/rinexWeekToUtc.d.ts

@@ -0,0 +1,34 @@
+import type { RinexWeekSystem } from "../../types/gnss.js";
+/**
+ * Convert a week number from a RINEX navigation file, and the seconds of that week, to a UTC
+ * instant string.
+ *
+ * - A RINEX navigation record's week is a continuous count that never wraps. For GPS, QZSS, NavIC
+ *   and Galileo records it counts from the GPS epoch, 1980-01-06 (RINEX 4.02 Table A30: "Continuous
+ *   number, not mod (1024), counted from 1980 (same as GPS)"; Tables A9, A13, A19). A BeiDou record
+ *   counts BDT weeks from 2006-01-01 (RINEX 4.02 §5.4.6, Table A23).
+ * - CNAV/CNAV-2, BDS CNAV-1/2/3 and NavIC L1NV records have no week column: take the week from the
+ *   record's epoch line.
+ * - It is not the week a satellite broadcasts: a NavIC broadcast week counts from 1999 and wraps.
+ *   Use `gnssWeekToUtc` for those.
+ * - A full GPS week number from any other source is the same count, so `"GPS"` reads it too.
+ * - GLONASS records carry no week number.
+ * - A week time inside an inserted leap second returns `…T23:59:60Z`.
+ * - `timeOfWeekSeconds` may have a fraction; it is rounded to the nearest nanosecond, and a value
+ *   that rounds to 604 800 s returns "".
+ * - "" for a negative or non-integer week, a time of week outside 0 up to 604 800, a time before
+ *   the system's epoch (Galileo and NavIC time start on 1999-08-22, RINEX week 1024), a result past
+ *   year 9999, and on invalid input.
+ *
+ * @param system the RINEX record's system: "GPS", "GAL", "BDT", "QZS" or "IRN"
+ * @param week the record's week number
+ * @param timeOfWeekSeconds seconds since the start of the week, 0 up to but not including 604 800, rounded to the nearest nanosecond; a value that rounds to 604 800 s returns ""
+ * @returns ISO 8601 UTC instant string (`Z`), or "" on invalid input
+ *
+ * @example rinexWeekToUtc("IRN", 2295, 86418) // "2024-01-01T00:00:00Z"
+ * @example rinexWeekToUtc("GPS", 1930, 17) // "2016-12-31T23:59:60Z"
+ * @example rinexWeekToUtc("GPS", 3072, 0) // "2038-11-20T23:59:42Z"
+ * @example rinexWeekToUtc("BDT", 809, 165600) // "2021-07-05T21:59:56Z" — RINEX Table A27's C05 record
+ * @example rinexWeekToUtc("GPS", -1, 0) // ""
+ */
+export declare function rinexWeekToUtc(system: RinexWeekSystem, week: number, timeOfWeekSeconds: number): string;