@northguild/gmt 1.19.0 → 1.20.0

package/dist/zoned/format/formatZonedRange.js

@@ -1,3 +1,4 @@
+import { cachedFormatter } from "../../internal/formatterCache.js";
 import { normalizeDateTime, zonedDateTimeFrom } from "../../internal/index.js";
 import { instantFormatOptions } from "../../internal/instantFormatOptions.js";
 import { isValidZonedDateTime } from "../validate/index.js";
@@ -27,15 +28,15 @@ import { readDateTimeFormatOptions } from "../../internal/readDateTimeFormatOpti
  * @param options optional Intl.DateTimeFormatOptions
  * @returns localized range string or "" when invalid
  *
- * @example formatZonedRange("2024-02-29T12:00:00.000+00:00[UTC]", "2024-02-29T14:00:00.000+00:00[UTC]", "en-US", { dateStyle: "long", timeStyle: "short" }) // "February 29, 2024, 12:00 - 2:00 PM"
+ * @example formatZonedRange("2024-02-29T12:00:00.000+00:00[UTC]", "2024-02-29T14:00:00.000+00:00[UTC]", "de-DE", { dateStyle: "long", timeStyle: "short" }) // "29. Februar 2024, 12:00-14:00 Uhr"
  * @example formatZonedRange("2024-02-29T12:00:00.000+00:00[UTC]", "2024-02-29T14:00:00.000+00:00[UTC]", "en-GB", { dateStyle: "short", timeStyle: "short" }) // "29/02/2024, 12:00-14:00"
- * @example formatZonedRange("2024-02-03T14:30:45-05:00[America/New_York]", "2024-02-03T15:30:45-05:00[America/New_York]", "zh-CN", { year: "numeric", month: "long" }) // "2024年2月"
- * @example formatZonedRange("2024-02-03T14:30:45-05:00[America/New_York]", "2024-02-03T15:30:45-05:00[America/New_York]", "en-US", { era: "long" }) // "2/3/2024 Anno Domini, 2:30:45 PM - 3:30:45 PM"
- * @example formatZonedRange("2024-02-29T10:00:00-05:00[America/New_York]", "2024-02-29T12:00:00-05:00[America/New_York]", "en-US", { hour: "numeric", timeZone: "UTC" }) // "" — a ZonedDateTime keeps its own zone
- * @example formatZonedRange("2024-02-29T10:00:00-05:00[America/New_York]", "2024-02-29T12:00:00-05:00[America/New_York]", "en-US", { hour: "numeric", minute: "numeric", timeZoneName: "short" }) // "10:00 AM - 12:00 PM EST" — the pre-1.16.0 text
- * @example formatZonedRange("invalid", "2024-02-29T14:00:00.000+00:00[UTC]", "en-US") // "" (invalid input)
+ * @example formatZonedRange("2024-02-03T14:30:45+08:00[Asia/Shanghai]", "2024-02-03T15:30:45+08:00[Asia/Shanghai]", "zh-CN", { year: "numeric", month: "long" }) // "2024年2月"
+ * @example formatZonedRange("2024-02-03T14:30:45+00:00[Europe/London]", "2024-02-03T15:30:45+00:00[Europe/London]", "en-GB", { era: "long" }) // "03/02/2024 Anno Domini, 14:30:45 - 15:30:45"
+ * @example formatZonedRange("2024-02-29T10:00:00+09:00[Asia/Tokyo]", "2024-02-29T12:00:00+09:00[Asia/Tokyo]", "ja-JP", { hour: "numeric", timeZone: "UTC" }) // "" — a ZonedDateTime keeps its own zone
+ * @example formatZonedRange("2024-02-29T10:00:00+00:00[Europe/London]", "2024-02-29T12:00:00+00:00[Europe/London]", "en-GB", { hour: "numeric", minute: "numeric", timeZoneName: "short" }) // "10:00-12:00 GMT" — the pre-1.16.0 text
+ * @example formatZonedRange("invalid", "2024-02-29T14:00:00.000+00:00[UTC]", "fr-FR") // "" (invalid input)
  * @example formatZonedRange("2024-02-03T14:30:45+01:00[Europe/Paris]", "2024-02-03T16:46:15+01:00[Europe/Paris]", ["fr-FR", "en-US"], { dateStyle: "short", timeStyle: "short" }) // "03/02/2024, 14:30 - 16:46"
- * @example formatZonedRange("2024-02-03T14:30:00-05:00[America/New_York]", "2024-02-05T17:00:00-05:00[America/New_York]", "en-US", null as never) // "" (null options, as ECMA-402 rejects them)
+ * @example formatZonedRange("2024-02-03T14:30:00-03:00[America/Sao_Paulo]", "2024-02-05T17:00:00-03:00[America/Sao_Paulo]", "pt-BR", null as never) // "" (null options, as ECMA-402 rejects them)
  */
 export function formatZonedRange(from, to, locale, options) {
     try {
@@ -67,7 +68,7 @@ export function formatZonedRange(from, to, locale, options) {
             return "";
         }
         try {
-            const out = new Intl.DateTimeFormat(locale, formatOptions).formatRange(zdt1.epochMilliseconds, zdt2.epochMilliseconds);
+            const out = cachedFormatter("DateTimeFormat", locale, formatOptions).formatRange(zdt1.epochMilliseconds, zdt2.epochMilliseconds);
             return normalizeDateTime(out);
         }
         catch {

package/dist/zoned/format/formatZonedToParts.d.ts

@@ -2,10 +2,10 @@ import type { DateTimeFormatOptions } from "../../types/index.js";
 /**
  * Return the locale-formatted parts of a ZonedDateTime.
  *
- * - This is GMT's substitute for a token formatter (Luxon `toFormat`, date-fns
- *   `format`). A token pattern hard-codes field order and ships US ordering to
- *   every locale; `formatToParts` gives the caller full control over presentation
- *   while the *locale* keeps control of order.
+ * - Use the parts instead of a fixed field pattern. A pattern such as UTS #35's `dd/MM/yyyy` fixes
+ *   one field order for every locale; ECMA-402's `Intl.DateTimeFormat.prototype.formatToParts`
+ *   (§11.3.6; `FormatDateTimeToParts` §11.5.7) returns the fields in the order of the locale's
+ *   CLDR date pattern, so the caller controls presentation and the locale keeps control of order.
  * - Each part is `{ type, value }` where `type` can be:
  *   `"era"`, `"year"`, `"relatedYear"`, `"yearName"`, `"month"`, `"day"`, `"weekday"`,
  *   `"hour"`, `"minute"`, `"second"`, `"fractionalSecond"`, `"dayPeriod"`,
@@ -37,17 +37,17 @@ import type { DateTimeFormatOptions } from "../../types/index.js";
  *   options value formats with the defaults, as `Intl.DateTimeFormat` does).
  *
  * @param value zoned ISO 8601 datetime string
- * @param locale optional locale tag (e.g. "en-US"), or a preference list of tags (ECMA-402)
+ * @param locale optional locale tag (e.g. "en-GB", "ja-JP"), or a preference list of tags (ECMA-402)
  * @param options optional Intl.DateTimeFormatOptions
  * @returns array of `{ type, value }` parts, or `[]` on invalid input
  *
- * @example formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US") // [{ type: "month", value: "3" }, { type: "literal", value: "/" }, { type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }, { type: "literal", value: ", " }, { type: "hour", value: "2" }, { type: "literal", value: ":" }, { type: "minute", value: "30" }, { type: "literal", value: ":" }, { type: "second", value: "00" }, { type: "literal", value: "\u202f" }, { type: "dayPeriod", value: "PM" }, { type: "literal", value: " " }, { type: "timeZoneName", value: "EDT" }]
- * @example formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US", { timeZoneName: "longOffset" }) // [{ type: "month", value: "3" }, { type: "literal", value: "/" }, { type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }, { type: "literal", value: ", " }, { type: "hour", value: "2" }, { type: "literal", value: ":" }, { type: "minute", value: "30" }, { type: "literal", value: ":" }, { type: "second", value: "00" }, { type: "literal", value: "\u202f" }, { type: "dayPeriod", value: "PM" }, { type: "literal", value: " " }, { type: "timeZoneName", value: "GMT-04:00" }]
- * @example formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US", { year: "numeric", month: "numeric", day: "numeric" }) // [{ type: "month", value: "3" }, { type: "literal", value: "/" }, { type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }] — the pre-1.16.0 default
- * @example formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US", { timeZone: "Asia/Tokyo" }) // [] — a ZonedDateTime keeps its own zone
- * @example formatZonedToParts("invalid", "en-US") // []
+ * @example formatZonedToParts("2024-03-15T14:30:00.000+00:00[Europe/London]", "en-GB") // [{ type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "month", value: "03" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }, { type: "literal", value: ", " }, { type: "hour", value: "14" }, { type: "literal", value: ":" }, { type: "minute", value: "30" }, { type: "literal", value: ":" }, { type: "second", value: "00" }, { type: "literal", value: " " }, { type: "timeZoneName", value: "GMT" }]
+ * @example formatZonedToParts("2024-03-15T14:30:00.000+05:30[Asia/Kolkata]", "en-US", { timeZoneName: "longOffset" }) // [{ type: "month", value: "3" }, { type: "literal", value: "/" }, { type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }, { type: "literal", value: ", " }, { type: "hour", value: "2" }, { type: "literal", value: ":" }, { type: "minute", value: "30" }, { type: "literal", value: ":" }, { type: "second", value: "00" }, { type: "literal", value: "\u202f" }, { type: "dayPeriod", value: "PM" }, { type: "literal", value: " " }, { type: "timeZoneName", value: "GMT+05:30" }]
+ * @example formatZonedToParts("2024-03-15T14:30:00.000+00:00[Europe/London]", "en-GB", { year: "numeric", month: "numeric", day: "numeric" }) // [{ type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "month", value: "03" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }] — the pre-1.16.0 default
+ * @example formatZonedToParts("2024-03-15T14:30:00.000+00:00[Europe/London]", "en-GB", { timeZone: "Asia/Tokyo" }) // [] — a ZonedDateTime keeps its own zone
+ * @example formatZonedToParts("invalid", "de-DE") // []
  * @example formatZonedToParts("2024-02-03T14:30:45+01:00[Europe/Paris]", ["fr-FR", "en-US"], { dateStyle: "medium", timeStyle: "short" }) // parts of "3 févr. 2024, 14:30"
- * @example formatZonedToParts("2024-02-03T14:30:00-05:00[America/New_York]", "en-US", null as never) // [] (null options, as ECMA-402 rejects them)
+ * @example formatZonedToParts("2024-02-03T14:30:00+02:00[Africa/Johannesburg]", "ar-EG", null as never) // [] (null options, as ECMA-402 rejects them)
  */
 export declare function formatZonedToParts(value: string, locale?: string | string[], options?: DateTimeFormatOptions): Array<{
     /**

package/dist/zoned/format/formatZonedToParts.js

@@ -1,3 +1,4 @@
+import { cachedFormatter } from "../../internal/formatterCache.js";
 import { isValidZonedDateTime } from "../validate/index.js";
 import { zonedDateTimeFrom } from "../../internal/index.js";
 import { instantFormatOptions } from "../../internal/instantFormatOptions.js";
@@ -5,10 +6,10 @@ import { readDateTimeFormatOptions } from "../../internal/readDateTimeFormatOpti
 /**
  * Return the locale-formatted parts of a ZonedDateTime.
  *
- * - This is GMT's substitute for a token formatter (Luxon `toFormat`, date-fns
- *   `format`). A token pattern hard-codes field order and ships US ordering to
- *   every locale; `formatToParts` gives the caller full control over presentation
- *   while the *locale* keeps control of order.
+ * - Use the parts instead of a fixed field pattern. A pattern such as UTS #35's `dd/MM/yyyy` fixes
+ *   one field order for every locale; ECMA-402's `Intl.DateTimeFormat.prototype.formatToParts`
+ *   (§11.3.6; `FormatDateTimeToParts` §11.5.7) returns the fields in the order of the locale's
+ *   CLDR date pattern, so the caller controls presentation and the locale keeps control of order.
  * - Each part is `{ type, value }` where `type` can be:
  *   `"era"`, `"year"`, `"relatedYear"`, `"yearName"`, `"month"`, `"day"`, `"weekday"`,
  *   `"hour"`, `"minute"`, `"second"`, `"fractionalSecond"`, `"dayPeriod"`,
@@ -40,17 +41,17 @@ import { readDateTimeFormatOptions } from "../../internal/readDateTimeFormatOpti
  *   options value formats with the defaults, as `Intl.DateTimeFormat` does).
  *
  * @param value zoned ISO 8601 datetime string
- * @param locale optional locale tag (e.g. "en-US"), or a preference list of tags (ECMA-402)
+ * @param locale optional locale tag (e.g. "en-GB", "ja-JP"), or a preference list of tags (ECMA-402)
  * @param options optional Intl.DateTimeFormatOptions
  * @returns array of `{ type, value }` parts, or `[]` on invalid input
  *
- * @example formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US") // [{ type: "month", value: "3" }, { type: "literal", value: "/" }, { type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }, { type: "literal", value: ", " }, { type: "hour", value: "2" }, { type: "literal", value: ":" }, { type: "minute", value: "30" }, { type: "literal", value: ":" }, { type: "second", value: "00" }, { type: "literal", value: "\u202f" }, { type: "dayPeriod", value: "PM" }, { type: "literal", value: " " }, { type: "timeZoneName", value: "EDT" }]
- * @example formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US", { timeZoneName: "longOffset" }) // [{ type: "month", value: "3" }, { type: "literal", value: "/" }, { type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }, { type: "literal", value: ", " }, { type: "hour", value: "2" }, { type: "literal", value: ":" }, { type: "minute", value: "30" }, { type: "literal", value: ":" }, { type: "second", value: "00" }, { type: "literal", value: "\u202f" }, { type: "dayPeriod", value: "PM" }, { type: "literal", value: " " }, { type: "timeZoneName", value: "GMT-04:00" }]
- * @example formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US", { year: "numeric", month: "numeric", day: "numeric" }) // [{ type: "month", value: "3" }, { type: "literal", value: "/" }, { type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }] — the pre-1.16.0 default
- * @example formatZonedToParts("2024-03-15T14:30:00.000-04:00[America/New_York]", "en-US", { timeZone: "Asia/Tokyo" }) // [] — a ZonedDateTime keeps its own zone
- * @example formatZonedToParts("invalid", "en-US") // []
+ * @example formatZonedToParts("2024-03-15T14:30:00.000+00:00[Europe/London]", "en-GB") // [{ type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "month", value: "03" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }, { type: "literal", value: ", " }, { type: "hour", value: "14" }, { type: "literal", value: ":" }, { type: "minute", value: "30" }, { type: "literal", value: ":" }, { type: "second", value: "00" }, { type: "literal", value: " " }, { type: "timeZoneName", value: "GMT" }]
+ * @example formatZonedToParts("2024-03-15T14:30:00.000+05:30[Asia/Kolkata]", "en-US", { timeZoneName: "longOffset" }) // [{ type: "month", value: "3" }, { type: "literal", value: "/" }, { type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }, { type: "literal", value: ", " }, { type: "hour", value: "2" }, { type: "literal", value: ":" }, { type: "minute", value: "30" }, { type: "literal", value: ":" }, { type: "second", value: "00" }, { type: "literal", value: "\u202f" }, { type: "dayPeriod", value: "PM" }, { type: "literal", value: " " }, { type: "timeZoneName", value: "GMT+05:30" }]
+ * @example formatZonedToParts("2024-03-15T14:30:00.000+00:00[Europe/London]", "en-GB", { year: "numeric", month: "numeric", day: "numeric" }) // [{ type: "day", value: "15" }, { type: "literal", value: "/" }, { type: "month", value: "03" }, { type: "literal", value: "/" }, { type: "year", value: "2024" }] — the pre-1.16.0 default
+ * @example formatZonedToParts("2024-03-15T14:30:00.000+00:00[Europe/London]", "en-GB", { timeZone: "Asia/Tokyo" }) // [] — a ZonedDateTime keeps its own zone
+ * @example formatZonedToParts("invalid", "de-DE") // []
  * @example formatZonedToParts("2024-02-03T14:30:45+01:00[Europe/Paris]", ["fr-FR", "en-US"], { dateStyle: "medium", timeStyle: "short" }) // parts of "3 févr. 2024, 14:30"
- * @example formatZonedToParts("2024-02-03T14:30:00-05:00[America/New_York]", "en-US", null as never) // [] (null options, as ECMA-402 rejects them)
+ * @example formatZonedToParts("2024-02-03T14:30:00+02:00[Africa/Johannesburg]", "ar-EG", null as never) // [] (null options, as ECMA-402 rejects them)
  */
 export function formatZonedToParts(value, locale, options) {
     // ECMA-402 CoerceOptionsToObject: null options throw TypeError, so they are invalid input.
@@ -70,7 +71,7 @@ export function formatZonedToParts(value, locale, options) {
         if (resolved === null) {
             return [];
         }
-        return new Intl.DateTimeFormat(locale, resolved)
+        return cachedFormatter("DateTimeFormat", locale, resolved)
             .formatToParts(zonedDateTime.epochMilliseconds)
             .map((p) => ({ type: p.type, value: p.value }));
     }

package/dist/zoned/get/getDstTransitions.d.ts

@@ -5,17 +5,17 @@
  * @example
  * import { DstTransition } from "@northguild/gmt/zoned";
  * const t: DstTransition = {
- *   instant: "2024-03-10T07:00:00Z",
- *   offsetBefore: "-05:00",
- *   offsetAfter: "-04:00",
+ *   instant: "2024-10-05T16:00:00Z",
+ *   offsetBefore: "+10:00",
+ *   offsetAfter: "+11:00",
  * };
  */
 export interface DstTransition {
-    /** The UTC instant of the offset change, ISO 8601 ending in `Z` (e.g. `2024-03-10T07:00:00Z`). */
+    /** The UTC instant of the offset change, ISO 8601 ending in `Z` (e.g. `2024-10-05T16:00:00Z`). */
     instant: string;
-    /** The UTC offset in effect immediately before the transition (e.g. `-05:00`). */
+    /** The UTC offset in effect immediately before the transition (e.g. `+10:00`). */
     offsetBefore: string;
-    /** The UTC offset in effect immediately after the transition (e.g. `-04:00`). */
+    /** The UTC offset in effect immediately after the transition (e.g. `+11:00`). */
     offsetAfter: string;
 }
 /**
@@ -43,10 +43,10 @@ export interface DstTransition {
  * @param year calendar year to scan (must be an integer)
  * @returns array of `{ instant, offsetBefore, offsetAfter }`, in chronological order
  *
- * @example getDstTransitions("America/New_York", 2024)
+ * @example getDstTransitions("Australia/Sydney", 2024)
  * // [
- * //   { instant: "2024-03-10T07:00:00Z", offsetBefore: "-05:00", offsetAfter: "-04:00" },
- * //   { instant: "2024-11-03T06:00:00Z", offsetBefore: "-04:00", offsetAfter: "-05:00" },
+ * //   { instant: "2024-04-06T16:00:00Z", offsetBefore: "+11:00", offsetAfter: "+10:00" },
+ * //   { instant: "2024-10-05T16:00:00Z", offsetBefore: "+10:00", offsetAfter: "+11:00" },
  * // ]
  * @example getDstTransitions("Asia/Singapore", 1982)
  * // [{ instant: "1981-12-31T16:00:00Z", offsetBefore: "+07:30", offsetAfter: "+08:00" }]

package/dist/zoned/get/getDstTransitions.js

@@ -27,10 +27,10 @@ const SEARCH_SPAN_NANOSECONDS = 368n * 86400000000000n;
  * @param year calendar year to scan (must be an integer)
  * @returns array of `{ instant, offsetBefore, offsetAfter }`, in chronological order
  *
- * @example getDstTransitions("America/New_York", 2024)
+ * @example getDstTransitions("Australia/Sydney", 2024)
  * // [
- * //   { instant: "2024-03-10T07:00:00Z", offsetBefore: "-05:00", offsetAfter: "-04:00" },
- * //   { instant: "2024-11-03T06:00:00Z", offsetBefore: "-04:00", offsetAfter: "-05:00" },
+ * //   { instant: "2024-04-06T16:00:00Z", offsetBefore: "+11:00", offsetAfter: "+10:00" },
+ * //   { instant: "2024-10-05T16:00:00Z", offsetBefore: "+10:00", offsetAfter: "+11:00" },
  * // ]
  * @example getDstTransitions("Asia/Singapore", 1982)
  * // [{ instant: "1981-12-31T16:00:00Z", offsetBefore: "+07:30", offsetAfter: "+08:00" }]

package/dist/zoned/get/getSystemTimeZone.d.ts

@@ -1,5 +1,5 @@
 /**
- * Return the runtime system timeZone name (for example "America/New_York").
+ * Return the runtime system timeZone name (for example "Europe/London").
  *
  * - Uses Intl.DateTimeFormat().resolvedOptions().timeZone to get system timezone.
  * - Returns "" when the host reports no usable time zone. With an empty `TZ` the runtime reports
@@ -8,6 +8,6 @@
  *
  * @returns system timeZone name or "" on failure
  *
- * @example getSystemTimeZone() // "America/New_York"
+ * @example getSystemTimeZone() // "Europe/London"
  */
 export declare function getSystemTimeZone(): string;

package/dist/zoned/get/getSystemTimeZone.js

@@ -1,6 +1,6 @@
 import { isValidTimeZone } from "../validate/isValidTimeZone.js";
 /**
- * Return the runtime system timeZone name (for example "America/New_York").
+ * Return the runtime system timeZone name (for example "Europe/London").
  *
  * - Uses Intl.DateTimeFormat().resolvedOptions().timeZone to get system timezone.
  * - Returns "" when the host reports no usable time zone. With an empty `TZ` the runtime reports
@@ -9,7 +9,7 @@ import { isValidTimeZone } from "../validate/isValidTimeZone.js";
  *
  * @returns system timeZone name or "" on failure
  *
- * @example getSystemTimeZone() // "America/New_York"
+ * @example getSystemTimeZone() // "Europe/London"
  */
 export function getSystemTimeZone() {
     try {

package/dist/zoned/get/getTimeZoneOffset.d.ts

@@ -25,17 +25,17 @@
  * @param timeZone IANA name or UTC offset: a time zone identifier (`+05:30`, `+0530`, `-08`) or a
  *   stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @param instant ISO 8601 instant string (e.g. "2024-07-15T12:00:00Z")
- * @returns offset string (e.g. "-04:00"), or "" on invalid input
+ * @returns offset string (e.g. "+10:00"), or "" on invalid input
  *
- * @example getTimeZoneOffset("America/New_York", "2024-07-15T12:00:00Z") // "-04:00"
- * @example getTimeZoneOffset("America/New_York", "2024-01-15T12:00:00Z") // "-05:00"
+ * @example getTimeZoneOffset("Australia/Sydney", "2024-07-15T12:00:00Z") // "+10:00"
+ * @example getTimeZoneOffset("Australia/Sydney", "2024-01-15T12:00:00Z") // "+11:00"
  * @example getTimeZoneOffset("Asia/Kathmandu", "2024-01-15T12:00:00Z") // "+05:45"
  * @example getTimeZoneOffset("Africa/Monrovia", "1970-01-01T12:00:00Z") // "-00:44:30" (an offset with seconds)
  * @example getTimeZoneOffset("-00:44:30", "1970-01-01T12:00:00Z") // "-00:44:30" (its own result, read back)
  * @example getTimeZoneOffset("+05:30:00", "1970-01-01T12:00:00Z") // "+05:30"
  * @example getTimeZoneOffset("Invalid/Zone", "2024-07-15T12:00:00Z") // ""
- * @example getTimeZoneOffset("America/New_York", "not an instant") // ""
- * @example getTimeZoneOffset("America/New_York", "2024-07-15T16:00:00z") // "" (lower-case z)
+ * @example getTimeZoneOffset("Africa/Johannesburg", "not an instant") // ""
+ * @example getTimeZoneOffset("Africa/Johannesburg", "2024-07-15T16:00:00z") // "" (lower-case z)
  * @example getTimeZoneOffset("UTC", "2016-12-31T23:59:60Z") // "" (leap second)
  * @example getTimeZoneOffset("UTC", "2016-12-31T23:59:60Z".replace(":60", ":59")) // "+00:00" (the clamped instant)
  */

package/dist/zoned/get/getTimeZoneOffset.js

@@ -29,17 +29,17 @@ import { frameOffset, zoneFrame } from "../../internal/zoneFrame.js";
  * @param timeZone IANA name or UTC offset: a time zone identifier (`+05:30`, `+0530`, `-08`) or a
  *   stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @param instant ISO 8601 instant string (e.g. "2024-07-15T12:00:00Z")
- * @returns offset string (e.g. "-04:00"), or "" on invalid input
+ * @returns offset string (e.g. "+10:00"), or "" on invalid input
  *
- * @example getTimeZoneOffset("America/New_York", "2024-07-15T12:00:00Z") // "-04:00"
- * @example getTimeZoneOffset("America/New_York", "2024-01-15T12:00:00Z") // "-05:00"
+ * @example getTimeZoneOffset("Australia/Sydney", "2024-07-15T12:00:00Z") // "+10:00"
+ * @example getTimeZoneOffset("Australia/Sydney", "2024-01-15T12:00:00Z") // "+11:00"
  * @example getTimeZoneOffset("Asia/Kathmandu", "2024-01-15T12:00:00Z") // "+05:45"
  * @example getTimeZoneOffset("Africa/Monrovia", "1970-01-01T12:00:00Z") // "-00:44:30" (an offset with seconds)
  * @example getTimeZoneOffset("-00:44:30", "1970-01-01T12:00:00Z") // "-00:44:30" (its own result, read back)
  * @example getTimeZoneOffset("+05:30:00", "1970-01-01T12:00:00Z") // "+05:30"
  * @example getTimeZoneOffset("Invalid/Zone", "2024-07-15T12:00:00Z") // ""
- * @example getTimeZoneOffset("America/New_York", "not an instant") // ""
- * @example getTimeZoneOffset("America/New_York", "2024-07-15T16:00:00z") // "" (lower-case z)
+ * @example getTimeZoneOffset("Africa/Johannesburg", "not an instant") // ""
+ * @example getTimeZoneOffset("Africa/Johannesburg", "2024-07-15T16:00:00z") // "" (lower-case z)
  * @example getTimeZoneOffset("UTC", "2016-12-31T23:59:60Z") // "" (leap second)
  * @example getTimeZoneOffset("UTC", "2016-12-31T23:59:60Z".replace(":60", ":59")) // "+00:00" (the clamped instant)
  */

package/dist/zoned/get/getTimeZones.d.ts

@@ -6,7 +6,7 @@
  *
  * @returns array of IANA timezone identifier strings, or `[]` on failure
  *
- * @example getTimeZones() // ["America/New_York", "Europe/London", ...]
+ * @example getTimeZones() // ["Africa/Abidjan", "Africa/Accra", ...]
  * @example getTimeZones().length // ~422 (varies by runtime/ICU)
  */
 export declare function getTimeZones(): string[];

package/dist/zoned/get/getTimeZones.js

@@ -6,7 +6,7 @@
  *
  * @returns array of IANA timezone identifier strings, or `[]` on failure
  *
- * @example getTimeZones() // ["America/New_York", "Europe/London", ...]
+ * @example getTimeZones() // ["Africa/Abidjan", "Africa/Accra", ...]
  * @example getTimeZones().length // ~422 (varies by runtime/ICU)
  */
 export function getTimeZones() {

package/dist/zoned/get/getZonedDay.d.ts

@@ -8,7 +8,7 @@
  *   a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns current day string (zero-padded to 2 digits) or "" on invalid input
  *
- * @example getZonedDay("America/New_York") // "28"
+ * @example getZonedDay("Asia/Tokyo") // "29"
  * @example getZonedDay("invalid") // ""
  */
 export declare function getZonedDay(ianaTimezone: string): string;

package/dist/zoned/get/getZonedDay.js

@@ -9,7 +9,7 @@ import { frameNowWallClock, zoneFrame } from "../../internal/zoneFrame.js";
  *   a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns current day string (zero-padded to 2 digits) or "" on invalid input
  *
- * @example getZonedDay("America/New_York") // "28"
+ * @example getZonedDay("Asia/Tokyo") // "29"
  * @example getZonedDay("invalid") // ""
  */
 export function getZonedDay(ianaTimezone) {

package/dist/zoned/get/getZonedDayOfWeek.d.ts

@@ -9,7 +9,7 @@
  *   a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns current day of week number (1-7) or null on invalid input
  *
- * @example getZonedDayOfWeek("America/New_York") // 3
+ * @example getZonedDayOfWeek("Australia/Sydney") // 5
  * @example getZonedDayOfWeek("invalid") // null
  */
 export declare function getZonedDayOfWeek(ianaTimezone: string): number | null;

package/dist/zoned/get/getZonedDayOfWeek.js

@@ -10,7 +10,7 @@ import { frameNowWallClock, zoneFrame } from "../../internal/zoneFrame.js";
  *   a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns current day of week number (1-7) or null on invalid input
  *
- * @example getZonedDayOfWeek("America/New_York") // 3
+ * @example getZonedDayOfWeek("Australia/Sydney") // 5
  * @example getZonedDayOfWeek("invalid") // null
  */
 export function getZonedDayOfWeek(ianaTimezone) {

package/dist/zoned/get/getZonedHour.d.ts

@@ -8,7 +8,7 @@
  *   a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns current hour string (zero-padded to 2 digits) or "" on invalid input
  *
- * @example getZonedHour("America/New_York") // "19"
+ * @example getZonedHour("Africa/Johannesburg") // "16"
  * @example getZonedHour("invalid") // ""
  */
 export declare function getZonedHour(ianaTimezone: string): string;

package/dist/zoned/get/getZonedHour.js

@@ -9,7 +9,7 @@ import { frameNowWallClock, zoneFrame } from "../../internal/zoneFrame.js";
  *   a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns current hour string (zero-padded to 2 digits) or "" on invalid input
  *
- * @example getZonedHour("America/New_York") // "19"
+ * @example getZonedHour("Africa/Johannesburg") // "16"
  * @example getZonedHour("invalid") // ""
  */
 export function getZonedHour(ianaTimezone) {

package/dist/zoned/get/getZonedMicrosecond.d.ts

@@ -8,7 +8,7 @@
  *   a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns current microsecond string (zero-padded to 3 digits) or "" on invalid input
  *
- * @example getZonedMicrosecond("America/New_York") // "000"
+ * @example getZonedMicrosecond("Europe/London") // "000"
  * @example getZonedMicrosecond("invalid") // ""
  */
 export declare function getZonedMicrosecond(ianaTimezone: string): string;

package/dist/zoned/get/getZonedMicrosecond.js

@@ -9,7 +9,7 @@ import { frameNowWallClock, zoneFrame } from "../../internal/zoneFrame.js";
  *   a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns current microsecond string (zero-padded to 3 digits) or "" on invalid input
  *
- * @example getZonedMicrosecond("America/New_York") // "000"
+ * @example getZonedMicrosecond("Europe/London") // "000"
  * @example getZonedMicrosecond("invalid") // ""
  */
 export function getZonedMicrosecond(ianaTimezone) {

package/dist/zoned/get/getZonedMillisecond.d.ts

@@ -8,7 +8,7 @@
  *   a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns current millisecond string (zero-padded to 3 digits) or "" on invalid input
  *
- * @example getZonedMillisecond("America/New_York") // "000"
+ * @example getZonedMillisecond("America/Sao_Paulo") // "123"
  * @example getZonedMillisecond("invalid") // ""
  */
 export declare function getZonedMillisecond(ianaTimezone: string): string;

package/dist/zoned/get/getZonedMillisecond.js

@@ -9,7 +9,7 @@ import { frameNowWallClock, zoneFrame } from "../../internal/zoneFrame.js";
  *   a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns current millisecond string (zero-padded to 3 digits) or "" on invalid input
  *
- * @example getZonedMillisecond("America/New_York") // "000"
+ * @example getZonedMillisecond("America/Sao_Paulo") // "123"
  * @example getZonedMillisecond("invalid") // ""
  */
 export function getZonedMillisecond(ianaTimezone) {

package/dist/zoned/get/getZonedMinute.d.ts

@@ -8,7 +8,7 @@
  *   a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns current minute string (zero-padded to 2 digits) or "" on invalid input
  *
- * @example getZonedMinute("America/New_York") // "00"
+ * @example getZonedMinute("Asia/Kolkata") // "00"
  * @example getZonedMinute("invalid") // ""
  */
 export declare function getZonedMinute(ianaTimezone: string): string;

package/dist/zoned/get/getZonedMinute.js

@@ -9,7 +9,7 @@ import { frameNowWallClock, zoneFrame } from "../../internal/zoneFrame.js";
  *   a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns current minute string (zero-padded to 2 digits) or "" on invalid input
  *
- * @example getZonedMinute("America/New_York") // "00"
+ * @example getZonedMinute("Asia/Kolkata") // "00"
  * @example getZonedMinute("invalid") // ""
  */
 export function getZonedMinute(ianaTimezone) {

package/dist/zoned/get/getZonedMonth.d.ts

@@ -8,7 +8,7 @@
  *   a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns current month string (zero-padded to 2 digits) or "" on invalid input
  *
- * @example getZonedMonth("America/New_York") // "02"
+ * @example getZonedMonth("Australia/Sydney") // "03"
  * @example getZonedMonth("invalid") // ""
  */
 export declare function getZonedMonth(ianaTimezone: string): string;

package/dist/zoned/get/getZonedMonth.js

@@ -9,7 +9,7 @@ import { frameNowWallClock, zoneFrame } from "../../internal/zoneFrame.js";
  *   a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns current month string (zero-padded to 2 digits) or "" on invalid input
  *
- * @example getZonedMonth("America/New_York") // "02"
+ * @example getZonedMonth("Australia/Sydney") // "03"
  * @example getZonedMonth("invalid") // ""
  */
 export function getZonedMonth(ianaTimezone) {

package/dist/zoned/get/getZonedNanosecond.d.ts

@@ -8,7 +8,7 @@
  *   a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns current nanosecond string (zero-padded to 3 digits) or "" on invalid input
  *
- * @example getZonedNanosecond("America/New_York") // "000"
+ * @example getZonedNanosecond("Africa/Johannesburg") // "000"
  * @example getZonedNanosecond("invalid") // ""
  */
 export declare function getZonedNanosecond(ianaTimezone: string): string;

package/dist/zoned/get/getZonedNanosecond.js

@@ -9,7 +9,7 @@ import { frameNowWallClock, zoneFrame } from "../../internal/zoneFrame.js";
  *   a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns current nanosecond string (zero-padded to 3 digits) or "" on invalid input
  *
- * @example getZonedNanosecond("America/New_York") // "000"
+ * @example getZonedNanosecond("Africa/Johannesburg") // "000"
  * @example getZonedNanosecond("invalid") // ""
  */
 export function getZonedNanosecond(ianaTimezone) {

package/dist/zoned/get/getZonedNow.d.ts

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 /**
  * Return the current zoned datetime for the specified IANA timeZone.
  *
@@ -16,10 +16,10 @@ import { Temporal } from "@js-temporal/polyfill";
  * @param optionsArg optional setting for the precision of the output string
  * @returns zoned ISO 8601 datetime string or "" on invalid input
  *
- * @example getZonedNow("America/New_York") // "2024-02-29T09:30:45.123-05:00[America/New_York]"
- * @example getZonedNow("America/New_York", { smallestUnit: "second" }) // "2024-02-29T09:30:45-05:00[America/New_York]"
+ * @example getZonedNow("Asia/Tokyo") // "2024-02-29T23:30:45.123+09:00[Asia/Tokyo]"
+ * @example getZonedNow("Asia/Tokyo", { smallestUnit: "second" }) // "2024-02-29T23:30:45+09:00[Asia/Tokyo]"
  * @example getZonedNow("Invalid/Zone") // ""
- * @example getZonedNow("America/New_York", { smallestUnit: "fortnight" as never }) // "" (not a unit from minute to nanosecond)
+ * @example getZonedNow("Asia/Tokyo", { smallestUnit: "fortnight" as never }) // "" (not a unit from minute to nanosecond)
  */
 export declare function getZonedNow(ianaTimezone: string, optionsArg?: {
     /**

package/dist/zoned/get/getZonedNow.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { isValidTimeZone } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 import { optionOrDefault } from "../../internal/optionOrDefault.js";
@@ -19,10 +19,10 @@ import { optionOrDefault } from "../../internal/optionOrDefault.js";
  * @param optionsArg optional setting for the precision of the output string
  * @returns zoned ISO 8601 datetime string or "" on invalid input
  *
- * @example getZonedNow("America/New_York") // "2024-02-29T09:30:45.123-05:00[America/New_York]"
- * @example getZonedNow("America/New_York", { smallestUnit: "second" }) // "2024-02-29T09:30:45-05:00[America/New_York]"
+ * @example getZonedNow("Asia/Tokyo") // "2024-02-29T23:30:45.123+09:00[Asia/Tokyo]"
+ * @example getZonedNow("Asia/Tokyo", { smallestUnit: "second" }) // "2024-02-29T23:30:45+09:00[Asia/Tokyo]"
  * @example getZonedNow("Invalid/Zone") // ""
- * @example getZonedNow("America/New_York", { smallestUnit: "fortnight" as never }) // "" (not a unit from minute to nanosecond)
+ * @example getZonedNow("Asia/Tokyo", { smallestUnit: "fortnight" as never }) // "" (not a unit from minute to nanosecond)
  */
 export function getZonedNow(ianaTimezone, optionsArg) {
     try {

package/dist/zoned/get/getZonedNowUnit.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "../../internal/temporal.js";
 /**
  * Units extractable from the current time in a specific IANA timeZone, as
  * consumed by `getZonedNowUnit`.
@@ -40,7 +40,7 @@ export type ZonedNowUnit = Temporal.SmallestUnit<"year" | "month" | "week" | "da
  * @param unit unit to extract from current zoned time
  * @returns string representation of the requested unit or "" on invalid input
  *
- * @example getZonedNowUnit("America/New_York", "hour") // "07"
+ * @example getZonedNowUnit("Asia/Tokyo", "hour") // "23"
  * @example getZonedNowUnit("UTC", "hours") // "14", if the UTC time is 14:xx (plural unit name)
  * @example getZonedNowUnit("invalid", "hour") // ""
  */

package/dist/zoned/get/getZonedNowUnit.js

@@ -33,7 +33,7 @@ function isValidZonedNowUnit(unit) {
  * @param unit unit to extract from current zoned time
  * @returns string representation of the requested unit or "" on invalid input
  *
- * @example getZonedNowUnit("America/New_York", "hour") // "07"
+ * @example getZonedNowUnit("Asia/Tokyo", "hour") // "23"
  * @example getZonedNowUnit("UTC", "hours") // "14", if the UTC time is 14:xx (plural unit name)
  * @example getZonedNowUnit("invalid", "hour") // ""
  */

package/dist/zoned/get/getZonedSecond.d.ts

@@ -8,7 +8,7 @@
  *   a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns current second string (zero-padded to 2 digits) or "" on invalid input
  *
- * @example getZonedSecond("America/New_York") // "00"
+ * @example getZonedSecond("Europe/London") // "45"
  * @example getZonedSecond("invalid") // ""
  */
 export declare function getZonedSecond(ianaTimezone: string): string;

package/dist/zoned/get/getZonedSecond.js

@@ -9,7 +9,7 @@ import { frameNowWallClock, zoneFrame } from "../../internal/zoneFrame.js";
  *   a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns current second string (zero-padded to 2 digits) or "" on invalid input
  *
- * @example getZonedSecond("America/New_York") // "00"
+ * @example getZonedSecond("Europe/London") // "45"
  * @example getZonedSecond("invalid") // ""
  */
 export function getZonedSecond(ianaTimezone) {

package/dist/zoned/get/getZonedToday.d.ts

@@ -8,7 +8,7 @@
  *   a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns ISO date string (YYYY-MM-DD) or "" when invalid
  *
- * @example getZonedToday("America/New_York") // "2024-02-29"
+ * @example getZonedToday("Asia/Kolkata") // "2024-02-29"
  * @example getZonedToday("invalid") // ""
  */
 export declare function getZonedToday(ianaTimezone: string): string;

package/dist/zoned/get/getZonedToday.js

@@ -9,7 +9,7 @@ import { frameNowWallClock, zoneFrame } from "../../internal/zoneFrame.js";
  *   a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @returns ISO date string (YYYY-MM-DD) or "" when invalid
  *
- * @example getZonedToday("America/New_York") // "2024-02-29"
+ * @example getZonedToday("Asia/Kolkata") // "2024-02-29"
  * @example getZonedToday("invalid") // ""
  */
 export function getZonedToday(ianaTimezone) {