JavaScript 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});
Result
P7DT2H
Try it Yourself »
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 nS
It 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.
P3Y6M4DT12H30M5S
More Examples
| Duration | Code |
|---|---|
| 1 Day | P1D |
| 45 Minutes | PT45M |
| 1 Year, 2 Months, 3 Days | P1Y2M3D |
| 4 Hours, 5 Minutes, 6 Seconds | PT4H5M6S |
| 2.5 Hours | PT2H30M |
| 5 Weeks | P5W |
Learn More:
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 of 7 days and 2 hours.
// Create a Duration object
const duration = new Temporal.Duration(0, 0, 0, 7, 2);
Try it Yourself »
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});
Try it Yourself »
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.
Learn More:
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;
Try it Yourself »
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 });
Try it Yourself »
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 });
Try it Yourself »
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:
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);
Try it Yourself »
// Create two Durations
const d1 = Temporal.Duration.from({ hours:1, minutes:30 });
const d2 = Temporal.Duration.from({ hours:1, minutes:30 });
// Compare the Durations
let result = Temporal.Duration.compare(d1, d2);
Try it Yourself »
Note that both examples return 0 for equal.
90 minutes is the same duration as 1 hour and 30 minutes.
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});
Try it Yourself »
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;
Try it Yourself »
