@northguild/gmt 1.14.2

package/skills/zoned-date-ops/SKILL.md

@@ -0,0 +1,422 @@
+---
+name: zoned-date-ops
+description: >
+  Work with timezone-aware dates and times using IANA timezone identifiers. Use
+  getZonedNow, formatZonedDateTime, formatZonedRange, formatRelativeZoned,
+  getSystemTimeZone, getTimeZones for basics. Use convertPlainDateTimeToZoned,
+  addZoned, subtractZoned, startOfZoned, endOfZoned, startOfQuarterForZoned,
+  endOfQuarterForZoned, mapZonedHoursInDay, getLocaleZonedStartOfWeek,
+  getLocaleZonedEndOfWeek, clampZoned, closestZonedTo, getHoursInZonedDay,
+  setZoned, setUnix, setUtc, cycleZoned for DST-aware construction, arithmetic,
+  boundaries, locale-week, day-length, field setting, and field cycling (wrap,
+  don't carry into the next field). Most accept disambiguation ("compatible" |
+  "earlier" | "later" | "reject") for gap/overlap resolution; boundary, set*,
+  and cycleZoned also accept offset ("prefer" | "use" | "ignore" | "reject",
+  default "ignore"). Use getZonedOffset, getZonedOffsetAs, getTimeZoneOffset,
+  formatTimeZoneName, isInDaylightSaving for reading a zoned value's UTC offset
+  and DST status.
+sources:
+  - 'northguild/gmt:packages/gmt/src/zoned/get/index.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/format/index.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/validate/index.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/parse/getZonedOffset.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/parse/getZonedOffsetAs.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/compare/isInDaylightSaving.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/convert/index.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/convert/convertZonedToCalendar.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/calculate/addZoned.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/calculate/subtractZoned.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/calculate/startOfZoned.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/calculate/endOfZoned.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/calculate/startOfQuarterForZoned.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/calculate/endOfQuarterForZoned.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/calculate/getLocaleZonedStartOfWeek.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/calculate/getLocaleZonedEndOfWeek.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/calculate/clampZoned.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/calculate/closestZonedTo.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/calculate/getHoursInZonedDay.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/map/mapZonedHoursInDay.ts'
+  - 'northguild/gmt:packages/gmt/src/unix/calculate/startOfUnix.ts'
+  - 'northguild/gmt:packages/gmt/src/unix/calculate/endOfUnix.ts'
+  - 'northguild/gmt:packages/gmt/src/unix/calculate/startOfQuarterForUnix.ts'
+  - 'northguild/gmt:packages/gmt/src/unix/calculate/endOfQuarterForUnix.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/calculate/setZoned.ts'
+  - 'northguild/gmt:packages/gmt/src/unix/calculate/setUnix.ts'
+  - 'northguild/gmt:packages/gmt/src/utc/calculate/setUtc.ts'
+  - 'northguild/gmt:packages/gmt/src/zoned/calculate/cycleZoned.ts'
+metadata:
+  type: core
+  library: '@northguild/gmt'
+  library_version: '1.14.2'
+---
+
+# Zoned Date Operations
+
+Use this skill when you need timezone-aware date/time operations.
+
+## Setup
+
+```ts
+import {
+  getZonedNow, getZonedToday, getSystemTimeZone, getTimeZones,
+  isValidTimeZone, formatZonedDateTime, formatZonedRange, formatRelativeZoned,
+  convertPlainDateTimeToZoned, addZoned, subtractZoned,
+  startOfZoned, endOfZoned, startOfQuarterForZoned, endOfQuarterForZoned,
+  getLocaleZonedStartOfWeek, getLocaleZonedEndOfWeek,
+  clampZoned, closestZonedTo, mapZonedHoursInDay, getHoursInZonedDay,
+  setZoned, getZonedOffset, getZonedOffsetAs, getTimeZoneOffset,
+  formatTimeZoneName, isInDaylightSaving
+} from "@northguild/gmt/zoned";
+```
+
+## Core Patterns
+
+### Get current time in a timezone
+
+```ts
+const now = getZonedNow("America/New_York"); // "2024-03-15T10:30:45"
+const today = getZonedToday("America/New_York"); // "2024-03-15"
+```
+
+### Format zoned datetime
+
+```ts
+formatZonedDateTime("2024-03-15T14:30:45[America/New_York]", "en-US");
+// "3/15/2024, 10:30:45 AM"
+```
+
+### Format zoned range
+
+```ts
+const from = "2024-02-29T10:00:00-05:00[America/New_York]";
+const to = "2024-02-29T12:00:00-05:00[America/New_York]";
+formatZonedRange(from, to, "en-US", { dateStyle: "long", timeStyle: "short" });
+// "February 29, 2024, 10:00 AM – 12:00 PM"
+```
+
+> Both endpoints must share the same IANA timezone. Mismatched zones return `""`.
+
+### Format relative zoned datetime (DST-safe)
+
+```ts
+const value = "2024-03-15T10:00:00-05:00[America/New_York]";
+const reference = "2024-03-15T12:00:00-05:00[America/New_York]";
+formatRelativeZoned(value, "en-US", { reference }); // "2 hours ago"
+```
+
+`formatRelativeZoned` computes the diff via `Temporal.ZonedDateTime` arithmetic, so it correctly handles DST transitions.
+
+### Validate and parse timezone
+
+```ts
+isValidTimeZone("America/New_York"); // true
+parseTimezoneFromZoned("2024-03-15T14:30:45[America/New_York]"); // "America/New_York"
+```
+
+### Get zoned date components
+
+```ts
+const zoned = "2024-03-15T14:30:45[America/New_York]";
+getYear(zoned); // 2024
+getMonth(zoned); // 3
+getDay(zoned); // 15
+```
+
+### Convert plain datetime to zoned (with DST disambiguation)
+
+```ts
+convertPlainDateTimeToZoned("2024-03-15T14:30:45", "America/New_York");
+// "2024-03-15T14:30:45.000-04:00[America/New_York]"
+```
+
+Pass `disambiguation` to control gap/overlap resolution: `"compatible"` (default), `"earlier"`, `"later"`, or `"reject"`. See [DST Disambiguation](../../../../docs/dst-disambiguation.md).
+
+### Add/subtract duration from zoned datetime
+
+```ts
+addZoned("2024-03-15T14:30:45[America/New_York]", { days: 1 });
+// "2024-03-16T14:30:45-04:00[America/New_York]"
+```
+
+Same `disambiguation` option, but it only affects fall-back overlaps — it has **no effect** on spring-forward gaps. See [DST Disambiguation](../../../../docs/dst-disambiguation.md#which-function-do-i-actually-need).
+
+### Jump to boundary (start/end of unit, quarter, hours-in-day)
+
+```ts
+startOfZoned("2024-03-15T14:30:45[America/New_York]", "month");
+// "2024-03-01T00:00:00-05:00[America/New_York]"
+
+endOfZoned("2024-03-15T14:30:45[America/New_York]", "hour");
+// "2024-03-15T14:59:59.999999999-04:00[America/New_York]"
+```
+
+These accept `disambiguation` (full gap/overlap control) and `offset` (`"prefer" | "use" | "ignore" | "reject"`, default `"ignore"`). Leave `offset` at default unless you deliberately need Temporal's raw `.with()` semantics. See [The offset parameter](../../../../docs/dst-disambiguation.md#the-offset-parameter).
+
+### Set one or more fields directly
+
+```ts
+setZoned("2024-03-15T14:30:45[America/New_York]", { hour: 9 });
+// "2024-03-15T09:30:45-04:00[America/New_York]"
+
+setZoned(
+  "2024-11-03T01:45:00-05:00[America/New_York]",
+  { minute: 0 },
+  { disambiguation: "reject" },
+);
+// "" — offset defaults to "ignore" so disambiguation actually fires on this fall-back overlap
+```
+
+`setZoned`/`setUnix`/`setUtc` wrap `Temporal.ZonedDateTime.prototype.with()`, resolving every supplied field in a single atomic overflow pass — the safe alternative to composing `addZoned()`/`addUnix()`/`addUtc()` calls field-by-field, and the only construction path that can reproduce `startOfZoned`'s disambiguation-plus-offset handling (`addZoned()` has no `offset` control equivalent, because `ZonedDateTime.prototype.add()` doesn't accept `disambiguation`/`offset` at all). They accept `disambiguation`, `offset` (default `"ignore"`, same rule as the `startOfZoned` family), and `overflow` (real effect here, since fields are caller-supplied rather than fixed literals). `setUtc`'s `disambiguation`/`offset` are accepted for signature consistency but are permanently inert — `"UTC"` has no DST transitions.
+
+### Cycle (wrap) a single field instead of setting it directly (E6)
+
+```ts
+import { cycleZoned } from "@northguild/gmt";
+
+cycleZoned("2024-12-15T09:30:00-06:00[America/Chicago]", "month", 1);
+// "2024-01-15T09:30:00-06:00[America/Chicago]" — wraps, stays in the same year
+
+cycleZoned("2024-03-10T01:30:00-06:00[America/Chicago]", "hour", 1);
+// "2024-03-10T03:30:00-05:00[America/Chicago]" — cycled hour lands in a spring-forward
+// gap; disambiguation ("compatible" by default) resolves it the same way setZoned does
+
+cycleZoned(
+  "2024-11-03T00:30:00-05:00[America/Chicago]",
+  "hour",
+  1,
+  { disambiguation: "reject" },
+);
+// "" — cycled hour lands in the fall-back overlap; offset defaults to "ignore" so
+// disambiguation actually fires (see the C3 trap below)
+```
+
+`cycleZoned` is not `addZoned`: it adjusts one field and wraps at that field's own min/max (`hour` always `0–23`, etc.) instead of carrying into the next larger field — building on `setZoned`'s J1 field-setting foundation the same way `cycleDate`/`cycleDateTime`/`cycleTime` build on `setDate`/`setDateTime`/`setTime` (see the `calculate-dates` skill). The wrap bounds themselves are plain, DST-agnostic local-field bounds; whatever DST edge case the wrapped local time lands on is then resolved by `disambiguation`/`offset`, passed straight through to `setZoned`, exactly like any other field-set call.
+
+### Get the number of hours in a zoned calendar day
+
+```ts
+getHoursInZonedDay("2024-03-10T12:00:00-04:00[America/New_York]");
+// 23 — spring-forward day "loses" an hour
+
+getHoursInZonedDay("2024-11-03T12:00:00-05:00[America/New_York]");
+// 25 — fall-back day "gains" an hour
+
+getHoursInZonedDay("2024-02-29T12:00:00+00:00[UTC]");
+// 24 — normal day
+```
+
+Returns `23`, `24`, or `25` depending on whether the local calendar day contains a DST transition — or a fractional value for zones whose DST shift isn't a whole hour (e.g. `Australia/Lord_Howe`'s 30-minute shift returns `23.5`/`24.5`). Returns `null` for invalid input. This is zoned-only — timezone-free days are always 24 hours.
+
+### Locale-aware week boundaries
+
+```ts
+getLocaleZonedStartOfWeek("2024-02-29T12:00:00+00:00[UTC]", "en-US");
+// "2024-02-25T00:00:00+00:00[UTC]" (Sunday)
+
+getLocaleZonedStartOfWeek("2024-02-29T12:00:00+00:00[UTC]", "fr-FR");
+// "2024-02-26T00:00:00+00:00[UTC]" (Monday)
+```
+
+Derives the week's first day from the locale (same as plain `getLocaleStartOfWeek`/`getLocaleEndOfWeek`). Accepts `disambiguation`/`offset` options; `offset` must stay at `"ignore"` for `disambiguation` to take effect.
+
+### Clamp a zoned datetime to a range
+
+```ts
+clampZoned(
+  "2024-03-15T12:00:00[America/New_York]",
+  "2024-03-01T00:00:00[America/New_York]",
+  "2024-03-31T23:59:59[America/New_York]",
+);
+// "2024-03-15T12:00:00-04:00[America/New_York]"
+```
+
+### Find nearest zoned datetime to a target
+
+```ts
+closestZonedTo(
+  "2024-03-15T12:00:00[America/New_York]",
+  ["2024-03-01T00:00:00[America/New_York]", "2024-03-20T00:00:00[America/New_York]"],
+);
+// "2024-03-18T00:00:00-04:00[America/New_York]"
+```
+
+Returns `null` for empty candidates or invalid target.
+
+### Read a zoned value's UTC offset
+
+```ts
+getZonedOffset("2024-07-15T12:00:00-04:00[America/New_York]"); // "-04:00"
+getZonedOffsetAs("2024-07-15T12:00:00-04:00[America/New_York]", "minutes"); // -240
+getTimeZoneOffset("America/New_York", "2024-07-15T12:00:00Z"); // "-04:00"
+```
+
+`getZonedOffset`/`getZonedOffsetAs` read the offset off an existing zoned value. `getTimeZoneOffset` looks one up for a bare timezone + instant, without needing a zoned value in hand.
+
+### Format a timezone's display name
+
+```ts
+formatTimeZoneName("America/New_York", "en-US", { style: "shortGeneric" }); // "ET"
+formatTimeZoneName("America/New_York", "en-US", { style: "long" }); // "Eastern Standard Time" or "Eastern Daylight Time", depending on today's date
+```
+
+`style` covers all six `Intl.DateTimeFormatOptions` `timeZoneName` values. `"shortGeneric"`/`"longGeneric"` are season-independent (`"ET"`, `"Eastern Time"`); `"short"`/`"long"`/`"shortOffset"`/`"longOffset"` name the zone's *current* offset and flip between standard/daylight forms depending on when this is called — there's no instant parameter to pin it to.
+
+### Check whether an instant is in daylight saving time
+
+```ts
+isInDaylightSaving("2024-07-15T12:00:00-04:00[America/New_York]"); // true
+isInDaylightSaving("2024-01-15T12:00:00-05:00[America/New_York]"); // false
+```
+
+See the Common Mistakes entry below for how this differs from `hasDaylightSaving` and `getDstTransitions`.
+
+## Timezone Reference
+
+See [references/timezones.md](references/timezones.md) for common IANA timezone identifiers.
+
+## Runtime ICU Data
+
+Zoned formatters delegate locale and timezone-name rendering to the host runtime's `Intl.DateTimeFormat`. Output depends on ICU data shipped with the running Node or browser. For consistent non-English output, deploy on a full-ICU Node build or polyfill `Intl`.
+
+## Calendar-Aware Zoned Datetimes
+
+`convertZonedToCalendar(value, calendar)` expresses a zoned datetime in any of the 13 supported
+calendar systems, keeping the instant, wall time, UTC offset and IANA zone unchanged:
+
+```
+<calendar-native-date>T<time><offset>[u-ca=<id>[;era=<era>]][<timeZone>]
+```
+
+```ts
+convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "hebrew");
+// "5785-01-01T14:30:45-04:00[u-ca=hebrew][America/New_York]"
+convertZonedToCalendar("2024-10-03T14:30:45+00:00[UTC]", "japanese");
+// "0006-10-03T14:30:45+00:00[u-ca=japanese;era=reiwa][UTC]"
+```
+
+`addZoned`/`subtractZoned` then do calendar-unit arithmetic and DST resolution in a single
+operation, re-deriving the calendar tag, era, wall time and offset from the result:
+
+```ts
+addZoned("0031-04-30T12:00:00+09:00[u-ca=japanese;era=heisei][Asia/Tokyo]", { days: 1 });
+// "0001-05-01T12:00:00+09:00[u-ca=japanese;era=reiwa][Asia/Tokyo]" — era changes
+```
+
+Validate with `isValidCalendarZonedDateTime` (not `isValidZonedDateTime`, which still rejects the
+annotation). See the Common Mistakes section for the segment-ordering trap.
+
+## Common Mistakes
+
+### Writing the calendar annotation in RFC 9557 order
+
+**This is the trap most likely to be hit by pattern-matching against Temporal's own docs.**
+
+GMT's calendar-annotated zoned string puts `[u-ca=...]` **before** `[timeZone]`:
+
+```
+5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]   // correct — GMT's grammar
+5784-06-15T14:30:00-05:00[America/New_York][u-ca=hebrew]   // WRONG — RFC 9557 / Temporal order
+```
+
+Every GMT function returns its sentinel for the second form. That looks like GMT being fussy; it
+is GMT refusing to guess. Temporal's ordering is a *silent misparse* here:
+
+```ts
+Temporal.ZonedDateTime.from("5784-01-01T14:30:00-05:00[America/New_York][u-ca=hebrew]");
+// SUCCEEDS — and reads 5784 as an ISO year, not a Hebrew year. A ~3760-year error, no throw.
+```
+
+GMT's digits are calendar-native (Hebrew year 5784), unlike Temporal's convention, which keeps ISO
+digits and only tags the calendar. The two shapes are indistinguishable by inspection, so GMT
+accepts exactly one ordering and rejects the other outright. The `;era=` suffix
+(`[u-ca=japanese;era=heisei]`) is not valid RFC 9557 at *any* ordering, so round-tripping GMT's
+string through `Temporal.ZonedDateTime.from` was never possible regardless.
+
+Always build these strings with `convertZonedToCalendar`, never by hand or by string concatenation.
+
+### Converting a calendar-annotated PlainDate to a zoned value drops the calendar
+
+```ts
+const hebrew = convertDateToCalendar("2024-10-03", "hebrew"); // "5785-01-01[u-ca=hebrew]"
+convertPlainDateTimeToZoned(`${hebrew}T14:30:00`, "America/New_York"); // "" — not a zoned grammar
+```
+
+Reaching for `convertDateToCalendar` and then a zoned conversion silently produces a Gregorian
+value (or a sentinel), and the calendar-unit arithmetic that follows is then wrong in exactly the
+cases the calendar was chosen for. Use `convertZonedToCalendar` on the zoned value instead:
+
+```ts
+convertZonedToCalendar("2024-10-03T14:30:45-04:00[America/New_York]", "hebrew");
+// "5785-01-01T14:30:45-04:00[u-ca=hebrew][America/New_York]"
+
+addZoned("5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]", { months: 1 });
+// "5784-07-15T14:30:00-04:00[u-ca=hebrew][America/New_York]"
+// Adar I -> Adar AND EST -> EDT in one call — no ordering of plain/ and zoned/ operations
+// reproduces this.
+```
+
+### Assuming every `zoned/` function accepts the annotation
+
+Only `addZoned`, `subtractZoned`, `diffZoned`, `diffZonedAsDuration`, `convertZonedToCalendar` and
+the `zoned/interval/*` family do. Everything else — `formatZonedDateTime`, `roundZoned`,
+`setZoned`, `startOfZoned`, `parseDateFromZoned`, `convertZonedToUtc`, the business-day pair, and
+~60 more — still rejects it and returns its sentinel. `isValidZonedDateTime` also still returns
+`false` for it; validate with `isValidCalendarZonedDateTime` when you mean the calendar grammar.
+
+### Using offset instead of IANA timezone
+
+Wrong: `"2024-03-15T14:30:45-05:00"`
+Correct: `"2024-03-15T14:30:45[America/New_York]"`
+
+### Not validating timezone before use
+
+Wrong: `getZonedNow("Invalid/Zone")` — may return `""`
+Correct: validate with `isValidTimeZone()` first.
+
+### Assuming `addZoned`/`subtractZoned` rejects DST gaps
+
+`disambiguation: "reject"` only catches fall-back overlaps, not spring-forward gaps. Use `convertPlainDateTimeToZoned` with `disambiguation: "reject"` if you need gap-safety.
+
+### Passing `offset: "prefer"` with `disambiguation`
+
+`offset: "prefer"` keeps the source's offset before disambiguation is consulted, so `disambiguation` never fires. Leave `offset` at its default `"ignore"`.
+
+### "I passed `disambiguation: 'reject'` to `setZoned` and it didn't throw"
+
+This is the C3 silent-no-op trap, and `setZoned`/`setUnix` hit it head-on because they're `.with()`-based. `offset` defaults to `"ignore"` specifically so `disambiguation` takes effect — but if you've also passed `offset: "prefer"` (or anything other than `"ignore"`), the source's still-valid offset gets kept and `disambiguation` is silently never consulted:
+
+```ts
+const source = "2024-11-03T01:45:00-05:00[America/New_York]"; // second, repeated 1am of the fall-back overlap
+
+setZoned(source, { minute: 0 }, { disambiguation: "reject" });
+// "" — offset defaults to "ignore", so disambiguation actually fires and "reject" throws
+
+setZoned(source, { minute: 0 }, { disambiguation: "reject", offset: "prefer" });
+// "2024-11-03T01:00:00-05:00[America/New_York]" — offset:"prefer" keeps the source's
+// still-valid -05:00 offset, so disambiguation is never consulted and "reject" never fires
+```
+
+Leave `offset` at its default unless you deliberately need Temporal's raw `.with()` semantics. See [The offset parameter](../../../../docs/dst-disambiguation.md#the-offset-parameter).
+
+### Confusing `hasDaylightSaving`, `getDstTransitions`, and `isInDaylightSaving`
+
+The names are close enough to be misread. Four different DST-related questions, four different functions:
+
+| Question | Function | Scope |
+| --- | --- | --- |
+| Does this zone observe DST at all? | `hasDaylightSaving(timeZone)` | Zone-level, no instant |
+| Where do this zone's transitions fall? | `getDstTransitions(timeZone, year)` | Enumerates instants |
+| Is *this particular instant* currently in DST? | `isInDaylightSaving(value)` | A single zoned value |
+| What happens when construction lands on an ambiguous/nonexistent instant? | `disambiguation` / `offset` | Orthogonal — a construction-time choice, not a query |
+
+Picking the wrong one is a common mistake: `hasDaylightSaving("America/New_York")` is `true` year-round (the zone observes DST), which tells you nothing about whether a *specific* March 15th value is currently in it — that's `isInDaylightSaving`'s job.
+
+### Reaching for `cycleZoned` when calendar arithmetic is wanted (or vice versa)
+
+`cycleZoned` is not `addZoned`. Cycling `month` by `+1` from December stays in the same year — `cycleZoned("2024-12-15T09:30:00-06:00[America/Chicago]", "month", 1)` returns `"2024-01-15T09:30:00-06:00[America/Chicago]"`, not `"2025-01-15..."`. Use `addZoned`/`subtractZoned` for calendar arithmetic where crossing a year boundary is the expected outcome; use `cycleZoned` only when a single field (e.g. a datepicker segment) must stay isolated from the others.
+
+## References
+
+- [Common IANA timezones](references/timezones.md)
+- [DST Disambiguation](../../../../docs/dst-disambiguation.md)
+- [Temporal.ZonedDateTime](https://tc39.es/proposal-temporal/docs/zoneddatetime.html)

package/skills/zoned-date-ops/references/timezones.md

@@ -0,0 +1,13 @@
+# Common IANA Timezones
+
+| Region | Identifiers |
+|--------|-------------|
+| US | `America/New_York`, `America/Los_Angeles`, `America/Chicago`, `America/Denver` |
+| Canada | `America/Toronto`, `America/Vancouver`, `America/Edmonton` |
+| Europe | `Europe/London`, `Europe/Paris`, `Europe/Berlin`, `Europe/Moscow` |
+| Asia | `Asia/Tokyo`, `Asia/Shanghai`, `Asia/Singapore`, `Asia/Kolkata`, `Asia/Dubai` |
+| Pacific | `Pacific/Auckland`, `Pacific/Honolulu`, `Pacific/Fiji` |
+| Australia | `Australia/Sydney`, `Australia/Melbourne`, `Australia/Perth` |
+| UTC | `UTC` |
+
+For the full list, call `getTimeZones()` (~422 entries, varies by runtime/ICU) or see the [IANA timezone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).