@ultimat3/time 1.0.0

package/src/zones.js

@@ -0,0 +1,116 @@
+/**
+ * IANA timezone primitives. The UTC offset of a zone is derived from
+ * `Intl.DateTimeFormat.formatToParts` — the runtime already ships the tzdata, so there
+ * is no offset table to keep in sync and no `date-fns-tz` dependency.
+ */
+import { timezoneInvalid } from './errors';
+export const UTC = 'UTC';
+/** ES2024 `Intl` accepts `+01:00` as a zone; we do not — a fixed offset has no DST rules. */
+const NUMERIC_OFFSET = /^[+-]/;
+export function isValidTimeZone(zone) {
+    if (zone === '' || NUMERIC_OFFSET.test(zone))
+        return false;
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone: zone });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function assertTimeZone(zone) {
+    if (!isValidTimeZone(zone))
+        throw timezoneInvalid(zone);
+    return zone;
+}
+/**
+ * Read the zone's wall clock for an instant. `hourCycle: 'h23'` is essential: without it
+ * some locales render midnight as hour 24 and every calculation downstream drifts a day.
+ */
+export function zonePartsAt(zone, at) {
+    const parts = partsFormatterFor(zone).formatToParts(at);
+    const read = (type) => {
+        const value = parts.find((part) => part.type === type)?.value;
+        if (value === undefined)
+            throw timezoneInvalid(zone);
+        return Number.parseInt(value, 10);
+    };
+    return {
+        year: read('year'),
+        month: read('month'),
+        day: read('day'),
+        hour: read('hour') % 24,
+        minute: read('minute'),
+        second: read('second'),
+    };
+}
+/**
+ * Offset in **minutes east of UTC** at a given instant: `Europe/Berlin` → 60 or 120,
+ * `Asia/Kathmandu` → 345, `America/New_York` → -300 or -240.
+ *
+ * The trick: format the instant in the zone, then re-read those wall-clock fields *as if
+ * they were UTC*. The difference between that and the real epoch is the offset.
+ */
+export function offsetAt(zone, at) {
+    const parts = zonePartsAt(zone, at);
+    const asIfUtc = Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second);
+    // Offsets are whole minutes; rounding absorbs the sub-second part `asIfUtc` drops.
+    return Math.round((asIfUtc - at.getTime()) / 60_000);
+}
+/** `+01:00`, `-04:00`, `+05:45`, `Z`. */
+export function offsetLabel(minutes) {
+    if (minutes === 0)
+        return 'Z';
+    const sign = minutes < 0 ? '-' : '+';
+    const absolute = Math.abs(minutes);
+    const hours = Math.floor(absolute / 60);
+    return `${sign}${pad2(hours)}:${pad2(absolute % 60)}`;
+}
+/** Locale-aware zone label: `CET`, `GMT+5:45`, `Central European Standard Time`. */
+export function zoneAbbrev(zone, at, locale = 'en-US', style = 'short') {
+    const formatter = new Intl.DateTimeFormat(locale, {
+        timeZone: zone,
+        timeZoneName: style,
+        hourCycle: 'h23',
+    });
+    const label = formatter.formatToParts(at).find((part) => part.type === 'timeZoneName')?.value;
+    return label ?? offsetLabel(offsetAt(zone, at));
+}
+/** True when the zone observes a different offset at some point in the surrounding year. */
+export function observesDst(zone, at) {
+    const offsets = new Set();
+    for (let month = 0; month < 12; month += 1) {
+        const probe = new Date(at.getTime());
+        probe.setUTCMonth(probe.getUTCMonth() + month);
+        offsets.add(offsetAt(zone, probe));
+    }
+    return offsets.size > 1;
+}
+const formatters = new Map();
+function partsFormatterFor(zone) {
+    const cached = formatters.get(zone);
+    if (cached !== undefined)
+        return cached;
+    let formatter;
+    try {
+        formatter = new Intl.DateTimeFormat('en-US', {
+            timeZone: zone,
+            hourCycle: 'h23',
+            year: 'numeric',
+            month: '2-digit',
+            day: '2-digit',
+            hour: '2-digit',
+            minute: '2-digit',
+            second: '2-digit',
+        });
+    }
+    catch {
+        throw timezoneInvalid(zone);
+    }
+    formatters.set(zone, formatter);
+    return formatter;
+}
+function pad2(value) {
+    return String(value).padStart(2, '0');
+}
+//# sourceMappingURL=zones.js.map

package/src/zones.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zones.js","sourceRoot":"","sources":["zones.ts"],"names":[],"mappings":"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"}

package/src/zones.ts

@@ -0,0 +1,167 @@
+/**
+ * IANA timezone primitives. The UTC offset of a zone is derived from
+ * `Intl.DateTimeFormat.formatToParts` — the runtime already ships the tzdata, so there
+ * is no offset table to keep in sync and no `date-fns-tz` dependency.
+ */
+
+import { timezoneInvalid } from './errors';
+import type { Instant } from './instant';
+
+/** An IANA identifier: `Europe/Berlin`, `Asia/Kathmandu`, `UTC`. Never `CET`, never `+01:00`. */
+export type TimeZone = string;
+
+export const UTC: TimeZone = 'UTC';
+
+/** ES2024 `Intl` accepts `+01:00` as a zone; we do not — a fixed offset has no DST rules. */
+const NUMERIC_OFFSET = /^[+-]/;
+
+/**
+ * The package's only builder of a UTC epoch from calendar fields, because `Date.UTC` remaps
+ * years 0–99 onto 1900–1999 — silently, so a first-century wall clock resolves 1900 years off
+ * and every derived answer (offset, weekday, day count) is wrong without ever throwing.
+ * Overflow still carries exactly as `Date.UTC` does: day 0, day 32 and hour 24 all roll.
+ */
+export function utcEpoch(
+  year: number,
+  month: number,
+  day: number,
+  hour = 0,
+  minute = 0,
+  second = 0,
+): number {
+  const at = new Date(0);
+  at.setUTCFullYear(year, month - 1, day);
+  at.setUTCHours(hour, minute, second, 0);
+  return at.getTime();
+}
+
+export function isValidTimeZone(zone: string): boolean {
+  if (zone === '' || NUMERIC_OFFSET.test(zone)) return false;
+  try {
+    new Intl.DateTimeFormat('en-US', { timeZone: zone });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function assertTimeZone(zone: string): TimeZone {
+  if (!isValidTimeZone(zone)) throw timezoneInvalid(zone);
+  return zone;
+}
+
+/** Wall-clock fields of an instant in a zone, seconds precision. */
+export interface ZoneParts {
+  year: number;
+  month: number;
+  day: number;
+  hour: number;
+  minute: number;
+  second: number;
+}
+
+/**
+ * Read the zone's wall clock for an instant. `hourCycle: 'h23'` is essential: without it
+ * some locales render midnight as hour 24 and every calculation downstream drifts a day.
+ */
+export function zonePartsAt(zone: TimeZone, at: Instant): ZoneParts {
+  const parts = partsFormatterFor(zone).formatToParts(at);
+  const read = (type: Intl.DateTimeFormatPartTypes): number => {
+    const value = parts.find((part) => part.type === type)?.value;
+    if (value === undefined) throw timezoneInvalid(zone);
+    return Number.parseInt(value, 10);
+  };
+  return {
+    year: read('year'),
+    month: read('month'),
+    day: read('day'),
+    hour: read('hour') % 24,
+    minute: read('minute'),
+    second: read('second'),
+  };
+}
+
+/**
+ * Offset in **minutes east of UTC** at a given instant: `Europe/Berlin` → 60 or 120,
+ * `Asia/Kathmandu` → 345, `America/New_York` → -300 or -240.
+ *
+ * The trick: format the instant in the zone, then re-read those wall-clock fields *as if
+ * they were UTC*. The difference between that and the real epoch is the offset.
+ */
+export function offsetAt(zone: TimeZone, at: Instant): number {
+  const parts = zonePartsAt(zone, at);
+  const asIfUtc = utcEpoch(
+    parts.year,
+    parts.month,
+    parts.day,
+    parts.hour,
+    parts.minute,
+    parts.second,
+  );
+  // Offsets are whole minutes; rounding absorbs the sub-second part `asIfUtc` drops.
+  return Math.round((asIfUtc - at.getTime()) / 60_000);
+}
+
+/** `+01:00`, `-04:00`, `+05:45`, `Z`. */
+export function offsetLabel(minutes: number): string {
+  if (minutes === 0) return 'Z';
+  const sign = minutes < 0 ? '-' : '+';
+  const absolute = Math.abs(minutes);
+  const hours = Math.floor(absolute / 60);
+  return `${sign}${pad2(hours)}:${pad2(absolute % 60)}`;
+}
+
+/** Locale-aware zone label: `CET`, `GMT+5:45`, `Central European Standard Time`. */
+export function zoneAbbrev(
+  zone: TimeZone,
+  at: Instant,
+  locale = 'en-US',
+  style: 'short' | 'long' | 'shortOffset' | 'longOffset' = 'short',
+): string {
+  const formatter = new Intl.DateTimeFormat(locale, {
+    timeZone: zone,
+    timeZoneName: style,
+    hourCycle: 'h23',
+  });
+  const label = formatter.formatToParts(at).find((part) => part.type === 'timeZoneName')?.value;
+  return label ?? offsetLabel(offsetAt(zone, at));
+}
+
+/** True when the zone observes a different offset at some point in the surrounding year. */
+export function observesDst(zone: TimeZone, at: Instant): boolean {
+  const offsets = new Set<number>();
+  for (let month = 0; month < 12; month += 1) {
+    const probe = new Date(at.getTime());
+    probe.setUTCMonth(probe.getUTCMonth() + month);
+    offsets.add(offsetAt(zone, probe as Instant));
+  }
+  return offsets.size > 1;
+}
+
+const formatters = new Map<string, Intl.DateTimeFormat>();
+
+function partsFormatterFor(zone: TimeZone): Intl.DateTimeFormat {
+  const cached = formatters.get(zone);
+  if (cached !== undefined) return cached;
+  let formatter: Intl.DateTimeFormat;
+  try {
+    formatter = new Intl.DateTimeFormat('en-US', {
+      timeZone: zone,
+      hourCycle: 'h23',
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+      hour: '2-digit',
+      minute: '2-digit',
+      second: '2-digit',
+    });
+  } catch {
+    throw timezoneInvalid(zone);
+  }
+  formatters.set(zone, formatter);
+  return formatter;
+}
+
+function pad2(value: number): string {
+  return String(value).padStart(2, '0');
+}