Breaking Changes Since 26.11.11
Tempo's surface was narrowed to its core: parsing, timezone resolution, DST-safe arithmetic, boundaries, comparison predicates, and the Intl formatting suite. Speculative and app-level clusters were removed, and inTimeZone() was replaced by the symmetric toInstant()/toZoned() pair.
Removed exports:
contains()/clamp()— range checks are twoInstantcomparisons; useisBefore()/isAfter()or compareepochMillisecondsdirectly.classifyExpiry()(withFixedDuration,ExpiryThresholds,ClassifyExpiryInput) — expiry buckets are application policy; express thresholds withdifference()in the app that owns them.timeDiff()/humanize()(withTimeDiffUnit,TimeDiffResult) —formatRelative()localizes the same spans, andTemporal.DurationplusformatDuration()cover unit-level rendering.dateRange()/recurrence()(withRecurrenceRule) — lazy calendar walks are a few lines ofTemporalarithmetic in the app that needs them; the toy recurrence subset was never RRULE-compatible and has been replaced by the RFC 5545 engine at@vielzeug/tempo/cadence(see Cadence).RelativeTimeInput— useAbsoluteTimedirectly.
inTimeZone() becomes toZoned()
// Before
import { inTimeZone } from '@vielzeug/tempo';
const local = inTimeZone(instant, 'Europe/Berlin');
// After
import { toZoned } from '@vielzeug/tempo';
const local = toZoned(instant, { timeZone: 'Europe/Berlin' });toZoned() mirrors toInstant(): named options, an explicit timeZone, and DST disambiguation for wall-clock inputs.
formatRange() and formatRangeParts() accept reversed bounds
Intl.DateTimeFormat.formatRange throws a native RangeError when the first value is later than the second. Tempo ranges are now order-free: reversed inputs are sorted before formatting, matching the normalized bounds the old contains()/clamp() provided.
Tempo 3 Changes
Tempo 3 preserves the timezone-aware arithmetic, comparison, boundary, and sequence APIs. It makes long-span relative formatting calendar-aware and rejects recurrence intervals that cannot advance safely.
Calendar-Aware Relative Formatting
formatRelative() no longer approximates months and years from average elapsed seconds. It resolves complete calendar units in the requested or inferred timezone while preserving localized future and past direction.
// Tempo 2: month and year output used average elapsed seconds
formatRelative(target, { base, locale: 'en-US' });
// Tempo 3: choose the calendar timezone explicitly
formatRelative(target, {
base,
locale: 'en-US',
timeZone: 'America/New_York',
});When both values are Instant, the default calendar timezone is UTC. One ZonedDateTime supplies its timezone. Two zoned values with different timezones require options.timeZone so the calendar boundary is unambiguous.
Recurrence moves to Cadence
The old recurrence() helper (a toy frequency/interval subset) is gone. Recurrence now lives in @vielzeug/tempo/cadence: a real RFC 5545 RRULE engine — parse, expand, and merge RDATE/EXDATE — built on Temporal, DST-correct by construction.
// Before: toy subset, never RRULE-compatible
import { recurrence } from '@vielzeug/tempo';
const dates = recurrence(start, { count: 4, frequency: 'weekly', interval: 2 });
// After: spec-conformant entry, same subpath import from tempo
import { expandCadence, parseCadence } from '@vielzeug/tempo/cadence';
const occurrences = [...expandCadence(start, parseCadence('FREQ=WEEKLY;INTERVAL=2;COUNT=4'))];See Cadence for the full engine: parseCadence, toCadence, expandCadence, and resolveCadenceDates.
Tempo 2 Changes
Tempo 2 makes string parsing and timezone conversion explicit. It removes auto-detection and old parser-specific helpers.
Removed exports:
parseInstantparseZonedparsePlainDateTimeparsePlainDateinTzwithinexpires
Parse With a Target
// Tempo 1
const instant = parseInstant(value);
const date = parsePlainDate(value);
// Tempo 2
const instant = parse(value, { as: 'instant' });
const date = parse(value, { as: 'plainDate' });Rename Timezone Options
// Tempo 1
const instant = toInstant(local, { prefer: 'later', tz: 'America/New_York' });
// Tempo 2
const instant = toInstant(local, {
disambiguation: 'later',
timeZone: 'America/New_York',
});now('UTC') becomes now({ timeZone: 'UTC' }). inTz(value, zone) becomes inTimeZone(value, zone).
Classify Fixed Expiry Durations
expires() becomes classifyExpiry() and uses named input. Thresholds no longer accept months or years because those are calendar-relative and must not be approximated.
const status = classifyExpiry({
thresholds: { expired: { days: 0 }, warning: { days: 14 } },
value: expiresAt,
});
const label = status ?? 'safe';Temporal Export
Temporal remains exported from @vielzeug/tempo. No migration is needed for advanced Temporal use.
Narrow Errors With instanceof
TempoError.is() is removed. Use instanceof TempoError to narrow any tempo-originated error.
// Tempo 1
if (TempoError.is(err)) { ... }
// Tempo 2
if (err instanceof TempoError) { ... }