JavaScript Temporal Arithmetic
Temporal Math
The JavaScript Temporal API provides add() and
subtract() methods for performing easy and reliable date and time arithmetic.
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()
Syntax
temporal.subtract(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 »
JavaScript Temporal add()
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 »
Temporal.Duration
+P nY nM nW nD T nH nM nS
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 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 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.
Date Comparison
Always use the .equals() or .compare() methods rather than standard equality operators:
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 »
Supported Units
You can add or subtract various time units using a duration object:
- years
- months
- weeks
- days
- hours
- minutes
- seconds
- milliseconds
- microseconds
- nanoseconds