Temporal API #
Temporal is the new Date and Time API for Javascript.
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal
-
Instant: a single instant in time. ex: unix timestamp. -
Duration: a length of time, such as two hours, or the difference between two timestamps. -
PlainTime: a time of day without a date. ex: 4:30 am. -
PlainDate: a date without a time: ex: June 12, 2026 -
PlainDateTime: a date and time together, but no timezone. -
ZonedDateTime: a date and time together in a specific timezone.
Create a new Instant for right now.
// simple 'now'
const now = Temporal.Now.instant();
// now with local time zone
const nowInLocalZone = Temporal.Now.zonedDateTimeISO();
// now with specific time zone
const nowInPacific = Temporal.Now.zonedDateTimeISO("America/Los_Angeles");
Difference between two Instants
const a = Temporal.Instant.from("2026-05-26T12:00:00Z");
const b = Temporal.Instant.from("2026-05-26T15:30:00Z");
const diff = a.until(b, {
largestUnit: "hours",
smallestUnit: "minutes"
});
console.log(diff.toString());
// "PT3H30M"
console.log(diff.hours); // 3
console.log(diff.minutes); // 30
Difference between two PlainDates (days without time)
const start = Temporal.PlainDate.from("2026-05-01");
const end = Temporal.PlainDate.from("2026-05-26");
const diff = start.until(end);
console.log(diff.toString());
// "P25D"
console.log(diff.days);
// 25
Convert Date to Instant
// Date from String
const date = new Date("2026-05-26T12:30:00Z");
// Date -> Temporal.Instant
const instant = Temporal.Instant.fromEpochMilliseconds(date.getTime());
// Temporal.Instant from a string
const instantLit = Temporal.Instant.from("2026-05-26T12:30:00Z");
// Temporal.Instant -> Date
const date = new Date(instant.epochMilliseconds);
To JSON
Converting a temporal object to JSON will turn it into a plain string. ex:
const obj = {
createdAt: Temporal.Instant.from("2026-05-26T12:30:00Z"),
dueDate: Temporal.PlainDate.from("2026-06-01"),
meetingTime: Temporal.PlainDateTime.from("2026-06-01T09:30:00"),
localMeeting: Temporal.ZonedDateTime.from(
"2026-06-01T09:30:00[America/Los_Angeles]"
)
};
console.log(JSON.stringify(obj, null, 2));
Produces:
{
"createdAt": "2026-05-26T12:30:00Z",
"dueDate": "2026-06-01",
"meetingTime": "2026-06-01T09:30:00",
"localMeeting": "2026-06-01T09:30:00-07:00[America/Los_Angeles]"
}
From JSON
To parse JSON and get the temporal object back you'll need to preserve the type and use a custom parser.
const obj = {
createdAt: {
type: "Temporal.Instant",
value: Temporal.Now.instant().toString()
}
};
const parsed = JSON.parse(json, (key, value) => {
if (
value &&
value.type === "Temporal.Instant" &&
typeof value.value === "string"
) {
return Temporal.Instant.from(value.value);
}
return value;
});
asd