@northguild/gmt 1.17.0 → 1.18.0

package/dist/zoned/interval/intervalXorAllZoned.d.ts

@@ -34,6 +34,15 @@ export declare function intervalXorAllZoned(intervals: Array<{
     start: string;
     end: string;
 }>): Array<{
+    /**
+     * The instant the interval begins at, as a zoned ISO 8601 string with offset and bracketed time
+     * zone. It keeps a calendar annotation such as `[u-ca=hebrew]` when the inputs carry one.
+     */
     start: string;
+    /**
+     * The first instant after the interval, in the same format as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It is always later
+     * than `start`.
+     */
     end: string;
 }>;

package/dist/zoned/interval/intervalXorZoned.d.ts

@@ -44,6 +44,15 @@
  * @example intervalXorZoned("invalid", "2024-06-30T12:00:00+00:00[UTC]", "2024-07-01T13:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // []
  */
 export declare function intervalXorZoned(aStart: string, aEnd: string, bStart: string, bEnd: string): Array<{
+    /**
+     * The instant the interval begins at, as a zoned ISO 8601 string with offset and bracketed time
+     * zone. It keeps a calendar annotation such as `[u-ca=hebrew]` when the inputs carry one.
+     */
     start: string;
+    /**
+     * The first instant after the interval, in the same format as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It is always later
+     * than `start`.
+     */
     end: string;
 }>;

package/dist/zoned/interval/mergeIntervalsZoned.d.ts

@@ -38,6 +38,15 @@ export declare function mergeIntervalsZoned(intervals: Array<{
     start: string;
     end: string;
 }>): Array<{
+    /**
+     * The instant the interval begins at, as a zoned ISO 8601 string with offset and bracketed time
+     * zone. It keeps a calendar annotation such as `[u-ca=hebrew]` when the inputs carry one.
+     */
     start: string;
+    /**
+     * The first instant after the interval, in the same format as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It is always later
+     * than `start`.
+     */
     end: string;
 }>;

package/dist/zoned/interval/splitIntervalByUnitZoned.d.ts

@@ -6,14 +6,20 @@
  *   no instant and together cover `[start, end)` exactly once.
  * - The final sub-interval is trimmed so its `end` never exceeds the original `end`.
  * - Calendar-unit boundaries (years, months, weeks, days) are computed from `start`
- *   (`start + k × amount`, as Temporal and Luxon's `Interval.splitBy` do), so month-end starts
- *   don't drift: a monthly split from January 31 lands on February 29, March 31, April 30.
+ *   (`start + k × amount`), so month-end starts don't drift: a monthly split from January 31
+ *   lands on February 29, March 31, April 30. Temporal's `add` constrains a day the month lacks
+ *   to the month's last day, and stepping from that boundary would keep the shortened day
+ *   (February 29, then March 29).
+ * - Comparison: Luxon's `Interval.splitBy` computes each boundary from the start the same way.
  * - Exact-unit boundaries (hours and smaller) step from the previous boundary. Exact units never
  *   clamp, and stepping keeps nanosecond precision where `k × amount` would pass
  *   `Number.MAX_SAFE_INTEGER`.
  * - A calendar step that resolves to the same instant as the previous boundary (a deleted local
  *   day, such as 30 December 2011 in `Pacific/Apia`) is skipped, so no empty slice is produced.
  *   A step that goes backwards returns `[]`.
+ * - `start` and `end` may name different time zones. Steps are taken from `start`, so the first
+ *   `start` and every inner boundary are written in `start`'s zone; the last `end` is the `end`
+ *   argument, in its own zone.
  * - Returns `[{ start, end }]` when `start === end` (zero-length interval).
  * - Accepts RFC 9557 calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
  *   well as bare ISO ones — E7 (issue #152). Stepping by a calendar unit ("1 month") resolves
@@ -24,9 +30,8 @@
  *   string (E7's D7-zoned).
  * - Returns `[]` on invalid input (unparseable start/end, unsupported unit, non-positive amount,
  *   leap-second strings).
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: a split
- *   into more slices returns `[]`, decided from the span before stepping where it can be, and
- *   otherwise as soon as slice `maxPieces + 1` is due. An invalid `maxPieces` also returns `[]`.
+ * - A split into more than `options.maxPieces` slices returns `[]`, decided from the span before
+ *   stepping where it can be, and otherwise as soon as slice `maxPieces + 1` is due.
  * - Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, the `[u-ca=<id>]`
  *   annotation after the zone, canonical calendar ids); see `isValidCalendarZonedDateTime`.
  *
@@ -34,7 +39,7 @@
  * @param end ISO 8601 zoned datetime string for the interval end
  * @param unit duration unit string — any `DateTimeDurationUnit`
  * @param amount positive number of units per step
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
+ * @param options optional limit on the size of the output
  * @returns array of `{ start, end }` records, or [] on invalid input
  *
  * @example splitIntervalByUnitZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-02T00:00:00+00:00[UTC]", "hour", 6) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-01T06:00:00+00:00[UTC]" }, { start: "2024-01-01T06:00:00+00:00[UTC]", end: "2024-01-01T12:00:00+00:00[UTC]" }, { start: "2024-01-01T12:00:00+00:00[UTC]", end: "2024-01-01T18:00:00+00:00[UTC]" }, { start: "2024-01-01T18:00:00+00:00[UTC]", end: "2024-01-02T00:00:00+00:00[UTC]" }]
@@ -47,8 +52,24 @@
  * @example splitIntervalByUnitZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-01T01:30:00+00:00[UTC]", "hour", 1, { maxPieces: 2 }) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-01T01:00:00+00:00[UTC]" }, { start: "2024-01-01T01:00:00+00:00[UTC]", end: "2024-01-01T01:30:00+00:00[UTC]" }]
  */
 export declare function splitIntervalByUnitZoned(start: string, end: string, unit: string, amount: number, options?: {
+    /**
+     * The most records the result may hold. A result that would hold more, or more than the longest
+     * possible array (2^32 - 1 elements), returns `[]` and none is built. A value that is not a
+     * positive safe integer also returns `[]`.
+     *
+     * @defaultValue `1_000_000`
+     */
     maxPieces?: number;
 }): Array<{
+    /**
+     * The instant the interval begins at, as a zoned ISO 8601 string with offset and bracketed time
+     * zone. It keeps a calendar annotation such as `[u-ca=hebrew]` when the inputs carry one.
+     */
     start: string;
+    /**
+     * The first instant after the interval, in the same format as `start`. It is exclusive: the
+     * interval holds everything from `start` up to but not including this value. It can equal
+     * `start`, which makes the interval empty.
+     */
     end: string;
 }>;

package/dist/zoned/interval/splitIntervalByUnitZoned.js

@@ -13,14 +13,20 @@ import { minSlicesForSpan } from "../../internal/splitStep.js";
  *   no instant and together cover `[start, end)` exactly once.
  * - The final sub-interval is trimmed so its `end` never exceeds the original `end`.
  * - Calendar-unit boundaries (years, months, weeks, days) are computed from `start`
- *   (`start + k × amount`, as Temporal and Luxon's `Interval.splitBy` do), so month-end starts
- *   don't drift: a monthly split from January 31 lands on February 29, March 31, April 30.
+ *   (`start + k × amount`), so month-end starts don't drift: a monthly split from January 31
+ *   lands on February 29, March 31, April 30. Temporal's `add` constrains a day the month lacks
+ *   to the month's last day, and stepping from that boundary would keep the shortened day
+ *   (February 29, then March 29).
+ * - Comparison: Luxon's `Interval.splitBy` computes each boundary from the start the same way.
  * - Exact-unit boundaries (hours and smaller) step from the previous boundary. Exact units never
  *   clamp, and stepping keeps nanosecond precision where `k × amount` would pass
  *   `Number.MAX_SAFE_INTEGER`.
  * - A calendar step that resolves to the same instant as the previous boundary (a deleted local
  *   day, such as 30 December 2011 in `Pacific/Apia`) is skipped, so no empty slice is produced.
  *   A step that goes backwards returns `[]`.
+ * - `start` and `end` may name different time zones. Steps are taken from `start`, so the first
+ *   `start` and every inner boundary are written in `start`'s zone; the last `end` is the `end`
+ *   argument, in its own zone.
  * - Returns `[{ start, end }]` when `start === end` (zero-length interval).
  * - Accepts RFC 9557 calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
  *   well as bare ISO ones — E7 (issue #152). Stepping by a calendar unit ("1 month") resolves
@@ -31,9 +37,8 @@ import { minSlicesForSpan } from "../../internal/splitStep.js";
  *   string (E7's D7-zoned).
  * - Returns `[]` on invalid input (unparseable start/end, unsupported unit, non-positive amount,
  *   leap-second strings).
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: a split
- *   into more slices returns `[]`, decided from the span before stepping where it can be, and
- *   otherwise as soon as slice `maxPieces + 1` is due. An invalid `maxPieces` also returns `[]`.
+ * - A split into more than `options.maxPieces` slices returns `[]`, decided from the span before
+ *   stepping where it can be, and otherwise as soon as slice `maxPieces + 1` is due.
  * - Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, the `[u-ca=<id>]`
  *   annotation after the zone, canonical calendar ids); see `isValidCalendarZonedDateTime`.
  *
@@ -41,7 +46,7 @@ import { minSlicesForSpan } from "../../internal/splitStep.js";
  * @param end ISO 8601 zoned datetime string for the interval end
  * @param unit duration unit string — any `DateTimeDurationUnit`
  * @param amount positive number of units per step
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
+ * @param options optional limit on the size of the output
  * @returns array of `{ start, end }` records, or [] on invalid input
  *
  * @example splitIntervalByUnitZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-02T00:00:00+00:00[UTC]", "hour", 6) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-01T06:00:00+00:00[UTC]" }, { start: "2024-01-01T06:00:00+00:00[UTC]", end: "2024-01-01T12:00:00+00:00[UTC]" }, { start: "2024-01-01T12:00:00+00:00[UTC]", end: "2024-01-01T18:00:00+00:00[UTC]" }, { start: "2024-01-01T18:00:00+00:00[UTC]", end: "2024-01-02T00:00:00+00:00[UTC]" }]

package/dist/zoned/map/mapZonedDatesInRange.d.ts

@@ -3,9 +3,7 @@
  *
  * - Both datetimes must have the same timezone.
  * - Returns [] for invalid inputs, mismatched timezones, start > end, or invalid step.
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: when the
- *   range holds more dates than that, it returns `[]` without generating any. An invalid
- *   `maxPieces` also returns `[]`.
+ * - A range holding more dates than `options.maxPieces` returns `[]` without generating any.
  * - An explicit `undefined` `stepDays` is the default step, so `(start, end, undefined, options)`
  *   reaches `options`. **Compatibility:** before 1.16.0 it returned `[]`.
  * - **End-inclusive, where the `interval*` functions are half-open.** This enumerates the dates a
@@ -16,7 +14,7 @@
  * @param startZonedDateTime start zoned ISO 8601 datetime string
  * @param endZonedDateTime end zoned ISO 8601 datetime string
  * @param stepDays optional positive integer step in days
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
+ * @param options optional limit on the size of the output
  * @returns array of ISO date strings or [] when invalid
  *
  * @example mapZonedDatesInRange("+275760-09-12T00:00:00+00:00[UTC]", "+275760-09-13T00:00:00+00:00[UTC]") // ["+275760-09-12", "+275760-09-13"] (a range ending on the maximum instant)
@@ -28,5 +26,12 @@
  * @example mapZonedDatesInRange("2024-02-28T12:00:00+00:00[UTC]", "2024-03-02T12:00:00+00:00[UTC]", 1, { maxPieces: 10 }) // ["2024-02-28", "2024-02-29", "2024-03-01", "2024-03-02"]
  */
 export declare function mapZonedDatesInRange(startZonedDateTime: string, endZonedDateTime: string, stepDays?: number, options?: {
+    /**
+     * The most dates the result may hold. A result that would hold more, or more than the longest
+     * possible array (2^32 - 1 elements), returns `[]` and none is built. A value that is not a
+     * positive safe integer also returns `[]`.
+     *
+     * @defaultValue `1_000_000`
+     */
     maxPieces?: number;
 }): string[];

package/dist/zoned/map/mapZonedDatesInRange.js

@@ -8,9 +8,7 @@ import { exceedsPieceLimit, resolveMaxPieces } from "../../internal/maxPieces.js
  *
  * - Both datetimes must have the same timezone.
  * - Returns [] for invalid inputs, mismatched timezones, start > end, or invalid step.
- * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: when the
- *   range holds more dates than that, it returns `[]` without generating any. An invalid
- *   `maxPieces` also returns `[]`.
+ * - A range holding more dates than `options.maxPieces` returns `[]` without generating any.
  * - An explicit `undefined` `stepDays` is the default step, so `(start, end, undefined, options)`
  *   reaches `options`. **Compatibility:** before 1.16.0 it returned `[]`.
  * - **End-inclusive, where the `interval*` functions are half-open.** This enumerates the dates a
@@ -21,7 +19,7 @@ import { exceedsPieceLimit, resolveMaxPieces } from "../../internal/maxPieces.js
  * @param startZonedDateTime start zoned ISO 8601 datetime string
  * @param endZonedDateTime end zoned ISO 8601 datetime string
  * @param stepDays optional positive integer step in days
- * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
+ * @param options optional limit on the size of the output
  * @returns array of ISO date strings or [] when invalid
  *
  * @example mapZonedDatesInRange("+275760-09-12T00:00:00+00:00[UTC]", "+275760-09-13T00:00:00+00:00[UTC]") // ["+275760-09-12", "+275760-09-13"] (a range ending on the maximum instant)

package/dist/zoned/parse/parseRfc2822.d.ts

@@ -3,7 +3,7 @@
  * `Date:` headers use — into a zoned ISO 8601 datetime string.
  *
  * - **Decoding, not display.** Weekday and month names are English, per the
- *   fixed grammar (see `formatRfc2822`'s JSDoc and roadmap Decision 1); like
+ *   fixed grammar (see `formatRfc2822`'s JSDoc); like
  *   every ABNF literal they match in any case (RFC 5234 §2.3).
  * - **Reads what a conformant receiver must.** RFC 5322 §3.3 syntax: folding
  *   white space (spaces, tabs, folded lines), nested comments such as a

package/dist/zoned/parse/parseRfc2822.js

@@ -5,7 +5,7 @@ import { readRfc5322DateTime } from "../../internal/rfc5322DateTime.js";
  * `Date:` headers use — into a zoned ISO 8601 datetime string.
  *
  * - **Decoding, not display.** Weekday and month names are English, per the
- *   fixed grammar (see `formatRfc2822`'s JSDoc and roadmap Decision 1); like
+ *   fixed grammar (see `formatRfc2822`'s JSDoc); like
  *   every ABNF literal they match in any case (RFC 5234 §2.3).
  * - **Reads what a conformant receiver must.** RFC 5322 §3.3 syntax: folding
  *   white space (spaces, tabs, folded lines), nested comments such as a

package/dist/zoned/parse/parseUnitFromZoned.d.ts

@@ -33,13 +33,11 @@ export type ZonedParseUnit = Temporal.SmallestUnit<"year" | "month" | "week" | "
  * - Uses Temporal.ZonedDateTime.from to parse.
  * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
  *   does; `"dayOfWeek"` has no plural.
- * - `weekStartsOn: "sunday"` numbers weeks by UTS #35 (week 1 holds 1 January, so late-December
- *   days can be week 1); any value other than `"monday"` or `"sunday"` returns "".
  * - Returns "" for invalid input.
  *
  * @param value zoned ISO 8601 datetime string
  * @param unit unit to extract
- * @param optionsArg optional settings (e.g. weekStartsOn for week calculations); a non-object value (such as `null`) is invalid
+ * @param optionsArg optional setting for the week's first day; a non-object value (such as `null`) is invalid
  * @returns string representation of the requested unit or "" when invalid
  *
  * @example parseUnitFromZoned("2024-02-29T12:34:56.789+00:00[UTC]", "year") // "2024"
@@ -48,5 +46,13 @@ export type ZonedParseUnit = Temporal.SmallestUnit<"year" | "month" | "week" | "
  * @example parseUnitFromZoned("invalid", "year") // ""
  */
 export declare function parseUnitFromZoned(value: string, unit: ZonedParseUnit, optionsArg?: {
+    /**
+     * The first day of the week, which sets how the `"week"` unit is numbered. `"monday"` gives the
+     * ISO 8601 week number, where week 1 holds the year's first Thursday; `"sunday"` gives the UTS
+     * #35 week number with a Sunday first day and one minimal day, where week 1 holds 1 January.
+     * Any other value returns `""`, whatever the unit.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
 }): string;

package/dist/zoned/parse/parseUnitFromZoned.js

@@ -27,13 +27,11 @@ function isValidZonedUnit(unit) {
  * - Uses Temporal.ZonedDateTime.from to parse.
  * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
  *   does; `"dayOfWeek"` has no plural.
- * - `weekStartsOn: "sunday"` numbers weeks by UTS #35 (week 1 holds 1 January, so late-December
- *   days can be week 1); any value other than `"monday"` or `"sunday"` returns "".
  * - Returns "" for invalid input.
  *
  * @param value zoned ISO 8601 datetime string
  * @param unit unit to extract
- * @param optionsArg optional settings (e.g. weekStartsOn for week calculations); a non-object value (such as `null`) is invalid
+ * @param optionsArg optional setting for the week's first day; a non-object value (such as `null`) is invalid
  * @returns string representation of the requested unit or "" when invalid
  *
  * @example parseUnitFromZoned("2024-02-29T12:34:56.789+00:00[UTC]", "year") // "2024"

package/dist/zoned/parse/parseWeekFromZoned.d.ts

@@ -1,18 +1,17 @@
 /**
  * Return the week of the year for a given ISO 8601 zoned datetime string.
  *
- * - `"monday"` (default) is the ISO 8601 week of the week-year: week 1 is the week containing the
+ * - `"monday"` is the ISO 8601 week of the week-year: week 1 is the week containing the
  *   first Thursday, so late-December days can be week 1 of the next year (a value on 2024-12-31
  *   → 1). The result is 1–53.
  * - `"sunday"` is the UTS #35 week of the week-year with a Sunday first day and minimal days 1:
  *   week 1 is the Sunday-first week holding 1 January, so late-December days can be week 1 of the
  *   next year (2024-12-31 → 1, 2000-12-30 → 53). The result is 1–53.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
  * - The week is read from the value's own date on its own wall clock.
  * - Returns null for invalid input.
  *
  * @param value ISO zoned datetime string
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations
+ * @param optionsArg optional setting for the week's first day
  * @returns Week number (1-53), or null on invalid input
  *
  * @example parseWeekFromZoned("2024-01-01T14:30:45.123+00:00[UTC]") // 1
@@ -23,5 +22,13 @@
  * @example parseWeekFromZoned("invalid") // null
  */
 export declare function parseWeekFromZoned(value: string, optionsArg?: {
+    /**
+     * The first day of the week, which sets how the week is numbered. `"monday"` gives the ISO 8601
+     * week number, where week 1 holds the year's first Thursday; `"sunday"` gives the UTS #35 week
+     * number with a Sunday first day and one minimal day, where week 1 holds 1 January. Any other
+     * value returns `null`.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
 }): number | null;

package/dist/zoned/parse/parseWeekFromZoned.js

@@ -6,18 +6,17 @@ import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the week of the year for a given ISO 8601 zoned datetime string.
  *
- * - `"monday"` (default) is the ISO 8601 week of the week-year: week 1 is the week containing the
+ * - `"monday"` is the ISO 8601 week of the week-year: week 1 is the week containing the
  *   first Thursday, so late-December days can be week 1 of the next year (a value on 2024-12-31
  *   → 1). The result is 1–53.
  * - `"sunday"` is the UTS #35 week of the week-year with a Sunday first day and minimal days 1:
  *   week 1 is the Sunday-first week holding 1 January, so late-December days can be week 1 of the
  *   next year (2024-12-31 → 1, 2000-12-30 → 53). The result is 1–53.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
  * - The week is read from the value's own date on its own wall clock.
  * - Returns null for invalid input.
  *
  * @param value ISO zoned datetime string
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations
+ * @param optionsArg optional setting for the week's first day
  * @returns Week number (1-53), or null on invalid input
  *
  * @example parseWeekFromZoned("2024-01-01T14:30:45.123+00:00[UTC]") // 1

package/dist/zoned/validate/hasDaylightSaving.d.ts

@@ -1,17 +1,48 @@
 /**
- * Check whether an IANA timeZone identifier observes daylight saving time.
+ * Check whether a timeZone observes daylight saving time at a reference instant.
  *
- * - Compares UTC offsets at two dates six months apart (January and July).
- * - A zone is considered to have DST if its offset differs between the two dates.
- * - Returns false for invalid or unresolvable timeZone identifiers.
+ * - True when the zone is in daylight time at the reference instant, or a daylight period begins
+ *   less than 365 days after it. So a zone in its winter is true, and a zone that has stopped
+ *   changing its clocks is false.
+ * - With `options.at` the answer does not depend on the day the code runs.
+ * - The rule is GMT's own definition, not the tz database's daylight flag, which no JavaScript
+ *   API exposes: daylight time runs from a forward change of the zone's clocks to the backward
+ *   change of the same size that undoes it, less than 365 days later.
+ * - Read as standard time, because the offsets do not show otherwise: the last summer before a
+ *   zone kept its daylight offset for good; a daylight period held 365 days or longer; one that
+ *   began, ended or was interrupted by a move of standard time, so the offset changes part-way
+ *   through and the rest, or all, of it is not paired (`Asia/Tomsk` 2002); and one whose end is
+ *   past the last instant Temporal can represent.
+ * - A forward change never undone is a change of standard time: `Europe/Istanbul` is false from
+ *   2016 on, although its clocks went forward in March 2016.
+ * - Read from the runtime's time zone data, so the answer can change when that data does.
+ * - Returns false for an invalid timeZone, an invalid `at`, an options argument that is not an
+ *   object, and a fixed offset.
  *
  * @param timeZone timeZone identifier to check
- * @returns boolean indicating whether the timeZone observes DST
+ * @param options optional setting for the reference instant
+ * @returns boolean indicating whether the timeZone observes DST, or false on invalid input
  *
- * @example hasDaylightSaving("America/New_York") // true
- * @example hasDaylightSaving("Europe/Berlin")     // true
- * @example hasDaylightSaving("Asia/Tokyo")        // false
- * @example hasDaylightSaving("UTC")               // false
- * @example hasDaylightSaving("Invalid/Zone")      // false
+ * @example hasDaylightSaving("America/New_York", { at: "2024-01-15T12:00:00Z" }) // true
+ * @example hasDaylightSaving("Australia/Sydney", { at: "2024-06-15T12:00:00Z" }) // true (winter; the next period begins in October)
+ * @example hasDaylightSaving("Asia/Tokyo", { at: "2024-01-15T12:00:00Z" }) // false
+ * @example hasDaylightSaving("Europe/Istanbul", { at: "2015-06-15T12:00:00Z" }) // true
+ * @example hasDaylightSaving("Europe/Istanbul", { at: "2016-06-15T12:00:00Z" }) // false (the March 2016 advance was never undone)
+ * @example hasDaylightSaving("America/Sao_Paulo", { at: "2018-06-15T12:00:00Z" }) // true
+ * @example hasDaylightSaving("America/Sao_Paulo", { at: "2019-06-15T12:00:00Z" }) // false (last daylight period ended 2019-02-17)
+ * @example hasDaylightSaving("UTC", { at: "2024-01-15T12:00:00Z" }) // false
+ * @example hasDaylightSaving("+05:00", { at: "2024-01-15T12:00:00Z" }) // false
+ * @example hasDaylightSaving("Invalid/Zone", { at: "2024-01-15T12:00:00Z" }) // false
+ * @example hasDaylightSaving("America/New_York", { at: "2024-01-15" }) // false (not an instant)
  */
-export declare function hasDaylightSaving(timeZone: string): boolean;
+export declare function hasDaylightSaving(timeZone: string, options?: {
+    /**
+     * The reference instant the zone is judged at, as an ISO 8601 instant string ending in `Z`, an
+     * offset or a bracketed zone. It only names an instant, as `isValidInstant` reads it: a
+     * bracketed zone is not validated and does not replace `timeZone`. An invalid value returns
+     * false.
+     *
+     * @defaultValue The current instant.
+     */
+    at?: string;
+}): boolean;

package/dist/zoned/validate/hasDaylightSaving.js

@@ -1,41 +1,57 @@
-import { zonedDateTimeFrom } from "../../internal/index.js";
+import { Temporal } from "@js-temporal/polyfill";
+import { isOptionsArgument, observesDaylightTime, parseInstantNanoseconds, } from "../../internal/index.js";
+import { isValidTimeZone } from "./isValidTimeZone.js";
 /**
- * Check whether an IANA timeZone identifier observes daylight saving time.
+ * Check whether a timeZone observes daylight saving time at a reference instant.
  *
- * - Compares UTC offsets at two dates six months apart (January and July).
- * - A zone is considered to have DST if its offset differs between the two dates.
- * - Returns false for invalid or unresolvable timeZone identifiers.
+ * - True when the zone is in daylight time at the reference instant, or a daylight period begins
+ *   less than 365 days after it. So a zone in its winter is true, and a zone that has stopped
+ *   changing its clocks is false.
+ * - With `options.at` the answer does not depend on the day the code runs.
+ * - The rule is GMT's own definition, not the tz database's daylight flag, which no JavaScript
+ *   API exposes: daylight time runs from a forward change of the zone's clocks to the backward
+ *   change of the same size that undoes it, less than 365 days later.
+ * - Read as standard time, because the offsets do not show otherwise: the last summer before a
+ *   zone kept its daylight offset for good; a daylight period held 365 days or longer; one that
+ *   began, ended or was interrupted by a move of standard time, so the offset changes part-way
+ *   through and the rest, or all, of it is not paired (`Asia/Tomsk` 2002); and one whose end is
+ *   past the last instant Temporal can represent.
+ * - A forward change never undone is a change of standard time: `Europe/Istanbul` is false from
+ *   2016 on, although its clocks went forward in March 2016.
+ * - Read from the runtime's time zone data, so the answer can change when that data does.
+ * - Returns false for an invalid timeZone, an invalid `at`, an options argument that is not an
+ *   object, and a fixed offset.
  *
  * @param timeZone timeZone identifier to check
- * @returns boolean indicating whether the timeZone observes DST
+ * @param options optional setting for the reference instant
+ * @returns boolean indicating whether the timeZone observes DST, or false on invalid input
  *
- * @example hasDaylightSaving("America/New_York") // true
- * @example hasDaylightSaving("Europe/Berlin")     // true
- * @example hasDaylightSaving("Asia/Tokyo")        // false
- * @example hasDaylightSaving("UTC")               // false
- * @example hasDaylightSaving("Invalid/Zone")      // false
+ * @example hasDaylightSaving("America/New_York", { at: "2024-01-15T12:00:00Z" }) // true
+ * @example hasDaylightSaving("Australia/Sydney", { at: "2024-06-15T12:00:00Z" }) // true (winter; the next period begins in October)
+ * @example hasDaylightSaving("Asia/Tokyo", { at: "2024-01-15T12:00:00Z" }) // false
+ * @example hasDaylightSaving("Europe/Istanbul", { at: "2015-06-15T12:00:00Z" }) // true
+ * @example hasDaylightSaving("Europe/Istanbul", { at: "2016-06-15T12:00:00Z" }) // false (the March 2016 advance was never undone)
+ * @example hasDaylightSaving("America/Sao_Paulo", { at: "2018-06-15T12:00:00Z" }) // true
+ * @example hasDaylightSaving("America/Sao_Paulo", { at: "2019-06-15T12:00:00Z" }) // false (last daylight period ended 2019-02-17)
+ * @example hasDaylightSaving("UTC", { at: "2024-01-15T12:00:00Z" }) // false
+ * @example hasDaylightSaving("+05:00", { at: "2024-01-15T12:00:00Z" }) // false
+ * @example hasDaylightSaving("Invalid/Zone", { at: "2024-01-15T12:00:00Z" }) // false
+ * @example hasDaylightSaving("America/New_York", { at: "2024-01-15" }) // false (not an instant)
  */
-export function hasDaylightSaving(timeZone) {
+export function hasDaylightSaving(timeZone, options) {
+    if (!isValidTimeZone(timeZone) || !isOptionsArgument(options)) {
+        return false;
+    }
     try {
-        const zdtJanuary = zonedDateTimeFrom({
-            year: 2024,
-            month: 1,
-            day: 15,
-            hour: 12,
-            minute: 0,
-            second: 0,
-            timeZone,
-        });
-        const zdtJuly = zonedDateTimeFrom({
-            year: 2024,
-            month: 7,
-            day: 15,
-            hour: 12,
-            minute: 0,
-            second: 0,
-            timeZone,
-        });
-        return zdtJanuary.offsetNanoseconds !== zdtJuly.offsetNanoseconds;
+        const at = options?.at;
+        if (at === undefined) {
+            return observesDaylightTime(Temporal.Now.zonedDateTimeISO(timeZone));
+        }
+        const epochNanoseconds = parseInstantNanoseconds(at);
+        if (epochNanoseconds === null) {
+            return false;
+        }
+        return observesDaylightTime(Temporal.Instant.fromEpochNanoseconds(epochNanoseconds).toZonedDateTimeISO(timeZone));
     }
     catch {
         return false;

package/dist/zoned/validate/isValidZonedDateTime.d.ts

@@ -6,7 +6,15 @@
  *   space or lower-case `t` separator, a lower-case `z`, an hour-only time or offset, and a date
  *   without a time are rejected, although `Temporal.ZonedDateTime.from` reads them.
  * - Uses Temporal.ZonedDateTime.from for validation.
+ * - A written offset must agree with the bracketed zone, as TC39 `ToTemporalZonedDateTime`
+ *   matches it: an offset written to the minute may be the zone's sub-minute offset rounded
+ *   (`-00:45[Africa/Monrovia]` for −00:44:30, which is how Temporal writes it), and an offset
+ *   written with seconds must be the zone's offset exactly.
  * - Rejects leap seconds.
+ * - With an offset, the local date must be inside Temporal's date range, as
+ *   `Temporal.ZonedDateTime.from` requires (`CheckISODaysRange`): a zoned string on
+ *   −271821-04-19, which a zone west of Greenwich shows for the first hours of the instant
+ *   range, is rejected although `isValidInstant` accepts it.
  * - Reads RFC 9557 annotations as `Temporal.ZonedDateTime.from` does: elective ones
  *   (`[foo=bar]`) are ignored and an unknown critical one (`[!foo=bar]`) is rejected.
  * - The calendar must be ISO: `[u-ca=iso8601]` is accepted, and a non-ISO calendar annotation is
@@ -24,6 +32,11 @@
  * @example isValidZonedDateTime("20241003T143000-0400[America/New_York]") // false (basic format)
  * @example isValidZonedDateTime("2024-10-03 14:30:00-04:00[America/New_York]") // false (space separator)
  * @example isValidZonedDateTime("2024-10-03[America/New_York]") // false (no time)
+ * @example isValidZonedDateTime("2024-10-03T14:30:00-05:00[America/New_York]") // false (New York is -04:00 in October)
+ * @example isValidZonedDateTime("1960-01-01T00:20:00-00:45[Africa/Monrovia]") // true (-00:45 is Monrovia's -00:44:30, rounded)
+ * @example isValidZonedDateTime("1960-01-01T00:20:00-00:44:30[Africa/Monrovia]") // true
+ * @example isValidZonedDateTime("1960-01-01T00:20:00-00:45:00[Africa/Monrovia]") // false (an offset with seconds must be exact)
+ * @example isValidZonedDateTime("-271821-04-19T23:59:00-00:01[Europe/London]") // false (the local date is before Temporal's date range)
  * @example isValidZonedDateTime("invalid") // false
  */
 export declare function isValidZonedDateTime(value: string): boolean;

package/dist/zoned/validate/isValidZonedDateTime.js

@@ -1,5 +1,5 @@
-import { zonedDateTimeFrom } from "../../internal/index.js";
 import { hasZonedDateTimeShape } from "../../internal/isoStringBody.js";
+import { zonedDateTimeFrom } from "../../internal/zonedWallClock.js";
 import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
 /**
  * Validate whether a string is a valid ISO 8601 zoned datetime string.
@@ -9,7 +9,15 @@ import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
  *   space or lower-case `t` separator, a lower-case `z`, an hour-only time or offset, and a date
  *   without a time are rejected, although `Temporal.ZonedDateTime.from` reads them.
  * - Uses Temporal.ZonedDateTime.from for validation.
+ * - A written offset must agree with the bracketed zone, as TC39 `ToTemporalZonedDateTime`
+ *   matches it: an offset written to the minute may be the zone's sub-minute offset rounded
+ *   (`-00:45[Africa/Monrovia]` for −00:44:30, which is how Temporal writes it), and an offset
+ *   written with seconds must be the zone's offset exactly.
  * - Rejects leap seconds.
+ * - With an offset, the local date must be inside Temporal's date range, as
+ *   `Temporal.ZonedDateTime.from` requires (`CheckISODaysRange`): a zoned string on
+ *   −271821-04-19, which a zone west of Greenwich shows for the first hours of the instant
+ *   range, is rejected although `isValidInstant` accepts it.
  * - Reads RFC 9557 annotations as `Temporal.ZonedDateTime.from` does: elective ones
  *   (`[foo=bar]`) are ignored and an unknown critical one (`[!foo=bar]`) is rejected.
  * - The calendar must be ISO: `[u-ca=iso8601]` is accepted, and a non-ISO calendar annotation is
@@ -27,6 +35,11 @@ import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
  * @example isValidZonedDateTime("20241003T143000-0400[America/New_York]") // false (basic format)
  * @example isValidZonedDateTime("2024-10-03 14:30:00-04:00[America/New_York]") // false (space separator)
  * @example isValidZonedDateTime("2024-10-03[America/New_York]") // false (no time)
+ * @example isValidZonedDateTime("2024-10-03T14:30:00-05:00[America/New_York]") // false (New York is -04:00 in October)
+ * @example isValidZonedDateTime("1960-01-01T00:20:00-00:45[Africa/Monrovia]") // true (-00:45 is Monrovia's -00:44:30, rounded)
+ * @example isValidZonedDateTime("1960-01-01T00:20:00-00:44:30[Africa/Monrovia]") // true
+ * @example isValidZonedDateTime("1960-01-01T00:20:00-00:45:00[Africa/Monrovia]") // false (an offset with seconds must be exact)
+ * @example isValidZonedDateTime("-271821-04-19T23:59:00-00:01[Europe/London]") // false (the local date is before Temporal's date range)
  * @example isValidZonedDateTime("invalid") // false
  */
 export function isValidZonedDateTime(value) {

package/dist/zoned/validate/isValidZonedRange.d.ts

@@ -5,16 +5,13 @@
  * - Both inputs must be valid ISO 8601 zoned datetime strings in extended format, as
  *   `isValidZonedDateTime` requires: basic format, a space or lower-case `t` separator, a
  *   lower-case `z` and a date without a time return `false`.
- * - Equal `value1 === value2` is valid when `options.allowEqual` is true.
  * - Comparison is done by instant, so intervals spanning DST transitions are compared
  *   by absolute time.
  * - Invalid input, malformed strings, or leap-second strings return `false`.
  * - Annotations are read as `isValidZonedDateTime` reads them: elective ones are ignored,
  *   `[u-ca=iso8601]` is accepted, and a non-ISO calendar on either endpoint returns `false`.
  *
- * @param value1 first ISO ZonedDateTime string
- * @param value2 second ISO ZonedDateTime string
- * @param options optional allowEqual flag
+ * @param props the two endpoints of the range and its optional settings
  * @returns boolean indicating whether the zoned range is valid
  *
  * @example isValidZonedRange({ value1: "2024-01-01T10:00:00+00:00[UTC]", value2: "2024-12-31T23:59:59+00:00[UTC]" }) // true
@@ -25,9 +22,23 @@
  * @example isValidZonedRange({ value1: "2024-01-01 10:00:00+00:00[UTC]", value2: "2024-12-31T23:59:59+00:00[UTC]" }) // false (space separator)
  */
 export declare function isValidZonedRange(props: {
+    /** The start of the range, as an ISO 8601 zoned datetime string. */
     value1: string;
+    /** The end of the range, as an ISO 8601 zoned datetime string. */
     value2: string;
+    /**
+     * The settings for the comparison. It must be an object or omitted; any other value, `null`
+     * included, returns `false`.
+     *
+     * @defaultValue None. Two values at the same instant are not a valid range.
+     */
     options?: {
+        /**
+         * Whether `value1` at the same instant as `value2` is a valid range. `false` requires `value1`
+         * to be before `value2`.
+         *
+         * @defaultValue `false`
+         */
         allowEqual?: boolean;
     };
 }): boolean;

package/dist/zoned/validate/isValidZonedRange.js

@@ -10,16 +10,13 @@ import { hasZonedDateTimeShape } from "../../internal/isoStringBody.js";
  * - Both inputs must be valid ISO 8601 zoned datetime strings in extended format, as
  *   `isValidZonedDateTime` requires: basic format, a space or lower-case `t` separator, a
  *   lower-case `z` and a date without a time return `false`.
- * - Equal `value1 === value2` is valid when `options.allowEqual` is true.
  * - Comparison is done by instant, so intervals spanning DST transitions are compared
  *   by absolute time.
  * - Invalid input, malformed strings, or leap-second strings return `false`.
  * - Annotations are read as `isValidZonedDateTime` reads them: elective ones are ignored,
  *   `[u-ca=iso8601]` is accepted, and a non-ISO calendar on either endpoint returns `false`.
  *
- * @param value1 first ISO ZonedDateTime string
- * @param value2 second ISO ZonedDateTime string
- * @param options optional allowEqual flag
+ * @param props the two endpoints of the range and its optional settings
  * @returns boolean indicating whether the zoned range is valid
  *
  * @example isValidZonedRange({ value1: "2024-01-01T10:00:00+00:00[UTC]", value2: "2024-12-31T23:59:59+00:00[UTC]" }) // true