JS Temporal Arithmetic
Add and Subtract Dates Safely
JavaScript Temporal has methods for easy and reliable date and time arithmetic.
Add and subtract days, months, years, and time without modifying the original value.
Perform date arithmetic without DST (Daylight Saving Time) or Time Zone problems.
Temporal add() and subtract()
All temporal objects have their own add() method:
- duration.add(duration)
- instant.add(duration)
- plaindate.add(duration)
- plaintime.add(duration)
- plainyearmonth.add(duration)
- plainmonthday.add(duration)
- plaindatetime.add(duration)
- zoneddatetime.add(duration)
All temporal objects have their own subtract() method:
- duration.subtract(duration)
- instant.subtract(duration)
- plaindate.subtract(duration)
- plaintime.subtract(duration)
- plainyearmonth.subtract(duration)
- plainmonthday.subtract(duration)
- plaindatetime.subtract(duration)
- zoneddatetime.subtract(duration)
JavaScript Temporal Add
The add() method accepts a duration object as input.
Example: { days: 10 }.
It returns a new temporal date object moved forward by the duration.
Syntax
Example
const myDate = Temporal.PlainDate.from("2026-05-17");
// Add a duration
const newDate = myDate.add({ days: 10 });
JavaScript Temporal Subtract
The subtract() method accepts a duration object as input.
Example: { days: 10 }.
It returns a new temporal date object moved backward by the duration.
Syntax
Example
const myDate = Temporal.PlainDate.from("2026-05-17");
// Subtract a duration
const newDate = myDate.subtract({ days: 10 });
Both add and subract are immutable: They both return a new Temporal object.
Date Boundaries
Both add and subtract handle date boundaries:
Adding one day to March 31st is April 1st.
Add Months
Temporal automatically handles different month lengths.
Example
const date = Temporal.PlainDate.from("2026-05-17");
const result = date.add({ months: 1 });
If the next month has fewer days, Temporal adjusts automatically.
Add Years
Adding years works correctly, even for leap years.
Example
const date = Temporal.PlainDate.from("2024-02-29");
const result = date.add({ years: 1 });
Temporal handles leap year adjustments automatically.
Supported Duration Units
The add() and subtract()
methods accept a duration object as input.
Example: { months: 2, days: 7, hours: 1 }.
The following duration units are supported:
- years
- months
- weeks
- days
- hours
- minutes
- seconds
- milliseconds
- microseconds
- nanoseconds
Add Multiple Units
Example
const myDate = Temporal.PlainDate.from('2026-05-17');
// Add multiple units
const newDate = myDate.add({ years: 1, months: 2, days: 15 });
PlainDateTime add() and subtract()
You can safely add or subtract time.
The original value does not change.
Example
const date = Temporal.PlainDateTime.from("2026-05-17T14:30:00");
// Add and subtract time
const earlier = dateTime.subtract({ minutes: 30 });
const later = dateTime.add({ hours: 2 });
PlainDate add() and subtract()
Example
const date = Temporal.PlainDate.from("2026-05-17");
// Add and subtract time
const earlier = date.subtract({ months: 3 });
const later = date.add({ days: 10 });
Instant add() and subtract()
From a Temporal.Instant you can only add or subtract time durations (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
const now = Temporal.Instant.fromEpochMilliseconds(Date.now());
// Subtract 5 hours and 30 minutes
const fiveHalfHoursAgo = now.subtract({ hours: 5, minutes: 30 });
Add a Duration to Now
Example
const today = Temporal.Now.plainDateISO();
// Add a duration
const nextWeek = today.add({ days: 7 });
Immutable
Unlike the old Date object, Temporal objects are immutable.
All methods return a new instance without modifying the existing one.
Date Arithmetic with ZonedDateTime
ZonedDateTime handles daylight saving time (DST) safely.
Example
("2026-03-29T00:00:00+01:00[Europe/Oslo]");
const nextDay = start.add({ days: 1 });
If a DST change occurs, Temporal adjusts automatically.
Compare with Date Arithmetic
The JavaScript Date object correctly implements leap year rules, but calendar calculations involving leap years can produce surprising results because invalid dates are automatically adjusted instead of reported as errors.
Adding one year to a leap day
let d = new Date("2024-02-29");
// Add one year
d.setFullYear(d.getFullYear() + 1);
Many people would expect February 28, but Date silently moves the date to March 1.
Adding 365 days is not the same
let d = new Date("2024-02-29");
// Add one year
d.setDate(d.getDate() + 365);
Now the result is February 28, which is different from setFullYear().
This illustrates that Date mixes calendar and day arithmetic in ways that can be surprising.
Invalid dates are silently corrected
let d = new Date(2025, 1, 29);
Instead of reporting an invalid date, JavaScript quietly changes it into another valid date.
Temporal Overflow
Temporal lets you choose what should happen when a date becomes invalid.
For example: February 29, 2024 + 1 year becomes invalid, because 2025 has no February 29.
The overflow option controls what happens when a date calculation produces an invalid date.
With overflow: "constrain", Temporal changes the result to the nearest valid date.
With overflow: "reject", Temporal throws an error instead of changing the date.
Overflow Default
const d = Temporal.PlainDate.from("2024-02-29");
// Add one year
const nextYear = d.add({ years: 1 });
Oveflow: "constrain"
const d = Temporal.PlainDate.from("2024-02-29");
// Add one year
const nextYear = d.add(
{ years: 1 },
{ overflow: "constrain" }
);
Oveflow: "reject"
const d = Temporal.PlainDate.from("2024-02-29");
// Add one year
try {
const nextYear = d.add(
{ years: 1 },
{ overflow: "reject" }
);
text = nextYear.toString();
} catch (err) {
text = err.name;
}
With Temporal, you can explicitly choose the overflow behavior.
Best Practices
Use PlainDate for date-only arithmetic.
Use ZonedDateTime for time zone-aware calculations.
Avoid manual millisecond calculations.
Prefer Temporal because it is Immutable.