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: Wednesday, 8 March 2023 at 12:16:05 UTC
Result: Wednesday, 8 March 2023 at 14:16:05 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: Wednesday, 8 March 2023 at 12:16:05 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: Wednesday, 8 March 2023
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: Wednesday, 8 March 2023 at 12:16:05 UTC
Result: Thursday, 8 December 2022 at 12:16:05 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('2022-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' });
Now: Wednesday, 8 March 2023 at 12:16:05 UTC
Result: Saturday, 8 April 2023 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: Wednesday, 8 March 2023 at 12:16:05 GMT
Result: Wednesday, 8 March 2023 at 09:16:05 GMT-3