JavaScript Temporal API Cheatsheet

What is the Temporal API?

The Temporal API is a JavaScript Stage 3 proposal which will make it much easier to manipulate dates than using the existing Date methods. You can try it now (using polyfill shown below) however, as it is still experimental, it is not recommended for production use.

Polyfill

The temporal API is not fully integrated into JavaScript so you need to install and import a polyfill package to use it:

Terminal:

pnpm install @js-temporal/polyfill

JavaScript or TypeScript source file:

import { Temporal } from '@js-temporal/polyfill';

Methods

add

Convenient for adding on an arbitrary time period to a given time or date. You might use this to work out the time you want a session cookie to expire.

const result = Temporal.Now.plainDateTimeISO()
	.add({ hours: 2 })
	.toLocaleString('en-GB', { dateStyle: 'full', timeStyle: 'long' });
Now: Friday 9 August 2024 at 03:52:08 UTC
Result: Friday 9 August 2024 at 05:52:08 UTC

compare

Useful for checking if something has expired. Returns -1 if first date is before second, 0 if they are identical and 1 otherwise. You might also use this with the Array.sort method to sort elements chronologically.

const result = Temporal.PlainDateTime.compare(
	Temporal.Now.plainDateTimeISO(),
	Temporal.PlainDate.from('2022-12-31'),
);
Now: Friday 9 August 2024 at 03:52:08 UTC
Result: 1

equals

Used to check two dates are the same. You might use this when filtering a list of events to find one which occurred at a certain time.

const result = Temporal.Now.plainDateISO().equals(Temporal.PlainDate.from('2022-12-25'));
Now: Friday 9 August 2024
Result: false

from

Create a new date based on year, month, day etc. values. You might use this to create a date from user form inputs, like a date of birth.

const result = Temporal.PlainDateTime.from({ year: 1997, month: 10, day: 1 }).toLocaleString(
	'en-GB',
	{ dateStyle: 'full', timeStyle: 'long' },
);
Result: Wednesday 1 October 1997 at 00:00:00 UTC

from(string)

Create a new date based on an ISO date string. You might use this to create a date object from a date received as a serialised string in a JSON POST request.

const result = Temporal.PlainDateTime.from('2022-05-27T06:22:11.000+0100').toLocaleString('en-GB', {
	dateStyle: 'full',
	timeStyle: 'long',
});
Result: Friday 27 May 2022 at 06:22:11 UTC

subtract

Convenient for taking off arbitrary time periods from given time or date. You might use this to filter the blog posts you want to show in a feed summary based on when they were created.

const result = Temporal.Now.plainDateTimeISO()
	.subtract({ months: 3 })
	.toLocaleString('en-GB', { dateStyle: 'full', timeStyle: 'long' });
Now: Friday 9 August 2024 at 03:52:08 UTC
Result: Thursday 9 May 2024 at 03:52:08 UTC

until

Works out how long the period between two dates is. You might use this when signing a JWT to work out how many seconds from now your expiry date is.

const now = Temporal.Now.instant();
const expiry = Temporal.Instant.from('2024-12-25T00:00:00.000+0000');
const result = now.until(expiry, { largestUnit: 'second' }).seconds;
Result: 11909271

with

You might want to set the date to a particular day of a month or a particular time on a given day. An example is where you want a user account to expire at midnight one month from today:

  • use add to shift the date to a month from today
  • use with to shift the time to a second before midnight
const result = Temporal.Now.plainDateTimeISO()
	.add({ months: 1 })
	.with({ hour: 23, minute: 59, second: 0 })
	.toLocaleString('en-GB', { dateStyle: 'full', timeStyle: 'long' });
Now: Friday 9 August 2024 at 03:52:08 UTC
Result: Monday 9 September 2024 at 23:59:00 UTC

withTimeZone

You want to call a colleague in a remote location but first check the local timing in their time zone is socially acceptable:

const local = Temporal.Now.plainDateTimeISO().toZonedDateTime('Europe/London');
const remoteTimeZone = Temporal.TimeZone.from('America/Sao_Paulo');
const result = local.withTimeZone(remoteTimeZone).plainDateTimeISO().toLocaleString('en-GB', {
	dateStyle: 'full',
	timeStyle: 'long',
});
Now: Friday 9 August 2024 at 03:52:08 BST
Result: Thursday 8 August 2024 at 23:52:08 GMT-3

Resources

Some useful links for extra colour: