Interface: Duration<IsValid>

A Duration object represents a period of time, like "2 months" or "1 day, 1 hour". Conceptually, it is just a map of units to their quantities, accompanied by some additional configuration and methods for creating, parsing, interrogating, transforming, and formatting them. They can be used on their own or in conjunction with other Luxon types; for example, you can use DateTime.plus to add a Duration object to a DateTime, producing another DateTime.

Here is a brief overview of commonly used methods and getters in Duration:

Creation To create a Duration, use Duration.fromMillis, Duration.fromObject, or Duration.fromISO.
Unit values See the Duration#years, Duration.months, Duration#weeks, Duration#days, Duration#hours, Duration#minutes,
Duration#seconds, Duration#milliseconds accessors.
Configuration See Duration#locale and Duration#numberingSystem accessors.
Transformation To create new Durations out of old ones use Duration#plus, Duration#minus, Duration#normalize, Duration#set, Duration#reconfigure,
Duration#shiftTo, and Duration#negate.
Output To convert the Duration into other representations, see Duration#as, Duration#toISO, Duration#toFormat, and Duration#toJSON

There's are more methods documented below. In addition, for more information on subtler topics like internationalization and validity, see the external documentation.

Type Parameters

Type Parameter	Default type
`IsValid` extends `boolean`	`DefaultValidity`

Accessors

days

Get Signature

get days(): IfValid<number, number, IsValid>;

Get the days.

Returns

IfValid<number, number, IsValid>

hours

Get Signature

get hours(): IfValid<number, number, IsValid>;

Get the hours.

Returns

IfValid<number, number, IsValid>

invalidExplanation

Get Signature

get invalidExplanation(): IfValid<null, string | null, IsValid>;

Returns an explanation of why this Duration became invalid, or null if the Duration is valid

Returns

IfValid<null, string | null, IsValid>

invalidReason

Get Signature

get invalidReason(): IfValid<null, string, IsValid>;

Returns an error code if this Duration became invalid, or null if the Duration is valid

Returns

IfValid<null, string, IsValid>

isValid

Get Signature

get isValid(): IfValid<true, false, IsValid>;

Returns whether the Duration is invalid. Diff operations on invalid DateTimes or Intervals return invalid Durations.

Returns

IfValid<true, false, IsValid>

locale

Get Signature

get locale(): IfValid<string, null, IsValid>;

Get the locale of a Duration, such as 'en-GB'

Returns

IfValid<string, null, IsValid>

milliseconds

Get Signature

get milliseconds(): IfValid<number, number, IsValid>;

Get the milliseconds.

Returns

IfValid<number, number, IsValid>

minutes

Get Signature

get minutes(): IfValid<number, number, IsValid>;

Get the minutes.

Returns

IfValid<number, number, IsValid>

months

Get Signature

get months(): IfValid<number, number, IsValid>;

Get the months.

Returns

IfValid<number, number, IsValid>

numberingSystem

Get Signature

get numberingSystem(): IfValid<string, null, IsValid>;

Get the numbering system of a Duration, such as 'beng'. The numbering system is used when formatting the Duration

Returns

IfValid<string, null, IsValid>

quarters

Get Signature

get quarters(): IfValid<number, number, IsValid>;

Get the quarters.

Returns

IfValid<number, number, IsValid>

seconds

Get Signature

get seconds(): IfValid<number, number, IsValid>;

Get the seconds.

Returns

IfValid<number, number, IsValid>

weeks

Get Signature

get weeks(): IfValid<number, number, IsValid>;

Get the weeks

Returns

IfValid<number, number, IsValid>

years

Get Signature

get years(): IfValid<number, number, IsValid>;

Get the years.

Returns

IfValid<number, number, IsValid>

Methods

as()

as(unit: keyof DurationLikeObject): IfValid<number, number, IsValid>;

Return the length of the duration in the specified unit.

Parameters

Parameter	Type	Description
`unit`	keyof `DurationLikeObject`	a unit such as 'minutes' or 'days'

Returns

IfValid<number, number, IsValid>

Examples

Duration.fromObject({ years: 1 }).as("days"); //=> 365

Duration.fromObject({ years: 1 }).as("months"); //=> 12

Duration.fromObject({ hours: 60 }).as("days"); //=> 2.5

equals()

equals(other: Duration): IfValid<boolean, false, IsValid>;

Equality check Two Durations are equal iff they have the same units and the same values for each unit.

Parameters

Parameter	Type
`other`	`Duration`

Returns

IfValid<boolean, false, IsValid>

get()

get(unit: keyof DurationLikeObject): IfValid<number, number, IsValid>;

Get the value of unit.

Parameters

Parameter	Type	Description
`unit`	keyof `DurationLikeObject`	a unit such as 'minute' or 'day'

Returns

IfValid<number, number, IsValid>

Examples

Duration.fromObject({ years: 2, days: 3 }).get("years"); //=> 2

Duration.fromObject({ years: 2, days: 3 }).get("months"); //=> 0

Duration.fromObject({ years: 2, days: 3 }).get("days"); //=> 3

mapUnits()

mapUnits(fn: (x: number, u?: keyof DurationLikeObject) => number): this;

Scale this Duration by the specified amount. Return a newly-constructed Duration.

Parameters

Parameter	Type
`fn`	(`x`: `number`, `u?`: keyof DurationLikeObject) => `number`

Returns

this

Examples

Duration.fromObject({ hours: 1, minutes: 30 }).mapUnit((x) => x * 2); //=> { hours: 2, minutes: 60 }

Duration.fromObject({ hours: 1, minutes: 30 }).mapUnit((x, u) =>
  u === "hour" ? x * 2 : x,
); //=> { hours: 2, minutes: 30 }

minus()

minus(duration: DurationLike): this;

Make this Duration shorter by the specified amount. Return a newly-constructed Duration.

Parameters

Parameter	Type	Description
`duration`	`DurationLike`	The amount to subtract. Either a Luxon Duration, a number of milliseconds, the object argument to Duration.fromObject()

Returns

this

negate()

negate(): this;

Return the negative of this Duration.

Returns

this

Example

Duration.fromObject({ hours: 1, seconds: 30 }).negate().toObject(); //=> { hours: -1, seconds: -30 }

normalize()

normalize(): this;

Reduce this Duration to its canonical representation in its current units.

Returns

this

Examples

Duration.fromObject({ years: 2, days: 5000 }).normalize().toObject(); //=> { years: 15, days: 255 }

Duration.fromObject({ hours: 12, minutes: -45 }).normalize().toObject(); //=> { hours: 11, minutes: 15 }

plus()

plus(duration: DurationLike): this;

Make this Duration longer by the specified amount. Return a newly-constructed Duration.

Parameters

Parameter	Type	Description
`duration`	`DurationLike`	The amount to add. Either a Luxon Duration, a number of milliseconds, the object argument to Duration.fromObject()

Returns

this

reconfigure()

reconfigure(opts?: DurationOptions): this;

"Set" the locale and/or numberingSystem. Returns a newly-constructed Duration.

Parameters

Parameter	Type
`opts?`	`DurationOptions`

Returns

this

Example

dur.reconfigure({ locale: "en-GB" });

removeZeros()

removeZeros(): this;

Removes all units with values equal to 0 from this Duration.

Returns

this

Example

Duration.fromObject({ years: 2, days: 0, hours: 0, minutes: 0 })
  .removeZeros()
  .toObject(); //=> { years: 2 }

rescale()

rescale(): this;

Rescale units to its largest representation.

Returns

this

Example

Duration.fromObject({ milliseconds: 90000 }).rescale().toObject(); //=> { minutes: 1, seconds: 30 }

set()

set(values: DurationLikeObject): this;

"Set" the values of specified units. Return a newly-constructed Duration.

Parameters

Parameter	Type	Description
`values`	`DurationLikeObject`	a mapping of units to numbers

Returns

this

Examples

dur.set({ years: 2017 });

dur.set({ hours: 8, minutes: 30 });

shiftTo()

shiftTo(...units: keyof DurationLikeObject[]): this;

Convert this Duration into its representation in a different set of units.

Parameters

Parameter	Type
...`units`	keyof `DurationLikeObject`[]

Returns

this

Example

Duration.fromObject({ hours: 1, seconds: 30 })
  .shiftTo("minutes", "milliseconds")
  .toObject(); //=> { minutes: 60, milliseconds: 30000 }

shiftToAll()

shiftToAll(): this;

Shift this Duration to all available units. Same as shiftTo("years", "months", "weeks", "days", "hours", "minutes", "seconds", "milliseconds")

Returns

this

toFormat()

toFormat(fmt: string, opts?: DurationFormatOptions): IfValid<string, "Invalid Duration", IsValid>;

Returns a string representation of this Duration formatted according to the specified format string. You may use these tokens:

S for milliseconds
s for seconds
m for minutes
h for hours
d for days
M for months
y for years Notes:
Add padding by repeating the token, e.g. "yy" pads the years to two digits, "hhhh" pads the hours out to four digits
The duration will be converted to the set of units in the format string using Duration.shiftTo and the Duration's conversion accuracy setting.

Parameters

Parameter	Type
`fmt`	`string`
`opts?`	`DurationFormatOptions`

Returns

IfValid<string, "Invalid Duration", IsValid>

Examples

Duration.fromObject({ years: 1, days: 6, seconds: 2 }).toFormat("y d s"); //=> "1 6 2"

Duration.fromObject({ years: 1, days: 6, seconds: 2 }).toFormat("yy dd sss"); //=> "01 06 002"

Duration.fromObject({ years: 1, days: 6, seconds: 2 }).toFormat("M S"); //=> "12 518402000"

Duration.fromObject({ days: 6, seconds: 2 }).toFormat("d s", {
  signMode: "all",
}); //=> "+6 +2"

Duration.fromObject({ days: -6, seconds: -2 }).toFormat("d s", {
  signMode: "all",
}); //=> "-6 -2"

Duration.fromObject({ days: -6, seconds: -2 }).toFormat("d s", {
  signMode: "negativeLargestOnly",
}); //=> "-6 2"

toHuman()

toHuman(opts?: ToHumanDurationOptions): string;

Returns a string representation of a Duration with all units included To modify its behavior use the listStyle and any Intl.NumberFormat option, though unitDisplay is especially relevant. See Intl.NumberFormat.

Parameters

Parameter	Type
`opts?`	`ToHumanDurationOptions`

Returns

string

Example

var dur = Duration.fromObject({ months: 1, weeks: 0, hours: 5, minutes: 6 });
dur.toHuman(); //=> '1 month, 0 weeks, 5 hours, 6 minutes'
dur.toHuman({ listStyle: "long" }); //=> '1 month, 0 weeks, 5 hours, and 6 minutes'
dur.toHuman({ unitDisplay: "short" }); //=> '1 mth, 0 wks, 5 hr, 6 min'
dur.toHuman({ showZeros: false }); //=> '1 month, 5 hours, 6 minutes'

toISO()

toISO(): IfValid<string, null, IsValid>;

Returns an ISO 8601-compliant string representation of this Duration.

Returns

IfValid<string, null, IsValid>

See

https://en.wikipedia.org/wiki/ISO_8601#Durations

Examples

Duration.fromObject({ years: 3, seconds: 45 }).toISO(); //=> 'P3YT45S'

Duration.fromObject({ months: 4, seconds: 45 }).toISO(); //=> 'P4MT45S'

Duration.fromObject({ months: 5 }).toISO(); //=> 'P5M'

Duration.fromObject({ minutes: 5 }).toISO(); //=> 'PT5M'

Duration.fromObject({ milliseconds: 6 }).toISO(); //=> 'PT0.006S'

toISOTime()

toISOTime(opts?: ToISOTimeDurationOptions): IfValid<string, null, IsValid>;

Returns an ISO 8601-compliant string representation of this Duration, formatted as a time of day.

Parameters

Parameter	Type	Description
`opts?`	`ToISOTimeDurationOptions`	options

Returns

IfValid<string, null, IsValid>

See

https://en.wikipedia.org/wiki/ISO_8601#Times

Examples

Duration.fromObject({ hours: 11 }).toISOTime(); //=> '11:00:00.000'

Duration.fromObject({ hours: 11 }).toISOTime({ suppressMilliseconds: true }); //=> '11:00:00'

Duration.fromObject({ hours: 11 }).toISOTime({ suppressSeconds: true }); //=> '11:00'

Duration.fromObject({ hours: 11 }).toISOTime({ includePrefix: true }); //=> 'T11:00:00.000'

Duration.fromObject({ hours: 11 }).toISOTime({ format: "basic" }); //=> '110000.000'

toJSON()

toJSON(): IfValid<string, null, IsValid>;

Returns an ISO 8601 representation of this Duration appropriate for use in JSON.

Returns

IfValid<string, null, IsValid>

toMillis()

toMillis(): IfValid<number, number, IsValid>;

Returns a millisecond value of this Duration.

Returns

IfValid<number, number, IsValid>

toObject()

toObject(): DurationObjectUnits;

Returns a JavaScript object with this Duration's values.

Returns

DurationObjectUnits

Example

Duration.fromObject({ years: 1, days: 6, seconds: 2 }).toObject(); //=> { years: 1, days: 6, seconds: 2 }

toString()

toString(): IfValid<string, null, IsValid>;

Returns an ISO 8601 representation of this Duration appropriate for use in debugging.

Returns

IfValid<string, null, IsValid>

valueOf()

valueOf(): IfValid<number, number, IsValid>;

Returns a millisecond value of this Duration. Alias of toMillis

Returns

IfValid<number, number, IsValid>

Interface: Duration<IsValid> ​

Type Parameters ​

Accessors ​

days ​

Get Signature ​

Returns ​

hours ​

Get Signature ​

Returns ​

invalidExplanation ​

Get Signature ​

Returns ​

invalidReason ​

Get Signature ​

Returns ​

isValid ​

Get Signature ​

Returns ​

locale ​

Get Signature ​

Returns ​

milliseconds ​

Get Signature ​

Returns ​

minutes ​

Get Signature ​

Returns ​

months ​

Get Signature ​

Returns ​

numberingSystem ​

Get Signature ​

Returns ​

quarters ​

Get Signature ​

Returns ​

seconds ​

Get Signature ​

Returns ​

weeks ​

Get Signature ​

Returns ​

years ​

Get Signature ​

Returns ​

Methods ​

as() ​

Parameters ​

Returns ​

Examples ​

equals() ​

Parameters ​

Returns ​

get() ​

Parameters ​

Returns ​

Examples ​

mapUnits() ​

Parameters ​

Returns ​

Examples ​

minus() ​

Parameters ​

Returns ​

negate() ​

Returns ​

Example ​

normalize() ​

Returns ​

Examples ​

plus() ​

Parameters ​

Returns ​

reconfigure() ​

Parameters ​

Returns ​

Example ​

removeZeros() ​

Returns ​

Example ​

Interface: Duration<IsValid>

Type Parameters

Accessors

days

Get Signature

Returns

hours

Get Signature

Returns

invalidExplanation

Get Signature

Returns

invalidReason

Get Signature

Returns

isValid

Get Signature

Returns

locale

Get Signature

Returns

milliseconds

Get Signature

Returns

minutes

Get Signature

Returns

months

Get Signature

Returns

numberingSystem

Get Signature

Returns

quarters

Get Signature

Returns

seconds

Get Signature

Returns

weeks

Get Signature

Returns

years

Get Signature

Returns

Methods

as()

Parameters

Returns

Examples

equals()

Parameters

Returns

get()

Parameters

Returns

Examples

mapUnits()

Parameters

Returns

Examples

minus()

Parameters

Returns

negate()

Returns

Example

normalize()

Returns

Examples

plus()

Parameters

Returns

reconfigure()

Parameters

Returns

Example

removeZeros()

Returns

Example