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

temporal.add(duration)

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

temporal.subtract(duration)

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

// Create a Temporal object

const date = Temporal.PlainDate.from("2026-05-17");

const result = date.add({ months: 1 });

Add Years

Adding years works correctly, even for leap years.

Example

// Create a Temporal object

const date = Temporal.PlainDate.from("2024-02-29");

const result = date.add({ years: 1 });

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

// Create any Temporal object

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

// Create a PlainDateTime object

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

// Create a PlainDate object

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

// 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 });

Add a Duration to Now

Example

// Create a Temporal object

const today = Temporal.Now.plainDateISO();

// Add a duration

const nextWeek = today.add({ days: 7 });

Date Arithmetic with ZonedDateTime

ZonedDateTime handles daylight saving time (DST) safely.

Example

const start = Temporal.ZonedDateTime.from

("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

// Create a Date object

let d = new Date("2024-02-29");

// Add one year

d.setFullYear(d.getFullYear() + 1);

Adding 365 days is not the same

// Create a Date object

let d = new Date("2024-02-29");

// Add one year

d.setDate(d.getDate() + 365);

Invalid dates are silently corrected

// Create a Date object

let d = new Date(2025, 1, 29);

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

// Create a PlainDate object

const d = Temporal.PlainDate.from("2024-02-29");

// Add one year

const nextYear = d.add({ years: 1 });

Oveflow: "constrain"

// Create a PlainDate object

const d = Temporal.PlainDate.from("2024-02-29");

// Add one year

const nextYear = d.add(

  { years: 1 },

  { overflow: "constrain" }

);

Oveflow: "reject"

// Create a PlainDate object

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;

}

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.