@northguild/gmt 1.18.0 → 1.20.0

package/dist/regex/leap-second.d.ts

@@ -15,7 +15,7 @@
  * - Rejecting a leap second is GMT's decision, not the grammar's range: Temporal's
  *   `TimeSecond` and RFC 3339's `time-second` both admit 60. GMT refuses the value because
  *   Temporal cannot represent it and would otherwise read it as `:59`.
- * - Used by `isLeapSecond`. Validators reject a second of 60 in their own patterns.
+ * - Used by `hasSecond60`. Validators reject a second of 60 in their own patterns.
  *
  * @example leapSecond.test("2024-12-31T23:59:60Z")                // true
  * @example leapSecond.test("2024-12-31T23:59:60.123+00:00")       // true

package/dist/regex/leap-second.js

@@ -15,7 +15,7 @@
  * - Rejecting a leap second is GMT's decision, not the grammar's range: Temporal's
  *   `TimeSecond` and RFC 3339's `time-second` both admit 60. GMT refuses the value because
  *   Temporal cannot represent it and would otherwise read it as `:59`.
- * - Used by `isLeapSecond`. Validators reject a second of 60 in their own patterns.
+ * - Used by `hasSecond60`. Validators reject a second of 60 in their own patterns.
  *
  * @example leapSecond.test("2024-12-31T23:59:60Z")                // true
  * @example leapSecond.test("2024-12-31T23:59:60.123+00:00")       // true

package/dist/regex/rfc-2822.d.ts

@@ -13,6 +13,8 @@
  *   `parseRfc2822` reads the full receiver grammar — use it to decode a header, and this
  *   pattern only to check that a string has the strict shape.
  * - The day-of-week is not checked against the date; `parseRfc2822` does check it.
+ * - To check that a string is a real RFC 5322 date-time, use `isValidRfc2822DateTime`: this
+ *   pattern also matches a day that does not exist and an hour or zone out of range.
  *
  * Capture groups: 1 day-of-week (optional, for weekday-prefixed form), 2 day, 3 month,
  * 4 year, 5 hour, 6 minute, 7 second (optional), 8 zone.

package/dist/regex/rfc-2822.js

@@ -13,6 +13,8 @@
  *   `parseRfc2822` reads the full receiver grammar — use it to decode a header, and this
  *   pattern only to check that a string has the strict shape.
  * - The day-of-week is not checked against the date; `parseRfc2822` does check it.
+ * - To check that a string is a real RFC 5322 date-time, use `isValidRfc2822DateTime`: this
+ *   pattern also matches a day that does not exist and an hour or zone out of range.
  *
  * Capture groups: 1 day-of-week (optional, for weekday-prefixed form), 2 day, 3 month,
  * 4 year, 5 hour, 6 minute, 7 second (optional), 8 zone.

package/dist/regex/rfc-3339.d.ts

@@ -11,7 +11,9 @@
  *   `:59`), and the fraction is capped at 9 digits (`time-secfrac` is `1*DIGIT`; Temporal keeps
  *   nanoseconds).
  * - Shape-only validation; real calendar validation is delegated to
- *   `Temporal.PlainDateTime.from(...).toZonedDateTime(offset)` in `parseRfc3339`.
+ *   `Temporal.PlainDateTime.from(...).toZonedDateTime(offset)` in `parseRfc3339`. To check that a
+ *   string is a real RFC 3339 date-time, use `isValidRfc3339DateTime`: this pattern also matches
+ *   a day that does not exist, such as 29 February 2023.
  * - Capture groups: 1 year, 2 month, 3 day, 4 hour, 5 minute, 6 second,
  *   7 fractional (optional), 8 offset.
  *

package/dist/regex/rfc-3339.js

@@ -11,7 +11,9 @@
  *   `:59`), and the fraction is capped at 9 digits (`time-secfrac` is `1*DIGIT`; Temporal keeps
  *   nanoseconds).
  * - Shape-only validation; real calendar validation is delegated to
- *   `Temporal.PlainDateTime.from(...).toZonedDateTime(offset)` in `parseRfc3339`.
+ *   `Temporal.PlainDateTime.from(...).toZonedDateTime(offset)` in `parseRfc3339`. To check that a
+ *   string is a real RFC 3339 date-time, use `isValidRfc3339DateTime`: this pattern also matches
+ *   a day that does not exist, such as 29 February 2023.
  * - Capture groups: 1 year, 2 month, 3 day, 4 hour, 5 minute, 6 second,
  *   7 fractional (optional), 8 offset.
  *

package/dist/regex/sql-date-time.d.ts

@@ -16,7 +16,8 @@
  * - SECOND `60`–`61` does not match, although Table 10 allows them: GMT rejects leap seconds
  *   because Temporal would read one as `:59`.
  * - Shape-only validation; the calendar date is checked by `Temporal.PlainDateTime.from` in
- *   `parseSql`.
+ *   `parseSqlDateTime`. To check that a string is a real SQL timestamp literal, use
+ *   `isValidSqlDateTime`: this pattern also matches a day that does not exist, such as 30 February.
  *
  * Capture groups: 1 month, 2 day, 3 hour. The year, minute, second and fraction are not
  * captured.

package/dist/regex/sql-date-time.js

@@ -16,7 +16,8 @@
  * - SECOND `60`–`61` does not match, although Table 10 allows them: GMT rejects leap seconds
  *   because Temporal would read one as `:59`.
  * - Shape-only validation; the calendar date is checked by `Temporal.PlainDateTime.from` in
- *   `parseSql`.
+ *   `parseSqlDateTime`. To check that a string is a real SQL timestamp literal, use
+ *   `isValidSqlDateTime`: this pattern also matches a day that does not exist, such as 30 February.
  *
  * Capture groups: 1 month, 2 day, 3 hour. The year, minute, second and fraction are not
  * captured.

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

@@ -1,11 +1,12 @@
 /**
  * RegExp matching the shape of a time zone identifier: Temporal's `TimeZoneIdentifier` grammar
- * (§14.6.2 Time Zone Identifiers), `UTCOffset[~SubMinutePrecision] | TimeZoneIANAName`.
+ * (§13.31, the ISO 8601 / RFC 9557 grammar),
+ * `TimeZoneIdentifier ::: UTCOffset[~SubMinutePrecision] | TimeZoneIANAName`.
  *
  * - An offset identifier (`UTCOffset[~SubMinutePrecision]`): an ASCII sign and a two-digit hour
  *   `00`–`23`, optionally followed by two minute digits `00`–`59`, with or without `:` (`+05`,
  *   `+0530`, `-08:00`). No seconds and no fraction. `Intl.DateTimeFormat` accepts the same
- *   offsets (ECMA-402 `IsTimeZoneOffsetString`).
+ *   offsets (ECMA-262 `IsTimeZoneOffsetString`, which ECMA-402 calls).
  * - An IANA name (`TimeZoneIANAName`): one or more `/`-separated components. Each starts with a
  *   letter, `.` or `_` (`TZLeadingChar`) and continues with letters, digits, `.`, `_`, `-` or `+`
  *   (`TZChar`). So single-component names match (`UTC`, `Japan`, `Zulu`, `EST5EDT`, `GMT+0`,
@@ -13,12 +14,12 @@
  *   `Etc/GMT+5`). Temporal must accept every Zone and Link name in the IANA database, and tzdb's
  *   `backward` file has more than forty slash-less ones.
  * - Letter case is not checked: ECMA-402 matches an identifier ASCII-case-insensitively, so `utc`
- *   and `america/new_york` name the same zones as `UTC` and `America/New_York`.
+ *   and `asia/kolkata` name the same zones as `UTC` and `Asia/Kolkata`.
  * - SHAPE ONLY. Whether the name exists is decided by Temporal: its only consumer,
  *   `isValidTimeZone`, also requires `Temporal.ZonedDateTime.from` to accept the zone.
  *
  * @example timeZoneLike.test("UTC")              // true
- * @example timeZoneLike.test("America/New_York") // true
+ * @example timeZoneLike.test("Asia/Kolkata")     // true
  * @example timeZoneLike.test("Japan")            // true (single-component IANA link)
  * @example timeZoneLike.test("Etc/GMT+5")        // true
  * @example timeZoneLike.test("Custom/Zone")      // true (shape only; existence is not checked)

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

@@ -1,11 +1,12 @@
 /**
  * RegExp matching the shape of a time zone identifier: Temporal's `TimeZoneIdentifier` grammar
- * (§14.6.2 Time Zone Identifiers), `UTCOffset[~SubMinutePrecision] | TimeZoneIANAName`.
+ * (§13.31, the ISO 8601 / RFC 9557 grammar),
+ * `TimeZoneIdentifier ::: UTCOffset[~SubMinutePrecision] | TimeZoneIANAName`.
  *
  * - An offset identifier (`UTCOffset[~SubMinutePrecision]`): an ASCII sign and a two-digit hour
  *   `00`–`23`, optionally followed by two minute digits `00`–`59`, with or without `:` (`+05`,
  *   `+0530`, `-08:00`). No seconds and no fraction. `Intl.DateTimeFormat` accepts the same
- *   offsets (ECMA-402 `IsTimeZoneOffsetString`).
+ *   offsets (ECMA-262 `IsTimeZoneOffsetString`, which ECMA-402 calls).
  * - An IANA name (`TimeZoneIANAName`): one or more `/`-separated components. Each starts with a
  *   letter, `.` or `_` (`TZLeadingChar`) and continues with letters, digits, `.`, `_`, `-` or `+`
  *   (`TZChar`). So single-component names match (`UTC`, `Japan`, `Zulu`, `EST5EDT`, `GMT+0`,
@@ -13,12 +14,12 @@
  *   `Etc/GMT+5`). Temporal must accept every Zone and Link name in the IANA database, and tzdb's
  *   `backward` file has more than forty slash-less ones.
  * - Letter case is not checked: ECMA-402 matches an identifier ASCII-case-insensitively, so `utc`
- *   and `america/new_york` name the same zones as `UTC` and `America/New_York`.
+ *   and `asia/kolkata` name the same zones as `UTC` and `Asia/Kolkata`.
  * - SHAPE ONLY. Whether the name exists is decided by Temporal: its only consumer,
  *   `isValidTimeZone`, also requires `Temporal.ZonedDateTime.from` to accept the zone.
  *
  * @example timeZoneLike.test("UTC")              // true
- * @example timeZoneLike.test("America/New_York") // true
+ * @example timeZoneLike.test("Asia/Kolkata")     // true
  * @example timeZoneLike.test("Japan")            // true (single-component IANA link)
  * @example timeZoneLike.test("Etc/GMT+5")        // true
  * @example timeZoneLike.test("Custom/Zone")      // true (shape only; existence is not checked)

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

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

package/dist/regex/utc-offset.js

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

package/dist/span/calculate/spanMs.d.ts

@@ -39,7 +39,8 @@
  * - Leap seconds are not counted. UTC repeats a second rather than numbering a 61st one, so
  *   a span across one is a second short of the physical elapsed time; against a smeared
  *   clock (Google, AWS, Meta) the error is up to a second spread over the smear window.
- *   Leap-second-exact spans need a TAI scale, which GMT does not yet ship.
+ *   For a leap-second-exact span, convert both ends with `toTAI` or add
+ *   `leapSecondsBetween(start, end)` seconds, both from `timescale/`.
  *
  * @param start ISO 8601 instant string the span is measured from
  * @param end ISO 8601 instant string the span is measured to
@@ -49,8 +50,8 @@
  * @example spanMs("2024-03-10T12:00:01Z", "2024-03-10T12:00:00Z") // -1000
  * @example spanMs("2024-03-10T12:00:00Z", "2024-03-10T12:00:00Z") // 0
  * @example spanMs("2024-03-10T12:00:00Z", "2024-03-10T12:00:00.123456789Z") // 123.456789
- * @example spanMs("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 82800000 — 23 hours, not 24
- * @example spanMs("2024-03-10T12:00:00+05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 32400000 — offsets decide, the zone is not checked
+ * @example spanMs("2024-03-30T12:00:00+00:00[Europe/London]", "2024-03-31T12:00:00+01:00[Europe/London]") // 82800000 — 23 hours, not 24
+ * @example spanMs("2024-03-10T12:00:00+05:00[Asia/Tokyo]", "2024-03-10T12:00:00-04:00[Asia/Tokyo]") // 32400000 — offsets decide, the zone is not checked
  * @example spanMs("1960-01-01T01:04:30Z", "1960-01-01T00:20:00-00:45[Africa/Monrovia]") // 0 — the zone's −00:44:30, which `-00:45` rounds
  * @example spanMs("-271821-04-20T00:00:00Z", "+275760-09-13T00:00:00Z") // null — past the safe integer range, use spanNs
  * @example spanMs("2024-03-10T12:00:00Z", "invalid") // null

package/dist/span/calculate/spanMs.js

@@ -51,7 +51,8 @@ const MAX_SAFE_NANOSECONDS = BigInt(Number.MAX_SAFE_INTEGER) * NANOSECONDS_PER_M
  * - Leap seconds are not counted. UTC repeats a second rather than numbering a 61st one, so
  *   a span across one is a second short of the physical elapsed time; against a smeared
  *   clock (Google, AWS, Meta) the error is up to a second spread over the smear window.
- *   Leap-second-exact spans need a TAI scale, which GMT does not yet ship.
+ *   For a leap-second-exact span, convert both ends with `toTAI` or add
+ *   `leapSecondsBetween(start, end)` seconds, both from `timescale/`.
  *
  * @param start ISO 8601 instant string the span is measured from
  * @param end ISO 8601 instant string the span is measured to
@@ -61,8 +62,8 @@ const MAX_SAFE_NANOSECONDS = BigInt(Number.MAX_SAFE_INTEGER) * NANOSECONDS_PER_M
  * @example spanMs("2024-03-10T12:00:01Z", "2024-03-10T12:00:00Z") // -1000
  * @example spanMs("2024-03-10T12:00:00Z", "2024-03-10T12:00:00Z") // 0
  * @example spanMs("2024-03-10T12:00:00Z", "2024-03-10T12:00:00.123456789Z") // 123.456789
- * @example spanMs("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 82800000 — 23 hours, not 24
- * @example spanMs("2024-03-10T12:00:00+05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 32400000 — offsets decide, the zone is not checked
+ * @example spanMs("2024-03-30T12:00:00+00:00[Europe/London]", "2024-03-31T12:00:00+01:00[Europe/London]") // 82800000 — 23 hours, not 24
+ * @example spanMs("2024-03-10T12:00:00+05:00[Asia/Tokyo]", "2024-03-10T12:00:00-04:00[Asia/Tokyo]") // 32400000 — offsets decide, the zone is not checked
  * @example spanMs("1960-01-01T01:04:30Z", "1960-01-01T00:20:00-00:45[Africa/Monrovia]") // 0 — the zone's −00:44:30, which `-00:45` rounds
  * @example spanMs("-271821-04-20T00:00:00Z", "+275760-09-13T00:00:00Z") // null — past the safe integer range, use spanNs
  * @example spanMs("2024-03-10T12:00:00Z", "invalid") // null

package/dist/span/calculate/spanNs.d.ts

@@ -31,7 +31,8 @@
  * - Leap seconds are not counted. UTC repeats a second rather than numbering a 61st one, so
  *   a span across one is a second short of the physical elapsed time; against a smeared
  *   clock (Google, AWS, Meta) the error is up to a second spread over the smear window.
- *   Leap-second-exact spans need a TAI scale, which GMT does not yet ship.
+ *   For a leap-second-exact span, convert both ends with `toTAI` or add
+ *   `leapSecondsBetween(start, end)` seconds, both from `timescale/`.
  *
  * @param start ISO 8601 instant string the span is measured from
  * @param end ISO 8601 instant string the span is measured to
@@ -41,8 +42,8 @@
  * @example spanNs("2024-03-10T12:00:01Z", "2024-03-10T12:00:00Z") // -1000000000n
  * @example spanNs("2024-03-10T12:00:00Z", "2024-03-10T12:00:00Z") // 0n
  * @example spanNs("2024-03-10T12:00:00.123456789Z", "2024-03-10T12:00:00.123456790Z") // 1n
- * @example spanNs("2024-03-10T07:00:00-05:00[America/New_York]", "2024-03-10T12:00:00Z") // 0n — same instant, different zones
- * @example spanNs("2024-03-10T12:00:00+05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 32400000000000n — offsets decide, the zone is not checked
+ * @example spanNs("2024-03-10T07:00:00-05:00[America/Bogota]", "2024-03-10T12:00:00Z") // 0n — same instant, different zones
+ * @example spanNs("2024-03-10T12:00:00+05:00[Asia/Tokyo]", "2024-03-10T12:00:00-04:00[Asia/Tokyo]") // 32400000000000n — offsets decide, the zone is not checked
  * @example spanNs("1960-01-01T01:04:30Z", "1960-01-01T00:20:00-00:45[Africa/Monrovia]") // 0n — the zone's −00:44:30, which `-00:45` rounds
  * @example spanNs("2024-03-10T12:00:00Z", "invalid") // null
  */

package/dist/span/calculate/spanNs.js

@@ -32,7 +32,8 @@ import { parseInstantNanoseconds } from "../../internal/index.js";
  * - Leap seconds are not counted. UTC repeats a second rather than numbering a 61st one, so
  *   a span across one is a second short of the physical elapsed time; against a smeared
  *   clock (Google, AWS, Meta) the error is up to a second spread over the smear window.
- *   Leap-second-exact spans need a TAI scale, which GMT does not yet ship.
+ *   For a leap-second-exact span, convert both ends with `toTAI` or add
+ *   `leapSecondsBetween(start, end)` seconds, both from `timescale/`.
  *
  * @param start ISO 8601 instant string the span is measured from
  * @param end ISO 8601 instant string the span is measured to
@@ -42,8 +43,8 @@ import { parseInstantNanoseconds } from "../../internal/index.js";
  * @example spanNs("2024-03-10T12:00:01Z", "2024-03-10T12:00:00Z") // -1000000000n
  * @example spanNs("2024-03-10T12:00:00Z", "2024-03-10T12:00:00Z") // 0n
  * @example spanNs("2024-03-10T12:00:00.123456789Z", "2024-03-10T12:00:00.123456790Z") // 1n
- * @example spanNs("2024-03-10T07:00:00-05:00[America/New_York]", "2024-03-10T12:00:00Z") // 0n — same instant, different zones
- * @example spanNs("2024-03-10T12:00:00+05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 32400000000000n — offsets decide, the zone is not checked
+ * @example spanNs("2024-03-10T07:00:00-05:00[America/Bogota]", "2024-03-10T12:00:00Z") // 0n — same instant, different zones
+ * @example spanNs("2024-03-10T12:00:00+05:00[Asia/Tokyo]", "2024-03-10T12:00:00-04:00[Asia/Tokyo]") // 32400000000000n — offsets decide, the zone is not checked
  * @example spanNs("1960-01-01T01:04:30Z", "1960-01-01T00:20:00-00:45[Africa/Monrovia]") // 0n — the zone's −00:44:30, which `-00:45` rounds
  * @example spanNs("2024-03-10T12:00:00Z", "invalid") // null
  */

package/dist/span/calculate/spanWallClock.d.ts

@@ -28,8 +28,8 @@ export type WallClockSpanUnit = "days" | "hours" | "day" | "hour";
  *   The wall clock is read straight off the string with `Temporal.PlainDateTime.from`. Going
  *   via `ZonedDateTime` would be a local → instant → local round trip, and that round trip is
  *   lossy at exactly the DST edges this function exists to get right: an offset-less
- *   `"2024-03-10T02:30:00[America/New_York]"` names a wall time that never occurred, and
- *   Temporal's default `compatible` disambiguation would silently advance it to `03:30`,
+ *   `"2024-03-31T01:30:00[Europe/London]"` names a wall time that never occurred, and
+ *   Temporal's default `compatible` disambiguation would silently advance it to `02:30`,
  *   turning a 24-hour answer into 23. A nonexistent or ambiguous local time is measured as
  *   written instead — for a clock-face question, the digits in the string *are* the answer.
  * - Requires a bracketed IANA time zone on both endpoints, as `isValidZonedDateTime` does —
@@ -38,8 +38,8 @@ export type WallClockSpanUnit = "days" | "hours" | "day" | "hour";
  *   `[u-ca=...]` calendar annotations are rejected; `days` and `hours` mean the same thing in
  *   every calendar system, so the annotation would change nothing.
  * - The endpoints need not share a zone. When they differ, this is the distance between two
- *   local wall clocks — a flight leaving New York at 23:00 and landing in Berlin at 11:00 the
- *   next local day is 12 wall-clock hours, and 7 elapsed hours by `spanMs`.
+ *   local wall clocks — a flight leaving São Paulo at 23:00 and landing in Berlin at 15:00 the
+ *   next local day is 16 wall-clock hours, and 12 elapsed hours by `spanMs`.
  * - Returns `null` on invalid input, not `0` — `0` is the span between a wall time and itself.
  *
  * @param start zoned ISO 8601 datetime string the span is measured from
@@ -47,14 +47,14 @@ export type WallClockSpanUnit = "days" | "hours" | "day" | "hour";
  * @param unit "days" or "hours" (or the singular "day" or "hour") of wall-clock distance
  * @returns whole wall-clock units, negative when start is after end, or null on invalid input
  *
- * @example spanWallClock("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]", "hours") // 24 — spanMs reports 82800000 (23 hours)
- * @example spanWallClock("2024-11-02T12:00:00-04:00[America/New_York]", "2024-11-03T12:00:00-05:00[America/New_York]", "days") // 1 — spanMs reports 90000000 (25 hours)
- * @example spanWallClock("2024-03-01T12:00:00-05:00[America/New_York]", "2024-03-02T18:00:00-05:00[America/New_York]", "days") // 1 — truncated toward zero
- * @example spanWallClock("2024-03-02T18:00:00-05:00[America/New_York]", "2024-03-01T12:00:00-05:00[America/New_York]", "hours") // -30
- * @example spanWallClock("2024-03-10T23:00:00-04:00[America/New_York]", "2024-03-11T11:00:00+01:00[Europe/Berlin]", "hours") // 12 — each endpoint's own wall clock
- * @example spanWallClock("2024-03-10T02:30:00[America/New_York]", "2024-03-11T02:30:00[America/New_York]", "hours") // 24 — a wall time that never occurred is measured as written
- * @example spanWallClock("2024-03-01T12:00:00-05:00[America/New_York]", "2024-03-02T12:00:00-05:00[America/New_York]", "day") // 1 — singular unit name
+ * @example spanWallClock("2024-03-30T12:00:00+00:00[Europe/London]", "2024-03-31T12:00:00+01:00[Europe/London]", "hours") // 24 — spanMs reports 82800000 (23 hours)
+ * @example spanWallClock("2024-04-06T12:00:00+11:00[Australia/Sydney]", "2024-04-07T12:00:00+10:00[Australia/Sydney]", "days") // 1 — spanMs reports 90000000 (25 hours)
+ * @example spanWallClock("2024-03-01T12:00:00+05:30[Asia/Kolkata]", "2024-03-02T18:00:00+05:30[Asia/Kolkata]", "days") // 1 — truncated toward zero
+ * @example spanWallClock("2024-03-02T18:00:00+05:30[Asia/Kolkata]", "2024-03-01T12:00:00+05:30[Asia/Kolkata]", "hours") // -30
+ * @example spanWallClock("2024-03-10T23:00:00-03:00[America/Sao_Paulo]", "2024-03-11T15:00:00+01:00[Europe/Berlin]", "hours") // 16 — each endpoint's own wall clock
+ * @example spanWallClock("2024-03-31T01:30:00[Europe/London]", "2024-04-01T01:30:00[Europe/London]", "hours") // 24 — a wall time that never occurred is measured as written
+ * @example spanWallClock("2024-03-01T12:00:00+02:00[Africa/Johannesburg]", "2024-03-02T12:00:00+02:00[Africa/Johannesburg]", "day") // 1 — singular unit name
  * @example spanWallClock("2024-03-10T12:00:00Z", "2024-03-11T12:00:00Z", "days") // null — no bracketed time zone
- * @example spanWallClock("2024-03-01T12:00:00-05:00[America/New_York]", "2024-03-02T12:00:00-05:00[America/New_York]", "minutes") // null
+ * @example spanWallClock("2024-03-01T12:00:00+02:00[Africa/Johannesburg]", "2024-03-02T12:00:00+02:00[Africa/Johannesburg]", "minutes") // null
  */
 export declare function spanWallClock(start: string, end: string, unit: WallClockSpanUnit): number | null;

package/dist/span/calculate/spanWallClock.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { isValidZonedDateTime } from "../../zoned/validate/index.js";
 const WALL_CLOCK_SPAN_UNITS = {
     days: "day",
@@ -26,8 +26,8 @@ const WALL_CLOCK_SPAN_UNITS = {
  *   The wall clock is read straight off the string with `Temporal.PlainDateTime.from`. Going
  *   via `ZonedDateTime` would be a local → instant → local round trip, and that round trip is
  *   lossy at exactly the DST edges this function exists to get right: an offset-less
- *   `"2024-03-10T02:30:00[America/New_York]"` names a wall time that never occurred, and
- *   Temporal's default `compatible` disambiguation would silently advance it to `03:30`,
+ *   `"2024-03-31T01:30:00[Europe/London]"` names a wall time that never occurred, and
+ *   Temporal's default `compatible` disambiguation would silently advance it to `02:30`,
  *   turning a 24-hour answer into 23. A nonexistent or ambiguous local time is measured as
  *   written instead — for a clock-face question, the digits in the string *are* the answer.
  * - Requires a bracketed IANA time zone on both endpoints, as `isValidZonedDateTime` does —
@@ -36,8 +36,8 @@ const WALL_CLOCK_SPAN_UNITS = {
  *   `[u-ca=...]` calendar annotations are rejected; `days` and `hours` mean the same thing in
  *   every calendar system, so the annotation would change nothing.
  * - The endpoints need not share a zone. When they differ, this is the distance between two
- *   local wall clocks — a flight leaving New York at 23:00 and landing in Berlin at 11:00 the
- *   next local day is 12 wall-clock hours, and 7 elapsed hours by `spanMs`.
+ *   local wall clocks — a flight leaving São Paulo at 23:00 and landing in Berlin at 15:00 the
+ *   next local day is 16 wall-clock hours, and 12 elapsed hours by `spanMs`.
  * - Returns `null` on invalid input, not `0` — `0` is the span between a wall time and itself.
  *
  * @param start zoned ISO 8601 datetime string the span is measured from
@@ -45,15 +45,15 @@ const WALL_CLOCK_SPAN_UNITS = {
  * @param unit "days" or "hours" (or the singular "day" or "hour") of wall-clock distance
  * @returns whole wall-clock units, negative when start is after end, or null on invalid input
  *
- * @example spanWallClock("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]", "hours") // 24 — spanMs reports 82800000 (23 hours)
- * @example spanWallClock("2024-11-02T12:00:00-04:00[America/New_York]", "2024-11-03T12:00:00-05:00[America/New_York]", "days") // 1 — spanMs reports 90000000 (25 hours)
- * @example spanWallClock("2024-03-01T12:00:00-05:00[America/New_York]", "2024-03-02T18:00:00-05:00[America/New_York]", "days") // 1 — truncated toward zero
- * @example spanWallClock("2024-03-02T18:00:00-05:00[America/New_York]", "2024-03-01T12:00:00-05:00[America/New_York]", "hours") // -30
- * @example spanWallClock("2024-03-10T23:00:00-04:00[America/New_York]", "2024-03-11T11:00:00+01:00[Europe/Berlin]", "hours") // 12 — each endpoint's own wall clock
- * @example spanWallClock("2024-03-10T02:30:00[America/New_York]", "2024-03-11T02:30:00[America/New_York]", "hours") // 24 — a wall time that never occurred is measured as written
- * @example spanWallClock("2024-03-01T12:00:00-05:00[America/New_York]", "2024-03-02T12:00:00-05:00[America/New_York]", "day") // 1 — singular unit name
+ * @example spanWallClock("2024-03-30T12:00:00+00:00[Europe/London]", "2024-03-31T12:00:00+01:00[Europe/London]", "hours") // 24 — spanMs reports 82800000 (23 hours)
+ * @example spanWallClock("2024-04-06T12:00:00+11:00[Australia/Sydney]", "2024-04-07T12:00:00+10:00[Australia/Sydney]", "days") // 1 — spanMs reports 90000000 (25 hours)
+ * @example spanWallClock("2024-03-01T12:00:00+05:30[Asia/Kolkata]", "2024-03-02T18:00:00+05:30[Asia/Kolkata]", "days") // 1 — truncated toward zero
+ * @example spanWallClock("2024-03-02T18:00:00+05:30[Asia/Kolkata]", "2024-03-01T12:00:00+05:30[Asia/Kolkata]", "hours") // -30
+ * @example spanWallClock("2024-03-10T23:00:00-03:00[America/Sao_Paulo]", "2024-03-11T15:00:00+01:00[Europe/Berlin]", "hours") // 16 — each endpoint's own wall clock
+ * @example spanWallClock("2024-03-31T01:30:00[Europe/London]", "2024-04-01T01:30:00[Europe/London]", "hours") // 24 — a wall time that never occurred is measured as written
+ * @example spanWallClock("2024-03-01T12:00:00+02:00[Africa/Johannesburg]", "2024-03-02T12:00:00+02:00[Africa/Johannesburg]", "day") // 1 — singular unit name
  * @example spanWallClock("2024-03-10T12:00:00Z", "2024-03-11T12:00:00Z", "days") // null — no bracketed time zone
- * @example spanWallClock("2024-03-01T12:00:00-05:00[America/New_York]", "2024-03-02T12:00:00-05:00[America/New_York]", "minutes") // null
+ * @example spanWallClock("2024-03-01T12:00:00+02:00[Africa/Johannesburg]", "2024-03-02T12:00:00+02:00[Africa/Johannesburg]", "minutes") // null
  */
 export function spanWallClock(start, end, unit) {
     if (typeof unit !== "string") {

package/dist/span/index.d.ts

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

package/dist/span/index.js

@@ -1,4 +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 "./calculate/index.js";
 export * from "./validate/index.js";

package/dist/span/validate/isValidSpan.d.ts

@@ -33,10 +33,10 @@
  * @example isValidSpan("2024-03-10T12:00:00Z", "2024-03-10T12:00:01Z") // true
  * @example isValidSpan("2024-03-10T12:00:00Z", "2024-03-10T12:00:00Z") // true — a zero span is a span
  * @example isValidSpan("2024-03-10T12:00:01Z", "2024-03-10T12:00:00Z") // true — spans are signed
- * @example isValidSpan("2024-03-10T07:00:00-05:00[America/New_York]", "2024-03-10T12:00:00Z") // true
- * @example isValidSpan("2024-03-10T12:00:00+05:00[America/New_York]", "2024-03-10T12:00:00Z[Not/AZone]") // true — zone annotations are not checked
+ * @example isValidSpan("2024-03-10T07:00:00-05:00[America/Bogota]", "2024-03-10T12:00:00Z") // true
+ * @example isValidSpan("2024-03-10T12:00:00+05:00[Asia/Tokyo]", "2024-03-10T12:00:00Z[Not/AZone]") // true — zone annotations are not checked
  * @example isValidSpan("-271821-04-20T00:00:00Z", "+275760-09-13T00:00:00Z") // true — but spanMs returns null, use spanNs
  * @example isValidSpan("2024-03-10T12:00:00Z", "invalid") // false
- * @example isValidSpan("2024-03-10T12:00:00[America/New_York]", "2024-03-11T12:00:00[America/New_York]") // false — no offset designator
+ * @example isValidSpan("2024-03-10T12:00:00[Europe/London]", "2024-03-11T12:00:00[Europe/London]") // false — no offset designator
  */
 export declare function isValidSpan(start: string, end: string): boolean;

package/dist/span/validate/isValidSpan.js

@@ -34,11 +34,11 @@ import { parseInstantNanoseconds } from "../../internal/index.js";
  * @example isValidSpan("2024-03-10T12:00:00Z", "2024-03-10T12:00:01Z") // true
  * @example isValidSpan("2024-03-10T12:00:00Z", "2024-03-10T12:00:00Z") // true — a zero span is a span
  * @example isValidSpan("2024-03-10T12:00:01Z", "2024-03-10T12:00:00Z") // true — spans are signed
- * @example isValidSpan("2024-03-10T07:00:00-05:00[America/New_York]", "2024-03-10T12:00:00Z") // true
- * @example isValidSpan("2024-03-10T12:00:00+05:00[America/New_York]", "2024-03-10T12:00:00Z[Not/AZone]") // true — zone annotations are not checked
+ * @example isValidSpan("2024-03-10T07:00:00-05:00[America/Bogota]", "2024-03-10T12:00:00Z") // true
+ * @example isValidSpan("2024-03-10T12:00:00+05:00[Asia/Tokyo]", "2024-03-10T12:00:00Z[Not/AZone]") // true — zone annotations are not checked
  * @example isValidSpan("-271821-04-20T00:00:00Z", "+275760-09-13T00:00:00Z") // true — but spanMs returns null, use spanNs
  * @example isValidSpan("2024-03-10T12:00:00Z", "invalid") // false
- * @example isValidSpan("2024-03-10T12:00:00[America/New_York]", "2024-03-11T12:00:00[America/New_York]") // false — no offset designator
+ * @example isValidSpan("2024-03-10T12:00:00[Europe/London]", "2024-03-11T12:00:00[Europe/London]") // false — no offset designator
  */
 export function isValidSpan(start, end) {
     return (parseInstantNanoseconds(start) !== null &&

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

@@ -0,0 +1,3 @@
+export * from "./leapSecondsBetween.js";
+export * from "./nextLeapSecond.js";
+export * from "./taiMinusUtc.js";

package/dist/timescale/calculate/index.js

@@ -0,0 +1,3 @@
+export * from "./leapSecondsBetween.js";
+export * from "./nextLeapSecond.js";
+export * from "./taiMinusUtc.js";

package/dist/timescale/calculate/leapSecondsBetween.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Return how many leap seconds start between two UTC instants, signed.
+ *
+ * - From the IERS leap-second table built into GMT (Leap_Second.dat through Bulletin C 72,
+ *   6 July 2026). The table is closed: after the last insertion (2016-12-31) there are none.
+ * - Counts each leap second whose second starts in `[start, end)`. An inserted second starts at
+ *   `…T23:59:60.000Z` (ITU-R TF.460-6 Annex 1 §2.2): from `…T23:59:60Z` to the next
+ *   `…T00:00:00Z` is 1; from `…T23:59:59Z` to `…T23:59:60Z` is 0; from `…T23:59:60.5Z` to the
+ *   next `…T00:00:00Z` is 0.
+ * - Over whole days this is the change in TAI − UTC (`taiMinusUtc`). Inside an inserted second
+ *   the two differ: TAI − UTC changes at 00:00:00, the count at 23:59:60.000.
+ * - Signed: negative when `end` is before `start`.
+ * - `null` when either instant is before 1972-01-01 or invalid.
+ *
+ * @param start ISO 8601 instant string
+ * @param end ISO 8601 instant string
+ * @returns the signed count, or null on invalid input or a date before 1972
+ *
+ * @example leapSecondsBetween("2020-01-01T00:00:00Z", "2024-01-01T00:00:00Z") // 0
+ * @example leapSecondsBetween("2000-01-01T00:00:00Z", "2024-01-01T00:00:00Z") // 5
+ * @example leapSecondsBetween("2024-01-01T00:00:00Z", "2000-01-01T00:00:00Z") // -5
+ * @example leapSecondsBetween("2016-12-31T23:59:60Z", "2017-01-01T00:00:00Z") // 1
+ * @example leapSecondsBetween("2016-12-31T23:59:60.5Z", "2017-01-01T00:00:00Z") // 0 — it started at 23:59:60.000
+ * @example leapSecondsBetween("1971-01-01T00:00:00Z", "2024-01-01T00:00:00Z") // null
+ */
+export declare function leapSecondsBetween(start: string, end: string): number | null;

package/dist/timescale/calculate/leapSecondsBetween.js

@@ -0,0 +1,62 @@
+import { LEAP_SECOND_STEPS, NANOSECONDS_PER_SECOND, parseUtcReading, taiOfUtc, } from "../../internal/index.js";
+/**
+ * The leap seconds that started before a UTC instant, as a running count: TAI − UTC there, plus
+ * 1 when the instant is inside an inserted second past its start. The inserted second begins at
+ * 23:59:60.000 (ITU-R TF.460-6 Annex 1 §2.2), while TAI − UTC steps only at the next 00:00:00.
+ *
+ * @param isoString ISO 8601 instant string
+ * @returns the count in seconds, or null where `taiMinusUtc` is null
+ */
+function leapSecondsStartedBefore(isoString) {
+    const reading = parseUtcReading(isoString);
+    if (reading === null) {
+        return null;
+    }
+    const tai = taiOfUtc(LEAP_SECOND_STEPS, reading);
+    if (tai === null) {
+        return null;
+    }
+    const taiMinusUtcSeconds = Number((tai - reading.epochNanoseconds) / NANOSECONDS_PER_SECOND) -
+        (reading.secondSixty ? 1 : 0);
+    const insideInsertedSecond = reading.secondSixty &&
+        reading.epochNanoseconds % NANOSECONDS_PER_SECOND !== 0n;
+    return taiMinusUtcSeconds + (insideInsertedSecond ? 1 : 0);
+}
+/**
+ * Return how many leap seconds start between two UTC instants, signed.
+ *
+ * - From the IERS leap-second table built into GMT (Leap_Second.dat through Bulletin C 72,
+ *   6 July 2026). The table is closed: after the last insertion (2016-12-31) there are none.
+ * - Counts each leap second whose second starts in `[start, end)`. An inserted second starts at
+ *   `…T23:59:60.000Z` (ITU-R TF.460-6 Annex 1 §2.2): from `…T23:59:60Z` to the next
+ *   `…T00:00:00Z` is 1; from `…T23:59:59Z` to `…T23:59:60Z` is 0; from `…T23:59:60.5Z` to the
+ *   next `…T00:00:00Z` is 0.
+ * - Over whole days this is the change in TAI − UTC (`taiMinusUtc`). Inside an inserted second
+ *   the two differ: TAI − UTC changes at 00:00:00, the count at 23:59:60.000.
+ * - Signed: negative when `end` is before `start`.
+ * - `null` when either instant is before 1972-01-01 or invalid.
+ *
+ * @param start ISO 8601 instant string
+ * @param end ISO 8601 instant string
+ * @returns the signed count, or null on invalid input or a date before 1972
+ *
+ * @example leapSecondsBetween("2020-01-01T00:00:00Z", "2024-01-01T00:00:00Z") // 0
+ * @example leapSecondsBetween("2000-01-01T00:00:00Z", "2024-01-01T00:00:00Z") // 5
+ * @example leapSecondsBetween("2024-01-01T00:00:00Z", "2000-01-01T00:00:00Z") // -5
+ * @example leapSecondsBetween("2016-12-31T23:59:60Z", "2017-01-01T00:00:00Z") // 1
+ * @example leapSecondsBetween("2016-12-31T23:59:60.5Z", "2017-01-01T00:00:00Z") // 0 — it started at 23:59:60.000
+ * @example leapSecondsBetween("1971-01-01T00:00:00Z", "2024-01-01T00:00:00Z") // null
+ */
+export function leapSecondsBetween(start, end) {
+    try {
+        const before = leapSecondsStartedBefore(start);
+        const after = leapSecondsStartedBefore(end);
+        if (before === null || after === null) {
+            return null;
+        }
+        return after - before;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/timescale/calculate/nextLeapSecond.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Return the first leap second after a UTC instant, as its UTC label `…T23:59:60Z`.
+ *
+ * - From the IERS leap-second table built into GMT (Leap_Second.dat through Bulletin C 72,
+ *   6 July 2026).
+ * - `""` for every instant from 2016-12-31T23:59:60Z on: there are no more. The table is closed
+ *   (continuous UTC from 20 May 2027, CGPM 2026).
+ * - `""` also on invalid input or a date before 1972; check with `isValidInstant` to tell them apart.
+ *
+ * @param isoString ISO 8601 instant string
+ * @returns the next leap second's UTC label, or "" when there is none or on invalid input
+ *
+ * @example nextLeapSecond("2016-01-01T00:00:00Z") // "2016-12-31T23:59:60Z"
+ * @example nextLeapSecond("1999-08-22T00:00:00Z") // "2005-12-31T23:59:60Z"
+ * @example nextLeapSecond("2016-12-31T23:59:60Z") // ""
+ * @example nextLeapSecond("2024-01-01T00:00:00Z") // ""
+ */
+export declare function nextLeapSecond(isoString: string): string;

package/dist/timescale/calculate/nextLeapSecond.js

@@ -0,0 +1,33 @@
+import { formatUtcReading, LEAP_SECOND_STEPS, nextStepIndex, parseUtcReading, stepReading, taiOfUtc, } from "../../internal/index.js";
+/**
+ * Return the first leap second after a UTC instant, as its UTC label `…T23:59:60Z`.
+ *
+ * - From the IERS leap-second table built into GMT (Leap_Second.dat through Bulletin C 72,
+ *   6 July 2026).
+ * - `""` for every instant from 2016-12-31T23:59:60Z on: there are no more. The table is closed
+ *   (continuous UTC from 20 May 2027, CGPM 2026).
+ * - `""` also on invalid input or a date before 1972; check with `isValidInstant` to tell them apart.
+ *
+ * @param isoString ISO 8601 instant string
+ * @returns the next leap second's UTC label, or "" when there is none or on invalid input
+ *
+ * @example nextLeapSecond("2016-01-01T00:00:00Z") // "2016-12-31T23:59:60Z"
+ * @example nextLeapSecond("1999-08-22T00:00:00Z") // "2005-12-31T23:59:60Z"
+ * @example nextLeapSecond("2016-12-31T23:59:60Z") // ""
+ * @example nextLeapSecond("2024-01-01T00:00:00Z") // ""
+ */
+export function nextLeapSecond(isoString) {
+    try {
+        const reading = parseUtcReading(isoString);
+        if (reading === null || taiOfUtc(LEAP_SECOND_STEPS, reading) === null) {
+            return "";
+        }
+        const index = nextStepIndex(LEAP_SECOND_STEPS, reading);
+        return index === -1
+            ? ""
+            : formatUtcReading(stepReading(LEAP_SECOND_STEPS, index));
+    }
+    catch {
+        return "";
+    }
+}

package/dist/timescale/calculate/taiMinusUtc.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Return TAI − UTC, in whole seconds, at a UTC instant.
+ *
+ * - From the IERS leap-second table built into GMT (Leap_Second.dat through Bulletin C 72,
+ *   6 July 2026): 10 s from 1972-01-01, 37 s from 2017-01-01 on. The table is closed
+ *   (continuous UTC from 20 May 2027, CGPM 2026), so 37 holds for every later date.
+ * - At an inserted leap second (`…T23:59:60Z`, accepted only on the 27 listed days) the value is
+ *   the one before the insertion: TAI − UTC changes at 00:00:00 UTC.
+ * - `null` before 1972-01-01 (TAI − UTC was then fractional with a daily rate term), for a
+ *   second-60 string on a day with no insertion, and on invalid input.
+ *
+ * @param isoString ISO 8601 instant string; a listed leap second (`…T23:59:60Z`) is accepted
+ * @returns TAI − UTC in seconds, or null on invalid input or a date before 1972
+ *
+ * @example taiMinusUtc("2024-01-01T00:00:00Z") // 37
+ * @example taiMinusUtc("2016-01-01T00:00:00Z") // 36
+ * @example taiMinusUtc("2016-12-31T23:59:60Z") // 36 — the inserted second
+ * @example taiMinusUtc("2100-01-01T00:00:00Z") // 37
+ * @example taiMinusUtc("1971-01-01T00:00:00Z") // null — before 1972
+ */
+export declare function taiMinusUtc(isoString: string): number | null;