JavaScript Temporal Math
Temporal Arithmetic
The Temporal API provides methods for performing easy and reliable date and time arithmetic.
temporal.add(temporal)temporal.subtract(temporal)temporal.since(temporal)temporal.until(temporal)
Example
// Create a Temporal object
const myDate = Temporal.PlainDate.from('2026-05-01');
// Subtract a duration
const newDate = myDate.subtract({ days: 7 });
Try it Yourself »
Temporal Add and Subtract
Both methods are immutable, returning new Temporal objects.
Both methods accept an object with duration properties { days: 7, hours: 1 } as input.
Both methods handles date boundaries: adding one day to March 31st is April 1st.
JavaScript Temporal subtract()
The subtract() method returns a new temporal object representing this date moved backward
by a given duration.
Syntax
temporal.subtract(duration)
From a Temporal.PlainDate (a date without a time zone) you can subtract a full duration:
Example
// Create a Temporal object
const myDate = Temporal.PlainDate.from('2026-05-01');
// Subtract a duration
const newDate = myDate.subtract({ days: 7 });
Try it Yourself »
Example
// Create a Temporal object
const today = Temporal.Now.plainDateISO();
// Subtract a duration
const lastWeek = today.subtract({ days: 7 });
Try it Yourself »
From a Temporal.Instant you can only subtract a fixed duration (hours, minutes, seconds) but not calendar durations like months or years, as their length can vary depending on the time zone and the calendar.
Example
// Create a Temporal.Instant object
const now = Temporal.Instant.fromEpochMilliseconds(Date.now());
// Subtract 5 hours and 30 minutes
const fiveHalfHoursAgo = now.subtract({ hours: 5, minutes: 30 });
Try it Yourself »
JavaScript Temporal add()
The add() method returns a new temporal object representing this date moved forward
by a given duration.
Syntax
temporal.add(duration)
Example
// Create a Temporal object
const myDate = Temporal.PlainDate.from('2026-05-01');
// Add a duration
const newDate = myDate.add({ days: 10 });
Try it Yourself »
Example
// Create a Temporal object
const today = Temporal.Now.plainDateISO();
// Add a duration
const nextWeek = today.add({ days: 7 });
Try it Yourself »
Example
// Create a Temporal object
const today = Temporal.Now.plainDateISO();
// Add multiple units
const newDate = today.add({ years: 1, months: 2, days: 15 });
Try it Yourself »
Supported Units
You can add or subtract various time units using a duration object:
- years
- months
- weeks
- days
- hours
- minutes
- seconds
- milliseconds
- microseconds
- nanoseconds
Note
Unlike the legacy Date object, Temporal objects are immutable.
Methods like until(), add(), or with() always return a new instance rather than modifying the existing one.
Temporal.Duration
Duration objects can be parsed as a string using the ISO 8601 duration format.
It has the following form (spaces are only for readability):
+P nY nM nW nD T nH nM nS
| Code | Description |
|---|---|
| + | Optional +/- sign for positive/negative duration. Default is +. |
| P | Duration designator (for period) |
| nY | Number of calendar years |
| nM | Number of calendar months |
| nW | Number of weeks |
| nD | Number of calendar days |
| T | Time designator (precedes time components) |
| nH | Number of hours |
| nM | Number of minutes |
| nS | Number of seconds |
For example, "P3Y6M4DT12H30M5S" represents a duration of "three years, six months, four days, twelve hours, thirty minutes, and five seconds".
JavaScript Temporal since()
The since() method calculates the duration between
two temporal date/time values.
The since() method is effectively the inverse of the
until() method.
Syntax
temporal.since(temporal, options)
The since() method returns a Temporal.Duration Object
representing the elapsed time.
The duration is positive if the "other" date is in the past, or negative if it is in the future:
Example
const wedding = Temporal.PlainDate.from('2026-05-01');
const today = Temporal.Now.plainDateISO();
const duration = today.since(wedding);
Try it Yourself »
You can control the precision using largestUnit and smallestUnit options:
Example
const wedding = Temporal.PlainDate.from('2026-05-01');
const today = Temporal.Now.plainDateISO();
const duration = today.since(wedding, {largestUnit:'years'});
Try it Yourself »
JavaScript Temporal until()
The until() method calculates the duration between
two temporal date/time values.
The until() method is effectively the inverse of the
since() method.
Syntax
temporal.until(temporal, options)
Example
const wedding = Temporal.PlainDate.from('2026-05-01');
const today = Temporal.Now.plainDateISO();
const duration = today.until(wedding);
Try it Yourself »
Note
The since() method does this - other.
The until() method does other - this.
The width() Method
The width() method returns a new date with specific fields replaced (changing the year).
Example
// Create a Temporal object
const date = Temporal.PlainDate.from("2026-05-01");
// Replace month and day
const customDate = date.with({ month:12, day:25 });
Try it Yourself »
The compare() Method
The compare() method returns -1 if the first date is earlier, 1 if it is later, and 0 if they are equal:
Example
// Create two Temporal objects
const date1 = Temporal.PlainDate.from("2026-05-01");
const date2 = Temporal.PlainDate.from("2024-12-25");
// Compare the dates
result = Temporal.PlainDate.compare(date1, date2);
Try it Yourself »
The compare() method is designed to be passed directly into the JavaScript Array.sort() method:
Example
// Create an Array of dates
const dates = [
Temporal.PlainDate.from("2026-05-01"),
Temporal.PlainDate.from("2022-01-01"),
Temporal.PlainDate.from("2024-12-25")
];
// Sort chronologically
dates.sort(Temporal.PlainDate.compare);
Try it Yourself »
Date Comparison
Always use the equals() or compare() methods rather than standard equality operators.
The equals() Method
Example
// Create two Temporal objects
const date1 = Temporal.PlainDate.from('2026-05-01');
const date2 = Temporal.PlainDate.from('2026-05-01');
let result = date1.equals(date2);
Try it Yourself »
