Luxon Manual Reference
import Duration from 'luxon/src/duration.js'
public class | source

Duration

A Duration object represents a period of time, like "2 months" or "1 day, 1 hour". Conceptually, it's 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:

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

Static Method Summary

Static Public Methods
public static

fromISO(text: string, opts: Object): Duration

Create a Duration from an ISO 8601 duration string.

public static

fromMillis(count: number, opts: Object): Duration

Create Duration from a number of milliseconds.

public static

Create a Duration from a Javascript object with keys like 'years' and 'hours. If this object is empty then zero milliseconds duration is returned.

public static

invalid(reason: string): Duration

Create an invalid Duration.

Member Summary

Public Members
public get

Get the days.

public get

Get the hours.

public get

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

public get

Returns whether the Duration is invalid.

public get

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

public get

Get the milliseconds.

public get

Get the minutes.

public get

Get the months.

public get

Get the numbering system of a Duration, such 'beng'.

public get

Get the quarters.

public get

Get the seconds.

public get

Get the weeks

public get

Get the years.

Method Summary

Public Methods
public

as(unit: string): number

Return the length of the duration in the specified unit.

public

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

public

get(unit: string): number

Get the value of unit.

public

Returns a string representation of this Duration appropriate for the REPL.

public

minus(duration: Duration | Object | number): Duration

Make this Duration shorter by the specified amount.

public

Return the negative of this Duration.

public

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

public

plus(duration: Duration | Object | number): Duration

Make this Duration longer by the specified amount.

public

reconfigure(objectPattern: {"locale": *, "numberingSystem": *, "conversionAccuracy": *}): Duration

"Set" the locale and/or numberingSystem.

public

set(values: Object): Duration

"Set" the values of specified units.

public

shiftTo(units: ...*): Duration

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

public

toFormat(fmt: string, opts: Object): string

Returns a string representation of this Duration formatted according to the specified format string.

public

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

public

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

public

toObject(opts: *): Object

Returns a Javascript object with this Duration's values.

public

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

public

Returns an milliseconds value of this Duration.

Static Public Methods

public static fromISO(text: string, opts: Object): Duration source

Create a Duration from an ISO 8601 duration string.

Params:

NameTypeAttributeDescription
text string

text to parse

opts Object

options for parsing

opts.locale string
  • optional
  • default: 'en-US'

the locale to use

opts.numberingSystem string

the numbering system to use

opts.conversionAccuracy string
  • optional
  • default: 'casual'

the conversion system to use

Return:

Duration

Example:

Duration.fromISO('P3Y6M4DT12H30M5S').toObject() //=> { years: 3, months: 6, day: 4, hours: 12, minutes: 30, seconds: 5 }
Duration.fromISO('PT23H').toObject() //=> { hours: 23 }
Duration.fromISO('P5Y3M').toObject() //=> { years: 5, months: 3 }

See:

public static fromMillis(count: number, opts: Object): Duration source

Create Duration from a number of milliseconds.

Params:

NameTypeAttributeDescription
count number

of milliseconds

opts Object

options for parsing

opts.locale string
  • optional
  • default: 'en-US'

the locale to use

opts.numberingSystem string

the numbering system to use

opts.conversionAccuracy string
  • optional
  • default: 'casual'

the conversion system to use

Return:

Duration

public static fromObject(obj: Object): Duration source

Create a Duration from a Javascript object with keys like 'years' and 'hours. If this object is empty then zero milliseconds duration is returned.

Params:

NameTypeAttributeDescription
obj Object

the object to create the DateTime from

obj.years number
obj.quarters number
obj.months number
obj.weeks number
obj.days number
obj.hours number
obj.minutes number
obj.seconds number
obj.milliseconds number
obj.locale string
  • optional
  • default: 'en-US'

the locale to use

obj.numberingSystem string

the numbering system to use

obj.conversionAccuracy string
  • optional
  • default: 'casual'

the conversion system to use

Return:

Duration

public static invalid(reason: string): Duration source

Create an invalid Duration.

Params:

NameTypeAttributeDescription
reason string

reason this is invalid

Return:

Duration

Public Members

public get days: number source

Get the days.

public get hours: number source

Get the hours.

public get invalidReason: string: * source

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

Return:

string

public get isValid: boolean: * source

Returns whether the Duration is invalid. Invalid durations are returned by diff operations on invalid DateTimes or Intervals.

Return:

boolean

public get locale: string source

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

public get milliseconds: number: * source

Get the milliseconds.

Return:

number

public get minutes: number source

Get the minutes.

public get months: number source

Get the months.

public get numberingSystem: string source

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

public get quarters: number source

Get the quarters.

public get seconds: number: * source

Get the seconds.

Return:

number

public get weeks: number source

Get the weeks

public get years: number source

Get the years.

Public Methods

public as(unit: string): number source

Return the length of the duration in the specified unit.

Params:

NameTypeAttributeDescription
unit string

a unit such as 'minutes' or 'days'

Return:

number

Example:

Duration.fromObject({years: 1}).as('days') //=> 365
Duration.fromObject({years: 1}).as('months') //=> 12
Duration.fromObject({hours: 60}).as('days') //=> 2.5

public equals(other: Duration): boolean source

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

Params:

NameTypeAttributeDescription
other Duration

Return:

boolean

public get(unit: string): number source

Get the value of unit.

Params:

NameTypeAttributeDescription
unit string

a unit such as 'minute' or 'day'

Return:

number

Example:

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

public inspect(): string source

Returns a string representation of this Duration appropriate for the REPL.

Return:

string

public minus(duration: Duration | Object | number): Duration source

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

Params:

NameTypeAttributeDescription
duration Duration | Object | number

The amount to subtract. Either a Luxon Duration, a number of milliseconds, the object argument to Duration.fromObject()

Return:

Duration

public negate(): Duration source

Return the negative of this Duration.

Return:

Duration

Example:

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

public normalize(): Duration source

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

Return:

Duration

Example:

Duration.fromObject({ years: 2, days: 5000 }).normalize().toObject() //=> { years: 15, days: 255 }
Duration.fromObject({ hours: 12, minutes: -45 }).normalize().toObject() //=> { hours: 11, minutes: 15 }

public plus(duration: Duration | Object | number): Duration source

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

Params:

NameTypeAttributeDescription
duration Duration | Object | number

The amount to add. Either a Luxon Duration, a number of milliseconds, the object argument to Duration.fromObject()

Return:

Duration

public reconfigure(objectPattern: {"locale": *, "numberingSystem": *, "conversionAccuracy": *}): Duration source

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

Params:

NameTypeAttributeDescription
objectPattern {"locale": *, "numberingSystem": *, "conversionAccuracy": *}
  • optional
  • default: {}

Return:

Duration

Example:

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

public set(values: Object): Duration source

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

Params:

NameTypeAttributeDescription
values Object

a mapping of units to numbers

Return:

Duration

Example:

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

public shiftTo(units: ...*): Duration source

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

Params:

NameTypeAttributeDescription
units ...*

Return:

Duration

Example:

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

public toFormat(fmt: string, opts: Object): string source

Returns a string representation of this Duration formatted according to the specified format string.

Params:

NameTypeAttributeDescription
fmt string

the format string

opts Object

options

opts.floor boolean
  • optional
  • default: true

floor numerical values

Return:

string

public toISO(): string source

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

Return:

string

Example:

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'

See:

public toJSON(): string source

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

Return:

string

public toObject(opts: *): Object source

Returns a Javascript object with this Duration's values.

Params:

NameTypeAttributeDescription
opts *

options for generating the object

opts.includeConfig boolean
  • optional
  • default: false

include configuration attributes in the output

Return:

Object

Example:

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

public toString(): string source

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

Return:

string

public valueOf(): number source

Returns an milliseconds value of this Duration.

Return:

number