@northguild/gmt 1.17.0 → 1.19.0

package/dist/duty/validate/isValidDutyLog.js

@@ -0,0 +1,34 @@
+import { parseDutyLog } from "../../internal/dutyLog.js";
+/**
+ * Validate whether a value is a duty log every `duty/` function accepts.
+ *
+ * - True for an array of `{ status, start, end }` entries where `status` is a string and `start`
+ *   and `end` are ISO 8601 instant strings (offset required, no leap second), `end` after `start`.
+ * - Entries must be ordered by `start` and must not overlap. One may start exactly where the
+ *   previous one ends, since entries are half-open, or later, leaving a gap. Order is by instant,
+ *   not text.
+ * - `[]` is a valid, empty log. Extra keys on an entry are ignored.
+ * - Every other `duty/` function returns its sentinel for a log this rejects.
+ * - Returns `false` for a non-array, an entry that is not an object, a non-string status, a bound
+ *   that is not an instant, a zero-length or inverted entry, and entries out of order or
+ *   overlapping.
+ *
+ * @param log candidate array of `{ status, start, end }` records
+ * @returns boolean indicating whether the log is valid
+ *
+ * @example isValidDutyLog([{ status: "off", start: "2024-01-01T00:00:00Z", end: "2024-01-01T10:00:00Z" }, { status: "driving", start: "2024-01-01T10:00:00Z", end: "2024-01-01T15:00:00Z" }]) // true
+ * @example isValidDutyLog([]) // true — an empty log
+ * @example isValidDutyLog([{ status: "on", start: "2024-01-01T02:00:00Z", end: "2024-01-01T01:00:00Z" }]) // false — inverted
+ * @example isValidDutyLog([{ status: "on", start: "2024-01-01T00:00:00Z", end: "2024-01-01T02:00:00Z" }, { status: "off", start: "2024-01-01T01:59:59Z", end: "2024-01-01T03:00:00Z" }]) // false — overlapping
+ * @example isValidDutyLog([{ status: "on", start: "2024-01-01T00:00:00", end: "2024-01-01T01:00:00Z" }]) // false — no offset
+ */
+export function isValidDutyLog(log) {
+    try {
+        return parseDutyLog(log) !== null;
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return false;
+    }
+}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from "@js-temporal/polyfill";
 export * from "./calendar/index.js";
 export * from "./duration/index.js";
+export * from "./duty/index.js";
 export * from "./instant/index.js";
 export * from "./intermodal/index.js";
 export * from "./interval/index.js";

package/dist/index.js

@@ -1,6 +1,7 @@
 export * from "@js-temporal/polyfill";
 export * from "./calendar/index.js";
 export * from "./duration/index.js";
+export * from "./duty/index.js";
 export * from "./instant/index.js";
 export * from "./intermodal/index.js";
 export * from "./interval/index.js";

package/dist/instant/convert/classifyLocal.d.ts

@@ -32,9 +32,12 @@ export type LocalTimeClassification = "unique" | "ambiguous" | "nonexistent";
  *   annotations are read as `Temporal.PlainDateTime.from` reads them, so a time zone annotation
  *   is ignored and `timeZone` alone is the zone.
  * - Returns null on invalid input — never `"unique"`, which would read as a verdict.
+ * - `timeZone` may be a UTC offset, including one `getTimeZoneOffset` returned with seconds. A
+ *   fixed offset names one instant for every wall time, so the classification is always `"unique"`.
  *
  * @param localDateTime zoneless ISO 8601 local datetime string (e.g. "2024-11-03T01:30:00")
- * @param timeZone IANA timeZone identifier the wall time is read in
+ * @param timeZone IANA name or UTC offset the wall time is read in: a time zone identifier
+ *   (`+05:30`, `+0530`, `-08`) or a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns "unique" | "ambiguous" | "nonexistent", or null on invalid input
  *
  * @example classifyLocal("2024-07-15T12:00:00", "America/New_York") // "unique"
@@ -44,6 +47,7 @@ export type LocalTimeClassification = "unique" | "ambiguous" | "nonexistent";
  * @example classifyLocal("2024-09-29T03:15:00", "Pacific/Chatham") // "nonexistent" (a 45-minute-offset zone's gap)
  * @example classifyLocal("2011-12-30T12:00:00", "Pacific/Apia") // "nonexistent" (the day Samoa skipped crossing the date line)
  * @example classifyLocal("2024-11-03T01:30:00", "UTC") // "unique" (UTC has no transitions)
+ * @example classifyLocal("1970-01-01T12:00:00", "-00:44:30") // "unique" (a fixed offset has no transitions)
  * @example classifyLocal("2024-11-03T01:30:00-04:00", "America/New_York") // null (not a zoneless wall time)
  * @example classifyLocal("2024-11-03T01:30:00", "Invalid/Zone") // null
  */

package/dist/instant/convert/classifyLocal.js

@@ -1,7 +1,6 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidDateTime } from "../../plain/validate/index.js";
-import { isValidTimeZone } from "../../zoned/validate/index.js";
-import { plainToZoned } from "../../internal/index.js";
+import { instantOfWallClock, isoStringBody, plainToZoned, zoneFrame, } from "../../internal/index.js";
 /**
  * Report whether a zoneless local wall time is unique, ambiguous or nonexistent in a zone —
  * before any policy resolves it.
@@ -20,9 +19,12 @@ import { plainToZoned } from "../../internal/index.js";
  *   annotations are read as `Temporal.PlainDateTime.from` reads them, so a time zone annotation
  *   is ignored and `timeZone` alone is the zone.
  * - Returns null on invalid input — never `"unique"`, which would read as a verdict.
+ * - `timeZone` may be a UTC offset, including one `getTimeZoneOffset` returned with seconds. A
+ *   fixed offset names one instant for every wall time, so the classification is always `"unique"`.
  *
  * @param localDateTime zoneless ISO 8601 local datetime string (e.g. "2024-11-03T01:30:00")
- * @param timeZone IANA timeZone identifier the wall time is read in
+ * @param timeZone IANA name or UTC offset the wall time is read in: a time zone identifier
+ *   (`+05:30`, `+0530`, `-08`) or a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns "unique" | "ambiguous" | "nonexistent", or null on invalid input
  *
  * @example classifyLocal("2024-07-15T12:00:00", "America/New_York") // "unique"
@@ -32,17 +34,25 @@ import { plainToZoned } from "../../internal/index.js";
  * @example classifyLocal("2024-09-29T03:15:00", "Pacific/Chatham") // "nonexistent" (a 45-minute-offset zone's gap)
  * @example classifyLocal("2011-12-30T12:00:00", "Pacific/Apia") // "nonexistent" (the day Samoa skipped crossing the date line)
  * @example classifyLocal("2024-11-03T01:30:00", "UTC") // "unique" (UTC has no transitions)
+ * @example classifyLocal("1970-01-01T12:00:00", "-00:44:30") // "unique" (a fixed offset has no transitions)
  * @example classifyLocal("2024-11-03T01:30:00-04:00", "America/New_York") // null (not a zoneless wall time)
  * @example classifyLocal("2024-11-03T01:30:00", "Invalid/Zone") // null
  */
 export function classifyLocal(localDateTime, timeZone) {
-    if (!isValidDateTime(localDateTime) || !isValidTimeZone(timeZone)) {
+    const frame = zoneFrame(timeZone);
+    if (!isValidDateTime(localDateTime) || frame === null) {
         return null;
     }
     try {
+        // A fixed offset has no transition: a wall time it can place is one instant, and one it
+        // cannot (past the instant range) throws.
+        if (frame.shiftNanoseconds !== 0n) {
+            instantOfWallClock(isoStringBody(localDateTime), frame);
+            return "unique";
+        }
         const wallClock = Temporal.PlainDateTime.from(localDateTime);
-        const earliest = plainToZoned(wallClock, timeZone, "earlier");
-        const latest = plainToZoned(wallClock, timeZone, "later");
+        const earliest = plainToZoned(wallClock, frame.timeZone, "earlier");
+        const latest = plainToZoned(wallClock, frame.timeZone, "later");
         if (earliest.epochNanoseconds === latest.epochNanoseconds) {
             return "unique";
         }

package/dist/instant/convert/fromOffsetInstant.d.ts

@@ -24,9 +24,15 @@ import type { OffsetInstant } from "./toOffsetInstant.js";
  * - With a `timeZone`, a sub-minute offset is *written* rounded to the minute, because RFC
  *   9557 has no field for the seconds — `Africa/Monrovia`'s `-00:44:30` renders as `-00:45`.
  *   The bracketed zone is what resolves it, so the instant stays exact and the round trip
- *   returns `-00:44:30`. Without a `timeZone` there is no zone to resolve against, so the
+ *   returns `-00:44:30`. Two exceptions, both Temporal's own: a wall time repeated inside
+ *   a sub-minute offset change reads back as its first pass (see `isValidInstant`), and a
+ *   string whose local date is −271821-04-19 is refused by `toOffsetInstant`. Without a `timeZone` there is no zone to resolve against, so the
  *   full `±HH:MM:SS` is written instead; that is ISO 8601, not RFC 9557.
  * - Returns `""` on invalid input.
+ * - A `timeZone` that is an offset with seconds (`-00:44:30`) returns `""`, as any offset there
+ *   does. A written zone cannot carry seconds (RFC 9557 §4.1), so the result could not name it.
+ *   Pass the IANA name as `timeZone`, or leave `timeZone` out for the local time with its full
+ *   offset and no bracket.
  *
  * @param value `{ instant, offset, timeZone? }` pair, as produced by `toOffsetInstant`
  * @returns local ISO 8601 string carrying the pair's own offset, or "" on invalid input

package/dist/instant/convert/fromOffsetInstant.js

@@ -1,6 +1,7 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { formatUtcOffset, parseInstantNanoseconds, parseUtcOffsetNanoseconds, wallClockAtOffset, } from "../../internal/index.js";
 import { utcOffset } from "../../regex/index.js";
+import { isObject } from "../../internal/isObject.js";
 /**
  * Render an instant-plus-offset pair back to the local time it describes.
  *
@@ -26,9 +27,15 @@ import { utcOffset } from "../../regex/index.js";
  * - With a `timeZone`, a sub-minute offset is *written* rounded to the minute, because RFC
  *   9557 has no field for the seconds — `Africa/Monrovia`'s `-00:44:30` renders as `-00:45`.
  *   The bracketed zone is what resolves it, so the instant stays exact and the round trip
- *   returns `-00:44:30`. Without a `timeZone` there is no zone to resolve against, so the
+ *   returns `-00:44:30`. Two exceptions, both Temporal's own: a wall time repeated inside
+ *   a sub-minute offset change reads back as its first pass (see `isValidInstant`), and a
+ *   string whose local date is −271821-04-19 is refused by `toOffsetInstant`. Without a `timeZone` there is no zone to resolve against, so the
  *   full `±HH:MM:SS` is written instead; that is ISO 8601, not RFC 9557.
  * - Returns `""` on invalid input.
+ * - A `timeZone` that is an offset with seconds (`-00:44:30`) returns `""`, as any offset there
+ *   does. A written zone cannot carry seconds (RFC 9557 §4.1), so the result could not name it.
+ *   Pass the IANA name as `timeZone`, or leave `timeZone` out for the local time with its full
+ *   offset and no bracket.
  *
  * @param value `{ instant, offset, timeZone? }` pair, as produced by `toOffsetInstant`
  * @returns local ISO 8601 string carrying the pair's own offset, or "" on invalid input
@@ -48,7 +55,7 @@ import { utcOffset } from "../../regex/index.js";
  */
 export function fromOffsetInstant(value) {
     try {
-        if (typeof value !== "object" || value === null) {
+        if (!isObject(value)) {
             return "";
         }
         const epochNanoseconds = parseInstantNanoseconds(value.instant);

package/dist/instant/convert/resolveLocal.d.ts

@@ -1,16 +1,13 @@
 import type { Disambiguation } from "../../types/index.js";
 /**
- * Resolve a zoneless local wall time against an IANA zone and return the instant it names.
+ * Resolve a zoneless local wall time in a time zone and return the instant it names.
  *
  * Feeds deliver wall times with no offset all the time — "gate-out 08:00" — and turning one
  * into an instant takes a zone the sender did not send plus a policy for the two days a year
  * the mapping is not one-to-one. This states both.
  *
- * - `disambiguation` decides what happens when the wall time is ambiguous (a fall-back hour
- *   that happens twice) or nonexistent (a spring-forward hour that never happens):
- *   `"compatible"` (the default, matching Temporal), `"earlier"`, `"later"`, or `"reject"`,
- *   which returns `""` rather than resolving. Call `classifyLocal` first to find out which
- *   case you are in before a policy is applied.
+ * - Call `classifyLocal` first to find out whether the wall time is ambiguous or nonexistent
+ *   before a `disambiguation` policy is applied.
  * - Returns a UTC instant, exactly — no rounding, so a nanosecond wall time survives. Pass it
  *   to `toOffsetInstant` for the offset pair, or reach for `convertPlainDateTimeToZoned` when
  *   what you want is the bracketed zoned string (it defaults to millisecond precision).
@@ -19,10 +16,14 @@ import type { Disambiguation } from "../../types/index.js";
  *   are read as `Temporal.PlainDateTime.from` reads them, so a time zone annotation
  *   (`[America/New_York]`) is ignored and `timeZone` alone resolves the wall time.
  * - Returns `""` on invalid input.
+ * - `timeZone` may be a UTC offset, including one `getTimeZoneOffset` returned with seconds. A
+ *   fixed offset names one instant for every wall time, so `disambiguation` has nothing to decide
+ *   and `"reject"` does not reject.
  *
  * @param localDateTime zoneless ISO 8601 local datetime string (e.g. "2024-11-03T01:30:00")
- * @param timeZone IANA timeZone identifier the wall time is read in
- * @param optionsArg optional: disambiguation ("compatible" | "earlier" | "later" | "reject")
+ * @param timeZone IANA name or UTC offset the wall time is read in: a time zone identifier
+ *   (`+05:30`, `+0530`, `-08`) or a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
+ * @param optionsArg How an ambiguous or nonexistent wall time is resolved
  * @returns UTC instant string ending in "Z", or "" on invalid input
  *
  * @example resolveLocal("2024-07-15T12:00:00", "America/New_York") // "2024-07-15T16:00:00Z"
@@ -32,9 +33,18 @@ import type { Disambiguation } from "../../types/index.js";
  * @example resolveLocal("2024-03-10T02:30:00", "America/New_York") // "2024-03-10T07:30:00Z" (nonexistent; "compatible" takes the later)
  * @example resolveLocal("2024-03-10T02:30:00", "America/New_York", { disambiguation: "earlier" }) // "2024-03-10T06:30:00Z"
  * @example resolveLocal("2024-07-15T12:00:00-04:00", "America/New_York") // "" (not a zoneless wall time)
+ * @example resolveLocal("1970-01-01T12:00:00", "-00:44:30") // "1970-01-01T12:44:30Z" (a stored offset with seconds, what `getTimeZoneOffset` returns for Africa/Monrovia then)
  * @example resolveLocal("2024-07-15T12:00:00[foo=bar]", "America/New_York") // "2024-07-15T16:00:00Z" (elective annotation ignored)
  * @example resolveLocal("2024-07-15T12:00:00", "Invalid/Zone") // ""
  */
 export declare function resolveLocal(localDateTime: string, timeZone: string, optionsArg?: {
+    /**
+     * What happens when the wall time is ambiguous (a fall-back hour that happens twice) or
+     * nonexistent (a spring-forward hour that never happens). `"compatible"` takes the earlier
+     * instant of an ambiguous time and the later one of a nonexistent time, `"earlier"` and
+     * `"later"` take that side in both cases, and `"reject"` returns `""` rather than resolving.
+     *
+     * @defaultValue `"compatible"`, Temporal's default.
+     */
     disambiguation?: Disambiguation;
 }): string;

package/dist/instant/convert/resolveLocal.js

@@ -1,7 +1,7 @@
 import { isValidDateTime } from "../../plain/validate/index.js";
-import { isValidTimeZone } from "../../zoned/validate/index.js";
-import { isoStringBody, zonedDateTimeFrom } from "../../internal/index.js";
+import { instantOfWallClock, isoStringBody, zonedDateTimeFrom, zoneFrame, } from "../../internal/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 const DISAMBIGUATIONS = [
     "compatible",
     "earlier",
@@ -9,17 +9,14 @@ const DISAMBIGUATIONS = [
     "reject",
 ];
 /**
- * Resolve a zoneless local wall time against an IANA zone and return the instant it names.
+ * Resolve a zoneless local wall time in a time zone and return the instant it names.
  *
  * Feeds deliver wall times with no offset all the time — "gate-out 08:00" — and turning one
  * into an instant takes a zone the sender did not send plus a policy for the two days a year
  * the mapping is not one-to-one. This states both.
  *
- * - `disambiguation` decides what happens when the wall time is ambiguous (a fall-back hour
- *   that happens twice) or nonexistent (a spring-forward hour that never happens):
- *   `"compatible"` (the default, matching Temporal), `"earlier"`, `"later"`, or `"reject"`,
- *   which returns `""` rather than resolving. Call `classifyLocal` first to find out which
- *   case you are in before a policy is applied.
+ * - Call `classifyLocal` first to find out whether the wall time is ambiguous or nonexistent
+ *   before a `disambiguation` policy is applied.
  * - Returns a UTC instant, exactly — no rounding, so a nanosecond wall time survives. Pass it
  *   to `toOffsetInstant` for the offset pair, or reach for `convertPlainDateTimeToZoned` when
  *   what you want is the bracketed zoned string (it defaults to millisecond precision).
@@ -28,10 +25,14 @@ const DISAMBIGUATIONS = [
  *   are read as `Temporal.PlainDateTime.from` reads them, so a time zone annotation
  *   (`[America/New_York]`) is ignored and `timeZone` alone resolves the wall time.
  * - Returns `""` on invalid input.
+ * - `timeZone` may be a UTC offset, including one `getTimeZoneOffset` returned with seconds. A
+ *   fixed offset names one instant for every wall time, so `disambiguation` has nothing to decide
+ *   and `"reject"` does not reject.
  *
  * @param localDateTime zoneless ISO 8601 local datetime string (e.g. "2024-11-03T01:30:00")
- * @param timeZone IANA timeZone identifier the wall time is read in
- * @param optionsArg optional: disambiguation ("compatible" | "earlier" | "later" | "reject")
+ * @param timeZone IANA name or UTC offset the wall time is read in: a time zone identifier
+ *   (`+05:30`, `+0530`, `-08`) or a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
+ * @param optionsArg How an ambiguous or nonexistent wall time is resolved
  * @returns UTC instant string ending in "Z", or "" on invalid input
  *
  * @example resolveLocal("2024-07-15T12:00:00", "America/New_York") // "2024-07-15T16:00:00Z"
@@ -41,6 +42,7 @@ const DISAMBIGUATIONS = [
  * @example resolveLocal("2024-03-10T02:30:00", "America/New_York") // "2024-03-10T07:30:00Z" (nonexistent; "compatible" takes the later)
  * @example resolveLocal("2024-03-10T02:30:00", "America/New_York", { disambiguation: "earlier" }) // "2024-03-10T06:30:00Z"
  * @example resolveLocal("2024-07-15T12:00:00-04:00", "America/New_York") // "" (not a zoneless wall time)
+ * @example resolveLocal("1970-01-01T12:00:00", "-00:44:30") // "1970-01-01T12:44:30Z" (a stored offset with seconds, what `getTimeZoneOffset` returns for Africa/Monrovia then)
  * @example resolveLocal("2024-07-15T12:00:00[foo=bar]", "America/New_York") // "2024-07-15T16:00:00Z" (elective annotation ignored)
  * @example resolveLocal("2024-07-15T12:00:00", "Invalid/Zone") // ""
  */
@@ -49,18 +51,20 @@ export function resolveLocal(localDateTime, timeZone, optionsArg) {
         if (!isOptionsArgument(optionsArg)) {
             return "";
         }
-        const disambiguation = optionsArg?.disambiguation === undefined
-            ? "compatible"
-            : optionsArg.disambiguation;
+        const disambiguation = optionOrDefault(optionsArg?.disambiguation, "compatible");
+        const frame = zoneFrame(timeZone);
         if (!isValidDateTime(localDateTime) ||
-            !isValidTimeZone(timeZone) ||
+            frame === null ||
             !DISAMBIGUATIONS.includes(disambiguation)) {
             return "";
         }
         try {
-            return zonedDateTimeFrom(`${isoStringBody(localDateTime)}[${timeZone}]`, {
-                disambiguation,
-            })
+            // An offset with seconds is no time zone identifier, so it cannot go in a bracket. It needs
+            // none: the wall time at a fixed offset is one instant, whatever `disambiguation` says.
+            if (frame.shiftNanoseconds !== 0n) {
+                return instantOfWallClock(isoStringBody(localDateTime), frame).toString();
+            }
+            return zonedDateTimeFrom(`${isoStringBody(localDateTime)}[${frame.timeZone}]`, { disambiguation })
                 .toInstant()
                 .toString();
         }

package/dist/instant/convert/toOffsetInstant.d.ts

@@ -1,17 +1,10 @@
 /**
  * An absolute instant paired with the local UTC offset in force where the event happened.
  *
- * @remarks Members:
- *
- * | Member | Type | Description |
- * | --- | --- | --- |
- * | `instant` | `string` | UTC instant, ISO 8601 ending in `Z` (e.g. `2024-07-15T16:00:00Z`). Orders events globally. |
- * | `offset` | `string` | UTC offset in force where the event happened, `±HH:MM` (or `±HH:MM:SS` for a pre-1972 zone that did not run on a whole minute). Renders the event as the human on the ground saw it. |
- * | `timeZone` | `string \| undefined` | IANA zone identifier, when one is known. Absent from most feeds, so absent from most pairs. |
- *
  * Neither `instant` nor `offset` derives from the other, which is why both are stored. It is
  * the shape GS1 EPCIS 2.0 (`eventTime` + a required `eventTimeZoneOffset`), UN/EDIFACT DTM
- * (qualifier `303`/`304`) and DICOM (`DT` + `&ZZXX`) all exchange.
+ * (format codes `205` and `208`, a date and time with a `±HHMM` offset) and DICOM (`DT` +
+ * `&ZZXX`) all exchange.
  *
  * @example
  * import { OffsetInstant } from "@northguild/gmt/instant";
@@ -22,8 +15,22 @@
  * };
  */
 export interface OffsetInstant {
+    /**
+     * The UTC instant, ISO 8601 ending in `Z` (e.g. `2024-07-15T16:00:00Z`). Orders events globally.
+     */
     instant: string;
+    /**
+     * The UTC offset in force where the event happened, `±HH:MM` (or `±HH:MM:SS` for a pre-1972
+     * zone that did not run on a whole minute). Renders the event as the human on the ground saw it.
+     */
     offset: string;
+    /**
+     * The IANA name of the zone, when one is known. Most feeds send none, so `toOffsetInstant` leaves
+     * it out unless the string or its `timeZone` argument names a zone.
+     *
+     * @defaultValue None. The pair names no zone, and `offset` alone places the instant on a local
+     * clock.
+     */
     timeZone?: string;
 }
 /**
@@ -46,12 +53,13 @@ export interface OffsetInstant {
  *   event happened when all it has is the offset it already stores. Every other bracketed
  *   identifier Temporal accepts is kept, including the single-component IANA names (`EST5EDT`,
  *   `Zulu`), in its IANA casing.
- * - `timeZone` names the zone the offset is read in, and is how a UTC-only feed gets a pair
- *   with a local offset. It also overrides a zone bracketed in the string — the instant is
- *   unchanged either way, only the local rendering differs. It is validated with
- *   `isValidTimeZone`, so any IANA Zone or Link name is accepted, single-component ones
- *   (`Japan`, `Zulu`, `EST5EDT`) included. An offset identifier (`"-05:00"`) sets the offset
- *   and, like a bracketed offset zone, yields no `timeZone` field.
+ * - `timeZone` names the zone the offset is read in, and is how a UTC-only feed gets a pair with a
+ *   local offset. It also overrides a zone bracketed in the string — the instant is unchanged
+ *   either way, only the local rendering differs. Any IANA Zone or Link name is accepted,
+ *   single-component ones (`Japan`, `Zulu`, `EST5EDT`) included, and so is a UTC offset: a time
+ *   zone identifier (`+05:30`, `+0530`, `-08`) or a stored offset (`±HH:MM[:SS]`, what
+ *   `getTimeZoneOffset` returns). An offset (`"-05:00"`, `"-00:44:30"`) sets the pair's offset and,
+ *   like a bracketed offset zone, yields no `timeZone` field.
  * - The returned `timeZone` is the identifier in its IANA casing on every path —
  *   `"america/new_york"` comes back as `"America/New_York"` — because identifiers match
  *   case-insensitively (ECMA-402). That is what the bracket path and `fromOffsetInstant` return,
@@ -68,10 +76,16 @@ export interface OffsetInstant {
  *   rounding it would put the pair 30 seconds from the event it describes. Such a zone's
  *   *string* still carries the rounded `-00:45`, because RFC 9557 caps a written offset at
  *   minutes; the bracketed zone is what resolves it, so the instant stays exact.
+ * - A bracketed zone is checked as `Temporal.ZonedDateTime.from` checks it, which also rejects
+ *   a local date of −271821-04-19. A zone west of Greenwich shows that date for the first hours
+ *   of the instant range, so a zoned string written there
+ *   (`-271821-04-19T23:59:00-00:01[Europe/London]`) returns null, although `isValidInstant`
+ *   accepts it. Pass the instant in `Z` form with `timeZone` instead.
  * - Returns null on invalid input, not a zero-offset pair — `+00:00` is a real offset.
  *
  * @param value ISO 8601 instant string, with an offset designator and optionally a bracketed zone
- * @param timeZone optional IANA zone identifier to read the offset in
+ * @param timeZone optional IANA name or UTC offset to read the offset in: a time zone identifier
+ *   (`+05:30`, `+0530`, `-08`) or a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns `{ instant, offset, timeZone? }`, or null on invalid input
  *
  * @example toOffsetInstant("2024-07-15T12:00:00-04:00[America/New_York]") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00", timeZone: "America/New_York" }
@@ -80,9 +94,12 @@ export interface OffsetInstant {
  * @example toOffsetInstant("2024-07-15T16:00:00Z", "America/New_York") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00", timeZone: "America/New_York" }
  * @example toOffsetInstant("2024-01-15T17:00:00Z", "America/New_York") // { instant: "2024-01-15T17:00:00Z", offset: "-05:00", timeZone: "America/New_York" } — same wall time, different offset, six months apart
  * @example toOffsetInstant("1970-01-01T00:00:00Z", "Africa/Monrovia") // { instant: "1970-01-01T00:00:00Z", offset: "-00:44:30", timeZone: "Africa/Monrovia" }
+ * @example toOffsetInstant("1970-01-01T12:44:30Z", "-00:44:30") // { instant: "1970-01-01T12:44:30Z", offset: "-00:44:30" } — a stored offset with seconds, and no timeZone field
  * @example toOffsetInstant("1969-12-31T23:15:30-00:45[Africa/Monrovia]") // { instant: "1970-01-01T00:00:00Z", offset: "-00:44:30", timeZone: "Africa/Monrovia" } — the zone, not the rounded offset, fixes the instant
  * @example toOffsetInstant("2024-07-15T12:00:00-04:00[-04:00]") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00" } — a bracketed offset is not a zone, so no timeZone field
  * @example toOffsetInstant("2024-07-15T12:00:00-05:00[America/New_York]") // null (offset contradicts the bracketed zone)
+ * @example toOffsetInstant("-271821-04-19T23:59:00-00:01[Europe/London]") // null (a bracketed zone on a local date before Temporal's date range)
+ * @example toOffsetInstant("-271821-04-20T00:00:15Z", "Europe/London") // { instant: "-271821-04-20T00:00:15Z", offset: "-00:01:15", timeZone: "Europe/London" }
  * @example toOffsetInstant("2024-07-15T12:00:00-04:00[foo=bar]") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00" } — an elective annotation is ignored
  * @example toOffsetInstant("2024-07-15T12:00:00-04:00[!foo=bar]") // null (an unknown critical annotation)
  * @example toOffsetInstant("2024-07-15T12:00:00") // null (no offset designator)

package/dist/instant/convert/toOffsetInstant.js

@@ -1,7 +1,6 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { formatUtcOffset, isoStringBody, parseInstantNanoseconds, TIME_ZONE_ANNOTATION, zonedDateTimeFrom, } from "../../internal/index.js";
+import { formatUtcOffset, frameOffset, isoStringBody, parseInstantNanoseconds, TIME_ZONE_ANNOTATION, zonedDateTimeFrom, zoneFrame, } from "../../internal/index.js";
 import { utcOffset } from "../../regex/index.js";
-import { isValidTimeZone } from "../../zoned/validate/index.js";
 /** A leading RFC 9557 time zone annotation: `[zone]` or `[!zone]`, with no `=`. */
 const timeZoneAnnotation = new RegExp(`^${TIME_ZONE_ANNOTATION}`);
 /**
@@ -24,12 +23,13 @@ const timeZoneAnnotation = new RegExp(`^${TIME_ZONE_ANNOTATION}`);
  *   event happened when all it has is the offset it already stores. Every other bracketed
  *   identifier Temporal accepts is kept, including the single-component IANA names (`EST5EDT`,
  *   `Zulu`), in its IANA casing.
- * - `timeZone` names the zone the offset is read in, and is how a UTC-only feed gets a pair
- *   with a local offset. It also overrides a zone bracketed in the string — the instant is
- *   unchanged either way, only the local rendering differs. It is validated with
- *   `isValidTimeZone`, so any IANA Zone or Link name is accepted, single-component ones
- *   (`Japan`, `Zulu`, `EST5EDT`) included. An offset identifier (`"-05:00"`) sets the offset
- *   and, like a bracketed offset zone, yields no `timeZone` field.
+ * - `timeZone` names the zone the offset is read in, and is how a UTC-only feed gets a pair with a
+ *   local offset. It also overrides a zone bracketed in the string — the instant is unchanged
+ *   either way, only the local rendering differs. Any IANA Zone or Link name is accepted,
+ *   single-component ones (`Japan`, `Zulu`, `EST5EDT`) included, and so is a UTC offset: a time
+ *   zone identifier (`+05:30`, `+0530`, `-08`) or a stored offset (`±HH:MM[:SS]`, what
+ *   `getTimeZoneOffset` returns). An offset (`"-05:00"`, `"-00:44:30"`) sets the pair's offset and,
+ *   like a bracketed offset zone, yields no `timeZone` field.
  * - The returned `timeZone` is the identifier in its IANA casing on every path —
  *   `"america/new_york"` comes back as `"America/New_York"` — because identifiers match
  *   case-insensitively (ECMA-402). That is what the bracket path and `fromOffsetInstant` return,
@@ -46,10 +46,16 @@ const timeZoneAnnotation = new RegExp(`^${TIME_ZONE_ANNOTATION}`);
  *   rounding it would put the pair 30 seconds from the event it describes. Such a zone's
  *   *string* still carries the rounded `-00:45`, because RFC 9557 caps a written offset at
  *   minutes; the bracketed zone is what resolves it, so the instant stays exact.
+ * - A bracketed zone is checked as `Temporal.ZonedDateTime.from` checks it, which also rejects
+ *   a local date of −271821-04-19. A zone west of Greenwich shows that date for the first hours
+ *   of the instant range, so a zoned string written there
+ *   (`-271821-04-19T23:59:00-00:01[Europe/London]`) returns null, although `isValidInstant`
+ *   accepts it. Pass the instant in `Z` form with `timeZone` instead.
  * - Returns null on invalid input, not a zero-offset pair — `+00:00` is a real offset.
  *
  * @param value ISO 8601 instant string, with an offset designator and optionally a bracketed zone
- * @param timeZone optional IANA zone identifier to read the offset in
+ * @param timeZone optional IANA name or UTC offset to read the offset in: a time zone identifier
+ *   (`+05:30`, `+0530`, `-08`) or a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns `{ instant, offset, timeZone? }`, or null on invalid input
  *
  * @example toOffsetInstant("2024-07-15T12:00:00-04:00[America/New_York]") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00", timeZone: "America/New_York" }
@@ -58,9 +64,12 @@ const timeZoneAnnotation = new RegExp(`^${TIME_ZONE_ANNOTATION}`);
  * @example toOffsetInstant("2024-07-15T16:00:00Z", "America/New_York") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00", timeZone: "America/New_York" }
  * @example toOffsetInstant("2024-01-15T17:00:00Z", "America/New_York") // { instant: "2024-01-15T17:00:00Z", offset: "-05:00", timeZone: "America/New_York" } — same wall time, different offset, six months apart
  * @example toOffsetInstant("1970-01-01T00:00:00Z", "Africa/Monrovia") // { instant: "1970-01-01T00:00:00Z", offset: "-00:44:30", timeZone: "Africa/Monrovia" }
+ * @example toOffsetInstant("1970-01-01T12:44:30Z", "-00:44:30") // { instant: "1970-01-01T12:44:30Z", offset: "-00:44:30" } — a stored offset with seconds, and no timeZone field
  * @example toOffsetInstant("1969-12-31T23:15:30-00:45[Africa/Monrovia]") // { instant: "1970-01-01T00:00:00Z", offset: "-00:44:30", timeZone: "Africa/Monrovia" } — the zone, not the rounded offset, fixes the instant
  * @example toOffsetInstant("2024-07-15T12:00:00-04:00[-04:00]") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00" } — a bracketed offset is not a zone, so no timeZone field
  * @example toOffsetInstant("2024-07-15T12:00:00-05:00[America/New_York]") // null (offset contradicts the bracketed zone)
+ * @example toOffsetInstant("-271821-04-19T23:59:00-00:01[Europe/London]") // null (a bracketed zone on a local date before Temporal's date range)
+ * @example toOffsetInstant("-271821-04-20T00:00:15Z", "Europe/London") // { instant: "-271821-04-20T00:00:15Z", offset: "-00:01:15", timeZone: "Europe/London" }
  * @example toOffsetInstant("2024-07-15T12:00:00-04:00[foo=bar]") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00" } — an elective annotation is ignored
  * @example toOffsetInstant("2024-07-15T12:00:00-04:00[!foo=bar]") // null (an unknown critical annotation)
  * @example toOffsetInstant("2024-07-15T12:00:00") // null (no offset designator)
@@ -76,12 +85,13 @@ export function toOffsetInstant(value, timeZone) {
     if (epochNanoseconds === null) {
         return null;
     }
-    if (timeZone !== undefined && !isValidTimeZone(timeZone)) {
+    const frame = timeZone === undefined ? undefined : zoneFrame(timeZone);
+    if (frame === null) {
         return null;
     }
     try {
-        // `parseInstantNanoseconds` reads the offset and ignores the bracket, so a self-
-        // contradictory string parses fine as an instant. `ZonedDateTime.from` is what checks
+        // `parseInstantNanoseconds` does not validate the bracket, so a self-contradictory string
+        // parses fine as an instant. `ZonedDateTime.from` is what checks
         // the two agree, and it runs even when `timeZone` overrides the bracketed zone.
         // Only a time zone annotation makes the string zoned: it is the first annotation, and the
         // only kind with no `=` (RFC 9557 §4.1). A calendar or elective annotation alone leaves an
@@ -109,7 +119,12 @@ export function toOffsetInstant(value, timeZone) {
         const instant = bracketed !== null
             ? bracketed.toInstant()
             : Temporal.Instant.fromEpochNanoseconds(epochNanoseconds);
-        const resolvedZone = timeZone ?? bracketedZone;
+        // A stored offset with seconds is the pair's offset as it stands. Like an offset identifier it
+        // names no place, so it fills no `timeZone` field.
+        if (frame !== undefined && frame.shiftNanoseconds !== 0n) {
+            return { instant: instant.toString(), offset: frameOffset(frame) };
+        }
+        const resolvedZone = frame?.timeZone ?? bracketedZone;
         if (resolvedZone !== undefined) {
             return offsetInstantInZone(instant, resolvedZone);
         }

package/dist/instant/index.d.ts

@@ -1,2 +1,3 @@
 export * from "@js-temporal/polyfill";
 export * from "./convert/index.js";
+export * from "./validate/index.js";

package/dist/instant/index.js

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

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

@@ -0,0 +1 @@
+export * from "./isValidUtcOffset.js";

package/dist/instant/validate/index.js

@@ -0,0 +1 @@
+export * from "./isValidUtcOffset.js";

package/dist/instant/validate/isValidUtcOffset.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Return true when `value` is a UTC offset in the form the offset-instant pair stores: ISO 8601
+ * extended `±HH:MM`, optionally `±HH:MM:SS`.
+ *
+ * - This is the offset `toOffsetInstant` returns and `fromOffsetInstant` takes, and the one
+ *   `getTimeZoneOffset` and `getZonedOffset` return.
+ * - **The `utcOffset` pattern is the whole check.** Every string it matches is in range (hour
+ *   `00`–`23`, minute and second `00`–`59`), so this validator is the pattern test plus the
+ *   answer false for a non-string.
+ * - `Z` is false: it is a designator meaning "this string is already UTC", and for an event at
+ *   UTC the pair's offset is `+00:00`.
+ * - Seconds are allowed because some zones did not run on a whole minute: `Africa/Monrovia` was
+ *   `-00:44:30` until 1972. A fraction of a second is false.
+ * - Basic format (`-0400`) and an hour alone (`-04`) are false.
+ * - `-00:00` is true, and the functions that take an offset read it as `+00:00`.
+ * - A function whose result has no zone in it takes this offset in its time zone position too. A
+ *   function that returns a zoned string, or formats with `Intl`, takes a time zone identifier
+ *   only: check that with `isValidTimeZone`, which accepts `+0530` and `-08` and rejects an offset
+ *   with seconds.
+ *
+ * @param value candidate UTC offset string
+ * @returns boolean indicating validity
+ *
+ * @example isValidUtcOffset("-04:00") // true
+ * @example isValidUtcOffset("+05:45") // true
+ * @example isValidUtcOffset("-00:44:30") // true (Africa/Monrovia before 1972)
+ * @example isValidUtcOffset("Z") // false (a designator, not an offset)
+ * @example isValidUtcOffset("-0400") // false (basic format)
+ * @example isValidUtcOffset("+24:00") // false (out of range)
+ * @example isValidUtcOffset("America/New_York") // false (a zone, not an offset)
+ */
+export declare function isValidUtcOffset(value: string): boolean;

package/dist/instant/validate/isValidUtcOffset.js

@@ -0,0 +1,35 @@
+import { utcOffset } from "../../regex/index.js";
+/**
+ * Return true when `value` is a UTC offset in the form the offset-instant pair stores: ISO 8601
+ * extended `±HH:MM`, optionally `±HH:MM:SS`.
+ *
+ * - This is the offset `toOffsetInstant` returns and `fromOffsetInstant` takes, and the one
+ *   `getTimeZoneOffset` and `getZonedOffset` return.
+ * - **The `utcOffset` pattern is the whole check.** Every string it matches is in range (hour
+ *   `00`–`23`, minute and second `00`–`59`), so this validator is the pattern test plus the
+ *   answer false for a non-string.
+ * - `Z` is false: it is a designator meaning "this string is already UTC", and for an event at
+ *   UTC the pair's offset is `+00:00`.
+ * - Seconds are allowed because some zones did not run on a whole minute: `Africa/Monrovia` was
+ *   `-00:44:30` until 1972. A fraction of a second is false.
+ * - Basic format (`-0400`) and an hour alone (`-04`) are false.
+ * - `-00:00` is true, and the functions that take an offset read it as `+00:00`.
+ * - A function whose result has no zone in it takes this offset in its time zone position too. A
+ *   function that returns a zoned string, or formats with `Intl`, takes a time zone identifier
+ *   only: check that with `isValidTimeZone`, which accepts `+0530` and `-08` and rejects an offset
+ *   with seconds.
+ *
+ * @param value candidate UTC offset string
+ * @returns boolean indicating validity
+ *
+ * @example isValidUtcOffset("-04:00") // true
+ * @example isValidUtcOffset("+05:45") // true
+ * @example isValidUtcOffset("-00:44:30") // true (Africa/Monrovia before 1972)
+ * @example isValidUtcOffset("Z") // false (a designator, not an offset)
+ * @example isValidUtcOffset("-0400") // false (basic format)
+ * @example isValidUtcOffset("+24:00") // false (out of range)
+ * @example isValidUtcOffset("America/New_York") // false (a zone, not an offset)
+ */
+export function isValidUtcOffset(value) {
+    return typeof value === "string" && utcOffset.test(value);
+}