@vielzeug/tempo

Temporal-powered parsing, timezone conversion, arithmetic (DST-safe), and Intl formatting for modern TypeScript.

Package: @vielzeug/tempo  ·  Category: Date-time

Key exports: now, parsePlainDateTime, parseInstant, parse, toInstant, inTz, shift, difference, format, formatRelative, isBefore, isAfter, isSame, startOf, endOf, expires, timeDiff, recurrence

When to use: Temporal-powered parsing, timezone conversion, arithmetic (DST-safe), and Intl formatting for modern TypeScript.

Related: @vielzeug/arsenal

@vielzeug/tempo is part of Vielzeug and ships as a zero-dependency TypeScript package with ESM+CJS output.

Installation

pnpm add @vielzeug/tempo
npm install @vielzeug/tempo
yarn add @vielzeug/tempo

Quick Start

import { format, formatInstant, inTz, parsePlainDateTime, shift, toInstant } from '@vielzeug/tempo';

// Parse a wall-clock string (no timezone attached)
const localMeeting = parsePlainDateTime('2026-03-21T10:30:00');

// Convert to an absolute instant using the user's timezone
const meetingInstant = toInstant(localMeeting, { tz: 'America/New_York' });

// Project to a zoned view and subtract 15 minutes (DST-safe)
const meetingNY = inTz(meetingInstant, 'America/New_York');
const reminder = shift(meetingNY, { minutes: -15 });

// Format for display
console.log(format(reminder, { pattern: 'short', locale: 'en-US', tz: 'America/New_York' }));

// Format for APIs / logs (stable UTC instant string)
console.log(formatInstant(reminder));

Since many function names (now, shift, clamp, difference, …) are common in application code, use a namespace import to avoid collisions while still getting full tree-shaking:

import * as tempo from '@vielzeug/tempo';

tempo.now('UTC');
tempo.difference(start, end, { largestUnit: 'day', tz: 'UTC' });
tempo.format(meeting, { pattern: 'short', locale: 'en-US', tz: 'America/New_York' });

Documentation

• Overview
• Usage Guide
• API Reference
• Examples

License

MIT © Helmuth Saatkamp — part of the Vielzeug monorepo.