JavaScript Temporal API Guide

The Temporal API provides modern date/time handling with proper timezone support, replacing the problematic Date object. Here's how to use it.

Core Concepts#

// Temporal has several types for different use cases

// Temporal.Instant - exact moment in time (like a timestamp)
const instant = Temporal.Instant.from('2024-03-15T10:30:00Z');

// Temporal.ZonedDateTime - date/time with timezone
const zoned = Temporal.ZonedDateTime.from('2024-03-15T10:30:00[America/New_York]');

// Temporal.PlainDateTime - date/time without timezone
const dateTime = Temporal.PlainDateTime.from('2024-03-15T10:30:00');

// Temporal.PlainDate - just the date
const date = Temporal.PlainDate.from('2024-03-15');

// Temporal.PlainTime - just the time
const time = Temporal.PlainTime.from('10:30:00');

// Temporal.Duration - a length of time
const duration = Temporal.Duration.from({ hours: 2, minutes: 30 });

Creating Dates#

// Current date/time
const now = Temporal.Now.instant();
const nowZoned = Temporal.Now.zonedDateTimeISO('America/New_York');
const today = Temporal.Now.plainDateISO();

// From string
const date1 = Temporal.PlainDate.from('2024-03-15');
const time1 = Temporal.PlainTime.from('14:30:00');
const dateTime1 = Temporal.PlainDateTime.from('2024-03-15T14:30:00');

// From components
const date2 = Temporal.PlainDate.from({
  year: 2024,
  month: 3,
  day: 15,
});

const time2 = Temporal.PlainTime.from({
  hour: 14,
  minute: 30,
  second: 0,
});

// From existing date
const legacyDate = new Date();
const instant = Temporal.Instant.fromEpochMilliseconds(legacyDate.getTime());

Timezones#

// Create zoned date/time
const meeting = Temporal.ZonedDateTime.from({
  timeZone: 'America/New_York',
  year: 2024,
  month: 3,
  day: 15,
  hour: 10,
  minute: 0,
});

console.log(meeting.toString());
// 2024-03-15T10:00:00-04:00[America/New_York]

// Convert timezone
const meetingInTokyo = meeting.withTimeZone('Asia/Tokyo');
console.log(meetingInTokyo.toString());
// 2024-03-15T23:00:00+09:00[Asia/Tokyo]

// Get offset
console.log(meeting.offset); // '-04:00'

// Available timezones
const timezones = Temporal.TimeZone.from('America/New_York');

Arithmetic#

const date = Temporal.PlainDate.from('2024-03-15');

// Add duration
const nextWeek = date.add({ days: 7 });
const nextMonth = date.add({ months: 1 });
const nextYear = date.add({ years: 1 });

// Subtract duration
const lastWeek = date.subtract({ days: 7 });

// Multiple units
const future = date.add({
  years: 1,
  months: 2,
  days: 15,
});

// With time
const dateTime = Temporal.PlainDateTime.from('2024-03-15T10:30:00');
const later = dateTime.add({ hours: 2, minutes: 30 });

Comparing Dates#

const date1 = Temporal.PlainDate.from('2024-03-15');
const date2 = Temporal.PlainDate.from('2024-03-20');

// Comparison methods
console.log(Temporal.PlainDate.compare(date1, date2)); // -1 (before)
console.log(date1.equals(date2)); // false

// Calculate difference
const diff = date1.until(date2);
console.log(diff.days); // 5

// Different units
const diff2 = date1.until(date2, { largestUnit: 'weeks' });
console.log(diff2.weeks, diff2.days); // 0, 5

// Since vs until
const daysSince = date2.since(date1);
console.log(daysSince.days); // 5

// With time precision
const dt1 = Temporal.PlainDateTime.from('2024-03-15T10:00:00');
const dt2 = Temporal.PlainDateTime.from('2024-03-15T14:30:00');
const timeDiff = dt1.until(dt2);
console.log(timeDiff.hours, timeDiff.minutes); // 4, 30

Duration#

// Create duration
const duration = Temporal.Duration.from({
  hours: 2,
  minutes: 30,
  seconds: 45,
});

// From string (ISO 8601)
const dur2 = Temporal.Duration.from('PT2H30M45S');

// Properties
console.log(duration.hours); // 2
console.log(duration.minutes); // 30
console.log(duration.total('minutes')); // 150.75

// Negate
const negative = duration.negated();

// Absolute value
const abs = negative.abs();

// Add durations
const total = duration.add({ hours: 1 });

// Round duration
const rounded = duration.round({ smallestUnit: 'minutes' });

Formatting#

const date = Temporal.PlainDate.from('2024-03-15');
const dateTime = Temporal.PlainDateTime.from('2024-03-15T14:30:00');

// ISO strings
console.log(date.toString()); // '2024-03-15'
console.log(dateTime.toString()); // '2024-03-15T14:30:00'

// With Intl.DateTimeFormat
const formatter = new Intl.DateTimeFormat('en-US', {
  weekday: 'long',
  year: 'numeric',
  month: 'long',
  day: 'numeric',
});

console.log(formatter.format(date));
// 'Friday, March 15, 2024'

// Custom formatting
function formatDate(date) {
  return `${date.year}-${String(date.month).padStart(2, '0')}-${String(date.day).padStart(2, '0')}`;
}

Calendar Support#

// Different calendar systems
const hebrewDate = Temporal.PlainDate.from({
  year: 5784,
  month: 6,
  day: 4,
  calendar: 'hebrew',
});

const islamicDate = Temporal.PlainDate.from({
  year: 1445,
  month: 9,
  day: 4,
  calendar: 'islamic',
});

// Convert between calendars
const gregorianFromHebrew = hebrewDate.withCalendar('gregory');

// Get calendar info
const date = Temporal.PlainDate.from('2024-03-15');
console.log(date.calendar.id); // 'iso8601'
console.log(date.daysInMonth); // 31
console.log(date.daysInYear); // 366 (leap year)
console.log(date.monthsInYear); // 12
console.log(date.inLeapYear); // true

Practical Examples#

// Age calculation
function calculateAge(birthDate) {
  const today = Temporal.Now.plainDateISO();
  const birth = Temporal.PlainDate.from(birthDate);
  const diff = birth.until(today, { largestUnit: 'years' });
  return diff.years;
}

console.log(calculateAge('1990-05-15')); // 33 (in 2024)

// Business days between dates
function businessDays(start, end) {
  let count = 0;
  let current = Temporal.PlainDate.from(start);
  const endDate = Temporal.PlainDate.from(end);

  while (Temporal.PlainDate.compare(current, endDate) < 0) {
    const dayOfWeek = current.dayOfWeek;
    if (dayOfWeek !== 6 && dayOfWeek !== 7) {
      count++;
    }
    current = current.add({ days: 1 });
  }

  return count;
}

// Meeting scheduler
function scheduleRecurring(startDate, intervalDays, count) {
  const meetings = [];
  let current = Temporal.PlainDateTime.from(startDate);

  for (let i = 0; i < count; i++) {
    meetings.push(current.toString());
    current = current.add({ days: intervalDays });
  }

  return meetings;
}

Time Zones Handling#

// Schedule across timezones
function scheduleGlobalMeeting(baseTime, attendeeTimezones) {
  const base = Temporal.ZonedDateTime.from(baseTime);

  return attendeeTimezones.map((tz) => ({
    timezone: tz,
    localTime: base.withTimeZone(tz).toString(),
  }));
}

const times = scheduleGlobalMeeting(
  '2024-03-15T10:00:00[America/New_York]',
  ['America/Los_Angeles', 'Europe/London', 'Asia/Tokyo']
);

// DST-safe scheduling
function addWeeks(zonedDateTime, weeks) {
  // This handles DST transitions correctly
  return zonedDateTime.add({ weeks });
}

Migration from Date#

// Convert Date to Temporal
function dateToTemporal(date) {
  return Temporal.Instant.fromEpochMilliseconds(date.getTime());
}

// Convert Temporal to Date
function temporalToDate(instant) {
  return new Date(instant.epochMilliseconds);
}

// Wrapper for gradual migration
class DateWrapper {
  constructor(input) {
    if (input instanceof Date) {
      this.temporal = Temporal.Instant.fromEpochMilliseconds(input.getTime());
    } else {
      this.temporal = Temporal.Instant.from(input);
    }
  }

  toDate() {
    return new Date(this.temporal.epochMilliseconds);
  }

  toZonedDateTime(timezone) {
    return this.temporal.toZonedDateTimeISO(timezone);
  }
}

Best Practices#

Choose the Right Type:
✓ Instant for timestamps
✓ ZonedDateTime for user-facing times
✓ PlainDateTime for local events
✓ PlainDate for dates without time
✓ Duration for time spans

Timezone Handling:
✓ Always store as UTC/Instant
✓ Convert to local for display
✓ Use named timezones, not offsets
✓ Handle DST transitions

Comparison:
✓ Use compare() for sorting
✓ Use equals() for equality
✓ Use until()/since() for differences
✓ Specify largestUnit for clarity

Avoid:
✗ Mixing Temporal and Date
✗ Storing local times as UTC
✗ Ignoring calendar systems
✗ Manual string formatting

The Temporal API provides comprehensive date/time handling with proper timezone support, duration arithmetic, and calendar systems. Use Instant for timestamps, ZonedDateTime for timezone-aware times, and Plain* types for calendar dates and times. The API handles DST transitions, leap years, and calendar conversions correctly, making it far superior to the legacy Date object for modern JavaScript applications.