Skip to content

Basic Usage ​

Parse ISO input with a declared target. Convert plain values with timeZone before treating them as an instant.

ts
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.

ts
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.

ts
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.

ts
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.

ts
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:

ts
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.

ts
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.

tsx
import { format, parse } from '@vielzeug/tempo';

const label = format(parse(iso, { as: 'instant' }), { locale: 'en-US', pattern: 'medium', timeZone: 'UTC' });
vue
<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>
svelte
<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.

ts
import { formatInstant, nowInstant } from '@vielzeug/tempo';

logger.info({ timestamp: formatInstant(nowInstant()) }, 'server started');

With Vault ​

Calculate an explicit instant before storing an expiring record.

ts
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 timeZone when resolving plain values.
  • Use disambiguation for 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 and format() for user-facing text.
  • Pass timeZone to formatRelative() when month and year boundaries must use a specific region.