@bimetal/temporal

The domain-neutral temporal kernel: timezone-aware date-time arithmetic in two named models (DST-safe civil units addDays/addWeeks/addMonths/addYears

• explicit elapsed durations addHours/addMinutes), time ranges, durations, granularity snapping, and formatting. Stateless, deterministic, pure functions. Zero external dependencies.

The calendar layer (grid/segmentation/layout/axis geometry, recurrence, the calendar config + domain model, and the validation rules) lives in @bimetal/calendar-core, which re-exports this kernel — a calendar-side consumer needs only that one import. Rule evaluation is its own engine: @bimetal/rule-engine + the calendar rule pack @bimetal/calendar-rules.

Installation

npm install @bimetal/temporal

What's Inside

Time Model

CalendarDateTime — a point in time with timezone context. All arithmetic happens in UTC, timezone is used for wall-clock interpretation.

import { createDateTime, addDays, daysBetween, getHours, isSameDay, Month } from '@bimetal/temporal';

const dt = createDateTime(2026, Month.March, 15, 9, 0, 'Europe/Berlin');
const tomorrow = addDays(dt, 1);       // DST-safe: preserves wall-clock time
const days = daysBetween(dt, tomorrow); // calendar days, not epochMs/86400000

TimeRange

import { createTimeRange, overlaps, durationInMinutes } from '@bimetal/temporal';

const range = createTimeRange(start, end); // throws if start >= end
const conflict = overlaps(rangeA, rangeB);
const mins = durationInMinutes(range);     // length of the range, in minutes

Granularity

import { snap, generateSlots } from '@bimetal/temporal';

const snapped = snap(dt, { minutes: 15 }, 'floor');    // 09:07 → 09:00
const slots = generateSlots(dayRange, { minutes: 15 }); // 96 slots for a 24h day

Formatting

import { formatDateTime, formatDayLabel } from '@bimetal/temporal';

const stamp = formatDateTime(dt, { locale: 'de-DE' }); // locale-aware date-time
const label = formatDayLabel(dt, 'de-DE');             // locale-aware day label

Grid/segmentation/layout/axis geometry, the calendar config (defaultConfig/ mergeConfig), domain models (getDomain), and validation moved to @bimetal/calendar-core (+ @bimetal/calendar-rules) in the core split — import them from there, not from @bimetal/temporal.

Key Design Decisions

• Temporal-aligned: { epochMs, timezone } — future-proof, DST-safe
• Immutable: all types are readonly, all functions return new objects
• Zero dependencies: only Intl.DateTimeFormat for formatting
• Deterministic: injectable Clock for tests and SSR