Duration
The Duration
immutable class represents a duration of time broken down into days, hours, minutes, seconds, and milliseconds. It provides a variety of methods for creation, formatting, comparison, calculation, and conversion of duration instances.
TIP
All instances of Duration
are immutable!
So all manipulation methods return a new instance of duration.
Table of Contents
Instance Properties
day
Return the number of days in the duration.
- Type:
number
Example:
const duration = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
console.log(duration.day); // 6
hour
Return the number of hours in the duration.
- Type:
number
Example:
const duration = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
console.log(duration.hour); // 12
minute
Return the number of minutes in the duration.
- Type:
number
Example:
const duration = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
console.log(duration.minute); // 30
second
Return the number of seconds in the duration.
- Type:
number
Example:
const duration = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
console.log(duration.second); // 45
millisecond
Return the number of milliseconds in the duration.
- Type:
number
Example:
const duration = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
console.log(duration.millisecond); // 2
inDays
Returns the total duration in days.
- Type:
number
Example:
const duration = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
console.log(duration.inDays); // 6.521354189814815
inHours
Returns the total duration in hours.
- Type:
number
Example:
const duration = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
console.log(duration.inHours); // 156.51250055555556
inMinutes
Returns the total duration in minutes.
- Type:
number
Example:
const duration = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
console.log(duration.inMinutes); // 9390.750033333334
inSeconds
Returns the total duration in seconds.
- Type:
number
Example:
const duration = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
console.log(duration.inSeconds); // 563445.002
inMilliseconds
Returns the total duration in milliseconds.
- Type:
number
Example:
const duration = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
console.log(duration.inMilliseconds); // 563445002
Instance Methods
valueOf
Returns the total duration in milliseconds.
valueOf(): number
- Parameters:
void
- Returns:
number
- Throws:
void
Example:
const duration = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
console.log(duration.valueOf()); // 563445002
toString
Returns the human-readable string representation of the duration.
toString(): string
- Parameters:
void
- Returns:
string
- Throws:
void
Example:
const duration = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
console.log(duration.toString()); // 6 days 12:30:45.002
[Symbol.toPrimitive]
Custom implementation to handle coercion.
[Symbol.toPrimitive](hint: string): number | string
- Parameters:
hint
:- description: The hint type (
"number"
or"string"
) - Type:
string
- description: The hint type (
- Returns:
string | number
- Throws:
void
Example:
const duration = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
console.log(+duration); // 563445002
console.log(`${duration}`); // 6 days 12:30:45.002
toJSON
Returns the JSON serialization representation of the duration.
toJSON(): string
- Parameters:
void
- Returns:
string
- Throws:
void
Example:
const duration = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
console.log(duration.toJSON()); // "P6DT12H30M45.002S"
toISOString
Returns the ISO 8601 representation of the duration.
toISOString(): string
- Parameters:
void
- Returns:
string
- Throws:
void
Example:
const duration = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
console.log(duration.toISOString()); // P6DT12H30M45.002S
toObject
Returns the object literal of the duration.
toObject(): Object
- Parameters:
void
- Returns:
Object
- Throws:
void
Example:
const duration = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
console.log(duration.toObject()); // {day: 6, hour: 12, minute: 30, second: 45, millisecond: 2}
equals
Returns whether the duration is equal to the other duration.
equals(other: Duration): boolean
- Parameters:
other
:- description: The other duration to compare against.
- Type:
Duration
- Returns:
boolean
- Throws:
void
Example:
const duration1 = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
const duration2 = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
console.log(duration1.equals(duration2)); // true
isLongerThan
Returns whether the duration is longer than the other duration.
isLongerThan(other: Duration): boolean
- Parameters:
other
:- description: The other duration to compare against.
- Type:
Duration
- Returns:
boolean
- Throws:
void
Example:
const duration1 = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
const duration2 = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
console.log(duration1.isLongerThan(duration2)); // false
isShorterThan
Returns whether the duration is shorter than the other duration.
isShorterThan(other: Duration): boolean
- Parameters:
other
:- description: The other duration to compare against.
- Type:
Duration
- Returns:
boolean
- Throws:
void
Example:
const duration1 = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
const duration2 = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
console.log(duration1.isShorterThan(duration2)); // false
withDay
Return a new duration with days replaced.
withDay(day: number): Duration
- Parameters:
day
:- description: The day to replace the old one.
- Type:
number
- Returns:
Duration
- Throws:
void
Example:
const duration = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
const durationWithDay = duration.withDay(3);
console.log(durationWithDay.toString()); // 3 days 12:30:45.002
withHour
Return a new duration with hours replaced.
withHour(hour: number): Duration
- Parameters:
hour
:- description: The hour to replace the old one.
- Type:
number
- Returns:
Duration
- Throws:
void
Example:
const duration = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
const durationWithHour = duration.withHour(23);
console.log(const durationWithHour = duration.withHour(23);
.toString()); // 6 days 23:30:45.002
withMinute
Return a new duration with minutes replaced.
withMinute(minute: number): Duration
- Parameters:
minute
:- description: The minute to replace the old one.
- Type:
number
- Returns:
Duration
- Throws:
void
Example:
const duration = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
const durationWithMinute = duration.withMinute(59);
console.log(durationWithMinute.toString()); // 6 days 12:59:45.002
withSecond
Return a new duration with seconds replaced.
withSecond(second: number): Duration
- Parameters:
second
:- description: The second to replace the old one.
- Type:
number
- Returns:
Duration
- Throws:
void
Example:
const duration = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
const durationWithSecond = duration.withSecond(59);
console.log(durationWithSecond.toString()); // 6 days 12:30:59.002
withMillisecond
Return a new duration with milliseconds replaced.
withMillisecond(millisecond: number): Duration
- Parameters:
millisecond
:- description: The millisecond to replace the old one.
- Type:
number
- Returns:
Duration
- Throws:
void
Example:
const duration = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
const durationWithMillisecond = duration.withMillisecond(999);
console.log(durationWithMillisecond.toString()); // 6 days 12:30:45.999
plus
Return a new duration as the sum of the duration with another duration.
plus(other: Duration): Duration
- Parameters:
other
:- description: The other duration to calculate the sum of.
- Type:
Duration
- Returns:
Duration
- Throws:
void
Example:
const duration1 = Duration.fromObject({
day: 6,
});
const duration2 = Duration.fromObject({
day: 2,
});
const sum = duration1.plus(duration2);
console.log(sum.toString()); // 8 days 00:00:00
minus
Return a new duration as the difference of the duration with another duration.
minus(other: Duration): Duration
- Parameters:
other
:- description: The other duration to calculate the difference of.
- Type:
Duration
- Returns:
Duration
- Throws:
void
Example:
const duration1 = Duration.fromObject({
day: 6,
});
const duration2 = Duration.fromObject({
day: 2,
});
const diff = duration1.minus(duration2);
console.log(diff.toString()); // 4 days 00:00:00
multiplyBy
Return a new duration as the product of the duration with a factor.
multiplyBy(factor: number): Duration
- Parameters:
factor
:- description: The factor to calculate the product of.
- Type:
number
- Returns:
Duration
- Throws:
void
Example:
const duration = Duration.fromObject({
day: 6,
});
const product = duration.multiplyBy(2);
console.log(product.toString()); // 12 days 00:00:00
divideBy
Return a new duration as the quotient of the duration with a divisor.
divideBy(divisor: number): Duration
- Parameters:
divisor
:- description: The divisor to calculate the quotient of.
- Type:
number
- Returns:
Duration
- Throws:
void
Example:
const duration = Duration.fromObject({
day: 6,
});
const quotient = duration.divideBy(2);
console.log(quotient.toString()); // 3 days 00:00:00
negate
Return a new duration as the negated duration.
negate(): Duration
- Parameters:
void
- Returns:
Duration
- Throws:
void
Example:
const duration = Duration.fromObject({
day: 6,
});
const negated = duration.negate();
console.log(negated.toString()); // -6 days 00:00:00
absolute
Return a new duration as the absolute duration.
absolute(): Duration
- Parameters:
void
- Returns:
Duration
- Throws:
void
Example:
const duration = Duration.fromObject({
day: -6,
});
const abs = duration.absolute();
console.log(abs.toString()); // 6 days 00:00:00
Static Properties
None
Static Methods
fromDays
Return a new duration from the total days.
Duration.fromDays(inDays: number): Duration
- Parameters:
inDays
:- description: the total duration in days.
- Type:
number
- Returns:
Duration
- Throws:
void
Example:
const duration = Duration.fromDays(6.521354189814815);
console.log(duration.toString()); // 6 days 12:30:45.002
fromHours
Return a new duration from the total hours.
Duration.fromHours(inHours: number): Duration
- Parameters:
inHours
:- description: the total duration in hours.
- Type:
number
- Returns:
Duration
- Throws:
void
Example:
const duration = Duration.fromHours(156.51250055555556);
console.log(duration.toString()); // 6 days 12:30:45.002
fromMinutes
Return a new duration from the total minutes.
Duration.fromMinutes(inMinutes: number): Duration
- Parameters:
inMinutes
:- description: the total duration in minutes.
- Type:
number
- Returns:
Duration
- Throws:
void
Example:
const duration = Duration.fromMinutes(9390.750033333334);
console.log(duration.toString()); // 6 days 12:30:45.002
fromSeconds
Return a new duration from the total seconds.
Duration.fromSeconds(inSeconds: number): Duration
- Parameters:
inSeconds
:- description: the total duration in seconds.
- Type:
number
- Returns:
Duration
- Throws:
void
Example:
const duration = Duration.fromSeconds(563445.002);
console.log(duration.toString()); // 6 days 12:30:45.002
fromMilliseconds
Return a new duration from the total milliseconds.
Duration.fromMilliseconds(inMilliseconds: number): Duration
- Parameters:
inMilliseconds
:- description: the total duration in milliseconds.
- Type:
number
- Returns:
Duration
- Throws:
void
Example:
const duration = Duration.fromMilliseconds(563445002);
console.log(duration.toString()); // 6 days 12:30:45.002
fromObject
Return a new duration from an object literal.
Duration.fromObject(object: Object): Duration
- Parameters:
object
:- description: the object literal.
- Type:
Object
- Returns:
Duration
- Throws:
void
Example:
const duration = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
console.log(duration.toString()); // 6 days 12:30:45.002
fromString
Return a new duration from a human-readable string representation.
Duration.fromString(str: string): Duration
- Parameters:
str
:- description: the human-readable string representation.
- Type:
string
- Returns:
Duration
- Throws:
void
Example:
const duration = Duration.fromString("6 days 12:30:45.002");
console.log(duration.toObject()); // {day: 6, hour: 12, minute: 30, second: 45, millisecond: 2}
fromISOString
Return a new duration from an ISO 8601 representation.
Duration.fromISOString(str: string): Duration
- Parameters:
str
:- description: the ISO 8601 representation.
- Type:
string
- Returns:
Duration
- Throws:
void
Example:
const duration = Duration.fromISOString("P6DT12H30M45.002S");
console.log(duration.toObject()); // {day: 6, hour: 12, minute: 30, second: 45, millisecond: 2}
parse
Return a new duration from any possible string.
Duration.parse(str: string): Duration
- Parameters:
str
:- description: the string.
- Type:
string
- Returns:
Duration
- Throws:
void
Example:
const duration = Duration.parse("6 days 12:30:45.002");
console.log(duration.toObject()); // {day: 6, hour: 12, minute: 30, second: 45, millisecond: 2}
compare
Returns the difference between two durations.
TIP
This method is useful for sorting Duration
instances in an array.
Duration.compare(duration1: Duration, duration2: Duration): number
- Parameters:
duration1
:- description: The first duration.
- Type:
Duration
duration2
:- description: The second duration.
- Type:
Duration
- Returns:
number
- Throws:
void
Example:
const duration1 = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
const duration2 = Duration.fromObject({
day: 6,
hour: 12,
minute: 30,
second: 45,
millisecond: 2,
});
console.log(Duration.compare(duration1, duration2)); // 0