The Temporal API in JavaScript provides a modern way to handle dates and times, offering precise and flexible methods to work with temporal data.
We can use the functions that comes with Temporal API as follows:
Temporal.PlainDate
Temporal.PlainDate represents a calendar date without time or timezone information.
For example, we write
const date = Temporal.PlainDate.from('2023-07-07');
console.log(date.toString()); // 2023-07-07
const now = Temporal.Now.plainDateISO();
console.log(now.toString()); // Current date in YYYY-MM-DD format
const nextWeek = date.add({ days: 7 });
console.log(nextWeek.toString()); // 2023-07-14
const pastDate = date.subtract({ months: 1 });
console.log(pastDate.toString()); // 2023-06-07
Dates are returned in YYYY-MM-DD format.
Temporal.PlainTime
Temporal.PlainTime represents a time of day without a date or timezone.
For instance, we write:
const time = Temporal.PlainTime.from('14:30:00');
console.log(time.toString()); // 14:30:00
const now = Temporal.Now.plainTimeISO();
console.log(now.toString()); // Current time in HH:mm:ss.sss format
const later = time.add({ hours: 2 });
console.log(later.toString()); // 16:30:00
const earlier = time.subtract({ minutes: 15 });
console.log(earlier.toString()); // 14:15:00
Temporal.PlainDateTime
Temporal.PlainDateTime combines a date and a time without timezone information.
For example, we write
const dateTime = Temporal.PlainDateTime.from('2023-07-07T14:30:00');
console.log(dateTime.toString()); // 2023-07-07T14:30:00
const now = Temporal.Now.plainDateTimeISO();
console.log(now.toString()); // Current date and time in YYYY-MM-DDTHH:mm:ss.sss format
const nextHour = dateTime.add({ hours: 1 });
console.log(nextHour.toString()); // 2023-07-07T15:30:00
const pastWeek = dateTime.subtract({ weeks: 1 });
console.log(pastWeek.toString()); // 2023-06-30T14:30:00
Temporal.ZonedDateTime
Temporal.ZonedDateTime represents a date and time with a timezone.
For example, we write:
const zonedDateTime = Temporal.ZonedDateTime.from('2023-07-07T14:30:00+01:00[Europe/London]');
console.log(zonedDateTime.toString()); // 2023-07-07T14:30:00+01:00[Europe/London]
const now = Temporal.Now.zonedDateTimeISO();
console.log(now.toString()); // Current date and time with timezone
const newYorkTime = zonedDateTime.withZone('America/New_York');
console.log(newYorkTime.toString()); // 2023-07-07T09:30:00-04:00[America/New_York]
const later = zonedDateTime.add({ hours: 2 });
console.log(later.toString()); // 2023-07-07T16:30:00+01:00[Europe/London]
Temporal.Duration
Temporal.Duration represents a length of time.
For example, we can use it as follows:
const duration = Temporal.Duration.from({ days: 2, hours: 5 });
console.log(duration.toString()); // P2DT5H
const dateTime = Temporal.PlainDateTime.from('2023-07-07T14:30:00');
const newDateTime = dateTime.add(duration);
console.log(newDateTime.toString()); // 2023-07-09T19:30:00
const elapsed = newDateTime.since(dateTime);
console.log(elapsed.toString()); // P2DT5H
We use Temporal.Duration.from to create the duration of 2 days and 5 hours.
And we can calculate the elapsed time between 2 different date time with since.
Temporal.Calendar
Temporal.Calendar allows for working with different calendar systems.
For example, we write:
const isoDate = Temporal.PlainDate.from('2023-07-07');
const hebrewDate = isoDate.withCalendar('hebrew');
console.log(hebrewDate.toString()); // Hebrew calendar date
const convertedBack = hebrewDate.withCalendar('iso8601');
console.log(convertedBack.toString()); // 2023-07-07
We call withCalendar to convert dates to different calendar systems.
Temporal.TimeZone
Temporal.TimeZone provides information about time zones.
For example, we write
const timeZone = Temporal.TimeZone.from('America/New_York');
const dateTime = Temporal.PlainDateTime.from('2023-07-07T14:30:00');
const zonedDateTime = dateTime.toZonedDateTime(timeZone);
console.log(zonedDateTime.toString()); // 2023-07-07T14:30:00-04:00[America/New_York]
const nowInZone = Temporal.Now.zonedDateTime(timeZone);
console.log(nowInZone.toString()); // Current date and time in the specified time zone
to convert date times to date times with time zones with toZonedDateTime.
And we get the current date time with time zone with zonedDateTime.
The Temporal API offers a more robust and intuitive way to work with date and time in JavaScript, addressing many limitations of the existing Date object.
