Timezone-Correct Day/Week/Month Buckets

Buckets timestamps into local calendar days, ISO weeks and months for an IANA timezone.

THE SILENT FAILURE. Daily aggregates are almost always computed in UTC and then reported as local days. Every metric near the day boundary lands on the wrong day -- a US evening event counts as tomorrow -- and nobody notices because the totals stay plausible and the shape looks roughly right. Worse, DST days are not 24 hours: spring-forward has 23, fall-back has 25 and contains a local time that occurs TWICE. Any code that buckets by dividing an epoch by 86400 is simply wrong on those days and quietly off-by-one for a whole timezone the rest of the year. Week boundaries differ by locale and month arithmetic overflows.

Uses the platform's own IANA database through Intl rather than a hand-rolled offset table, because a hardcoded table goes stale and fails silently. An unknown timezone identifier is REFUSED rather than falling back to UTC -- a silent UTC fallback is exactly this product's failure. Ambiguous and non-existent local times are handled with a documented, caller-visible policy instead of a quiet pick. Boundaries are half-open and tested as such, and each bucket reports the local offset actually used.

Verified on the hardest real case there is: Samoa's 2011 dateline jump, where an entire local calendar day never existed. It produces no bucket for that day rather than fabricating one.

VERIFIED: 75 tests. Every mutation was observed FAILING before the source was restored -- a test never seen to fail is a decoration. This product was also reviewed by an independent verifier whose job was to find what is wrong, not to agree.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function bucketTimestamps( timestampsMs: readonly number[], options: BucketOptions, ): TimestampBucket[];
  export function addCalendarDays(d: CalendarDate, days: number): CalendarDate;
  export function addCalendarMonths(d: CalendarDate, months: number): CalendarDate;
  export function isoDayOfWeek(d: CalendarDate): number;
  export function isoWeekInfo(d: CalendarDate): IsoWeekInfo;
  export function isoWeekMonday(isoYear: number, isoWeek: number): CalendarDate;
  export function pad(n: number, len = 2): string;
  export function isValidTimeZone(timeZone: string): boolean;
  export function assertValidTimeZone(timeZone: string): void;
  export function epochToLocalTime(epochMs: number, timeZone: string): LocalDateTimeParts;
  export function getUtcOffsetMinutes(epochMs: number, timeZone: string): number;

  export type Granularity = "day" | "isoWeek" | "month";
  export type AmbiguousLocalTimePolicy = "earliest" | "latest" | "reject";
  export type NonExistentLocalTimePolicy = "shiftForward" | "shiftBack" | "reject";