Temporal Duration

The Temporal.Duration Object

The Temporal.Duration object represents a length of time.

Example: 7 days and 1 hour.

The Temporal.Duration object includes these properties:

years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds and nanoseconds.

Example

// Create a Duration object

const duration = Temporal.Duration.from({days:7, hours:2});

ISO 8601 Duration Codes

An ISO 8601 duration represent lengths of time.

It uses a standard format starting with ±P (Period), followed by the structure nYnMnDTnHnMnS.

Syntax

+P nY nM nW nD T nH nM nS

It covers years nY, months nM, weeks nW, days nD, and a T before hours nH, minutes nM, and seconds nS.

Example

P3Y6M4DT12H30M5S

More Examples

Note: Learn More: JavaScript Temporal Standards

How to Create a Temporal.Duration

A Duration can be created in several different ways:

Create a Duration Using new

You can create a Temporal.Duration object using the new constructor with integer parameters.

Example

// Create a Duration object

const duration = new Temporal.Duration(0, 0, 0, 7, 2);

The parameters must be in this orde:

• Years
• Months
• Weeks
• Days
• Hours
• Minutes
• Seconds
• Milliseconds
• Microseconds
• Nanoseconds

Create a Duration Using an Object

You can create a duration object using the from() method with an object literal parameter like {days:7, hours: 2}:

Example

// Create a Duration object

const duration = Temporal.Duration.from({days:7, hours:2});

Note: An object literal is the most common method for creating JavaScript objects. You create an object by literally writing its contents as key:value pairs enclosed in curly braces { }.

Create a Duration Using an ISO string

You can create a Duration object using the from() method with an ISO duration string as parameter.

Example

// Create a Duration

const duration = Temporal.Duration.from("P7DT2H");

Note: Learn More: ISO Duration Strings

Temporal.Duration Properties

The Temporal.Duration object has 12 properties of time information.

Example

//Create a Duration

const duration = new Temporal.Duration(0, 0, 0, 7, 2, 0);

// List the Properties

let text =

"blank: " + duration.blank + " " +

"sign: " + duration.sign + " " +

"years: " + duration.years + " " +

"months: " + duration.months + " " +

"weeks: " + duration.weeks + " " +

"days: " + duration.days + " " +

"hour: " + duration.hours  + " " +

"minutes: " + duration.minutes  + " " +

"seconds: " + duration.seconds  + " " +

"milliseconds: " + duration.milliseconds  + " " +

"microseconds: " + duration.microseconds  + " " +

"nanoseconds: " + duration.nanoseconds;

The with() Method

The with() method returns a new duration with specific properties (time units) replaced:

Example

// Create a Duration

const duration = Temporal.Duration.from({hours:10, minutes:30});

// Create a new duration with the minutes changed to 45

const newDuration = duration.with({minutes:45});

Safe Date Arithmetic

The Duration object facilitates safe and clear date and time arithmetic, preventing issues related to DST (daylight saving time) and time zone changes.

The Duration object can handle time in various units, including years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds, and nanoseconds.

The Duration object makes date arithmetic clear, readable, and safer than using manual millisecond calculations.

The Duration add() Method

The add() method returns a new duration with a duration added.

The add() method does not change the original duration.

Example

// Create a Duration

const d1 = Temporal.Duration.from({ hours:2, minutes:30 });

// Add a Duration

const d2 = d1.add({ hours:1, minutes:30 });

The Duration subtract() Method

The subtract() method returns a new duration with a duration subtracted.

The subtract() method does not change the original duration.

Example

// Create a Duration

const d1 = Temporal.Duration.from({ hours:2, minutes:30 });

// Subtract a Duration

const d2 = d1.subtract({ hours:1, minutes:30 });

Note: Immutability Temporal objects are immutable, meaning operations like add() or subtract() return a new Temporal.Duration instance, leaving the original unchanged.

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)

Note: Learn More: Temporal Arithmetic

The Compare() Method

The Temporal.Duration object does not have an equals() method due to the complexity of handling different representations of the same duration.

Instead, equality is checked using the static Temporal.Duration.compare() method.

This method returns -1 if the first duration is shorter, 0 if it is the same, and 1 if it is longer.

Examples

// Create two Durations

const d1 = Temporal.Duration.from({ hours:1, minutes:30 });

const d2 = Temporal.Duration.from({ minutes:90 });

// Compare the Durations

let result = Temporal.Duration.compare(d1, d2);

Note: that both examples return 0 for equal. 90 minutes is the same duration as 1 hour and 30 minutes.

All temporal objects have their own compare() method:

• Temporal.Instant.compare(instant1, instant2)
• Temporal.PlainDate.compare(plaindate1, plaindate2)
• Temporal.PlainTime.compare(plaintime1, plaintime2)
• Temporal.PlainYearMonth.compare(plainyearmonth1, plainyearmonth2)
• Temporal.PlainMonthDay.compare(plainmonthday1 plainmonthday2)
• Temporal.PlainDateTime.compare(plaindatetime1,plaindatetime2)
• Temporal.ZonedDateTime.compare(zoneddtatime1, zoneddtatime2)
• Temporal.Duration.compare(duration1, duration2)

Note: Learn More: Temporal Compare

Range Errors

Example

// Create two Durations

const d1 = Temporal.Duration.from({ days:30 });

const d2 = Temporal.Duration.from({ months: 1 });

// Compare the Durations

let result = Temporal.Duration.compare(d1, d2);

The code above fails and throws a RangeError because d2 contains a calendar unit (months), which has an uneven and variable length.

Without a specific starting point on the calendar, the JavaScript runtime cannot determine exactly how many days are in "1 month" to perform the comparison.

For example, 1 month starting in February could be 28 or 29 days, while 1 month starting in January is 31 days.

No equals() Method

The Temporal.Duration object does not have an equals() method because durations can be represented in multiple "unbalanced" ways that are mathematically equivalent but structurally different.

For example, a duration of 90 seconds is logically equal to 1 minute and 30 seconds, but they are stored as distinct property sets within the Temporal.Duration object.

Unbalanced Units: By default, Temporal.Duration preserves the units exactly as they were defined. Because "60 minutes" and "1 hour" are different internal representations, a standard equals() method would be ambiguous (should it check for identical properties or identical time length?)

Variable Unit Lengths: Units like days, months, and years do not have a fixed length. A "month" can be 28, 30, or 31 days depending on the calendar and reference date.

Need for Context: To accurately compare two durations containing calendar units (years, months, weeks), you must provide a relativeTo option (a specific starting point). Without this reference, the API cannot determine if two calendar-based durations are truly "equal".

Note: Instead of a simple equals() method, the TC39 Temporal proposal requires developers to use the static Temporal.Duration.compare() method instead.

When to Use Duration

• Adding or subtracting time
• Calculating age
• Calculating differences between dates
• Calculating time spans (hours, days, months)

Temporal.Duration Methods

Temporal.Duration Properties

Display All Duration Properties

//Create a Duration

const duration = new Temporal.Duration(0, 0, 0, 7, 2, 0);

// List the Properties

let text =

"blank: " + duration.blank + " " +

"sign: " + duration.sign + " " +

"years: " + duration.years + " " +

"months: " + duration.months + " " +

"weeks: " + duration.weeks + " " +

"days: " + duration.days + " " +

"hour: " + duration.hours  + " " +

"minutes: " + duration.minutes  + " " +

"seconds: " + duration.seconds  + " " +

"milliseconds: " + duration.milliseconds  + " " +

"microseconds: " + duration.microseconds  + " " +

"nanoseconds: " + duration.nanoseconds;