Timezones and dates

Store UTC. Format at the edge with Intl.DateTimeFormat and an explicit IANA timeZone.

A Intl.DateTimeFormat or toLocaleString call with no timeZone option is a lint failure and fails x verify (check 2). It silently uses the process TZ, which in a container is UTC and in a laptop is not — the same code renders two different days depending on where it runs.

Storage

The actor's zone

import { currentTimeZone } from '@ultimat3/time';

resolveTimeZone reads, first valid IANA name wins, canonicalized; an invalid one is skipped, never thrown. As of 2026-11:

Detecting a new visitor's zone

A document navigation sends no x-timezone, so a new visitor's server-rendered app/ pages render in the default zone. time: { detect: true } in app.config.ts (off by default: it writes a cookie) puts a 153 B inline script on every app/ document — never on site/ — that writes x_timezone_detected from Intl.DateTimeFormat().resolvedOptions().timeZone. The first paint stays the default; every page after it is in the visitor's zone. The script is admitted by its own CSP hash, and it never touches the chosen x_timezone cookie.

import { defineConfig } from '@ultimat3/core';

export const config = defineConfig({ name: 'my-app', time: { detect: true } });

The zone rides the ALS request context alongside the locale, so format* helpers take neither argument. Jobs and scheduled tasks carry the enqueueing actor's zone in the payload — a worker has no request and must not invent one.

Formatting

All of them read locale and zone from the context and pass timeZone explicitly to Intl. There is no variant that omits it.

Pickers

As of 2026-11. A calendar date the user picks is a PlainDate — DatePicker, DateRangePicker and Calendar take and post YYYY-MM-DD and know no zone. Month and weekday names are Intl.DateTimeFormat with timeZone: 'UTC' on the plain date's UTC midnight, which names the date and never shifts it; the week starts on the locale's day (Intl.Locale#getWeekInfo). A window is instants: timeRangeUrl(url, { presets, default, timeZone, now }) reads a custom from/to as wall-clock time in timeZone (a spring-forward gap resolves forward) and TimeRangePicker requires the same timeZone as a prop — omitting it is a type error. "Today" is the caller's: pass month (or now) computed with plainDateIn(now(), actor.tz); with none, Calendar opens on today in useUi().timeZone, the request's zone, never the device's.

Common mistakes

Month arithmetic

A month has no fixed length, so both helpers clamp the day to the target month's last day.

Compute a recurring date from its anchor, never by chaining. A clamp does not compose: 2026-01-31 + 1 + 1 is 2026-03-28, 2026-01-31 + 2 is 2026-03-31.

import { addMonthsInZone, fromIso } from '@ultimat3/time';

const anchor = fromIso('2026-01-31T00:00:00-05:00');
const renewal = (n: number) => addMonthsInZone(anchor, n, 'America/Bogota');
// renewal(1): Feb 28 00:00, renewal(2): Mar 31 00:00 — never stuck on the 28th

Full rules: packages/time/README.md.

Duration strings

One notation for every "how long" field.

Parsed once into milliseconds. A bare number is a type error — the unit must be in the string. See Caching and invalidation and Jobs and workflows.

Scheduled tasks

tz is required on every task and must be an explicit IANA zone. There is no default.

// task (cron)
export const nightlyDigest = task({
  cron: '0 3 * * *',
  tz: 'UTC',
  enqueue: () => [[sendDigest, {}]],
});

See Scheduled tasks.

DST-crossing recurrence

Cron is a civil-calendar schedule; sleeps are elapsed time. Mixing them is where "the job ran twice in November" comes from.

Tests

Declare a zone when the behavior is the point:

test('digest window respects the org zone', async ({ seed, clock }) => {
  const { org } = await seed('org-in-berlin');
  clock.advance('1d');
  const window = digestWindow(org, 'Europe/Berlin');
  expect(window.label).toBe('Jul 27, 2026');
});

See Testing.

Rules

• timestamptz for instants, date for civil dates. Nothing else.
• Never format without an explicit IANA timeZone.
• Never read the process TZ. Roles run with TZ=UTC and it is not an input.
• Zone comes from the actor; a worker gets it from the job payload.
• Format at the edge only — routes and components, never services or repos.
• Durations are strings with units.
• tz on a task is explicit and required.
• Advance the frozen clock; never sleep in a test.