@northguild/gmt 1.18.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 name or UTC offset 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 name or UTC offset 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

@@ -29,6 +29,10 @@ import type { OffsetInstant } from "./toOffsetInstant.js";
  *   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.
  *
@@ -31,6 +32,10 @@ import { utcOffset } from "../../regex/index.js";
  *   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
@@ -50,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,6 +1,6 @@
 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
@@ -16,9 +16,13 @@ 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 name or UTC offset 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)
  * @param optionsArg How an ambiguous or nonexistent wall time is resolved
  * @returns UTC instant string ending in "Z", or "" on invalid input
  *
@@ -29,6 +33,7 @@ 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") // ""
  */

package/dist/instant/convert/resolveLocal.js

@@ -1,6 +1,5 @@
 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 = [
@@ -10,7 +9,7 @@ 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
@@ -26,9 +25,13 @@ 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 name or UTC offset 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)
  * @param optionsArg How an ambiguous or nonexistent wall time is resolved
  * @returns UTC instant string ending in "Z", or "" on invalid input
  *
@@ -39,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") // ""
  */
@@ -48,15 +52,19 @@ export function resolveLocal(localDateTime, timeZone, optionsArg) {
             return "";
         }
         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

@@ -3,7 +3,8 @@
  *
  * 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";
@@ -52,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,
@@ -82,7 +84,8 @@ export interface OffsetInstant {
  * - 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 name or UTC offset 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" }
@@ -91,6 +94,7 @@ 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)

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,
@@ -54,7 +54,8 @@ const timeZoneAnnotation = new RegExp(`^${TIME_ZONE_ANNOTATION}`);
  * - 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 name or UTC offset 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" }
@@ -63,6 +64,7 @@ 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)
@@ -83,7 +85,8 @@ 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 {
@@ -116,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);
+}

package/dist/intermodal/calculate/chargeableDays.d.ts

@@ -77,6 +77,12 @@ export type FreeTimeChargeOptions = FreeTimeOptions & {
  *   inverted dwell is a data error), `freeDays` is not a whole number of at least `0`, the
  *   options fail as they do for `freeTimeExpiry`, `tiers` has a hole, an unsafe integer or does not ascend, or the walk would pass
  *   10,000 local days.
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the last instant Temporal supports
+ *   (`+275760-09-13T00:00:00Z`) for an offset east of UTC, or of the first
+ *   (`-271821-04-20T00:00:00Z`) for one west, this returns `null`. An offset to the minute has no
+ *   such limit.
  *
  * @param clockStart ISO 8601 instant string of the event that starts the clock
  * @param clockEnd ISO 8601 instant string of the event that stops it (gate-out or empty return)

package/dist/intermodal/calculate/chargeableDays.js

@@ -1,5 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { bandsByTier, instantFrom, parseFreeDays, parseFreeTimeTerms, parseTiers, walkFreeTime, } from "../../internal/index.js";
+import { bandsByTier, frameInstant, frameZoned, instantFrom, parseFreeDays, parseFreeTimeTerms, parseTiers, walkFreeTime, zoneFrame, } from "../../internal/index.js";
 import { isValidInstant } from "../../precision/validate/isValidInstant.js";
 /**
  * Count the days a container is charged for between the start of its clock and its exit,
@@ -38,6 +38,12 @@ import { isValidInstant } from "../../precision/validate/isValidInstant.js";
  *   inverted dwell is a data error), `freeDays` is not a whole number of at least `0`, the
  *   options fail as they do for `freeTimeExpiry`, `tiers` has a hole, an unsafe integer or does not ascend, or the walk would pass
  *   10,000 local days.
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the last instant Temporal supports
+ *   (`+275760-09-13T00:00:00Z`) for an offset east of UTC, or of the first
+ *   (`-271821-04-20T00:00:00Z`) for one west, this returns `null`. An offset to the minute has no
+ *   such limit.
  *
  * @param clockStart ISO 8601 instant string of the event that starts the clock
  * @param clockEnd ISO 8601 instant string of the event that stops it (gate-out or empty return)
@@ -64,15 +70,17 @@ export function chargeableDays(clockStart, clockEnd, freeDays, options) {
         const allowed = parseFreeDays(freeDays, 0);
         // Read after the terms, so a non-object `options` is never read from.
         const tiers = terms === null ? null : parseTiers(options.tiers);
+        const frame = terms === null ? null : zoneFrame(terms.timeZone);
         if (!isValidInstant(clockStart) ||
             !isValidInstant(clockEnd) ||
             terms === null ||
+            frame === null ||
             allowed === null ||
             tiers === null) {
             return null;
         }
-        const start = instantFrom(clockStart).toZonedDateTimeISO(terms.timeZone);
-        const end = instantFrom(clockEnd).toZonedDateTimeISO(terms.timeZone);
+        const start = frameZoned(instantFrom(clockStart), frame);
+        const end = frameZoned(instantFrom(clockEnd), frame);
         if (Temporal.ZonedDateTime.compare(start, end) > 0) {
             return null;
         }
@@ -83,7 +91,7 @@ export function chargeableDays(clockStart, clockEnd, freeDays, options) {
         return {
             freeDaysUsed: ledger.used,
             chargeableDays: ledger.charged.length,
-            expiresAt: ledger.expiresAt.toInstant().toString(),
+            expiresAt: frameInstant(ledger.expiresAt, frame).toString(),
             chargedDates: ledger.charged.map((day) => day.date),
             byTier: bandsByTier(tiers, ledger.charged.length),
         };

package/dist/intermodal/calculate/freeTimeExpiry.d.ts

@@ -46,6 +46,12 @@ export interface FreeTime {
  *   least `1`, `options` is not an object, `basis` or `firstDay` is missing or unknown,
  *   `timeZone` is invalid, `basis` is `"working"` without a valid `BusinessCalendar`, or the walk
  *   would pass 10,000 local days.
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the last instant Temporal supports
+ *   (`+275760-09-13T00:00:00Z`) for an offset east of UTC, or of the first
+ *   (`-271821-04-20T00:00:00Z`) for one west, this returns `null`. An offset to the minute has no
+ *   such limit.
  *
  * @param clockStart ISO 8601 instant string of the event that starts the clock (discharge, availability or gate-out)
  * @param freeDays whole number of free days the tariff allows, at least 1
@@ -63,5 +69,6 @@ export interface FreeTime {
  * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "working", timeZone: "America/New_York", firstDay: "eventDay" }) // null (a working-day count needs the terminal's calendar)
  * @example freeTimeExpiry("2024-06-14T19:00:00Z", 0, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // null (no free days means no last free day)
  * @example freeTimeExpiry("2024-06-14T19:00:00", 3, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // null (no offset: not an instant)
+ * @example freeTimeExpiry("1970-01-01T00:30:00Z", 3, { basis: "calendar", firstDay: "eventDay", timeZone: "-00:44:30" }) // { freeTimeStart: "1969-12-31", lastFreeDay: "1970-01-02", expiresAt: "1970-01-03T00:44:30Z" }
  */
 export declare function freeTimeExpiry(clockStart: string, freeDays: number, options: FreeTimeOptions): FreeTime | null;

package/dist/intermodal/calculate/freeTimeExpiry.js

@@ -1,4 +1,4 @@
-import { instantFrom, parseFreeDays, parseFreeTimeTerms, walkFreeTime, } from "../../internal/index.js";
+import { frameInstant, frameZoned, instantFrom, parseFreeDays, parseFreeTimeTerms, walkFreeTime, zoneFrame, } from "../../internal/index.js";
 import { isValidInstant } from "../../precision/validate/isValidInstant.js";
 /**
  * Lay out a container's free time from the instant its clock started, and say when it ends.
@@ -38,6 +38,12 @@ import { isValidInstant } from "../../precision/validate/isValidInstant.js";
  *   least `1`, `options` is not an object, `basis` or `firstDay` is missing or unknown,
  *   `timeZone` is invalid, `basis` is `"working"` without a valid `BusinessCalendar`, or the walk
  *   would pass 10,000 local days.
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the last instant Temporal supports
+ *   (`+275760-09-13T00:00:00Z`) for an offset east of UTC, or of the first
+ *   (`-271821-04-20T00:00:00Z`) for one west, this returns `null`. An offset to the minute has no
+ *   such limit.
  *
  * @param clockStart ISO 8601 instant string of the event that starts the clock (discharge, availability or gate-out)
  * @param freeDays whole number of free days the tariff allows, at least 1
@@ -55,15 +61,20 @@ import { isValidInstant } from "../../precision/validate/isValidInstant.js";
  * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "working", timeZone: "America/New_York", firstDay: "eventDay" }) // null (a working-day count needs the terminal's calendar)
  * @example freeTimeExpiry("2024-06-14T19:00:00Z", 0, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // null (no free days means no last free day)
  * @example freeTimeExpiry("2024-06-14T19:00:00", 3, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // null (no offset: not an instant)
+ * @example freeTimeExpiry("1970-01-01T00:30:00Z", 3, { basis: "calendar", firstDay: "eventDay", timeZone: "-00:44:30" }) // { freeTimeStart: "1969-12-31", lastFreeDay: "1970-01-02", expiresAt: "1970-01-03T00:44:30Z" }
  */
 export function freeTimeExpiry(clockStart, freeDays, options) {
     try {
         const terms = parseFreeTimeTerms(options);
         const allowed = parseFreeDays(freeDays, 1);
-        if (!isValidInstant(clockStart) || terms === null || allowed === null) {
+        const frame = terms === null ? null : zoneFrame(terms.timeZone);
+        if (!isValidInstant(clockStart) ||
+            terms === null ||
+            frame === null ||
+            allowed === null) {
             return null;
         }
-        const start = instantFrom(clockStart).toZonedDateTimeISO(terms.timeZone);
+        const start = frameZoned(instantFrom(clockStart), frame);
         const ledger = walkFreeTime(start, allowed, terms);
         if (ledger === null) {
             return null;
@@ -71,7 +82,7 @@ export function freeTimeExpiry(clockStart, freeDays, options) {
         return {
             freeTimeStart: ledger.free[0].date,
             lastFreeDay: ledger.free[allowed - 1].date,
-            expiresAt: ledger.expiresAt.toInstant().toString(),
+            expiresAt: frameInstant(ledger.expiresAt, frame).toString(),
         };
     }
     catch {

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

@@ -2,3 +2,4 @@ export * from "./billingTimeline.js";
 export * from "./chargeableDays.js";
 export * from "./demurrageClock.js";
 export * from "./freeTimeExpiry.js";
+export * from "./multimodalETA.js";