@northguild/gmt 1.18.0 → 1.20.0

package/dist/internal/inputChecks.d.ts

@@ -0,0 +1,53 @@
+import type { RollConvention } from "../types/index.js";
+/** The cores of the `isValid*` functions, so a public function never calls another. */
+/**
+ * The check behind `isValidTimeZone`: an IANA name or a UTC offset to the minute. A pass is
+ * remembered, so a repeat builds nothing.
+ *
+ * @param timeZone the candidate
+ * @returns whether it names a zone
+ *
+ * @example isZoneId("Europe/London") // true
+ * @example isZoneId("Not/AZone") // false
+ */
+export declare function isZoneId(timeZone: unknown): boolean;
+/**
+ * The check behind `isValidTime`: a plain ISO 8601 time of day.
+ *
+ * @param value the candidate string
+ * @returns whether Temporal reads it as a `PlainTime` and it has the strict shape
+ *
+ * @example isTimeString("17:00") // true
+ * @example isTimeString("25:00") // false
+ */
+export declare function isTimeString(value: string): boolean;
+/**
+ * The check behind `isValidDate`: a plain ISO 8601 calendar date.
+ *
+ * @param value the candidate string
+ * @returns whether Temporal reads it as an ISO calendar `PlainDate` and it has the strict shape
+ *
+ * @example isDateString("2024-02-29") // true
+ * @example isDateString("2024-02-30") // false
+ */
+export declare function isDateString(value: string): boolean;
+/**
+ * The check behind `isValidDuration`: an ISO 8601 duration string.
+ *
+ * @param value the candidate
+ * @returns whether it is a string Temporal reads as a `Duration`
+ *
+ * @example isDurationString("P1DT2H") // true
+ * @example isDurationString("2 days") // false
+ */
+export declare function isDurationString(value: unknown): boolean;
+/**
+ * The check behind `isValidRollConvention`: membership in the roll set.
+ *
+ * @param convention the candidate
+ * @returns whether it is one of the six conventions
+ *
+ * @example isRollConventionName("following") // true
+ * @example isRollConventionName("nearest") // false
+ */
+export declare function isRollConventionName(convention: unknown): convention is RollConvention;

package/dist/internal/inputChecks.js

@@ -0,0 +1,132 @@
+import { Temporal } from "./temporal.js";
+import { isoStringBody } from "./isoStringBody.js";
+import { isRememberedZone, rememberZone } from "./validatedZones.js";
+import { hasSecond60 } from "../plain/validate/hasSecond60.js";
+import { plainDate, plainTime, timeZoneLike } from "../regex/index.js";
+/** The cores of the `isValid*` functions, so a public function never calls another. */
+/**
+ * The check behind `isValidTimeZone`: an IANA name or a UTC offset to the minute. A pass is
+ * remembered, so a repeat builds nothing.
+ *
+ * @param timeZone the candidate
+ * @returns whether it names a zone
+ *
+ * @example isZoneId("Europe/London") // true
+ * @example isZoneId("Not/AZone") // false
+ */
+export function isZoneId(timeZone) {
+    if (typeof timeZone === "string" && isRememberedZone(timeZone)) {
+        return true;
+    }
+    try {
+        // The fixed 2020 bag is never near the range edge, so `zonedDateTimeFrom`'s only
+        // workaround does not apply; calling Temporal directly keeps `zonedWallClock` out of the
+        // business-day entries.
+        Temporal.ZonedDateTime.from({
+            year: 2020,
+            month: 2,
+            day: 28,
+            hour: 0,
+            minute: 0,
+            second: 0,
+            timeZone: timeZone,
+        });
+        if (!timeZoneLike.test(timeZone)) {
+            return false;
+        }
+        // Only a pass is stored, so hostile strings cannot grow the set.
+        if (typeof timeZone !== "string") {
+            return true;
+        }
+        rememberZone(timeZone);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The check behind `isValidTime`: a plain ISO 8601 time of day.
+ *
+ * @param value the candidate string
+ * @returns whether Temporal reads it as a `PlainTime` and it has the strict shape
+ *
+ * @example isTimeString("17:00") // true
+ * @example isTimeString("25:00") // false
+ */
+export function isTimeString(value) {
+    const body = isoStringBody(value);
+    if (hasSecond60(body) || !plainTime.test(body)) {
+        return false;
+    }
+    try {
+        Temporal.PlainTime.from(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The check behind `isValidDate`: a plain ISO 8601 calendar date.
+ *
+ * @param value the candidate string
+ * @returns whether Temporal reads it as an ISO calendar `PlainDate` and it has the strict shape
+ *
+ * @example isDateString("2024-02-29") // true
+ * @example isDateString("2024-02-30") // false
+ */
+export function isDateString(value) {
+    const body = isoStringBody(value);
+    if (hasSecond60(body) || !plainDate.test(body)) {
+        return false;
+    }
+    try {
+        return Temporal.PlainDate.from(value).calendarId === "iso8601";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The check behind `isValidDuration`: an ISO 8601 duration string.
+ *
+ * @param value the candidate
+ * @returns whether it is a string Temporal reads as a `Duration`
+ *
+ * @example isDurationString("P1DT2H") // true
+ * @example isDurationString("2 days") // false
+ */
+export function isDurationString(value) {
+    if (typeof value !== "string") {
+        return false;
+    }
+    try {
+        Temporal.Duration.from(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const ROLL_CONVENTIONS = [
+    "following",
+    "modifiedFollowing",
+    "preceding",
+    "modifiedPreceding",
+    "endOfMonth",
+    "none",
+];
+/**
+ * The check behind `isValidRollConvention`: membership in the roll set.
+ *
+ * @param convention the candidate
+ * @returns whether it is one of the six conventions
+ *
+ * @example isRollConventionName("following") // true
+ * @example isRollConventionName("nearest") // false
+ */
+export function isRollConventionName(convention) {
+    return (typeof convention === "string" &&
+        ROLL_CONVENTIONS.includes(convention));
+}

package/dist/internal/instantFormatOptions.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "./temporal.js";
 type Options = Intl.DateTimeFormatOptions;
 /**
  * Resolve caller options into runtime `Intl.DateTimeFormat` options that

package/dist/internal/instantFormatOptions.js

@@ -1,8 +1,4 @@
-// Option resolution for formatting an exact time (a ZonedDateTime, or an
-// Instant in a given zone) through the runtime's `Intl.DateTimeFormat`. The
-// rules are the Temporal proposal's ECMA-402 amendments: CreateDateTimeFormat
-// and GetDateTimeFormat with required ~any~ and inherit ~all~, so every caller
-// field, including `era` and `timeZoneName`, is passed on unchanged.
+import { cachedFormatter, checkFormatterArguments } from "./formatterCache.js";
 import { plainDateTimeFormatOptions } from "./plainFormatOptions.js";
 import { optionOrDefault } from "./optionOrDefault.js";
 // GetDateTimeFormat requiredOptions for ~any~. `era` and `timeZoneName` are
@@ -86,15 +82,15 @@ export function instantFormatOptions(options, timeZone, defaults) {
  * @returns the formatted text, not yet normalised
  */
 export function formatWallClockOrZoned(zonedDateTime, locale, options, includeTimeZoneName) {
-    new Intl.DateTimeFormat(locale, options);
+    checkFormatterArguments("DateTimeFormat", locale, options);
     if (includeTimeZoneName) {
         const resolved = instantFormatOptions(options, zonedDateTime.timeZoneId, "zoned-date-time");
         return resolved === null
             ? ""
-            : new Intl.DateTimeFormat(locale, resolved).format(zonedDateTime.epochMilliseconds);
+            : cachedFormatter("DateTimeFormat", locale, resolved).format(zonedDateTime.epochMilliseconds);
     }
     const wallClockMilliseconds = zonedDateTime
         .toPlainDateTime()
         .toZonedDateTime("UTC").epochMilliseconds;
-    return new Intl.DateTimeFormat(locale, plainDateTimeFormatOptions(options)).format(wallClockMilliseconds);
+    return cachedFormatter("DateTimeFormat", locale, plainDateTimeFormatOptions(options)).format(wallClockMilliseconds);
 }

package/dist/internal/instantIntervalText.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "./temporal.js";
 /**
  * Re-serialise instant intervals to `Temporal.Instant.prototype.toString()` spelling.
  *

package/dist/internal/instantNanoseconds.d.ts

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "./temporal.js";
 /**
  * Parse an ISO 8601 instant string to epoch nanoseconds, or `null` when it is not one.
  *
@@ -47,7 +47,7 @@ import { Temporal } from "@js-temporal/polyfill";
  *   bracket; a `Z` instant; an offset written with seconds, which TC39 matches exactly
  *   (`-00:45:00[Africa/Monrovia]` is −00:45:00); a bracket whose zone does not exist; and a
  *   bracket whose zone has no instant in range with that wall time at the written offset or at
- *   an offset that rounds to it (`-00:44[Africa/Monrovia]`, `-05:00[America/New_York]` in
+ *   an offset that rounds to it (`-00:44[Africa/Monrovia]`, `+00:00[Europe/London]` in
  *   June). Such a bracket is not validated here; a function that keeps the zone
  *   (`transitTime`, `toOffsetInstant`) rejects it instead. Calendar and elective annotations
  *   never change the reading. A string whose written reading is outside the instant range, and

package/dist/internal/instantNanoseconds.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "./temporal.js";
 import { instantLeapSecond } from "../regex/leap-second.js";
 import { hasInstantShape, isoStringBody } from "./isoStringBody.js";
 import { parseUtcOffsetNanoseconds } from "./utcOffsetString.js";
@@ -68,7 +68,7 @@ const minuteOffset = /[+-]\d{2}:\d{2}$/;
  *   bracket; a `Z` instant; an offset written with seconds, which TC39 matches exactly
  *   (`-00:45:00[Africa/Monrovia]` is −00:45:00); a bracket whose zone does not exist; and a
  *   bracket whose zone has no instant in range with that wall time at the written offset or at
- *   an offset that rounds to it (`-00:44[Africa/Monrovia]`, `-05:00[America/New_York]` in
+ *   an offset that rounds to it (`-00:44[Africa/Monrovia]`, `+00:00[Europe/London]` in
  *   June). Such a bracket is not validated here; a function that keeps the zone
  *   (`transitTime`, `toOffsetInstant`) rejects it instead. Calendar and elective annotations
  *   never change the reading. A string whose written reading is outside the instant range, and

package/dist/internal/intervalCountHelpers.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "./temporal.js";
 import type { DateTimeUnit } from "../types/index.js";
 /**
  * Singular DateTimeUnit to its `Temporal.Duration` field name.

package/dist/internal/intervalNanoseconds.js

@@ -1,4 +1,5 @@
 import { parseInstantNanoseconds } from "./instantNanoseconds.js";
+import { isObject } from "./isObject.js";
 /**
  * Parse a candidate `Interval` to epoch nanoseconds, or `null` when it is not one.
  *
@@ -13,7 +14,7 @@ import { parseInstantNanoseconds } from "./instantNanoseconds.js";
  * @example parseIntervalNanoseconds({ start: "1970-01-01T00:00:01Z", end: "1970-01-01T00:00:00Z" }) // null — inverted
  */
 export function parseIntervalNanoseconds(value) {
-    if (typeof value !== "object" || value === null) {
+    if (!isObject(value)) {
         return null;
     }
     const { start: startText, end: endText } = value;

package/dist/internal/isObject.d.ts

@@ -1,18 +1,25 @@
 /**
- * Type guard for a non-null object (arrays included), the shape an options bag or a props
- * object must have before it is destructured. A default parameter covers only `undefined`, so a
- * `null` or primitive argument reaches the destructure and throws `TypeError` without this check.
+ * Type guard for an ECMAScript Object (ECMA-262 §6.1.7): a non-null object, arrays included, or a
+ * function. It is the shape an options bag, a property bag or a props object must have before it
+ * is destructured. A default parameter covers only `undefined`, so a `null` or primitive argument
+ * reaches the destructure and throws `TypeError` without this check.
+ *
+ * A function is an Object, so it is accepted wherever Temporal and ECMA-402 accept one:
+ * GetOptionsObject returns any Object, and the polyfill reads
+ * `Object.assign(() => 0, { largestUnit: "hours" })` as `{ largestUnit: "hours" }`. Checking
+ * `typeof value === "object"` alone wrongly refused it.
  *
  * @param value candidate
  * @example isObject({ smallestUnit: "day" }) // true
+ * @example isObject(Object.assign(() => 0, { smallestUnit: "day" })) // true
  * @example isObject(null) // false
  * @example isObject("day") // false
- * @returns whether `value` is a non-null object
+ * @returns whether `value` is an Object
  */
 export declare function isObject(value: unknown): value is object;
 /**
  * Whether an `options` argument is acceptable under Temporal GetOptionsObject: omitted
- * (`undefined`, the defaults) or an object. `null`, a string, a number or a boolean is a TypeError
+ * (`undefined`, the defaults) or an Object, a function included. `null`, a string, a number or a boolean is a TypeError
  * there, so a function that takes an options bag returns its sentinel for it rather than silently
  * reading the defaults (e.g. a legacy positional unit string such as `"seconds"`).
  *
@@ -21,6 +28,6 @@ export declare function isObject(value: unknown): value is object;
  * @example isOptionsArgument({ overflow: "reject" }) // true
  * @example isOptionsArgument(null) // false
  * @example isOptionsArgument("seconds") // false
- * @returns whether `options` is `undefined` or a non-null object
+ * @returns whether `options` is `undefined` or an Object
  */
 export declare function isOptionsArgument(options: unknown): boolean;

package/dist/internal/isObject.js

@@ -1,20 +1,27 @@
 /**
- * Type guard for a non-null object (arrays included), the shape an options bag or a props
- * object must have before it is destructured. A default parameter covers only `undefined`, so a
- * `null` or primitive argument reaches the destructure and throws `TypeError` without this check.
+ * Type guard for an ECMAScript Object (ECMA-262 §6.1.7): a non-null object, arrays included, or a
+ * function. It is the shape an options bag, a property bag or a props object must have before it
+ * is destructured. A default parameter covers only `undefined`, so a `null` or primitive argument
+ * reaches the destructure and throws `TypeError` without this check.
+ *
+ * A function is an Object, so it is accepted wherever Temporal and ECMA-402 accept one:
+ * GetOptionsObject returns any Object, and the polyfill reads
+ * `Object.assign(() => 0, { largestUnit: "hours" })` as `{ largestUnit: "hours" }`. Checking
+ * `typeof value === "object"` alone wrongly refused it.
  *
  * @param value candidate
  * @example isObject({ smallestUnit: "day" }) // true
+ * @example isObject(Object.assign(() => 0, { smallestUnit: "day" })) // true
  * @example isObject(null) // false
  * @example isObject("day") // false
- * @returns whether `value` is a non-null object
+ * @returns whether `value` is an Object
  */
 export function isObject(value) {
-    return typeof value === "object" && value !== null;
+    return ((typeof value === "object" && value !== null) || typeof value === "function");
 }
 /**
  * Whether an `options` argument is acceptable under Temporal GetOptionsObject: omitted
- * (`undefined`, the defaults) or an object. `null`, a string, a number or a boolean is a TypeError
+ * (`undefined`, the defaults) or an Object, a function included. `null`, a string, a number or a boolean is a TypeError
  * there, so a function that takes an options bag returns its sentinel for it rather than silently
  * reading the defaults (e.g. a legacy positional unit string such as `"seconds"`).
  *
@@ -23,7 +30,7 @@ export function isObject(value) {
  * @example isOptionsArgument({ overflow: "reject" }) // true
  * @example isOptionsArgument(null) // false
  * @example isOptionsArgument("seconds") // false
- * @returns whether `options` is `undefined` or a non-null object
+ * @returns whether `options` is `undefined` or an Object
  */
 export function isOptionsArgument(options) {
     return options === undefined || isObject(options);

package/dist/internal/isoStringBody.d.ts

@@ -50,8 +50,8 @@ export declare const TIME_ZONE_ANNOTATION = "\\[!?[^\\]=]+\\]";
  * @param value candidate zoned datetime string
  * @returns whether the unannotated part has GMT's strict extended zoned shape
  *
- * @example hasZonedDateTimeShape("2024-10-03T14:30:00-04:00[America/New_York]") // true
- * @example hasZonedDateTimeShape("2024-10-03 14:30:00-04:00[America/New_York]") // false
+ * @example hasZonedDateTimeShape("2024-10-03T14:30:00+05:30[Asia/Kolkata]") // true
+ * @example hasZonedDateTimeShape("2024-10-03 14:30:00+05:30[Asia/Kolkata]") // false
  */
 export declare function hasZonedDateTimeShape(value: string): boolean;
 /**

package/dist/internal/isoStringBody.js

@@ -85,8 +85,8 @@ const instantBody = new RegExp(`^${EXTENDED_DATE_TIME}(?:Z|${EXTENDED_UTC_OFFSET
  * @param value candidate zoned datetime string
  * @returns whether the unannotated part has GMT's strict extended zoned shape
  *
- * @example hasZonedDateTimeShape("2024-10-03T14:30:00-04:00[America/New_York]") // true
- * @example hasZonedDateTimeShape("2024-10-03 14:30:00-04:00[America/New_York]") // false
+ * @example hasZonedDateTimeShape("2024-10-03T14:30:00+05:30[Asia/Kolkata]") // true
+ * @example hasZonedDateTimeShape("2024-10-03 14:30:00+05:30[Asia/Kolkata]") // false
  */
 export function hasZonedDateTimeShape(value) {
     return (typeof value === "string" && zonedDateTimeBody.test(isoStringBody(value)));

package/dist/internal/isoYearString.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Write an ISO year as Temporal writes it at the head of a date string (TC39 Temporal
+ * `PadISOYear ( y )`, §3.5.10): four digits from 0000 to 9999, otherwise a sign and six digits.
+ *
+ * A year written any other way does not read back. `"10000-01-01"` and `"00-5-01-01"` are not ISO
+ * 8601 or Temporal strings, and `isValidDate` rejects both; `"+010000-01-01"` and
+ * `"-000005-01-01"` are what `Temporal.PlainDate#toString` writes.
+ *
+ * - Every function that returns a year on its own writes it this way.
+ * - Where a Temporal value is at hand, let its own `toString` write the whole date. This is for a
+ *   year on its own, or a date assembled from fields with no Temporal value behind them.
+ *
+ * @param year an ISO year, an integer
+ * @returns the year as `YYYY` or `±YYYYYY`
+ *
+ * @example isoYearString(2024) // "2024"
+ * @example isoYearString(5) // "0005"
+ * @example isoYearString(10000) // "+010000"
+ * @example isoYearString(-5) // "-000005"
+ */
+export declare function isoYearString(year: number): string;

package/dist/internal/isoYearString.js

@@ -0,0 +1,27 @@
+/** TC39 Temporal `PadISOYear ( y )`, §3.5.10: a year from 0 to 9999 is written with four digits. */
+const MAX_FOUR_DIGIT_YEAR = 9999;
+/**
+ * Write an ISO year as Temporal writes it at the head of a date string (TC39 Temporal
+ * `PadISOYear ( y )`, §3.5.10): four digits from 0000 to 9999, otherwise a sign and six digits.
+ *
+ * A year written any other way does not read back. `"10000-01-01"` and `"00-5-01-01"` are not ISO
+ * 8601 or Temporal strings, and `isValidDate` rejects both; `"+010000-01-01"` and
+ * `"-000005-01-01"` are what `Temporal.PlainDate#toString` writes.
+ *
+ * - Every function that returns a year on its own writes it this way.
+ * - Where a Temporal value is at hand, let its own `toString` write the whole date. This is for a
+ *   year on its own, or a date assembled from fields with no Temporal value behind them.
+ *
+ * @param year an ISO year, an integer
+ * @returns the year as `YYYY` or `±YYYYYY`
+ *
+ * @example isoYearString(2024) // "2024"
+ * @example isoYearString(5) // "0005"
+ * @example isoYearString(10000) // "+010000"
+ * @example isoYearString(-5) // "-000005"
+ */
+export function isoYearString(year) {
+    return year < 0 || year > MAX_FOUR_DIGIT_YEAR
+        ? `${year < 0 ? "-" : "+"}${String(Math.abs(year)).padStart(6, "0")}`
+        : String(year).padStart(4, "0");
+}

package/dist/internal/joinDateTimeConnector.js

@@ -1,3 +1,4 @@
+import { cachedFormatter } from "./formatterCache.js";
 // `Intl.DateTimeFormat`'s part types that belong to the *date* half of a
 // combined `dateStyle` + `timeStyle` format. Everything else (`hour`,
 // `minute`, `second`, `fractionalSecond`, `dayPeriod`, `timeZoneName`, and
@@ -48,7 +49,7 @@ const DATE_PART_TYPES = new Set([
  * @returns `dayLabel` joined to the localized time with the locale's own connector
  */
 export function joinDateTimeConnector(epochMilliseconds, timeZone, locale, dayLabel, timeStyle) {
-    const parts = new Intl.DateTimeFormat(locale, {
+    const parts = cachedFormatter("DateTimeFormat", locale, {
         dateStyle: "full",
         timeStyle,
         timeZone,
@@ -62,7 +63,7 @@ export function joinDateTimeConnector(epochMilliseconds, timeZone, locale, dayLa
     // dateStyle-only format would still produce with no time present — it
     // belongs to the date field, not the connector, even though the combined
     // format fuses it into the same literal token as the real connector.
-    const dateOnlyParts = new Intl.DateTimeFormat(locale, {
+    const dateOnlyParts = cachedFormatter("DateTimeFormat", locale, {
         dateStyle: "full",
         timeZone,
     }).formatToParts(epochMilliseconds);

package/dist/internal/leapSeconds.d.ts

@@ -0,0 +1,63 @@
+import type { UtcReading } from "./utcReading.js";
+/** TAI − UTC by date: `at[i]` (epoch ns, 00:00:00 UTC on a month's first day) starts `taiMinusUtc[i]`. */
+export interface LeapSecondSteps {
+    /** Epoch nanoseconds at which each row's TAI − UTC takes effect, strictly increasing. */
+    readonly at: readonly bigint[];
+    /** TAI − UTC in whole seconds from `at[i]` until `at[i + 1]`. */
+    readonly taiMinusUtc: readonly bigint[];
+}
+/**
+ * IERS Earth Orientation Center, Leap_Second.dat (https://hpiers.obspm.fr/iers/bul/bulc/Leap_Second.dat),
+ * updated through IERS Bulletin C 72, 6 July 2026. Closed: CGPM 2026 Resolution 5 makes UTC
+ * continuous from 20 May 2027, and Bulletin C 72 rules out the end of December 2026. After the last
+ * row TAI − UTC stays 37 s. Checked weekly against IERS by scripts/leap-seconds.mjs.
+ */
+export declare const LEAP_SECOND_STEPS: LeapSecondSteps;
+/**
+ * TAI of a UTC reading, as label nanoseconds (the TAI wall clock read as if UTC), or `null` when
+ * the reading has no TAI instant.
+ *
+ * - `null` before the first row: TAI − UTC was not a whole number of seconds before 1972 (BIPM
+ *   Annual Report vol. 15, Table 2).
+ * - A second-60 reading is valid only in the second before a positive step, where it maps to
+ *   that inserted second: old offset + 1 s (ITU-R TF.460-6 Annex 1 §2.2).
+ * - An ordinary reading inside a deleted second (before a negative step) has no instant.
+ * - No upper bound: after the last row its offset holds.
+ *
+ * @param steps the leap-second table
+ * @param reading the UTC reading
+ * @returns TAI label nanoseconds, or null
+ */
+export declare function taiOfUtc(steps: LeapSecondSteps, reading: UtcReading): bigint | null;
+/**
+ * The UTC reading of a TAI instant given as label nanoseconds, or `null` before the table's
+ * first TAI instant (1972-01-01T00:00:10 TAI).
+ *
+ * - Inside an inserted second the reading is second 60: its `epochNanoseconds` is the
+ *   `…T23:59:59.f` instant Temporal would clamp `…:60.f` to.
+ * - A negative step needs no special case: the deleted second has no TAI instant to map.
+ *
+ * @param steps the leap-second table
+ * @param tai TAI label nanoseconds
+ * @returns the UTC reading, or null
+ */
+export declare function utcOfTai(steps: LeapSecondSteps, tai: bigint): UtcReading | null;
+/**
+ * The UTC reading of step `index`'s own second, the second before `at[index]` (ITU-R TF.460-6
+ * Annex 1 §2.2): for a positive step the inserted `…T23:59:60` (a second-60 reading); for a
+ * negative step the omitted `…T23:59:59` (an ordinary reading of its label).
+ *
+ * @param steps the leap-second table
+ * @param index a row index from 1
+ * @returns the reading of that step's second
+ */
+export declare function stepReading(steps: LeapSecondSteps, index: number): UtcReading;
+/**
+ * Index of the first step (row 1 on) that starts after a UTC reading, or −1 when there is none.
+ * A second-60 reading counts as the instant one second later, so its own step is behind it.
+ *
+ * @param steps the leap-second table
+ * @param reading the UTC reading
+ * @returns the row index, or −1
+ */
+export declare function nextStepIndex(steps: LeapSecondSteps, reading: UtcReading): number;