const date = Temporal.Now.plainDateISO(); // Gets the current date
date.toString(); // returns the date in ISO 8601 date format
// If you additionally want the time:
Temporal.Now.plainDateTimeISO().toString(); // date and time in ISO 8601 formatTemporal cookbook / notebook
Temporal cookbook
Runnable notebook: every JavaScript, HTML and CSS example on this page executes in a sandboxed local frame. Nothing leaves the browser.
const timeStamp = Temporal.Now.instant();
// Timestamp in milliseconds
timeStamp.epochMilliseconds;
// Timestamp in seconds
Math.floor(timeStamp.epochMilliseconds / 1000);const legacyDate = new Date("1970-01-01T00:00:01Z");
const instant = legacyDate.toTemporalInstant();
console.log(instant.epochMilliseconds === legacyDate.getTime()); // true
console.log(instant.toString()); // '1970-01-01T00:00:01Z'
const zoned = instant.toZonedDateTimeISO(Temporal.Now.timeZoneId());
console.log(zoned.epochMilliseconds === legacyDate.getTime()); // trueconst zoned2 = instant.toZonedDateTimeISO("Asia/Shanghai");
console.log(zoned2.epochMilliseconds === legacyDate.getTime()); // true
console.log(zoned2.timeZoneId); // 'Asia/Shanghai'// Convert a year/month/day `Date` to a `Temporal.PlainDate`. Uses the caller's time zone.
let date = new Date(2000, 0, 1);
// Sat Jan 01 2000 00:00:00 GMT-0800 (Pacific Standard Time)
let plainDate = date
.toTemporalInstant() // 2000-01-01T08:00:00Z
.toZonedDateTimeISO(Temporal.Now.timeZoneId()) // 2000-01-01T00:00:00-08:00[America/Los_Angeles]
.toPlainDate(); // 2000-01-01
console.log(plainDate.toString()); // '2000-01-01'
// Convert a year/month/day `Date` to a `Temporal.PlainDate`. Uses UTC.
date = new Date(Date.UTC(2000, 0, 1));
// Fri Dec 31 1999 16:00:00 GMT-0800 (Pacific Standard Time)
date = new Date("2000-01-01T00:00Z");
// Fri Dec 31 1999 16:00:00 GMT-0800 (Pacific Standard Time)
plainDate = date
.toTemporalInstant() // 2000-01-01T00:00:00Z
.toZonedDateTimeISO("UTC") // 2000-01-01T00:00:00+00:00[UTC]
.toPlainDate(); // 2000-01-01
console.log(plainDate.toString()); // '2000-01-01'const instant = Temporal.Instant.from("2020-01-01T00:00:01.000999Z");
const result = new Date(instant.epochMilliseconds);
console.log(result.getTime()); // 1577836801000 // ms since Unix epoch
console.log(result.toISOString()); // '2020-01-01T00:00:01.000Z'const zoned = Temporal.ZonedDateTime.from(
"2020-01-01T00:00:01.001[Asia/Tokyo]",
);
const result2 = new Date(zoned.epochMilliseconds);
console.log(result2.getTime()); // 1577804401001 // note, different time
console.log(result2.toISOString()); // '2019-12-31T15:00:01.001Z'const result3 = new Date(
instant.round({ smallestUnit: "millisecond" }).epochMilliseconds,
);
console.log(result3.getTime()); // 1577836801001
console.log(result3.toISOString()); // '2020-01-01T00:00:01.001Z'<input type="date" id="calendar-input" />const datePicker = document.getElementById("calendar-input");
const today = Temporal.Now.plainDateISO();
datePicker.max = today;
datePicker.value = today;const date = Temporal.PlainDate.from("2020-05-14");
const noonOnDate = date.toPlainDateTime(Temporal.PlainTime.from({ hour: 12 }));
console.log(noonOnDate.toString()); // '2020-05-14T12:00:00'const birthday = Temporal.PlainMonthDay.from("12-15");
const birthdayIn2030 = birthday.toPlainDate({ year: 2030 });
birthdayIn2030.dayOfWeek; // 7
console.log(birthdayIn2030.toString()); // '2030-12-15'const instant = Temporal.Instant.from("2020-01-03T10:41:51Z");
const result = instant.toString();
console.log(result); // '2020-01-03T10:41:51Z'
console.log(instant.equals(Temporal.Instant.from(result))); // trueconst result2 = instant.toString({ timeZone: "America/Yellowknife" });
console.log(result2); // '2020-01-03T03:41:51-07:00'
console.log(instant.equals(Temporal.Instant.from(result2))); // trueconst zoned = instant.toZonedDateTimeISO("Asia/Seoul");
const result3 = zoned.toString();
console.log(result3); // '2020-01-03T19:41:51+09:00[Asia/Seoul]'
console.log(instant.equals(Temporal.Instant.from(result3))); // true
console.log(zoned.equals(Temporal.ZonedDateTime.from(result3))); // truefunction getSortedLocalDateTimes(dateTimes, reverse = false) {
let newDateTimes = Array.from(dateTimes).sort(Temporal.PlainDateTime.compare);
return reverse ? newDateTimes.reverse() : newDateTimes;
}
// Sorting some conferences without timezones for example vue.js Amsterdam 2020
const a = Temporal.PlainDateTime.from({
year: 2020,
day: 20,
month: 2,
hour: 8,
minute: 45,
}); // Introduction
const b = Temporal.PlainDateTime.from({
year: 2020,
day: 21,
month: 2,
hour: 13,
minute: 10,
}); // Lunch Break
const c = Temporal.PlainDateTime.from({
year: 2020,
day: 20,
month: 2,
hour: 15,
minute: 30,
}); // Coffee Break
const results = getSortedLocalDateTimes([a, b, c]);
console.log(results.map((x) => x.toString()));
// ['2020-02-20T08:45:00', '2020-02-20T15:30:00', '2020-02-21T13:10:00']function sortInstantStrings(strings, reverse = false) {
const sortedInstants = strings
.map((v) => [v, Temporal.Instant.from(v)])
.sort(([, i1], [, i2]) => Temporal.Instant.compare(i1, i2))
.map(([str]) => str);
return reverse ? sortedInstants.reverse() : sortedInstants;
}
// simple string comparison order would not be correct here:
const a = "2020-01-23T17:04:36.491865121-08:00";
const b = "2020-02-10T17:04:36.491865121-08:00";
const c = "2020-04-01T05:01:00-04:00[America/New_York]";
const d = "2020-04-01T10:00:00+01:00[Europe/London]";
const e = "2020-04-01T11:02:00+02:00[Europe/Berlin]";
const results = sortInstantStrings([a, b, c, d, e]);
// results will have correct order
console.log(results);
// [
// '2020-01-23T17:04:36.491865121-08:00',
// '2020-02-10T17:04:36.491865121-08:00',
// '2020-04-01T10:00:00+01:00[Europe/London]',
// '2020-04-01T05:01:00-04:00[America/New_York]',
// '2020-04-01T11:02:00+02:00[Europe/Berlin]'
// ]const time = Temporal.PlainTime.from("12:38:28.138818731");
const wholeHour = time.round({ smallestUnit: "hour", roundingMode: "floor" });
console.log(wholeHour.toString()); // '12:00:00'const date = Temporal.PlainDate.from("2018-09-16");
const firstOfCurrentMonth = date.with({ day: 1 });
const firstOfNextMonth = firstOfCurrentMonth.add({ months: 1 });
const sinceCurrent = date.since(firstOfCurrentMonth);
const untilNext = date.until(firstOfNextMonth);
const isCloserToNextMonth =
Temporal.Duration.compare(sinceCurrent, untilNext) >= 0;
const nearestMonth = isCloserToNextMonth
? firstOfNextMonth
: firstOfCurrentMonth;
console.log(nearestMonth.toString()); // '2018-10-01'function getInstantWithLocalTimeInZone(
dateTime,
timeZone,
disambiguation = "earlier",
) {
// Handle the built-in modes first
if (["compatible", "earlier", "later", "reject"].includes(disambiguation)) {
return dateTime.toZonedDateTime(timeZone, { disambiguation }).toInstant();
}
const possibilities = ["earlier", "later"].map((disambiguation) =>
dateTime.toZonedDateTime(timeZone, { disambiguation }),
);
const instants = possibilities
.map((zdt) => zdt.toInstant())
.reduce((a, b) => (a.equals(b) ? [a] : [a, b]));
// Return only possibility if no disambiguation needed
if (instants.length === 1) return instants[0];
switch (disambiguation) {
case "clipEarlier":
if (possibilities[0].toPlainDateTime().equals(dateTime)) {
return instants[0];
}
return possibilities[0]
.getTimeZoneTransition("next")
.subtract({ nanoseconds: 1 })
.toInstant();
case "clipLater":
if (possibilities[1].toPlainDateTime().equals(dateTime)) {
return instants[1];
}
return possibilities[0].getTimeZoneTransition("next").toInstant();
}
throw new RangeError(`invalid disambiguation ${disambiguation}`);
}
const nonexistentGermanWallTime =
Temporal.PlainDateTime.from("2019-03-31T02:45");
const germanResults = {
earlier: "2019-03-31T01:45:00+01:00",
later: "2019-03-31T03:45:00+02:00",
compatible: "2019-03-31T03:45:00+02:00",
clipEarlier: "2019-03-31T01:59:59.999999999+01:00",
clipLater: "2019-03-31T03:00:00+02:00",
};
for (const [disambiguation, result] of Object.entries(germanResults)) {
console.log(
getInstantWithLocalTimeInZone(
nonexistentGermanWallTime,
"Europe/Berlin",
disambiguation,
).toString({
timeZone: "Europe/Berlin",
}) === result,
); // true
}
const doubleEasternBrazilianWallTime =
Temporal.PlainDateTime.from("2019-02-16T23:45");
const brazilianResults = {
earlier: "2019-02-16T23:45:00-02:00",
later: "2019-02-16T23:45:00-03:00",
compatible: "2019-02-16T23:45:00-02:00",
clipEarlier: "2019-02-16T23:45:00-02:00",
clipLater: "2019-02-16T23:45:00-03:00",
};
for (const [disambiguation, result] of Object.entries(brazilianResults)) {
console.log(
getInstantWithLocalTimeInZone(
doubleEasternBrazilianWallTime,
"America/Sao_Paulo",
disambiguation,
).toString({
timeZone: "America/Sao_Paulo",
}) === result,
); // true
}const source = Temporal.ZonedDateTime.from("2020-01-09T00:00[America/Chicago]");
const result = source.withTimeZone("America/Los_Angeles");
// On this date, when it's midnight in Chicago, it's 10 PM the previous night in LA
console.log(result.toString());
// '2020-01-08T22:00:00-08:00[America/Los_Angeles]'// Dates of the 2019 TC39 meetings:
const tc39meetings = [
{
dateTime: "2019-01-28T10:00",
timeZone: "America/Phoenix",
},
{
dateTime: "2019-03-26T10:00",
timeZone: "America/New_York",
},
{
dateTime: "2019-06-04T10:00",
timeZone: "Europe/Berlin",
},
{
dateTime: "2019-07-23T10:00",
timeZone: "America/Los_Angeles",
},
{
dateTime: "2019-10-01T10:00",
timeZone: "America/New_York",
},
{
dateTime: "2019-12-03T10:00",
timeZone: "America/Los_Angeles",
},
];
// To follow the meetings remotely from Tokyo, calculate the times you would
// need to join:
const localTimeZone = "Asia/Tokyo";
const localTimes = tc39meetings.map(({ dateTime, timeZone }) =>
Temporal.PlainDateTime.from(dateTime)
.toZonedDateTime(timeZone, { disambiguation: "reject" })
.withTimeZone(localTimeZone)
.toPlainDateTime(),
);
console.log(localTimes.map((dt) => dt.toString()));
// [
// "2019-01-29T02:00:00",
// "2019-03-26T23:00:00",
// "2019-06-04T17:00:00",
// "2019-07-24T02:00:00",
// "2019-10-01T23:00:00",
// "2019-12-04T03:00:00",
// ]function* calculateDailyOccurrence(startDate, plainTime, timeZone) {
for (let date = startDate; ; date = date.add({ days: 1 })) {
yield date.toZonedDateTime({ plainTime, timeZone }).toInstant();
}
}
// Daily meeting at 8 AM California time
const startDate = Temporal.PlainDate.from("2017-03-10");
const time = Temporal.PlainTime.from("08:00");
const timeZone = "America/Los_Angeles";
const iter = calculateDailyOccurrence(startDate, time, timeZone);
console.log(iter.next().value.toString()); // '2017-03-10T16:00:00Z'
console.log(iter.next().value.toString()); // '2017-03-11T16:00:00Z'
// DST change:
console.log(iter.next().value.toString()); // '2017-03-12T15:00:00Z'
console.log(iter.next().value.toString()); // '2017-03-13T15:00:00Z'const instant = Temporal.Instant.from("2020-01-09T00:00Z");
const source = instant.toZonedDateTimeISO("America/New_York");
source.offset; // '-05:00'const instant = Temporal.Instant.from("2020-01-09T00:00Z");
instant.toZonedDateTimeISO("America/New_York").offsetNanoseconds / 1e9;
// -18000function getUtcOffsetDifferenceSecondsAtInstant(
instant,
sourceTimeZone,
targetTimeZone,
) {
const sourceOffsetNs =
instant.toZonedDateTimeISO(sourceTimeZone).offsetNanoseconds;
const targetOffsetNs =
instant.toZonedDateTimeISO(targetTimeZone).offsetNanoseconds;
return (targetOffsetNs - sourceOffsetNs) / 1e9;
}
const instant = Temporal.Instant.from("2020-01-09T00:00Z");
// At this exact time, Chicago is 3600 seconds earlier than New York
console.log(
getUtcOffsetDifferenceSecondsAtInstant(
instant,
"America/New_York",
"America/Chicago",
),
); // -3600