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.