@northguild/gmt 1.18.0 → 1.19.0

package/dist/regex/time-zone-like.d.ts

@@ -1,11 +1,12 @@
 /**
  * RegExp matching the shape of a time zone identifier: Temporal's `TimeZoneIdentifier` grammar
- * (§14.6.2 Time Zone Identifiers), `UTCOffset[~SubMinutePrecision] | TimeZoneIANAName`.
+ * (§13.31, the ISO 8601 / RFC 9557 grammar),
+ * `TimeZoneIdentifier ::: UTCOffset[~SubMinutePrecision] | TimeZoneIANAName`.
  *
  * - An offset identifier (`UTCOffset[~SubMinutePrecision]`): an ASCII sign and a two-digit hour
  *   `00`–`23`, optionally followed by two minute digits `00`–`59`, with or without `:` (`+05`,
  *   `+0530`, `-08:00`). No seconds and no fraction. `Intl.DateTimeFormat` accepts the same
- *   offsets (ECMA-402 `IsTimeZoneOffsetString`).
+ *   offsets (ECMA-262 `IsTimeZoneOffsetString`, which ECMA-402 calls).
  * - An IANA name (`TimeZoneIANAName`): one or more `/`-separated components. Each starts with a
  *   letter, `.` or `_` (`TZLeadingChar`) and continues with letters, digits, `.`, `_`, `-` or `+`
  *   (`TZChar`). So single-component names match (`UTC`, `Japan`, `Zulu`, `EST5EDT`, `GMT+0`,

package/dist/regex/time-zone-like.js

@@ -1,11 +1,12 @@
 /**
  * RegExp matching the shape of a time zone identifier: Temporal's `TimeZoneIdentifier` grammar
- * (§14.6.2 Time Zone Identifiers), `UTCOffset[~SubMinutePrecision] | TimeZoneIANAName`.
+ * (§13.31, the ISO 8601 / RFC 9557 grammar),
+ * `TimeZoneIdentifier ::: UTCOffset[~SubMinutePrecision] | TimeZoneIANAName`.
  *
  * - An offset identifier (`UTCOffset[~SubMinutePrecision]`): an ASCII sign and a two-digit hour
  *   `00`–`23`, optionally followed by two minute digits `00`–`59`, with or without `:` (`+05`,
  *   `+0530`, `-08:00`). No seconds and no fraction. `Intl.DateTimeFormat` accepts the same
- *   offsets (ECMA-402 `IsTimeZoneOffsetString`).
+ *   offsets (ECMA-262 `IsTimeZoneOffsetString`, which ECMA-402 calls).
  * - An IANA name (`TimeZoneIANAName`): one or more `/`-separated components. Each starts with a
  *   letter, `.` or `_` (`TZLeadingChar`) and continues with letters, digits, `.`, `_`, `-` or `+`
  *   (`TZChar`). So single-component names match (`UTC`, `Japan`, `Zulu`, `EST5EDT`, `GMT+0`,

package/dist/regex/utc-offset.d.ts

@@ -12,7 +12,8 @@
  * - Sub-second offsets are rejected. ISO 8601 permits them and `Temporal.Instant.from` parses
  *   them, but no zone, and no standard that stores this pair, has ever used one.
  * - Shape only. Whether the offset is in Temporal's representable range is a separate check —
- *   `internal/utcOffsetString.ts` applies both.
+ *   `internal/utcOffsetString.ts` applies both. To check a value that may not be a string, use
+ *   `isValidUtcOffset`: for a string it gives this pattern's answer.
  *
  * @example utcOffset.test("-04:00") // true
  * @example utcOffset.test("+05:45") // true

package/dist/regex/utc-offset.js

@@ -12,7 +12,8 @@
  * - Sub-second offsets are rejected. ISO 8601 permits them and `Temporal.Instant.from` parses
  *   them, but no zone, and no standard that stores this pair, has ever used one.
  * - Shape only. Whether the offset is in Temporal's representable range is a separate check —
- *   `internal/utcOffsetString.ts` applies both.
+ *   `internal/utcOffsetString.ts` applies both. To check a value that may not be a string, use
+ *   `isValidUtcOffset`: for a string it gives this pattern's answer.
  *
  * @example utcOffset.test("-04:00") // true
  * @example utcOffset.test("+05:45") // true

package/dist/transport/calculate/crossingTime.d.ts

@@ -39,10 +39,15 @@ export interface Crossing {
  * - Returns `null` when either instant is invalid, when `exit` is before `entry` (an inverted
  *   crossing is a data error, not a negative transit), or when the zone is invalid. A zero-length
  *   crossing is `PT0S`.
+ * - An offset with seconds (`-00:44:30`) returns `null`. A written zone cannot carry seconds (RFC
+ *   9557 §4.1), so the result could not name it. Pass the IANA name, or call
+ *   `fromOffsetInstant({ instant, offset })` for the local time with its full offset and no
+ *   bracket.
  *
  * @param entry ISO 8601 zoned datetime or instant string of entering the crossing
  * @param exit ISO 8601 zoned datetime or instant string of leaving it
- * @param targetZone IANA timeZone identifier or fixed offset the crossing is read in
+ * @param targetZone IANA name or a UTC offset to the minute (what `isValidTimeZone` accepts) the
+ *   crossing is read in
  * @returns exact duration and zone-local entry and exit, or null on invalid input
  *
  * @example crossingTime("2024-06-15T08:00:00Z", "2024-06-15T17:30:00Z", "Europe/Berlin") // { duration: "PT9H30M", enter: "2024-06-15T10:00:00+02:00[Europe/Berlin]", exit: "2024-06-15T19:30:00+02:00[Europe/Berlin]" }

package/dist/transport/calculate/crossingTime.js

@@ -31,10 +31,15 @@ import { isValidTimeZone } from "../../zoned/validate/isValidTimeZone.js";
  * - Returns `null` when either instant is invalid, when `exit` is before `entry` (an inverted
  *   crossing is a data error, not a negative transit), or when the zone is invalid. A zero-length
  *   crossing is `PT0S`.
+ * - An offset with seconds (`-00:44:30`) returns `null`. A written zone cannot carry seconds (RFC
+ *   9557 §4.1), so the result could not name it. Pass the IANA name, or call
+ *   `fromOffsetInstant({ instant, offset })` for the local time with its full offset and no
+ *   bracket.
  *
  * @param entry ISO 8601 zoned datetime or instant string of entering the crossing
  * @param exit ISO 8601 zoned datetime or instant string of leaving it
- * @param targetZone IANA timeZone identifier or fixed offset the crossing is read in
+ * @param targetZone IANA name or a UTC offset to the minute (what `isValidTimeZone` accepts) the
+ *   crossing is read in
  * @returns exact duration and zone-local entry and exit, or null on invalid input
  *
  * @example crossingTime("2024-06-15T08:00:00Z", "2024-06-15T17:30:00Z", "Europe/Berlin") // { duration: "PT9H30M", enter: "2024-06-15T10:00:00+02:00[Europe/Berlin]", exit: "2024-06-15T19:30:00+02:00[Europe/Berlin]" }

package/dist/transport/calculate/cutoffAt.d.ts

@@ -1,7 +1,10 @@
 import type { BusinessCalendar, RollConvention } from "../../types/index.js";
 /** Options for `cutoffAt`. */
 export interface CutoffOptions {
-    /** The time zone the cut-off is read in, the terminal's clock: an IANA name or a UTC offset. */
+    /**
+     * The time zone the cut-off is read in, the terminal's clock: an IANA name or a UTC offset to the
+     * minute (what `isValidTimeZone` accepts).
+     */
     timeZone: string;
     /**
      * The local time of day the cut-off is pinned to (`"17:00"`), as `isValidTime` accepts.
@@ -69,6 +72,8 @@ export interface CutoffOptions {
  *   **nonexistent** one (a skipped hour, a deleted day) returns `""` rather than being
  *   shifted. An exact result that is not re-resolved stays as it is.
  * - Returns the cut-off as a zoned string in `timeZone`, or `""` on invalid input.
+ * - An offset with seconds (`-00:44:30`) returns `""`. A written zone cannot carry seconds (RFC
+ *   9557 §4.1), so the result could not name it. Pass the IANA name.
  *
  * @param anchor ISO 8601 instant or zoned datetime string of the event the deadline counts back from
  * @param offset ISO 8601 duration before the anchor

package/dist/transport/calculate/cutoffAt.js

@@ -144,6 +144,8 @@ function rolledDate(date, options) {
  *   **nonexistent** one (a skipped hour, a deleted day) returns `""` rather than being
  *   shifted. An exact result that is not re-resolved stays as it is.
  * - Returns the cut-off as a zoned string in `timeZone`, or `""` on invalid input.
+ * - An offset with seconds (`-00:44:30`) returns `""`. A written zone cannot carry seconds (RFC
+ *   9557 §4.1), so the result could not name it. Pass the IANA name.
  *
  * @param anchor ISO 8601 instant or zoned datetime string of the event the deadline counts back from
  * @param offset ISO 8601 duration before the anchor

package/dist/transport/calculate/cutoffSchedule.d.ts

@@ -22,7 +22,10 @@ export interface CutoffTime {
 }
 /** Options for `cutoffSchedule`: `cutoffAt`'s, with `atLocalTime` read from each entry instead. */
 export interface CutoffScheduleOptions {
-    /** The time zone every cut-off is read in: an IANA name or a UTC offset. */
+    /**
+     * The time zone every cut-off is read in: an IANA name or a UTC offset to the minute (what
+     * `isValidTimeZone` accepts).
+     */
     timeZone: string;
     /**
      * The working week and holidays every cut-off's local date is rolled against. Requires `roll`.
@@ -55,6 +58,8 @@ export interface CutoffScheduleOptions {
  * - Every entry must succeed: one invalid entry, or one cut-off in a skipped local hour,
  *   returns `[]` rather than a stack with a deadline silently missing. An empty `cutoffs` array
  *   returns `[]`.
+ * - An offset with seconds (`-00:44:30`) returns `[]`. A written zone cannot carry seconds (RFC
+ *   9557 §4.1), so the result could not name it. Pass the IANA name.
  *
  * @param anchor ISO 8601 instant or zoned datetime string of the event the deadlines count back from
  * @param cutoffs the named deadlines, each with an offset and an optional local time of day

package/dist/transport/calculate/cutoffSchedule.js

@@ -20,6 +20,8 @@ import { cutoffAt } from "./cutoffAt.js";
  * - Every entry must succeed: one invalid entry, or one cut-off in a skipped local hour,
  *   returns `[]` rather than a stack with a deadline silently missing. An empty `cutoffs` array
  *   returns `[]`.
+ * - An offset with seconds (`-00:44:30`) returns `[]`. A written zone cannot carry seconds (RFC
+ *   9557 §4.1), so the result could not name it. Pass the IANA name.
  *
  * @param anchor ISO 8601 instant or zoned datetime string of the event the deadlines count back from
  * @param cutoffs the named deadlines, each with an offset and an optional local time of day

package/dist/transport/calculate/dwellTime.d.ts

@@ -60,10 +60,15 @@ export interface Dwell {
  *   more than 10,000 transitions (about 5,000 years of twice-yearly DST) returns `null`.
  * - Returns `null` when either instant is invalid, when `exit` is before `entry` (an inverted
  *   dwell is a data error, not a negative stay), or when no zone can be determined.
+ * - An offset with seconds (`-00:44:30`) returns `null`. A written zone cannot carry seconds (RFC
+ *   9557 §4.1), so the result could not name it. Pass the IANA name, or call
+ *   `fromOffsetInstant({ instant, offset })` for the local time with its full offset and no
+ *   bracket.
  *
  * @param entry ISO 8601 zoned datetime or instant string of the gate-in, arrival or admission
  * @param exit ISO 8601 zoned datetime or instant string of the gate-out, departure or discharge
- * @param targetZone IANA timeZone identifier or fixed offset the days are counted in; defaults to `entry`'s bracketed zone
+ * @param targetZone IANA name or a UTC offset to the minute (what `isValidTimeZone` accepts) the
+ *   days are counted in; defaults to `entry`'s bracketed zone
  * @returns exact duration, zone-local entry and exit, and the local calendar days touched, or null on invalid input
  *
  * @example dwellTime("2024-06-15T23:00:00-04:00[America/New_York]", "2024-06-16T01:00:00-04:00[America/New_York]") // { duration: "PT2H", enter: "2024-06-15T23:00:00-04:00[America/New_York]", exit: "2024-06-16T01:00:00-04:00[America/New_York]", calendarDays: 2 }

package/dist/transport/calculate/dwellTime.js

@@ -69,10 +69,15 @@ function dwellZone(entry, targetZone) {
  *   more than 10,000 transitions (about 5,000 years of twice-yearly DST) returns `null`.
  * - Returns `null` when either instant is invalid, when `exit` is before `entry` (an inverted
  *   dwell is a data error, not a negative stay), or when no zone can be determined.
+ * - An offset with seconds (`-00:44:30`) returns `null`. A written zone cannot carry seconds (RFC
+ *   9557 §4.1), so the result could not name it. Pass the IANA name, or call
+ *   `fromOffsetInstant({ instant, offset })` for the local time with its full offset and no
+ *   bracket.
  *
  * @param entry ISO 8601 zoned datetime or instant string of the gate-in, arrival or admission
  * @param exit ISO 8601 zoned datetime or instant string of the gate-out, departure or discharge
- * @param targetZone IANA timeZone identifier or fixed offset the days are counted in; defaults to `entry`'s bracketed zone
+ * @param targetZone IANA name or a UTC offset to the minute (what `isValidTimeZone` accepts) the
+ *   days are counted in; defaults to `entry`'s bracketed zone
  * @returns exact duration, zone-local entry and exit, and the local calendar days touched, or null on invalid input
  *
  * @example dwellTime("2024-06-15T23:00:00-04:00[America/New_York]", "2024-06-16T01:00:00-04:00[America/New_York]") // { duration: "PT2H", enter: "2024-06-15T23:00:00-04:00[America/New_York]", exit: "2024-06-16T01:00:00-04:00[America/New_York]", calendarDays: 2 }

package/dist/transport/calculate/scheduleDelivery.d.ts

@@ -12,7 +12,10 @@ export interface Leg {
     departure?: string;
     /** The ISO 8601 duration of the leg; time units and 24-hour days only (`transitTime`'s rule). */
     duration: string;
-    /** The time zone of the destination, the caller's fact: an IANA name or a UTC offset. */
+    /**
+     * The time zone of the destination, the caller's fact: an IANA name or a UTC offset to the minute
+     * (what `isValidTimeZone` accepts).
+     */
     timeZone: string;
     /**
      * The handling time at the handoff after this leg; the minimum connect time.
@@ -57,10 +60,11 @@ export interface LegTime {
 /** Options for `scheduleDelivery`. */
 export interface ScheduleDeliveryOptions {
     /**
-     * The time zone a zoneless first-leg departure is read in, an IANA name or a UTC offset, for
-     * schedules published as local wall times. An ambiguous wall time resolves to the earlier instant
-     * and a nonexistent one to the later instant (`"compatible"`). Ignored when the first departure
-     * is already exact; never applied to later legs.
+     * The time zone a zoneless first-leg departure is read in, an IANA name or a UTC offset to the
+     * minute (what `isValidTimeZone` accepts), for schedules published as local wall times. An
+     * ambiguous wall time resolves to the earlier instant and a nonexistent one to the later instant
+     * (`"compatible"`). Ignored when the first departure is already exact; never applied to later
+     * legs.
      *
      * @defaultValue None. A zoneless first-leg departure is invalid input.
      */
@@ -128,6 +132,10 @@ export interface DeliverySchedule {
  * - An empty legs array is valid vacuous input and returns `{ eta: "", legTimes: [] }`;
  *   malformed input (a non-array, a non-object leg, an invalid field) returns `null`.
  * - Returns `null` on invalid input.
+ * - An offset with seconds (`-00:44:30`) as a leg's `timeZone` or as `startTimeZone` returns
+ *   `null`. A written zone cannot carry seconds (RFC 9557 §4.1), so `eta` and `localArrival` could
+ *   not name it. Pass the IANA name, or call `fromOffsetInstant({ instant, offset })` on a leg's
+ *   `arrival` for the local time with its full offset and no bracket.
  *
  * @param legs the journey's legs, in travel order
  * @param options The zone a zoneless first-leg departure is read in

package/dist/transport/calculate/scheduleDelivery.js

@@ -7,6 +7,7 @@ import { isValidZonedDateTime } from "../../zoned/validate/isValidZonedDateTime.
 import { etaAtZone } from "../convert/etaAtZone.js";
 import { transitTime } from "./transitTime.js";
 import { optionOrDefault } from "../../internal/optionOrDefault.js";
+import { isObject } from "../../internal/isObject.js";
 /**
  * A time-zone annotation anywhere in the string (`TIME_ZONE_ANNOTATION`): a bracket without
  * `=`. A departure that names a zone must name a real one that agrees with its offset.
@@ -172,7 +173,7 @@ function chainLegs(legs, startTimeZone) {
     let cursor = null;
     let previousTimeZone;
     for (const [index, leg] of legs.entries()) {
-        if (typeof leg !== "object" || leg === null) {
+        if (!isObject(leg)) {
             return null;
         }
         const tags = legTags(leg);
@@ -253,6 +254,10 @@ function chainLegs(legs, startTimeZone) {
  * - An empty legs array is valid vacuous input and returns `{ eta: "", legTimes: [] }`;
  *   malformed input (a non-array, a non-object leg, an invalid field) returns `null`.
  * - Returns `null` on invalid input.
+ * - An offset with seconds (`-00:44:30`) as a leg's `timeZone` or as `startTimeZone` returns
+ *   `null`. A written zone cannot carry seconds (RFC 9557 §4.1), so `eta` and `localArrival` could
+ *   not name it. Pass the IANA name, or call `fromOffsetInstant({ instant, offset })` on a leg's
+ *   `arrival` for the local time with its full offset and no bracket.
  *
  * @param legs the journey's legs, in travel order
  * @param options The zone a zoneless first-leg departure is read in

package/dist/transport/convert/etaAtZone.d.ts

@@ -27,9 +27,14 @@
  *   identifier, or a fixed offset such as `"+09:00"`, which renders with the offset as its zone.
  *   A fixed offset is a legitimate rendering choice for a ship's log (MAR-18); it is not a place.
  * - Returns `""` when the instant or the zone is invalid.
+ * - An offset with seconds (`-00:44:30`) returns `""`. A written zone cannot carry seconds (RFC
+ *   9557 §4.1), so the result could not name it. Pass the IANA name, or call
+ *   `fromOffsetInstant({ instant, offset })` for the local time with its full offset and no
+ *   bracket.
  *
  * @param arrivalUtc ISO 8601 instant string of the arrival
- * @param targetZone IANA timeZone identifier of the place the arrival is read in
+ * @param targetZone IANA name or a UTC offset to the minute (what `isValidTimeZone` accepts), for
+ *   the place the arrival is read in
  * @returns zoned ISO 8601 string of the local arrival, or "" on invalid input
  *
  * @example etaAtZone("2024-06-15T12:30:00Z", "Asia/Tokyo") // "2024-06-15T21:30:00+09:00[Asia/Tokyo]"

package/dist/transport/convert/etaAtZone.js

@@ -30,9 +30,14 @@ import { isValidTimeZone } from "../../zoned/validate/isValidTimeZone.js";
  *   identifier, or a fixed offset such as `"+09:00"`, which renders with the offset as its zone.
  *   A fixed offset is a legitimate rendering choice for a ship's log (MAR-18); it is not a place.
  * - Returns `""` when the instant or the zone is invalid.
+ * - An offset with seconds (`-00:44:30`) returns `""`. A written zone cannot carry seconds (RFC
+ *   9557 §4.1), so the result could not name it. Pass the IANA name, or call
+ *   `fromOffsetInstant({ instant, offset })` for the local time with its full offset and no
+ *   bracket.
  *
  * @param arrivalUtc ISO 8601 instant string of the arrival
- * @param targetZone IANA timeZone identifier of the place the arrival is read in
+ * @param targetZone IANA name or a UTC offset to the minute (what `isValidTimeZone` accepts), for
+ *   the place the arrival is read in
  * @returns zoned ISO 8601 string of the local arrival, or "" on invalid input
  *
  * @example etaAtZone("2024-06-15T12:30:00Z", "Asia/Tokyo") // "2024-06-15T21:30:00+09:00[Asia/Tokyo]"

package/dist/types/business-calendar.d.ts

@@ -23,10 +23,11 @@ export type BusinessCalendar = {
      */
     holidays: string[];
     /**
-     * The time zone recording which locality the calendar describes, an IANA name or a UTC offset. It
-     * must be a valid zone, but the business-day functions never use it: they take and return local
-     * dates, so the answer is the same whatever it says. A caller holding an instant uses it to
-     * reduce that instant to a local date first, with `floorToZone` or `getZonedDateTimeFields`.
+     * The time zone recording which locality the calendar describes, an IANA name or a UTC offset to
+     * the minute (what `isValidTimeZone` accepts). It must be a valid zone, but the business-day
+     * functions never use it: they take and return local dates, so the answer is the same whatever it
+     * says. A caller holding an instant uses it to reduce that instant to a local date first, with
+     * `floorToZone` or `getZonedDateTimeFields`.
      */
     timeZone: string;
 };