@northguild/gmt 1.18.0 → 1.20.0

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
@@ -24,22 +23,27 @@ const DISAMBIGUATIONS = [
  * - `localDateTime` is a PlainDateTime string, as `isValidDateTime` accepts: `<date>T<time>`
  *   with no offset (an offset means the wall time already resolved). Its RFC 9557 annotations
  *   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.
+ *   (`[Asia/Tokyo]`) 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
  *
- * @example resolveLocal("2024-07-15T12:00:00", "America/New_York") // "2024-07-15T16:00:00Z"
- * @example resolveLocal("2024-11-03T01:30:00", "America/New_York") // "2024-11-03T05:30:00Z" (ambiguous; "compatible" takes the earlier)
- * @example resolveLocal("2024-11-03T01:30:00", "America/New_York", { disambiguation: "later" }) // "2024-11-03T06:30:00Z" (the same wall time, an hour later)
- * @example resolveLocal("2024-11-03T01:30:00", "America/New_York", { disambiguation: "reject" }) // "" (ambiguous, and not guessed)
- * @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("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", "Asia/Tokyo") // "2024-07-15T03:00:00Z"
+ * @example resolveLocal("2024-10-27T01:30:00", "Europe/London") // "2024-10-27T00:30:00Z" (ambiguous; "compatible" takes the earlier)
+ * @example resolveLocal("2024-10-27T01:30:00", "Europe/London", { disambiguation: "later" }) // "2024-10-27T01:30:00Z" (the same wall time, an hour later)
+ * @example resolveLocal("2024-10-27T01:30:00", "Europe/London", { disambiguation: "reject" }) // "" (ambiguous, and not guessed)
+ * @example resolveLocal("2024-10-06T02:30:00", "Australia/Sydney") // "2024-10-05T16:30:00Z" (nonexistent; "compatible" takes the later)
+ * @example resolveLocal("2024-10-06T02:30:00", "Australia/Sydney", { disambiguation: "earlier" }) // "2024-10-05T15:30:00Z"
+ * @example resolveLocal("2024-07-15T12:00:00+05:30", "Asia/Kolkata") // "" (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]", "Africa/Johannesburg") // "2024-07-15T10:00:00Z" (elective annotation ignored)
  * @example resolveLocal("2024-07-15T12:00:00", "Invalid/Zone") // ""
  */
 export function resolveLocal(localDateTime, timeZone, optionsArg) {
@@ -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,14 +3,15 @@
  *
  * 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";
  * const pair: OffsetInstant = {
  *   instant: "2024-07-15T16:00:00Z",
- *   offset: "-04:00",
- *   timeZone: "America/New_York",
+ *   offset: "+05:30",
+ *   timeZone: "Asia/Kolkata",
  * };
  */
 export interface OffsetInstant {
@@ -35,8 +36,8 @@ export interface OffsetInstant {
 /**
  * Split an ISO 8601 instant string into the instant-plus-offset pair the world exchanges.
  *
- * - **An offset is not a zone.** `-05:00` does not identify `America/New_York` — it is every
- *   zone at `-05:00` that day. Keep the offset for what already happened; keep the zone for
+ * - **An offset is not a zone.** `+02:00` does not identify `Africa/Johannesburg` — it is every
+ *   zone at `+02:00` that day. Keep the offset for what already happened; keep the zone for
  *   anything still to be scheduled. `timeZone` is optional because most feeds send no zone.
  * - Accepts a `Z` instant, a bare `±HH:MM` offset, or a bracketed IANA zone, in ISO 8601
  *   extended format with a `T` separator — `isValidInstant`'s grammar. Basic format, a space or
@@ -44,7 +45,7 @@ export interface OffsetInstant {
  *   annotations are read as Temporal reads them (RFC 9557 §3.3, proposal-temporal
  *   `ParseISODateTime`): a calendar (`[u-ca=hebrew]`) or elective (`[x-provenance=estimated]`)
  *   annotation is ignored, and an unknown critical one (`[!foo=bar]`) returns null.
- * - A bracketed zone whose offset contradicts it (`"...T12:00:00-05:00[America/New_York]"` in
+ * - A bracketed zone whose offset contradicts it (`"...T12:00:00+00:00[Europe/London]"` in
  *   July) returns null. The string states two things that cannot both be true, and guessing
  *   which one the sender meant is exactly the bug the pair exists to prevent.
  * - A bracketed *offset* time zone (Temporal's own `[-04:00]` shape) yields no `timeZone`
@@ -52,14 +53,15 @@ 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
+ *   `"europe/london"` comes back as `"Europe/London"` — because identifiers match
  *   case-insensitively (ECMA-402). That is what the bracket path and `fromOffsetInstant` return,
  *   so `toOffsetInstant(fromOffsetInstant(pair))` returns `pair`. A link name is kept, not
  *   replaced by its target. Compatibility: earlier releases echoed the argument's casing; pass
@@ -82,25 +84,27 @@ 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" }
+ * @example toOffsetInstant("2024-07-15T12:00:00+09:00[Asia/Tokyo]") // { instant: "2024-07-15T03:00:00Z", offset: "+09:00", timeZone: "Asia/Tokyo" }
  * @example toOffsetInstant("2024-07-15T12:00:00-04:00") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00" } — an offset with no zone behind it
  * @example toOffsetInstant("2024-07-15T16:00:00Z") // { instant: "2024-07-15T16:00:00Z", offset: "+00:00" }
- * @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("2024-07-15T16:00:00Z", "Europe/London") // { instant: "2024-07-15T16:00:00Z", offset: "+01:00", timeZone: "Europe/London" }
+ * @example toOffsetInstant("2024-01-15T17:00:00Z", "Europe/London") // { instant: "2024-01-15T17:00:00Z", offset: "+00:00", timeZone: "Europe/London" } — 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("2024-07-15T12:00:00+00:00[Europe/London]") // 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)
  * @example toOffsetInstant("20240715T120000-0400") // null (basic format)
- * @example toOffsetInstant("2024-07-15T16:00:00Z", "america/new_york") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00", timeZone: "America/New_York" } — IANA casing
+ * @example toOffsetInstant("2024-07-15T16:00:00Z", "europe/london") // { instant: "2024-07-15T16:00:00Z", offset: "+01:00", timeZone: "Europe/London" } — IANA casing
  * @example toOffsetInstant("2024-07-15T16:00:00Z", "Japan") // { instant: "2024-07-15T16:00:00Z", offset: "+09:00", timeZone: "Japan" }
  * @example toOffsetInstant("2024-07-15T16:00:00-00:00") // { instant: "2024-07-15T16:00:00Z", offset: "+00:00" } — "offset unknown" is not preserved
  * @example toOffsetInstant("2024-07-15T16:00:00+01:00:00.5") // null (fractional-second offset)

package/dist/instant/convert/toOffsetInstant.js

@@ -1,14 +1,13 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { formatUtcOffset, isoStringBody, parseInstantNanoseconds, TIME_ZONE_ANNOTATION, zonedDateTimeFrom, } from "../../internal/index.js";
+import { Temporal } from "../../internal/temporal.js";
+import { frameOffset, isoStringBody, parseInstantNanoseconds, TIME_ZONE_ANNOTATION, writtenOffset, 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}`);
 /**
  * Split an ISO 8601 instant string into the instant-plus-offset pair the world exchanges.
  *
- * - **An offset is not a zone.** `-05:00` does not identify `America/New_York` — it is every
- *   zone at `-05:00` that day. Keep the offset for what already happened; keep the zone for
+ * - **An offset is not a zone.** `+02:00` does not identify `Africa/Johannesburg` — it is every
+ *   zone at `+02:00` that day. Keep the offset for what already happened; keep the zone for
  *   anything still to be scheduled. `timeZone` is optional because most feeds send no zone.
  * - Accepts a `Z` instant, a bare `±HH:MM` offset, or a bracketed IANA zone, in ISO 8601
  *   extended format with a `T` separator — `isValidInstant`'s grammar. Basic format, a space or
@@ -16,7 +15,7 @@ const timeZoneAnnotation = new RegExp(`^${TIME_ZONE_ANNOTATION}`);
  *   annotations are read as Temporal reads them (RFC 9557 §3.3, proposal-temporal
  *   `ParseISODateTime`): a calendar (`[u-ca=hebrew]`) or elective (`[x-provenance=estimated]`)
  *   annotation is ignored, and an unknown critical one (`[!foo=bar]`) returns null.
- * - A bracketed zone whose offset contradicts it (`"...T12:00:00-05:00[America/New_York]"` in
+ * - A bracketed zone whose offset contradicts it (`"...T12:00:00+00:00[Europe/London]"` in
  *   July) returns null. The string states two things that cannot both be true, and guessing
  *   which one the sender meant is exactly the bug the pair exists to prevent.
  * - A bracketed *offset* time zone (Temporal's own `[-04:00]` shape) yields no `timeZone`
@@ -24,14 +23,15 @@ 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
+ *   `"europe/london"` comes back as `"Europe/London"` — because identifiers match
  *   case-insensitively (ECMA-402). That is what the bracket path and `fromOffsetInstant` return,
  *   so `toOffsetInstant(fromOffsetInstant(pair))` returns `pair`. A link name is kept, not
  *   replaced by its target. Compatibility: earlier releases echoed the argument's casing; pass
@@ -54,25 +54,27 @@ 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" }
+ * @example toOffsetInstant("2024-07-15T12:00:00+09:00[Asia/Tokyo]") // { instant: "2024-07-15T03:00:00Z", offset: "+09:00", timeZone: "Asia/Tokyo" }
  * @example toOffsetInstant("2024-07-15T12:00:00-04:00") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00" } — an offset with no zone behind it
  * @example toOffsetInstant("2024-07-15T16:00:00Z") // { instant: "2024-07-15T16:00:00Z", offset: "+00:00" }
- * @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("2024-07-15T16:00:00Z", "Europe/London") // { instant: "2024-07-15T16:00:00Z", offset: "+01:00", timeZone: "Europe/London" }
+ * @example toOffsetInstant("2024-01-15T17:00:00Z", "Europe/London") // { instant: "2024-01-15T17:00:00Z", offset: "+00:00", timeZone: "Europe/London" } — 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("2024-07-15T12:00:00+00:00[Europe/London]") // 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)
  * @example toOffsetInstant("20240715T120000-0400") // null (basic format)
- * @example toOffsetInstant("2024-07-15T16:00:00Z", "america/new_york") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00", timeZone: "America/New_York" } — IANA casing
+ * @example toOffsetInstant("2024-07-15T16:00:00Z", "europe/london") // { instant: "2024-07-15T16:00:00Z", offset: "+01:00", timeZone: "Europe/London" } — IANA casing
  * @example toOffsetInstant("2024-07-15T16:00:00Z", "Japan") // { instant: "2024-07-15T16:00:00Z", offset: "+09:00", timeZone: "Japan" }
  * @example toOffsetInstant("2024-07-15T16:00:00-00:00") // { instant: "2024-07-15T16:00:00Z", offset: "+00:00" } — "offset unknown" is not preserved
  * @example toOffsetInstant("2024-07-15T16:00:00+01:00:00.5") // null (fractional-second offset)
@@ -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);
         }
@@ -150,20 +158,3 @@ function offsetInstantInZone(instant, zone) {
         timeZone: zoned.timeZoneId,
     };
 }
-/** The offset the string's own digits were written in, recovered for an unbracketed value. */
-function writtenOffset(instant, body) {
-    // With no zone and no bracket, the offset is the distance between two wall clocks: the digits as
-    // written, and the same instant read in UTC. That recovers it without slicing the
-    // string. The subtraction stays on `PlainDateTime` rather than going through an
-    // instant, because a wall clock reaches a day further either side than an instant does
-    // — `+275760-09-13T14:00:00+14:00` names a representable instant whose digits, read as
-    // UTC, are past the end of the range. `PlainDateTime.from` parses every shape this
-    // grammar allows but the `Z` designator, and a `Z` string's wall clock *is* the UTC
-    // one, so its offset is `+00:00` by definition.
-    const utcWallClock = instant.toZonedDateTimeISO("UTC").toPlainDateTime();
-    const writtenWallClock = body.endsWith("Z") || body.endsWith("z")
-        ? utcWallClock
-        : Temporal.PlainDateTime.from(body);
-    return formatUtcOffset(BigInt(utcWallClock.until(writtenWallClock, { largestUnit: "nanosecond" })
-        .nanoseconds));
-}

package/dist/instant/index.d.ts

@@ -1,2 +1,3 @@
-export * from "@js-temporal/polyfill";
+export { Intl, Temporal, toTemporalInstant } from "../internal/temporal.js";
 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";
+// Re-export `Temporal`, `Intl` and `toTemporalInstant` from the internal seam so every namespace subpath offers them
+export { Intl, Temporal, toTemporalInstant } from "../internal/temporal.js";
 export * from "./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("Europe/London") // 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("Europe/London") // false (a zone, not an offset)
+ */
+export function isValidUtcOffset(value) {
+    return typeof value === "string" && utcOffset.test(value);
+}

package/dist/intermodal/calculate/billingTimeline.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { isObject } from "../../internal/index.js";
 import { isValidDate } from "../../plain/validate/isValidDate.js";
 /**

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)
@@ -84,17 +90,17 @@ export type FreeTimeChargeOptions = FreeTimeOptions & {
  * @param options The tariff's counting terms for free time and for charged days, and the tier bands
  * @returns the free days used, the chargeable days, the expiry, the charged dates and the days per tier band, or null on invalid input
  *
- * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeDaysUsed: 3, chargeableDays: 0, expiresAt: "2024-06-17T04:00:00Z", chargedDates: [], byTier: [{ from: 1, to: null, days: 0 }] } (gate-out exactly at expiry is free)
- * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeDaysUsed: 3, chargeableDays: 1, expiresAt: "2024-06-17T04:00:00Z", chargedDates: ["2024-06-17"], byTier: [{ from: 1, to: null, days: 1 }] } (one second later is a charged day)
- * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "nextDay" }) // { freeDaysUsed: 3, chargeableDays: 0, expiresAt: "2024-06-18T04:00:00Z", chargedDates: [], byTier: [{ from: 1, to: null, days: 0 }] } (the other start-day convention: still free)
- * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-28T15:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay", tiers: [5, 10] }) // { freeDaysUsed: 3, chargeableDays: 12, expiresAt: "2024-06-17T04:00:00Z", chargedDates: ["2024-06-17", "2024-06-18", "2024-06-19", "2024-06-20", "2024-06-21", "2024-06-22", "2024-06-23", "2024-06-24", "2024-06-25", "2024-06-26", "2024-06-27", "2024-06-28"], byTier: [{ from: 1, to: 5, days: 5 }, { from: 6, to: 10, days: 5 }, { from: 11, to: null, days: 2 }] }
- * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-24T15:00:00Z", 3, { basis: "working", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: ["2024-06-19"], timeZone: "America/New_York" } }) // { freeDaysUsed: 3, chargeableDays: 6, expiresAt: "2024-06-19T04:00:00Z", chargedDates: ["2024-06-19", "2024-06-20", "2024-06-21", "2024-06-22", "2024-06-23", "2024-06-24"], byTier: [{ from: 1, to: null, days: 6 }] } (free days in working days, every calendar day after expiry charged)
- * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-24T15:00:00Z", 3, { basis: "working", chargeBasis: "working", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: ["2024-06-19"], timeZone: "America/New_York" } }) // { freeDaysUsed: 3, chargeableDays: 3, expiresAt: "2024-06-19T04:00:00Z", chargedDates: ["2024-06-20", "2024-06-21", "2024-06-24"], byTier: [{ from: 1, to: null, days: 3 }] } (working days throughout: closed days after expiry are not charged)
- * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-15T15:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeDaysUsed: 2, chargeableDays: 0, expiresAt: "2024-06-17T04:00:00Z", chargedDates: [], byTier: [{ from: 1, to: null, days: 0 }] } (out on the second free day)
- * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-16T15:00:00Z", 0, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeDaysUsed: 0, chargeableDays: 3, expiresAt: "2024-06-14T04:00:00Z", chargedDates: ["2024-06-14", "2024-06-15", "2024-06-16"], byTier: [{ from: 1, to: null, days: 3 }] } (no free time: every day is charged)
- * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-28T15:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay", tiers: [10, 5] }) // null (tiers must ascend)
- * @example chargeableDays("2024-06-17T04:00:01Z", "2024-06-14T19:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // null (exit before the clock started)
- * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York" }) // null (firstDay has no default)
- * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // null (chargeBasis has no default)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/Port_of_Spain", firstDay: "eventDay" }) // { freeDaysUsed: 3, chargeableDays: 0, expiresAt: "2024-06-17T04:00:00Z", chargedDates: [], byTier: [{ from: 1, to: null, days: 0 }] } (gate-out exactly at expiry is free)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/Port_of_Spain", firstDay: "eventDay" }) // { freeDaysUsed: 3, chargeableDays: 1, expiresAt: "2024-06-17T04:00:00Z", chargedDates: ["2024-06-17"], byTier: [{ from: 1, to: null, days: 1 }] } (one second later is a charged day)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/Port_of_Spain", firstDay: "nextDay" }) // { freeDaysUsed: 3, chargeableDays: 0, expiresAt: "2024-06-18T04:00:00Z", chargedDates: [], byTier: [{ from: 1, to: null, days: 0 }] } (the other start-day convention: still free)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-28T15:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/Port_of_Spain", firstDay: "eventDay", tiers: [5, 10] }) // { freeDaysUsed: 3, chargeableDays: 12, expiresAt: "2024-06-17T04:00:00Z", chargedDates: ["2024-06-17", "2024-06-18", "2024-06-19", "2024-06-20", "2024-06-21", "2024-06-22", "2024-06-23", "2024-06-24", "2024-06-25", "2024-06-26", "2024-06-27", "2024-06-28"], byTier: [{ from: 1, to: 5, days: 5 }, { from: 6, to: 10, days: 5 }, { from: 11, to: null, days: 2 }] }
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-24T15:00:00Z", 3, { basis: "working", chargeBasis: "calendar", timeZone: "America/Port_of_Spain", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: ["2024-06-19"], timeZone: "America/Port_of_Spain" } }) // { freeDaysUsed: 3, chargeableDays: 6, expiresAt: "2024-06-19T04:00:00Z", chargedDates: ["2024-06-19", "2024-06-20", "2024-06-21", "2024-06-22", "2024-06-23", "2024-06-24"], byTier: [{ from: 1, to: null, days: 6 }] } (free days in working days, every calendar day after expiry charged)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-24T15:00:00Z", 3, { basis: "working", chargeBasis: "working", timeZone: "America/Port_of_Spain", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: ["2024-06-19"], timeZone: "America/Port_of_Spain" } }) // { freeDaysUsed: 3, chargeableDays: 3, expiresAt: "2024-06-19T04:00:00Z", chargedDates: ["2024-06-20", "2024-06-21", "2024-06-24"], byTier: [{ from: 1, to: null, days: 3 }] } (working days throughout: closed days after expiry are not charged)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-15T15:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/Port_of_Spain", firstDay: "eventDay" }) // { freeDaysUsed: 2, chargeableDays: 0, expiresAt: "2024-06-17T04:00:00Z", chargedDates: [], byTier: [{ from: 1, to: null, days: 0 }] } (out on the second free day)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-16T15:00:00Z", 0, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/Port_of_Spain", firstDay: "eventDay" }) // { freeDaysUsed: 0, chargeableDays: 3, expiresAt: "2024-06-14T04:00:00Z", chargedDates: ["2024-06-14", "2024-06-15", "2024-06-16"], byTier: [{ from: 1, to: null, days: 3 }] } (no free time: every day is charged)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-28T15:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/Port_of_Spain", firstDay: "eventDay", tiers: [10, 5] }) // null (tiers must ascend)
+ * @example chargeableDays("2024-06-17T04:00:01Z", "2024-06-14T19:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/Port_of_Spain", firstDay: "eventDay" }) // null (exit before the clock started)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/Port_of_Spain" }) // null (firstDay has no default)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", timeZone: "America/Port_of_Spain", firstDay: "eventDay" }) // null (chargeBasis has no default)
  */
 export declare function chargeableDays(clockStart: string, clockEnd: string, freeDays: number, options: FreeTimeChargeOptions): FreeTimeCharges | null;

package/dist/intermodal/calculate/chargeableDays.js

@@ -1,5 +1,6 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { bandsByTier, instantFrom, parseFreeDays, parseFreeTimeTerms, parseTiers, walkFreeTime, } from "../../internal/index.js";
+import { isoDateString } from "../../internal/epochDay.js";
+import { Temporal } from "../../internal/temporal.js";
+import { bandsByTier, 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 +39,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)
@@ -45,18 +52,18 @@ import { isValidInstant } from "../../precision/validate/isValidInstant.js";
  * @param options The tariff's counting terms for free time and for charged days, and the tier bands
  * @returns the free days used, the chargeable days, the expiry, the charged dates and the days per tier band, or null on invalid input
  *
- * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeDaysUsed: 3, chargeableDays: 0, expiresAt: "2024-06-17T04:00:00Z", chargedDates: [], byTier: [{ from: 1, to: null, days: 0 }] } (gate-out exactly at expiry is free)
- * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeDaysUsed: 3, chargeableDays: 1, expiresAt: "2024-06-17T04:00:00Z", chargedDates: ["2024-06-17"], byTier: [{ from: 1, to: null, days: 1 }] } (one second later is a charged day)
- * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "nextDay" }) // { freeDaysUsed: 3, chargeableDays: 0, expiresAt: "2024-06-18T04:00:00Z", chargedDates: [], byTier: [{ from: 1, to: null, days: 0 }] } (the other start-day convention: still free)
- * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-28T15:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay", tiers: [5, 10] }) // { freeDaysUsed: 3, chargeableDays: 12, expiresAt: "2024-06-17T04:00:00Z", chargedDates: ["2024-06-17", "2024-06-18", "2024-06-19", "2024-06-20", "2024-06-21", "2024-06-22", "2024-06-23", "2024-06-24", "2024-06-25", "2024-06-26", "2024-06-27", "2024-06-28"], byTier: [{ from: 1, to: 5, days: 5 }, { from: 6, to: 10, days: 5 }, { from: 11, to: null, days: 2 }] }
- * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-24T15:00:00Z", 3, { basis: "working", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: ["2024-06-19"], timeZone: "America/New_York" } }) // { freeDaysUsed: 3, chargeableDays: 6, expiresAt: "2024-06-19T04:00:00Z", chargedDates: ["2024-06-19", "2024-06-20", "2024-06-21", "2024-06-22", "2024-06-23", "2024-06-24"], byTier: [{ from: 1, to: null, days: 6 }] } (free days in working days, every calendar day after expiry charged)
- * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-24T15:00:00Z", 3, { basis: "working", chargeBasis: "working", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: ["2024-06-19"], timeZone: "America/New_York" } }) // { freeDaysUsed: 3, chargeableDays: 3, expiresAt: "2024-06-19T04:00:00Z", chargedDates: ["2024-06-20", "2024-06-21", "2024-06-24"], byTier: [{ from: 1, to: null, days: 3 }] } (working days throughout: closed days after expiry are not charged)
- * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-15T15:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeDaysUsed: 2, chargeableDays: 0, expiresAt: "2024-06-17T04:00:00Z", chargedDates: [], byTier: [{ from: 1, to: null, days: 0 }] } (out on the second free day)
- * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-16T15:00:00Z", 0, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeDaysUsed: 0, chargeableDays: 3, expiresAt: "2024-06-14T04:00:00Z", chargedDates: ["2024-06-14", "2024-06-15", "2024-06-16"], byTier: [{ from: 1, to: null, days: 3 }] } (no free time: every day is charged)
- * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-28T15:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay", tiers: [10, 5] }) // null (tiers must ascend)
- * @example chargeableDays("2024-06-17T04:00:01Z", "2024-06-14T19:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // null (exit before the clock started)
- * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York" }) // null (firstDay has no default)
- * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // null (chargeBasis has no default)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/Port_of_Spain", firstDay: "eventDay" }) // { freeDaysUsed: 3, chargeableDays: 0, expiresAt: "2024-06-17T04:00:00Z", chargedDates: [], byTier: [{ from: 1, to: null, days: 0 }] } (gate-out exactly at expiry is free)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/Port_of_Spain", firstDay: "eventDay" }) // { freeDaysUsed: 3, chargeableDays: 1, expiresAt: "2024-06-17T04:00:00Z", chargedDates: ["2024-06-17"], byTier: [{ from: 1, to: null, days: 1 }] } (one second later is a charged day)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/Port_of_Spain", firstDay: "nextDay" }) // { freeDaysUsed: 3, chargeableDays: 0, expiresAt: "2024-06-18T04:00:00Z", chargedDates: [], byTier: [{ from: 1, to: null, days: 0 }] } (the other start-day convention: still free)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-28T15:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/Port_of_Spain", firstDay: "eventDay", tiers: [5, 10] }) // { freeDaysUsed: 3, chargeableDays: 12, expiresAt: "2024-06-17T04:00:00Z", chargedDates: ["2024-06-17", "2024-06-18", "2024-06-19", "2024-06-20", "2024-06-21", "2024-06-22", "2024-06-23", "2024-06-24", "2024-06-25", "2024-06-26", "2024-06-27", "2024-06-28"], byTier: [{ from: 1, to: 5, days: 5 }, { from: 6, to: 10, days: 5 }, { from: 11, to: null, days: 2 }] }
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-24T15:00:00Z", 3, { basis: "working", chargeBasis: "calendar", timeZone: "America/Port_of_Spain", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: ["2024-06-19"], timeZone: "America/Port_of_Spain" } }) // { freeDaysUsed: 3, chargeableDays: 6, expiresAt: "2024-06-19T04:00:00Z", chargedDates: ["2024-06-19", "2024-06-20", "2024-06-21", "2024-06-22", "2024-06-23", "2024-06-24"], byTier: [{ from: 1, to: null, days: 6 }] } (free days in working days, every calendar day after expiry charged)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-24T15:00:00Z", 3, { basis: "working", chargeBasis: "working", timeZone: "America/Port_of_Spain", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: ["2024-06-19"], timeZone: "America/Port_of_Spain" } }) // { freeDaysUsed: 3, chargeableDays: 3, expiresAt: "2024-06-19T04:00:00Z", chargedDates: ["2024-06-20", "2024-06-21", "2024-06-24"], byTier: [{ from: 1, to: null, days: 3 }] } (working days throughout: closed days after expiry are not charged)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-15T15:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/Port_of_Spain", firstDay: "eventDay" }) // { freeDaysUsed: 2, chargeableDays: 0, expiresAt: "2024-06-17T04:00:00Z", chargedDates: [], byTier: [{ from: 1, to: null, days: 0 }] } (out on the second free day)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-16T15:00:00Z", 0, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/Port_of_Spain", firstDay: "eventDay" }) // { freeDaysUsed: 0, chargeableDays: 3, expiresAt: "2024-06-14T04:00:00Z", chargedDates: ["2024-06-14", "2024-06-15", "2024-06-16"], byTier: [{ from: 1, to: null, days: 3 }] } (no free time: every day is charged)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-28T15:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/Port_of_Spain", firstDay: "eventDay", tiers: [10, 5] }) // null (tiers must ascend)
+ * @example chargeableDays("2024-06-17T04:00:01Z", "2024-06-14T19:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/Port_of_Spain", firstDay: "eventDay" }) // null (exit before the clock started)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/Port_of_Spain" }) // null (firstDay has no default)
+ * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:01Z", 3, { basis: "calendar", timeZone: "America/Port_of_Spain", firstDay: "eventDay" }) // null (chargeBasis has no default)
  */
 export function chargeableDays(clockStart, clockEnd, freeDays, options) {
     try {
@@ -64,15 +71,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,8 +92,8 @@ export function chargeableDays(clockStart, clockEnd, freeDays, options) {
         return {
             freeDaysUsed: ledger.used,
             chargeableDays: ledger.charged.length,
-            expiresAt: ledger.expiresAt.toInstant().toString(),
-            chargedDates: ledger.charged.map((day) => day.date),
+            expiresAt: Temporal.Instant.fromEpochNanoseconds(ledger.expiresAtNs).toString(),
+            chargedDates: ledger.charged.map(isoDateString),
             byTier: bandsByTier(tiers, ledger.charged.length),
         };
     }

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

@@ -91,7 +91,7 @@ export interface ClockOptions {
  * @example demurrageClock([{ type: "emptyReleased", at: "2024-07-01T08:00:00Z" }, { type: "gatedIn", at: "2024-07-05T16:00:00Z" }, { type: "loaded", at: "2024-07-09T03:00:00Z" }], "demurrage", { direction: "export" }) // { start: "2024-07-05T16:00:00Z", end: "2024-07-09T03:00:00Z" } (gate-in full to loaded on board)
  * @example demurrageClock([{ type: "emptyReleased", at: "2024-07-01T08:00:00Z" }, { type: "gatedIn", at: "2024-07-05T16:00:00Z" }, { type: "loaded", at: "2024-07-09T03:00:00Z" }], "detention", { direction: "export" }) // { start: "2024-07-01T08:00:00Z", end: "2024-07-05T16:00:00Z" } (empty picked up to gate-in full)
  * @example demurrageClock([{ type: "emptyReleased", at: "2024-07-01T08:00:00Z" }, { type: "gatedIn", at: "2024-07-05T16:00:00Z" }, { type: "loaded", at: "2024-07-09T03:00:00Z" }], "combined", { direction: "export" }) // { start: "2024-07-01T08:00:00Z", end: "2024-07-09T03:00:00Z" }
- * @example demurrageClock([{ type: "gatedOut", at: "2024-06-20T10:30:00-04:00[America/New_York]" }, { type: "emptyReturned", at: "2024-06-27T09:00:00Z" }], "detention", { direction: "import", startEvent: "available" }) // { start: "2024-06-20T10:30:00-04:00[America/New_York]", end: "2024-06-27T09:00:00Z" } (startEvent is not read for detention; strings are echoed as given)
+ * @example demurrageClock([{ type: "gatedOut", at: "2024-06-20T10:30:00+02:00[Africa/Johannesburg]" }, { type: "emptyReturned", at: "2024-06-27T09:00:00Z" }], "detention", { direction: "import", startEvent: "available" }) // { start: "2024-06-20T10:30:00+02:00[Africa/Johannesburg]", end: "2024-06-27T09:00:00Z" } (startEvent is not read for detention; strings are echoed as given)
  * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }], "demurrage") // null (direction has no default)
  * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }], "demurrage", { direction: "import", startEvent: "available" }) // null (no availability event)
  * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }], "demurrage", { direction: "import" }) // null (still in the terminal: no gate-out)