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
(spaces are added for readability)
+P nY nM nW nD T nH nM nSIt covers years nY , months nM , weeks nW , days nD , and a T before hours nH , minutes nM , and seconds nS .
Example
Three years, six months, four days, twelve hours, thirty minutes, and five seconds.
P3Y6M4DT12H30M5SLearn More
JavaScript Temporal Standards
How to Create a Temporal.Duration
A Duration can be created in several different ways:
| From | Code |
|---|---|
| With Constructor | new Temporal.Duration() |
| From Object | Temporal.Duration.from() |
| From ISO String | Temporal.Duration.from() |
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});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");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;Safe Date Arithmetic
The Duration object facilitates safe and clear date and time arithmetic, preventing issues related to 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 });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 )
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 )
Learn More
Temporal Compare
The with() Method
The with() method returns a new duration with specific 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});When to Use Duration
- Adding or subtracting time
- Calculating age
- Calculating differences between dates
- Calculating time spans (hours, days, months)
Temporal.Duration Methods
| Constructing | Description |
|---|---|
| from() | Returns a new duration object from an object or an ISO string |
| new() | Returns a new duration object from integer parameters |
| Arithmetic | |
| abs() | Returns a new duration with the absolute value of this duration |
| add() | Returns a new duration with a duration added to this duration |
| negated() | Returns a new duration with this duration negated |
| round() | Returns a new duration with this duration rounded |
| subtract() | Returns a new duration with a duration subtracted from this duration |
| Comparing | |
| compare() | Compares two durations (returning -1, 0, or 1) |
| Converting | |
| with() | Returns a new duration with specified field(s) modified |
| Formatting | |
| total() | Returns a number representing the duration in a given unit |
| toJSON() | Returns an RFC 9557 format string for JSON serialization |
| toLocaleString() | Returns a language-sensitive representation of the time |
| toString() | Returns an RFC 9557 format string representation |
| valueOf() | Throws a TypeError (prevents temporals from being converted to primitives) |
Temporal.Duration Properties
| Property | Description |
|---|---|
| blank | Boolean true if the duration represents a zero duration |
| days | Days as an integer (1-31) |
| hours | Hours as an integer (0-23) |
| microseconds | Microseconds as an integer (0-999) |
| milliseconds | Milliseconds as an integer (0-999) |
| minutes | Minutes as an integer (0-59) |
| months | Months as an integer (1-12) |
| nanoseconds | Nanoseconds as an integer (0-999) |
| seconds | Seconds as an integer (0-59) |
| sign | 1 positive -1 negative |
| weeks | Weeks as an integer |
| years | Years as an integer |
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;