Basic Usage
Parse ISO input with a declared target. Convert plain values with timeZone before treating them as an instant.
import { format, parse, shift } from '@vielzeug/tempo';
const local = parse('2026-03-21T10:15:30', { as: 'plainDateTime' });
const reminder = shift(local, { minutes: -15 }, { timeZone: 'America/New_York' });
format(reminder, { locale: 'en-US', pattern: 'short' });Parse ISO Values
Choose the value your boundary actually represents. Tempo does not auto-detect ISO strings.
import { parse } from '@vielzeug/tempo';
const occurredAt = parse('2026-03-21T10:15:30Z', { as: 'instant' });
const meeting = parse('2026-03-21T10:15:30+01:00[Europe/Berlin]', { as: 'zonedDateTime' });
const localStart = parse('2026-03-21T10:15:30', { as: 'plainDateTime' });
const birthday = parse('2026-03-21', { as: 'plainDate' });Convert Timezones
Use toZoned() to project a value into a display timezone. Use toInstant() only when resolving a wall-clock value.
import { parse, toInstant, toZoned } from '@vielzeug/tempo';
const local = parse('2026-11-01T01:30:00', { as: 'plainDateTime' });
const firstOccurrence = toInstant(local, {
disambiguation: 'earlier',
timeZone: 'America/New_York',
});
const berlin = toZoned(firstOccurrence, { timeZone: 'Europe/Berlin' });Calculate and Compare
Use Tempo helpers when an operation must resolve timezones or compare calendar units. Use Temporal methods directly when values are already the exact kind and timezone you need.
import { difference, isAfter, isBefore, isSame, parse, shift } from '@vielzeug/tempo';
const start = parse('2026-03-21T10:00:00Z', { as: 'instant' });
const end = parse('2026-03-21T12:00:00Z', { as: 'instant' });
const duration = difference({ end, largestUnit: 'hour', start });
const isWithinWindow = isAfter(end, start) && isBefore(end, parse('2026-03-21T14:00:00Z', { as: 'instant' }));
const sameDay = isSame(start, end, { timeZone: 'UTC', unit: 'day' });
const local = parse('2026-03-08T01:30:00', { as: 'plainDateTime' });
const tomorrow = shift(local, { days: 1 }, { timeZone: 'America/New_York' });Format Values
Use format() for UI, formatInstant() for transport, and formatZoned() for a zoned ISO string.
import { format, formatInstant, formatRelative, formatZoned, parse } from '@vielzeug/tempo';
const instant = parse('2026-03-21T10:15:30Z', { as: 'instant' });
format(instant, { locale: 'en-GB', pattern: 'short', timeZone: 'UTC' });
formatInstant(instant);
formatZoned(instant, { timeZone: 'Europe/Berlin' });
formatRelative(instant, { base: parse('2026-03-21T09:15:30Z', { as: 'instant' }) });formatRelative() uses fixed elapsed-time units for short spans and complete calendar months or years for longer spans. Pass timeZone when calendar-relative output must use a specific regional calendar boundary.
Use formatTimer() for stopwatch-style clocks: elapsed timers, recorded durations: where localized prose does not fit:
import { formatTimer } from '@vielzeug/tempo';
formatTimer('PT47M12S'); // '47:12'
formatTimer({ milliseconds: 3_753_000 }); // '1:02:33'
formatTimer('PT5M', { hours: 'always' }); // '0:05:00'Testing
Pin reference instants so relative and boundary assertions stay deterministic.
import { formatRelative, parse, startOf } from '@vielzeug/tempo';
const base = parse('2026-06-01T00:00:00Z', { as: 'instant' });
const value = parse('2026-06-04T00:00:00Z', { as: 'instant' });
formatRelative(value, { base, locale: 'en-US' }); // 'in 3 days'
startOf(value, 'month').toString(); // '2026-06-01T00:00:00+00:00[UTC]'Framework Integration
Pass ISO strings through component props. Parse and format at the rendering boundary.
import { format, parse } from '@vielzeug/tempo';
const label = format(parse(iso, { as: 'instant' }), { locale: 'en-US', pattern: 'medium', timeZone: 'UTC' });<script setup lang="ts">
import { format, parse } from '@vielzeug/tempo';
const props = defineProps<{ iso: string }>();
const label = format(parse(props.iso, { as: 'instant' }), { locale: 'en-US', pattern: 'medium', timeZone: 'UTC' });
</script><script lang="ts">
import { format, parse } from '@vielzeug/tempo';
export let iso: string;
$: label = format(parse(iso, { as: 'instant' }), { locale: 'en-US', pattern: 'medium', timeZone: 'UTC' });
</script>Working with Other Vielzeug Libraries
With Rune
Write stable UTC timestamps to structured logs.
import { formatInstant, nowInstant } from '@vielzeug/tempo';
logger.info({ timestamp: formatInstant(nowInstant()) }, 'server started');With Vault
Calculate an explicit instant before storing an expiring record.
import { now } from '@vielzeug/tempo';
const expiresAt = now({ timeZone: 'UTC' }).add({ minutes: 30 }).toInstant();Best Practices
- Parse strings with their actual temporal meaning and pass
timeZonewhen resolving plain values. - Use
disambiguationfor DST overlap and gap handling. - Use Tempo helpers for timezone resolution and calendar units; use Temporal directly for already-normalized values.
- Store instants for transport and database values.
- Use
formatInstant()for machine output andformat()for user-facing text. - Pass
timeZonetoformatRelative()when month and year boundaries must use a specific region.