JavaScript Temporal API Cheatsheet

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' });

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'),
);

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'));

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' },
);

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',
});

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' });

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;

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' });

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',
});