@ultimat3/time 1.0.0

package/src/schedule.js.map

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

package/src/schedule.ts

@@ -0,0 +1,90 @@
+/**
+ * "Send at 09:00 local" — the scheduling primitive digests, reminders and drip campaigns
+ * are built from. Local means the *recipient's* local, and it survives DST.
+ */
+
+import { scheduleInvalid, timezoneInvalid } from './errors';
+import type { Instant } from './instant';
+import { fromZoned, toZoned } from './zoned';
+import { assertTimeZone, type TimeZone } from './zones';
+
+export interface LocalSlot {
+  zone: TimeZone;
+  /** 0–23, wall clock in `zone`. */
+  hour: number;
+  /** 0–59. */
+  minute?: number;
+  second?: number;
+}
+
+/**
+ * Next instant matching the local `HH:mm` in `zone`, strictly after `after`.
+ *
+ * Walks forward day by day on the *local* calendar rather than adding 86 400 000 ms, so
+ * a 23- or 25-hour day does not shift the slot. If the slot falls in a spring-forward
+ * gap, `{ gap: 'next' }` picks the first existing local time instead of skipping the day.
+ */
+/** Wall-clock fields are never wrapped or clamped — a shifted schedule beats no schedule. */
+function assertWallField(field: string, value: number, max: number): void {
+  if (!Number.isInteger(value) || value < 0 || value > max) {
+    throw scheduleInvalid(field, value, `an integer 0-${String(max)}`);
+  }
+}
+
+export function nextLocalSlot(slot: LocalSlot, after: Instant): Instant {
+  assertTimeZone(slot.zone);
+  assertWallField('slot.hour', slot.hour, 23);
+  const minute = slot.minute ?? 0;
+  const second = slot.second ?? 0;
+  // Validated too: a minute of 90 would otherwise roll into the next hour and ship a
+  // schedule an hour off, which is exactly the class of bug this package exists to prevent.
+  assertWallField('slot.minute', minute, 59);
+  assertWallField('slot.second', second, 59);
+  const start = toZoned(after, slot.zone);
+
+  for (let dayOffset = 0; dayOffset < 4; dayOffset += 1) {
+    const candidate = fromZoned(
+      {
+        year: start.year,
+        month: start.month,
+        day: start.day + dayOffset,
+        hour: slot.hour,
+        minute,
+        second,
+      },
+      slot.zone,
+      { gap: 'next', overlap: 'first' },
+    );
+    if (candidate.getTime() > after.getTime()) return candidate;
+  }
+
+  // Four local days always contain the slot; reaching here means the zone data is broken.
+  throw timezoneInvalid(slot.zone);
+}
+
+/** The next `count` daily slots — a preview for the schedule screen. */
+export function nextLocalSlots(slot: LocalSlot, after: Instant, count: number): Instant[] {
+  const slots: Instant[] = [];
+  let cursor = after;
+  for (let index = 0; index < count; index += 1) {
+    cursor = nextLocalSlot(slot, cursor);
+    slots.push(cursor);
+  }
+  return slots;
+}
+
+export interface WeeklySlot extends LocalSlot {
+  /** ISO weekday: 1 = Monday … 7 = Sunday. */
+  weekday: number;
+}
+
+/** Next `weekday` at the local time, strictly after `after`. */
+export function nextWeeklySlot(slot: WeeklySlot, after: Instant): Instant {
+  let cursor = after;
+  for (let index = 0; index < 8; index += 1) {
+    const candidate = nextLocalSlot(slot, cursor);
+    if (toZoned(candidate, slot.zone).weekday === slot.weekday) return candidate;
+    cursor = candidate;
+  }
+  throw timezoneInvalid(slot.zone);
+}

package/src/zoned.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The two conversions everything else is built on: instant → wall clock, and wall clock →
+ * instant. `fromZoned` is the DST-correct one, and it is the reason this package exists.
+ */
+import { type Instant } from './instant';
+import { type TimeZone } from './zones';
+/** A local date and time with no zone attached — meaningless until paired with one. */
+export interface WallClock {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second?: number;
+    millisecond?: number;
+}
+export interface ZonedDateTime {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+    millisecond: number;
+    zone: TimeZone;
+    /** Minutes east of UTC in effect at this instant. */
+    offsetMinutes: number;
+    /** ISO weekday: 1 = Monday … 7 = Sunday. */
+    weekday: number;
+}
+/** What to do with a wall-clock time that does not exist (spring forward). */
+export type GapPolicy = 'next' | 'previous' | 'throw';
+/** What to do with a wall-clock time that happens twice (fall back). */
+export type OverlapPolicy = 'first' | 'second' | 'throw';
+export interface FromZonedOptions {
+    gap?: GapPolicy;
+    overlap?: OverlapPolicy;
+}
+export type ZonedResolution = 'exact' | 'gap' | 'overlap';
+export interface FromZonedResult {
+    instant: Instant;
+    /** Which case the wall-clock time fell into — log it when scheduling. */
+    resolution: ZonedResolution;
+    offsetMinutes: number;
+}
+/** Instant → the zone's wall clock. */
+export declare function toZoned(at: Instant, zone: TimeZone): ZonedDateTime;
+/**
+ * Wall clock + zone → instant, DST-correct.
+ *
+ * Algorithm (search and verify — never `offset * 3600`):
+ *  1. Read the wall-clock fields as if they were UTC. Call that `target`.
+ *  2. Collect the candidate offsets in force around `target` — 24h before, at, and 24h
+ *     after. Any DST transition puts both of its offsets in that set.
+ *  3. For each distinct offset `o`, the candidate instant is `target - o`.
+ *  4. Verify each candidate by converting it *back* with `toZoned`. A candidate that does
+ *     not reproduce the requested wall clock is not a real instant for it.
+ *      - two distinct verified candidates → the hour repeats (overlap)
+ *      - exactly one                      → normal case
+ *      - none                             → the hour was skipped (gap)
+ *
+ * Milliseconds ride along untouched: every real offset is a whole number of minutes.
+ */
+export declare function fromZonedDetailed(wall: WallClock, zone: TimeZone, options?: FromZonedOptions): FromZonedResult;
+/** The common form: just the instant. */
+export declare function fromZoned(wall: WallClock, zone: TimeZone, options?: FromZonedOptions): Instant;
+/** Midnight local, as an instant. DST-correct: on a spring-forward day it still exists. */
+export declare function startOfDay(at: Instant, zone: TimeZone): Instant;
+/** The last millisecond of the local day. */
+export declare function endOfDay(at: Instant, zone: TimeZone): Instant;
+/**
+ * Add calendar days in a zone, keeping the wall-clock time. Adding one day is 23, 24 or
+ * 25 hours depending on the transition — which is why this is not `+ 86_400_000`.
+ */
+export declare function addDaysInZone(at: Instant, days: number, zone: TimeZone): Instant;
+/** `2026-03-14` for the given instant in the given zone. */
+export declare function isoDateInZone(at: Instant, zone: TimeZone): string;
+/** True when both instants fall on the same local calendar day. */
+export declare function isSameLocalDay(left: Instant, right: Instant, zone: TimeZone): boolean;
+//# sourceMappingURL=zoned.d.ts.map

package/src/zoned.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zoned.d.ts","sourceRoot":"","sources":["zoned.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAS,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAA4B,KAAK,QAAQ,EAAe,MAAM,SAAS,CAAC;AAE/E,uFAAuF;AACvF,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,QAAQ,CAAC;IACf,qDAAqD;IACrD,aAAa,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,8EAA8E;AAC9E,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC;AACtD,wEAAwE;AACxE,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEzD,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,KAAK,GAAG,SAAS,CAAC;AAE1D,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,yEAAyE;IACzE,UAAU,EAAE,eAAe,CAAC;IAC5B,aAAa,EAAE,MAAM,CAAC;CACvB;AAID,uCAAuC;AACvC,wBAAgB,OAAO,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,GAAG,aAAa,CAalE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,QAAQ,EACd,OAAO,GAAE,gBAAqB,GAC7B,eAAe,CA2CjB;AAED,yCAAyC;AACzC,wBAAgB,SAAS,CACvB,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,QAAQ,EACd,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAET;AAED,2FAA2F;AAC3F,wBAAgB,UAAU,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAO/D;AAED,6CAA6C;AAC7C,wBAAgB,QAAQ,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAQ7D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAehF;AAED,4DAA4D;AAC5D,wBAAgB,aAAa,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,CAGjE;AAED,mEAAmE;AACnE,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAErF"}

package/src/zoned.js

@@ -0,0 +1,146 @@
+/**
+ * The two conversions everything else is built on: instant → wall clock, and wall clock →
+ * instant. `fromZoned` is the DST-correct one, and it is the reason this package exists.
+ */
+import { dstAmbiguous, dstNonexistent } from './errors';
+import { addMs } from './instant';
+import { assertTimeZone, offsetAt, zonePartsAt } from './zones';
+const DEFAULTS = { gap: 'next', overlap: 'first' };
+/** Instant → the zone's wall clock. */
+export function toZoned(at, zone) {
+    assertTimeZone(zone);
+    const parts = zonePartsAt(zone, at);
+    const offsetMinutes = offsetAt(zone, at);
+    const asIfUtc = Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute);
+    return {
+        ...parts,
+        millisecond: at.getTime() - Math.floor(at.getTime() / 1000) * 1000,
+        zone,
+        offsetMinutes,
+        // getUTCDay on the as-if-UTC epoch gives the *local* weekday: 0 = Sunday.
+        weekday: ((new Date(asIfUtc).getUTCDay() + 6) % 7) + 1,
+    };
+}
+/**
+ * Wall clock + zone → instant, DST-correct.
+ *
+ * Algorithm (search and verify — never `offset * 3600`):
+ *  1. Read the wall-clock fields as if they were UTC. Call that `target`.
+ *  2. Collect the candidate offsets in force around `target` — 24h before, at, and 24h
+ *     after. Any DST transition puts both of its offsets in that set.
+ *  3. For each distinct offset `o`, the candidate instant is `target - o`.
+ *  4. Verify each candidate by converting it *back* with `toZoned`. A candidate that does
+ *     not reproduce the requested wall clock is not a real instant for it.
+ *      - two distinct verified candidates → the hour repeats (overlap)
+ *      - exactly one                      → normal case
+ *      - none                             → the hour was skipped (gap)
+ *
+ * Milliseconds ride along untouched: every real offset is a whole number of minutes.
+ */
+export function fromZonedDetailed(wall, zone, options = {}) {
+    assertTimeZone(zone);
+    const { gap, overlap } = { ...DEFAULTS, ...options };
+    const millisecond = wall.millisecond ?? 0;
+    // Normalize overflow first (day 32, hour 24, month 13) so callers can do naive calendar
+    // arithmetic — `addDaysInZone` relies on it — and so verification compares real fields.
+    const normal = normalizeWall(wall);
+    const target = Date.UTC(normal.year, normal.month - 1, normal.day, normal.hour, normal.minute, normal.second);
+    const probes = [target - 86_400_000, target, target + 86_400_000];
+    const offsets = new Set(probes.map((ms) => offsetAt(zone, new Date(ms))));
+    const verified = [];
+    for (const offsetMinutes of offsets) {
+        const candidate = target - offsetMinutes * 60_000;
+        if (matchesWall(candidate, zone, normal))
+            verified.push(candidate);
+    }
+    const distinct = [...new Set(verified)].sort((a, b) => a - b);
+    if (distinct.length > 1) {
+        if (overlap === 'throw')
+            throw dstAmbiguous(describeWall(normal), zone);
+        const chosen = overlap === 'first' ? distinct[0] : distinct[distinct.length - 1];
+        return finish(chosen ?? target, millisecond, zone, 'overlap');
+    }
+    const single = distinct[0];
+    if (single !== undefined)
+        return finish(single, millisecond, zone, 'exact');
+    // Gap: the requested wall clock was skipped. The two unverified candidates bracket it —
+    // the smaller lands before the transition, the larger after it.
+    if (gap === 'throw')
+        throw dstNonexistent(describeWall(normal), zone);
+    const bracket = [...offsets]
+        .map((offsetMinutes) => target - offsetMinutes * 60_000)
+        .sort((a, b) => a - b);
+    const chosen = gap === 'next' ? bracket[bracket.length - 1] : bracket[0];
+    return finish(chosen ?? target, millisecond, zone, 'gap');
+}
+/** The common form: just the instant. */
+export function fromZoned(wall, zone, options = {}) {
+    return fromZonedDetailed(wall, zone, options).instant;
+}
+/** Midnight local, as an instant. DST-correct: on a spring-forward day it still exists. */
+export function startOfDay(at, zone) {
+    const zoned = toZoned(at, zone);
+    return fromZoned({ year: zoned.year, month: zoned.month, day: zoned.day, hour: 0, minute: 0 }, zone, { gap: 'next' });
+}
+/** The last millisecond of the local day. */
+export function endOfDay(at, zone) {
+    const zoned = toZoned(at, zone);
+    const nextMidnight = fromZoned({ year: zoned.year, month: zoned.month, day: zoned.day + 1, hour: 0, minute: 0 }, zone, { gap: 'next' });
+    return addMs(nextMidnight, -1);
+}
+/**
+ * Add calendar days in a zone, keeping the wall-clock time. Adding one day is 23, 24 or
+ * 25 hours depending on the transition — which is why this is not `+ 86_400_000`.
+ */
+export function addDaysInZone(at, days, zone) {
+    const zoned = toZoned(at, zone);
+    return fromZoned({
+        year: zoned.year,
+        month: zoned.month,
+        day: zoned.day + days,
+        hour: zoned.hour,
+        minute: zoned.minute,
+        second: zoned.second,
+        millisecond: zoned.millisecond,
+    }, zone, { gap: 'next' });
+}
+/** `2026-03-14` for the given instant in the given zone. */
+export function isoDateInZone(at, zone) {
+    const zoned = toZoned(at, zone);
+    return `${String(zoned.year).padStart(4, '0')}-${pad2(zoned.month)}-${pad2(zoned.day)}`;
+}
+/** True when both instants fall on the same local calendar day. */
+export function isSameLocalDay(left, right, zone) {
+    return isoDateInZone(left, zone) === isoDateInZone(right, zone);
+}
+function finish(epochMs, millisecond, zone, resolution) {
+    const value = new Date(epochMs + millisecond);
+    return { instant: value, resolution, offsetMinutes: offsetAt(zone, value) };
+}
+function normalizeWall(wall) {
+    const asUtc = new Date(Date.UTC(wall.year, wall.month - 1, wall.day, wall.hour, wall.minute, wall.second ?? 0));
+    return {
+        year: asUtc.getUTCFullYear(),
+        month: asUtc.getUTCMonth() + 1,
+        day: asUtc.getUTCDate(),
+        hour: asUtc.getUTCHours(),
+        minute: asUtc.getUTCMinutes(),
+        second: asUtc.getUTCSeconds(),
+    };
+}
+function matchesWall(epochMs, zone, wall) {
+    const parts = zonePartsAt(zone, new Date(epochMs));
+    return (parts.year === wall.year &&
+        parts.month === wall.month &&
+        parts.day === wall.day &&
+        parts.hour === wall.hour &&
+        parts.minute === wall.minute &&
+        parts.second === wall.second);
+}
+function describeWall(wall) {
+    return `${String(wall.year).padStart(4, '0')}-${pad2(wall.month)}-${pad2(wall.day)} ${pad2(wall.hour)}:${pad2(wall.minute)}:${pad2(wall.second)}`;
+}
+function pad2(value) {
+    return String(value).padStart(2, '0');
+}
+//# sourceMappingURL=zoned.js.map

package/src/zoned.js.map

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

package/src/zoned.ts

@@ -0,0 +1,268 @@
+/**
+ * The two conversions everything else is built on: instant → wall clock, and wall clock →
+ * instant. `fromZoned` is the DST-correct one, and it is the reason this package exists.
+ */
+
+import { dstAmbiguous, dstNonexistent } from './errors';
+import { addMs, type Instant } from './instant';
+import { assertTimeZone, offsetAt, type TimeZone, utcEpoch, zonePartsAt } from './zones';
+
+/** A local date and time with no zone attached — meaningless until paired with one. */
+export interface WallClock {
+  year: number;
+  month: number;
+  day: number;
+  hour: number;
+  minute: number;
+  second?: number;
+  millisecond?: number;
+}
+
+export interface ZonedDateTime {
+  year: number;
+  month: number;
+  day: number;
+  hour: number;
+  minute: number;
+  second: number;
+  millisecond: number;
+  zone: TimeZone;
+  /** Minutes east of UTC in effect at this instant. */
+  offsetMinutes: number;
+  /** ISO weekday: 1 = Monday … 7 = Sunday. */
+  weekday: number;
+}
+
+/** What to do with a wall-clock time that does not exist (spring forward). */
+export type GapPolicy = 'next' | 'previous' | 'throw';
+/** What to do with a wall-clock time that happens twice (fall back). */
+export type OverlapPolicy = 'first' | 'second' | 'throw';
+
+export interface FromZonedOptions {
+  gap?: GapPolicy;
+  overlap?: OverlapPolicy;
+}
+
+export type ZonedResolution = 'exact' | 'gap' | 'overlap';
+
+export interface FromZonedResult {
+  instant: Instant;
+  /** Which case the wall-clock time fell into — log it when scheduling. */
+  resolution: ZonedResolution;
+  offsetMinutes: number;
+}
+
+const DEFAULTS: Required<FromZonedOptions> = { gap: 'next', overlap: 'first' };
+
+/** Instant → the zone's wall clock. */
+export function toZoned(at: Instant, zone: TimeZone): ZonedDateTime {
+  assertTimeZone(zone);
+  const parts = zonePartsAt(zone, at);
+  const offsetMinutes = offsetAt(zone, at);
+  const asIfUtc = utcEpoch(parts.year, parts.month, parts.day);
+  return {
+    ...parts,
+    millisecond: at.getTime() - Math.floor(at.getTime() / 1000) * 1000,
+    zone,
+    offsetMinutes,
+    // getUTCDay on the as-if-UTC epoch gives the *local* weekday: 0 = Sunday.
+    weekday: ((new Date(asIfUtc).getUTCDay() + 6) % 7) + 1,
+  };
+}
+
+/**
+ * Wall clock + zone → instant, DST-correct.
+ *
+ * Algorithm (search and verify — never `offset * 3600`):
+ *  1. Read the wall-clock fields as if they were UTC. Call that `target`.
+ *  2. Collect the candidate offsets in force around `target` — 24h before, at, and 24h
+ *     after. Any DST transition puts both of its offsets in that set.
+ *  3. For each distinct offset `o`, the candidate instant is `target - o`.
+ *  4. Verify each candidate by converting it *back* with `toZoned`. A candidate that does
+ *     not reproduce the requested wall clock is not a real instant for it.
+ *      - two distinct verified candidates → the hour repeats (overlap)
+ *      - exactly one                      → normal case
+ *      - none                             → the hour was skipped (gap)
+ *
+ * Milliseconds ride along untouched: every real offset is a whole number of minutes.
+ */
+export function fromZonedDetailed(
+  wall: WallClock,
+  zone: TimeZone,
+  options: FromZonedOptions = {},
+): FromZonedResult {
+  assertTimeZone(zone);
+  const { gap, overlap } = { ...DEFAULTS, ...options };
+  const millisecond = wall.millisecond ?? 0;
+  // Normalize overflow first (day 32, hour 24, month 13) so callers can do naive calendar
+  // arithmetic — `addDaysInZone` relies on it — and so verification compares real fields.
+  const normal = normalizeWall(wall);
+  const target = utcEpoch(
+    normal.year,
+    normal.month,
+    normal.day,
+    normal.hour,
+    normal.minute,
+    normal.second,
+  );
+
+  const probes = [target - 86_400_000, target, target + 86_400_000];
+  const offsets = new Set(probes.map((ms) => offsetAt(zone, new Date(ms) as Instant)));
+
+  const verified: number[] = [];
+  for (const offsetMinutes of offsets) {
+    const candidate = target - offsetMinutes * 60_000;
+    if (matchesWall(candidate, zone, normal)) verified.push(candidate);
+  }
+  const distinct = [...new Set(verified)].sort((a, b) => a - b);
+
+  if (distinct.length > 1) {
+    if (overlap === 'throw') throw dstAmbiguous(describeWall(normal), zone);
+    const chosen = overlap === 'first' ? distinct[0] : distinct[distinct.length - 1];
+    return finish(chosen ?? target, millisecond, zone, 'overlap');
+  }
+
+  const single = distinct[0];
+  if (single !== undefined) return finish(single, millisecond, zone, 'exact');
+
+  // Gap: the requested wall clock was skipped. The two unverified candidates bracket it —
+  // the smaller lands before the transition, the larger after it.
+  if (gap === 'throw') throw dstNonexistent(describeWall(normal), zone);
+  const bracket = [...offsets]
+    .map((offsetMinutes) => target - offsetMinutes * 60_000)
+    .sort((a, b) => a - b);
+  const chosen = gap === 'next' ? bracket[bracket.length - 1] : bracket[0];
+  return finish(chosen ?? target, millisecond, zone, 'gap');
+}
+
+/** The common form: just the instant. */
+export function fromZoned(
+  wall: WallClock,
+  zone: TimeZone,
+  options: FromZonedOptions = {},
+): Instant {
+  return fromZonedDetailed(wall, zone, options).instant;
+}
+
+/** Midnight local, as an instant. DST-correct: on a spring-forward day it still exists. */
+export function startOfDay(at: Instant, zone: TimeZone): Instant {
+  const zoned = toZoned(at, zone);
+  return fromZoned(
+    { year: zoned.year, month: zoned.month, day: zoned.day, hour: 0, minute: 0 },
+    zone,
+    { gap: 'next' },
+  );
+}
+
+/** The last millisecond of the local day. */
+export function endOfDay(at: Instant, zone: TimeZone): Instant {
+  const zoned = toZoned(at, zone);
+  const nextMidnight = fromZoned(
+    { year: zoned.year, month: zoned.month, day: zoned.day + 1, hour: 0, minute: 0 },
+    zone,
+    { gap: 'next' },
+  );
+  return addMs(nextMidnight, -1);
+}
+
+/**
+ * Add calendar days in a zone, keeping the wall-clock time. Adding one day is 23, 24 or
+ * 25 hours depending on the transition — which is why this is not `+ 86_400_000`.
+ */
+export function addDaysInZone(at: Instant, days: number, zone: TimeZone): Instant {
+  const zoned = toZoned(at, zone);
+  return fromZoned(
+    {
+      year: zoned.year,
+      month: zoned.month,
+      day: zoned.day + days,
+      hour: zoned.hour,
+      minute: zoned.minute,
+      second: zoned.second,
+      millisecond: zoned.millisecond,
+    },
+    zone,
+    { gap: 'next' },
+  );
+}
+
+/** `2026-03-14` for the given instant in the given zone. */
+export function isoDateInZone(at: Instant, zone: TimeZone): string {
+  const zoned = toZoned(at, zone);
+  return `${String(zoned.year).padStart(4, '0')}-${pad2(zoned.month)}-${pad2(zoned.day)}`;
+}
+
+/** True when both instants fall on the same local calendar day. */
+export function isSameLocalDay(left: Instant, right: Instant, zone: TimeZone): boolean {
+  return isoDateInZone(left, zone) === isoDateInZone(right, zone);
+}
+
+/**
+ * Whole calendar days from `from` to `to`, counted as local day boundaries crossed in `zone`.
+ * Signed, and always integral. Not `differenceMs / 86_400_000`: a 23- or 25-hour DST day is
+ * still one day, and 24 real hours inside a 25-hour local day is still zero.
+ */
+export function daysBetween(from: Instant, to: Instant, zone: TimeZone): number {
+  // Both dates are reduced to a UTC midnight, so the subtraction carries no offset at all.
+  return (localDayEpoch(to, zone) - localDayEpoch(from, zone)) / 86_400_000;
+}
+
+/** The instant's local calendar date, expressed as the UTC midnight of that date. */
+function localDayEpoch(at: Instant, zone: TimeZone): number {
+  const zoned = toZoned(at, zone);
+  return utcEpoch(zoned.year, zoned.month, zoned.day);
+}
+
+function finish(
+  epochMs: number,
+  millisecond: number,
+  zone: TimeZone,
+  resolution: ZonedResolution,
+): FromZonedResult {
+  const value = new Date(epochMs + millisecond) as Instant;
+  return { instant: value, resolution, offsetMinutes: offsetAt(zone, value) };
+}
+
+/** Field-complete wall clock with all overflow carried into the higher fields. */
+interface NormalWall {
+  year: number;
+  month: number;
+  day: number;
+  hour: number;
+  minute: number;
+  second: number;
+}
+
+function normalizeWall(wall: WallClock): NormalWall {
+  const asUtc = new Date(
+    utcEpoch(wall.year, wall.month, wall.day, wall.hour, wall.minute, wall.second ?? 0),
+  );
+  return {
+    year: asUtc.getUTCFullYear(),
+    month: asUtc.getUTCMonth() + 1,
+    day: asUtc.getUTCDate(),
+    hour: asUtc.getUTCHours(),
+    minute: asUtc.getUTCMinutes(),
+    second: asUtc.getUTCSeconds(),
+  };
+}
+
+function matchesWall(epochMs: number, zone: TimeZone, wall: NormalWall): boolean {
+  const parts = zonePartsAt(zone, new Date(epochMs) as Instant);
+  return (
+    parts.year === wall.year &&
+    parts.month === wall.month &&
+    parts.day === wall.day &&
+    parts.hour === wall.hour &&
+    parts.minute === wall.minute &&
+    parts.second === wall.second
+  );
+}
+
+function describeWall(wall: NormalWall): string {
+  return `${String(wall.year).padStart(4, '0')}-${pad2(wall.month)}-${pad2(wall.day)} ${pad2(wall.hour)}:${pad2(wall.minute)}:${pad2(wall.second)}`;
+}
+
+function pad2(value: number): string {
+  return String(value).padStart(2, '0');
+}

package/src/zones.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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 type { Instant } from './instant';
+/** An IANA identifier: `Europe/Berlin`, `Asia/Kathmandu`, `UTC`. Never `CET`, never `+01:00`. */
+export type TimeZone = string;
+export declare const UTC: TimeZone;
+export declare function isValidTimeZone(zone: string): boolean;
+export declare function assertTimeZone(zone: string): TimeZone;
+/** 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 declare function zonePartsAt(zone: TimeZone, at: Instant): ZoneParts;
+/**
+ * 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 declare function offsetAt(zone: TimeZone, at: Instant): number;
+/** `+01:00`, `-04:00`, `+05:45`, `Z`. */
+export declare function offsetLabel(minutes: number): string;
+/** Locale-aware zone label: `CET`, `GMT+5:45`, `Central European Standard Time`. */
+export declare function zoneAbbrev(zone: TimeZone, at: Instant, locale?: string, style?: 'short' | 'long' | 'shortOffset' | 'longOffset'): string;
+/** True when the zone observes a different offset at some point in the surrounding year. */
+export declare function observesDst(zone: TimeZone, at: Instant): boolean;
+//# sourceMappingURL=zones.d.ts.map

package/src/zones.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zones.d.ts","sourceRoot":"","sources":["zones.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,iGAAiG;AACjG,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE9B,eAAO,MAAM,GAAG,EAAE,QAAgB,CAAC;AAKnC,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAQrD;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAGrD;AAED,oEAAoE;AACpE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,GAAG,SAAS,CAelE;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,GAAG,MAAM,CAY5D;AAED,yCAAyC;AACzC,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMnD;AAED,oFAAoF;AACpF,wBAAgB,UAAU,CACxB,IAAI,EAAE,QAAQ,EACd,EAAE,EAAE,OAAO,EACX,MAAM,SAAU,EAChB,KAAK,GAAE,OAAO,GAAG,MAAM,GAAG,aAAa,GAAG,YAAsB,GAC/D,MAAM,CAQR;AAED,4FAA4F;AAC5F,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,GAAG,OAAO,CAQhE"}