Luxon Manual Reference
import {DateTime} from 'luxon/src/datetime.js'
public class | source

DateTime

A DateTime is an immutable data structure representing a specific date and time and accompanying methods. It contains class and instance methods for creating, parsing, interrogating, transforming, and formatting them.

A DateTime comprises of:

  • A timestamp. Each DateTime instance refers to a specific millisecond of the Unix epoch.
  • A time zone. Each instance is considered in the context of a specific zone (by default the local system's zone).
  • Configuration properties that effect how output strings are formatted, such as locale, numberingSystem, and outputCalendar.

Here is a brief overview of the most commonly used functionality it provides:

There's plenty others documented below. In addition, for more information on subtler topics like internationalization, time zones, alternative calendars, validity, and so on, see the external documentation.

Static Member Summary

Static Public Members
public static get

toLocaleString format like 'October 14, 1983, 9:30 AM EDT'.

public static get

toLocaleString format like 'October 14, 1983, 9:303 AM EDT'.

public static get

toLocaleString format like 'Friday, October 14, 1983, 9:30 AM Eastern Daylight Time'.

public static get

toLocaleString format like 'Friday, October 14, 1983, 9:30:33 AM Eastern Daylight Time'.

public static get

toLocaleString format like 'Oct 14, 1983, 9:30 AM'.

public static get

toLocaleString format like 'Oct 14, 1983, 9:30:33 AM'.

public static get

toLocaleString format like '10/14/1983, 9:30 AM'.

public static get

toLocaleString format like '10/14/1983, 9:30:33 AM'.

public static get

toLocaleString format like 'October 14, 1983'

public static get

toLocaleString format like 'Tuesday, October 14, 1983'

public static get

toLocaleString format like 'Oct 14, 1983'

public static get

toLocaleString format like 10/14/1983

public static get

toLocaleString format like '09:30', always 24-hour.

public static get

toLocaleString format like '09:30:23 Eastern Daylight Time', always 24-hour.

public static get

toLocaleString format like '09:30:23', always 24-hour.

public static get

toLocaleString format like '09:30:23 EDT', always 24-hour.

public static get

toLocaleString format like '09:30 AM'.

public static get

toLocaleString format like '09:30:23 AM Eastern Daylight Time'.

public static get

toLocaleString format like '09:30:23 AM'.

public static get

toLocaleString format like '09:30:23 AM EDT'.

Static Method Summary

Static Public Methods
public static

fromHTTP(text: string, options: object): DateTime

Create a DateTime from an HTTP header date

public static

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

Create a DateTime from an ISO 8601 string

public static

fromJSDate(date: Date, options: Object): DateTime

Create an DateTime from a Javascript Date object.

public static

fromMillis(milliseconds: number, options: Object): DateTime

Create an DateTime from a count of epoch milliseconds.

public static

Create an DateTime from a Javascript object with keys like 'year' and 'hour' with reasonable defaults.

public static

Create a DateTime from an RFC 2822 string

public static

fromSQL(text: string, options: Object): DateTime

Create a DateTime from a SQL date, time, or datetime Defaults to en-US if no locale has been specified, regardless of the system's locale

public static

fromString(text: string, fmt: string, options: Object): DateTime

Create a DateTime from an input string and format string Defaults to en-US if no locale has been specified, regardless of the system's locale

public static

fromStringExplain(text: string, fmt: string, options: object): object

Explain how a string would be parsed by fromString()

public static

invalid(reason: *): DateTime

Create an invalid DateTime.

public static

local(year: number, month: number, day: number, hour: number, minute: number, second: number, millisecond: number): DateTime

Create a local DateTime

public static

max(dateTimes: ...DateTime): DateTime

Return the max of several date times

public static

min(dateTimes: ...DateTime): DateTime

Return the min of several date times

public static

utc(year: number, month: number, day: number, hour: number, minute: number, second: number, millisecond: number): DateTime

Create a DateTime in UTC

Constructor Summary

Private Constructor
private

Member Summary

Public Members
public get

day: number: *

Get the day of the month (1-30ish).

public get

Returns the number of days in this DateTime's month

public get

Returns the number of days in this DateTime's year

public get

hour: number: *

Get the hour of the day (0-23).

public get

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

public get

Get whether the DateTime is in a DST.

public get

Returns true if this DateTime is in a leap year, false otherwise

public get

Get whether this zone's offset ever changes, as in a DST.

public get

Returns whether the DateTime is valid.

public get

Get the locale of a DateTime, such 'en-GB'.

public get

Get the millisecond of the second (0-999).

public get

Get the minute of the hour (0-59).

public get

Get the month (1-12).

public get

Get the human readable long month name, such as 'October'.

public get

Get the human readable short month name, such as 'Oct'.

public get

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

public get

Get the UTC offset of this DateTime in minutes

public get

Get the long human name for the zone's current offset, for example "Eastern Standard Time" or "Eastern Daylight Time". Defaults to the system's locale if no locale has been specified

public get

Get the short human name for the zone's current offset, for example "EST" or "EDT". Defaults to the system's locale if no locale has been specified

public get

Get the ordinal (i.e.

public get

Get the output calendar of a DateTime, such 'islamic'.

public get

Get the second of the minute (0-59).

public get

Get the week number of the week year (1-52ish).

public get

Get the week year

public get

Get the day of the week.

public get

Get the human readable long weekday, such as 'Monday'.

public get

Get the human readable short weekday, such as 'Mon'.

public get

year: number: *

Get the year

public get

Get the name of the time zone.

Private Members
private

c: *

private

invalid: *

private

loc: *

private

o: *

private

ts: *

private
private

zone: *

Method Summary

Public Methods
public

diff(otherDateTime: DateTime, unit: string | string[], opts: Object): Duration

Return the difference between two DateTimes as a Duration.

public

diffNow(unit: string | string[], opts: Object): Duration

Return the difference between this DateTime and right now.

public

"Set" this DateTime to the end (i.e.

public

Equality check Two DateTimes are equal iff they represent the same millisecond

public

get(unit: string): number

Get the value of unit.

public

hasSame(otherDateTime: DateTime, unit: string): boolean

Return whether this DateTime is in the same unit of time as another DateTime

public

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

public

minus(duration: Duration | number | object): DateTime

Subtract a period of time to this DateTime and return the resulting DateTime See plus

public

plus(duration: Duration | number | object): DateTime

Add a period of time to this DateTime and return the resulting DateTime

public

reconfigure(properties: object): DateTime

"Set" the locale, numberingSystem, or outputCalendar.

public

Returns the resolved Intl options for this DateTime.

public

set(values: object): DateTime

"Set" the values of specified units.

public

setLocale(locale: *): DateTime

"Set" the locale.

public

setZone(zone: string | Zone, opts: object): DateTime

"Set" the DateTime's zone to specified zone. Returns a newly-constructed DateTime.

By default, the setter keeps the underlying time the same (as in, the same UTC timestamp), but the new instance will report different local times and consider DSTs when making computations, as with plus. You may wish to use toLocal and toUTC which provide simple convenience wrappers for commonly used zones.

public

"Set" this DateTime to the beginning of a unit of time.

public

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

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

public

Returns a string representation of this DateTime appropriate for use in HTTP headers.

public

toISO(opts: object): string

Returns an ISO 8601-compliant string representation of this DateTime

public

Returns an ISO 8601-compliant string representation of this DateTime's date component

public

Returns an ISO 8601-compliant string representation of this DateTime's time component

public

Returns an ISO 8601-compliant string representation of this DateTime's week date

public

Returns a Javascript Date equivalent to this DateTime.

public

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

public

"Set" the DateTime's zone to the host's local zone.

public

toLocaleParts(opts: *): *

Returns an array of format "parts", i.e.

public

Returns a localized string representing this date.

public

toObject(opts: *): object

Returns a Javascript object with this DateTime's year, month, day, and so on.

public

Returns an RFC 2822-compatible string representation of this DateTime, always in UTC

public

toSQL(opts: object): string

Returns a string representation of this DateTime appropriate for use in SQL DateTime

public

Returns a string representation of this DateTime appropriate for use in SQL Date

public

Returns a string representation of this DateTime appropriate for use in SQL Time

public

Returns a string representation of this DateTime appropriate for debugging

public

toUTC(offset: number, opts: object): DateTime

"Set" the DateTime's zone to UTC. Returns a newly-constructed DateTime.

Equivalent to setZone('utc')

public

until(otherDateTime: DateTime): Duration

Return an Interval spanning between this DateTime and another DateTime

public

Returns the epoch milliseconds of this DateTime

Static Public Members

public static get DATETIME_FULL: * source

toLocaleString format like 'October 14, 1983, 9:30 AM EDT'. Only 12-hour if the locale is.

public static get DATETIME_FULL_WITH_SECONDS: * source

toLocaleString format like 'October 14, 1983, 9:303 AM EDT'. Only 12-hour if the locale is.

public static get DATETIME_HUGE: * source

toLocaleString format like 'Friday, October 14, 1983, 9:30 AM Eastern Daylight Time'. Only 12-hour if the locale is.

public static get DATETIME_HUGE_WITH_SECONDS: * source

toLocaleString format like 'Friday, October 14, 1983, 9:30:33 AM Eastern Daylight Time'. Only 12-hour if the locale is.

public static get DATETIME_MED: * source

toLocaleString format like 'Oct 14, 1983, 9:30 AM'. Only 12-hour if the locale is.

public static get DATETIME_MED_WITH_SECONDS: * source

toLocaleString format like 'Oct 14, 1983, 9:30:33 AM'. Only 12-hour if the locale is.

public static get DATETIME_SHORT: * source

toLocaleString format like '10/14/1983, 9:30 AM'. Only 12-hour if the locale is.

public static get DATETIME_SHORT_WITH_SECONDS: * source

toLocaleString format like '10/14/1983, 9:30:33 AM'. Only 12-hour if the locale is.

public static get DATE_FULL: * source

toLocaleString format like 'October 14, 1983'

public static get DATE_HUGE: * source

toLocaleString format like 'Tuesday, October 14, 1983'

public static get DATE_MED: * source

toLocaleString format like 'Oct 14, 1983'

public static get DATE_SHORT: * source

toLocaleString format like 10/14/1983

public static get TIME_24_SIMPLE: * source

toLocaleString format like '09:30', always 24-hour.

public static get TIME_24_WITH_LONG_OFFSET: * source

toLocaleString format like '09:30:23 Eastern Daylight Time', always 24-hour.

public static get TIME_24_WITH_SECONDS: * source

toLocaleString format like '09:30:23', always 24-hour.

public static get TIME_24_WITH_SHORT_OFFSET: * source

toLocaleString format like '09:30:23 EDT', always 24-hour.

public static get TIME_SIMPLE: * source

toLocaleString format like '09:30 AM'. Only 12-hour if the locale is.

public static get TIME_WITH_LONG_OFFSET: * source

toLocaleString format like '09:30:23 AM Eastern Daylight Time'. Only 12-hour if the locale is.

public static get TIME_WITH_SECONDS: * source

toLocaleString format like '09:30:23 AM'. Only 12-hour if the locale is.

public static get TIME_WITH_SHORT_OFFSET: * source

toLocaleString format like '09:30:23 AM EDT'. Only 12-hour if the locale is.

Static Public Methods

public static fromHTTP(text: string, options: object): DateTime source

Create a DateTime from an HTTP header date

Params:

NameTypeAttributeDescription
text string

the HTTP header date

options object

options to affect the creation

options.zone boolean
  • optional
  • default: 'local'

convert the time to this zone. Since HTTP dates are always in UTC, this has no effect on the interpretation of string, merely the zone the resulting DateTime is expressed in.

options.setZone boolean
  • optional
  • default: false

override the zone with the fixed-offset zone specified in the string. For HTTP dates, this is always UTC, so this option is equivalent to setting the zone option to 'utc', but this option is included for consistency with similar methods.

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

a locale to set on the resulting DateTime instance

options.outputCalendar string

the output calendar to set on the resulting DateTime instance

options.numberingSystem string

the numbering system to set on the resulting DateTime instance

Return:

DateTime

Example:

DateTime.fromHTTP('Sun, 06 Nov 1994 08:49:37 GMT')
DateTime.fromHTTP('Sunday, 06-Nov-94 08:49:37 GMT')
DateTime.fromHTTP('Sun Nov  6 08:49:37 1994')

See:

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

Create a DateTime from an ISO 8601 string

Params:

NameTypeAttributeDescription
text string

the ISO string

opts Object

options to affect the creation

opts.zone boolean
  • optional
  • default: 'local'

use this zone if no offset is specified in the input string itself. Will also convert the time to this zone

opts.setZone boolean
  • optional
  • default: false

override the zone with a fixed-offset zone specified in the string itself, if it specifies one

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

a locale to set on the resulting DateTime instance

opts.outputCalendar string

the output calendar to set on the resulting DateTime instance

opts.numberingSystem string

the numbering system to set on the resulting DateTime instance

Return:

DateTime

Example:

DateTime.fromISO('2016-05-25T09:08:34.123')
DateTime.fromISO('2016-05-25T09:08:34.123+06:00')
DateTime.fromISO('2016-05-25T09:08:34.123+06:00', {setZone: true})
DateTime.fromISO('2016-05-25T09:08:34.123', {zone: 'utc')
DateTime.fromISO('2016-W05-4')

public static fromJSDate(date: Date, options: Object): DateTime source

Create an DateTime from a Javascript Date object. Uses the default zone.

Params:

NameTypeAttributeDescription
date Date

a Javascript Date object

options Object

configuration options for the DateTime

options.zone string | Zone
  • optional
  • default: 'local'

the zone to place the DateTime into

Return:

DateTime

public static fromMillis(milliseconds: number, options: Object): DateTime source

Create an DateTime from a count of epoch milliseconds. Uses the default zone.

Params:

NameTypeAttributeDescription
milliseconds number

a number of milliseconds since 1970 UTC

options Object

configuration options for the DateTime

options.zone string | Zone
  • optional
  • default: 'local'

the zone to place the DateTime into

options.locale string
  • optional

a locale to set on the resulting DateTime instance

options.outputCalendar string

the output calendar to set on the resulting DateTime instance

options.numberingSystem string

the numbering system to set on the resulting DateTime instance

Return:

DateTime

public static fromObject(obj: Object): DateTime source

Create an DateTime from a Javascript object with keys like 'year' and 'hour' with reasonable defaults.

Params:

NameTypeAttributeDescription
obj Object

the object to create the DateTime from

obj.year number

a year, such as 1987

obj.month number

a month, 1-12

obj.day number

a day of the month, 1-31, depending on the month

obj.ordinal number

day of the year, 1-365 or 366

obj.weekYear number

an ISO week year

obj.weekNumber number

an ISO week number, between 1 and 52 or 53, depending on the year

obj.weekday number

an ISO weekday, 1-7, where 1 is Monday and 7 is Sunday

obj.hour number

hour of the day, 0-23

obj.minute number

minute of the hour, 0-59

obj.second number

second of the minute, 0-59

obj.millisecond number

millisecond of the second, 0-999

obj.zone string | Zone
  • optional
  • default: 'local'

interpret the numbers in the context of a particular zone. Can take any value taken as the first argument to setZone()

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

a locale to set on the resulting DateTime instance

obj.outputCalendar string

the output calendar to set on the resulting DateTime instance

obj.numberingSystem string

the numbering system to set on the resulting DateTime instance

Return:

DateTime

Example:

DateTime.fromObject({ year: 1982, month: 5, day: 25}).toISODate() //=> '1982-05-25'
DateTime.fromObject({ year: 1982 }).toISODate() //=> '1982-01-01T00'
DateTime.fromObject({ hour: 10, minute: 26, second: 6 }) //~> today at 10:26:06
DateTime.fromObject({ hour: 10, minute: 26, second: 6, zone: 'utc' }),
DateTime.fromObject({ hour: 10, minute: 26, second: 6, zone: 'local' })
DateTime.fromObject({ hour: 10, minute: 26, second: 6, zone: 'America/New_York' })
DateTime.fromObject({ weekYear: 2016, weekNumber: 2, weekday: 3 }).toISODate() //=> '2016-01-13'

public static fromRFC2822(text: string, opts: Object): DateTime source

Create a DateTime from an RFC 2822 string

Params:

NameTypeAttributeDescription
text string

the RFC 2822 string

opts Object

options to affect the creation

opts.zone boolean
  • optional
  • default: 'local'

convert the time to this zone. Since the offset is always specified in the string itself, this has no effect on the interpretation of string, merely the zone the resulting DateTime is expressed in.

opts.setZone boolean
  • optional
  • default: false

override the zone with a fixed-offset zone specified in the string itself, if it specifies one

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

a locale to set on the resulting DateTime instance

opts.outputCalendar string

the output calendar to set on the resulting DateTime instance

opts.numberingSystem string

the numbering system to set on the resulting DateTime instance

Return:

DateTime

Example:

DateTime.fromRFC2822('25 Nov 2016 13:23:12 GMT')
DateTime.fromRFC2822('Tue, 25 Nov 2016 13:23:12 +0600')
DateTime.fromRFC2822('25 Nov 2016 13:23 Z')

public static fromSQL(text: string, options: Object): DateTime source

Create a DateTime from a SQL date, time, or datetime Defaults to en-US if no locale has been specified, regardless of the system's locale

Params:

NameTypeAttributeDescription
text string

the string to parse

options Object

options to affect the creation

options.zone boolean
  • optional
  • default: 'local'

use this zone if no offset is specified in the input string itself. Will also convert the DateTime to this zone

options.setZone boolean
  • optional
  • default: false

override the zone with a zone specified in the string itself, if it specifies one

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

a locale string to use when parsing. Will also set the DateTime to this locale

options.numberingSystem string

the numbering system to use when parsing. Will also set the resulting DateTime to this numbering system

options.outputCalendar string

the output calendar to set on the resulting DateTime instance

Return:

DateTime

Example:

DateTime.fromSQL('2017-05-15')
DateTime.fromSQL('2017-05-15 09:12:34')
DateTime.fromSQL('2017-05-15 09:12:34.342')
DateTime.fromSQL('2017-05-15 09:12:34.342+06:00')
DateTime.fromSQL('2017-05-15 09:12:34.342 America/Los_Angeles')
DateTime.fromSQL('2017-05-15 09:12:34.342 America/Los_Angeles', { setZone: true })
DateTime.fromSQL('2017-05-15 09:12:34.342', { zone: 'America/Los_Angeles' })
DateTime.fromSQL('09:12:34.342')

public static fromString(text: string, fmt: string, options: Object): DateTime source

Create a DateTime from an input string and format string Defaults to en-US if no locale has been specified, regardless of the system's locale

Params:

NameTypeAttributeDescription
text string

the string to parse

fmt string

the format the string is expected to be in (see description)

options Object

options to affect the creation

options.zone boolean
  • optional
  • default: 'local'

use this zone if no offset is specified in the input string itself. Will also convert the DateTime to this zone

options.setZone boolean
  • optional
  • default: false

override the zone with a zone specified in the string itself, if it specifies one

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

a locale string to use when parsing. Will also set the DateTime to this locale

options.numberingSystem string

the numbering system to use when parsing. Will also set the resulting DateTime to this numbering system

options.outputCalendar string

the output calendar to set on the resulting DateTime instance

Return:

DateTime

public static fromStringExplain(text: string, fmt: string, options: object): object source

Explain how a string would be parsed by fromString()

Params:

NameTypeAttributeDescription
text string

the string to parse

fmt string

the format the string is expected to be in (see description)

options object

options taken by fromString()

Return:

object

public static invalid(reason: *): DateTime source

Create an invalid DateTime.

Params:

NameTypeAttributeDescription
reason *

Return:

DateTime

public static local(year: number, month: number, day: number, hour: number, minute: number, second: number, millisecond: number): DateTime source

Create a local DateTime

Params:

NameTypeAttributeDescription
year number

The calendar year. If omitted (as in, call local() with no arguments), the current time will be used

month number
  • optional
  • default: 1

The month, 1-indexed

day number
  • optional
  • default: 1

The day of the month

hour number
  • optional
  • default: 0

The hour of the day, in 24-hour time

minute number
  • optional
  • default: 0

The minute of the hour, i.e. a number between 0 and 59

second number
  • optional
  • default: 0

The second of the minute, i.e. a number between 0 and 59

millisecond number
  • optional
  • default: 0

The millisecond of the second, i.e. a number between 0 and 999

Return:

DateTime

Example:

DateTime.local()                            //~> now
DateTime.local(2017)                        //~> 2017-01-01T00:00:00
DateTime.local(2017, 3)                     //~> 2017-03-01T00:00:00
DateTime.local(2017, 3, 12)                 //~> 2017-03-12T00:00:00
DateTime.local(2017, 3, 12, 5)              //~> 2017-03-12T05:00:00
DateTime.local(2017, 3, 12, 5, 45)          //~> 2017-03-12T05:45:00
DateTime.local(2017, 3, 12, 5, 45, 10)      //~> 2017-03-12T05:45:10
DateTime.local(2017, 3, 12, 5, 45, 10, 765) //~> 2017-03-12T05:45:10.675

public static max(dateTimes: ...DateTime): DateTime source

Return the max of several date times

Params:

NameTypeAttributeDescription
dateTimes ...DateTime

the DateTimes from which to choose the maximum

Return:

DateTime

public static min(dateTimes: ...DateTime): DateTime source

Return the min of several date times

Params:

NameTypeAttributeDescription
dateTimes ...DateTime

the DateTimes from which to choose the minimum

Return:

DateTime

public static utc(year: number, month: number, day: number, hour: number, minute: number, second: number, millisecond: number): DateTime source

Create a DateTime in UTC

Params:

NameTypeAttributeDescription
year number

The calendar year. If omitted (as in, call utc() with no arguments), the current time will be used

month number
  • optional
  • default: 1

The month, 1-indexed

day number
  • optional
  • default: 1

The day of the month

hour number
  • optional
  • default: 0

The hour of the day, in 24-hour time

minute number
  • optional
  • default: 0

The minute of the hour, i.e. a number between 0 and 59

second number
  • optional
  • default: 0

The second of the minute, i.e. a number between 0 and 59

millisecond number
  • optional
  • default: 0

The millisecond of the second, i.e. a number between 0 and 999

Return:

DateTime

Example:

DateTime.utc()                            //~> now
DateTime.utc(2017)                        //~> 2017-01-01T00:00:00Z
DateTime.utc(2017, 3)                     //~> 2017-03-01T00:00:00Z
DateTime.utc(2017, 3, 12)                 //~> 2017-03-12T00:00:00Z
DateTime.utc(2017, 3, 12, 5)              //~> 2017-03-12T05:00:00Z
DateTime.utc(2017, 3, 12, 5, 45)          //~> 2017-03-12T05:45:00Z
DateTime.utc(2017, 3, 12, 5, 45, 10)      //~> 2017-03-12T05:45:10Z
DateTime.utc(2017, 3, 12, 5, 45, 10, 765) //~> 2017-03-12T05:45:10.675Z

Private Constructors

private constructor() source

Public Members

public get day: number: * source

Get the day of the month (1-30ish).

Return:

number

Example:

DateTime.local(2017, 5, 25).day //=> 25

public get daysInMonth: number: * source

Returns the number of days in this DateTime's month

Return:

number

Example:

DateTime.local(2016, 2).daysInMonth //=> 29
DateTime.local(2016, 3).daysInMonth //=> 31

public get daysInYear: number: * source

Returns the number of days in this DateTime's year

Return:

number

Example:

DateTime.local(2016).daysInYear //=> 366
DateTime.local(2013).daysInYear //=> 365

public get hour: number: * source

Get the hour of the day (0-23).

Return:

number

Example:

DateTime.local(2017, 5, 25, 9).hour //=> 9

public get invalidReason: string: * source

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

Return:

string

public get isInDST: boolean: * source

Get whether the DateTime is in a DST.

Return:

boolean

public get isInLeapYear: boolean: * source

Returns true if this DateTime is in a leap year, false otherwise

Return:

boolean

Example:

DateTime.local(2016).isInLeapYear //=> true
DateTime.local(2013).isInLeapYear //=> false

public get isOffsetFixed: boolean: * source

Get whether this zone's offset ever changes, as in a DST.

Return:

boolean

public get isValid: boolean: * source

Returns whether the DateTime is valid. Invalid DateTimes occur when:

  • The DateTime was created from invalid calendar information, such as the 13th month or February 30
  • The DateTime was created by an operation on another invalid date

Return:

boolean

public get locale: string: * source

Get the locale of a DateTime, such 'en-GB'. The locale is used when formatting the DateTime

Return:

string

public get millisecond: number: * source

Get the millisecond of the second (0-999).

Return:

number

Example:

DateTime.local(2017, 5, 25, 9, 30, 52, 654).millisecond //=> 654

public get minute: number: * source

Get the minute of the hour (0-59).

Return:

number

Example:

DateTime.local(2017, 5, 25, 9, 30).minute //=> 30

public get month: number: * source

Get the month (1-12).

Return:

number

Example:

DateTime.local(2017, 5, 25).month //=> 5

public get monthLong: string: * source

Get the human readable long month name, such as 'October'. Defaults to the system's locale if no locale has been specified

Return:

string

Example:

DateTime.local(2017, 10, 30).monthLong //=> October

public get monthShort: string: * source

Get the human readable short month name, such as 'Oct'. Defaults to the system's locale if no locale has been specified

Return:

string

Example:

DateTime.local(2017, 10, 30).monthShort //=> Oct

public get numberingSystem: string: * source

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

Return:

string

public get offset: number: * source

Get the UTC offset of this DateTime in minutes

Return:

number

Example:

DateTime.local().offset //=> -240
DateTime.utc().offset //=> 0

public get offsetNameLong: String: * source

Get the long human name for the zone's current offset, for example "Eastern Standard Time" or "Eastern Daylight Time". Defaults to the system's locale if no locale has been specified

Return:

String

public get offsetNameShort: String: * source

Get the short human name for the zone's current offset, for example "EST" or "EDT". Defaults to the system's locale if no locale has been specified

Return:

String

public get ordinal: number | DateTime: * source

Get the ordinal (i.e. the day of the year)

Return:

number | DateTime

Example:

DateTime.local(2017, 5, 25).ordinal //=> 145

public get outputCalendar: string: * source

Get the output calendar of a DateTime, such 'islamic'. The output calendar is used when formatting the DateTime

Return:

string

public get second: number: * source

Get the second of the minute (0-59).

Return:

number

Example:

DateTime.local(2017, 5, 25, 9, 30, 52).second //=> 52

public get weekNumber: number: * source

Get the week number of the week year (1-52ish).

Return:

number

Example:

DateTime.local(2017, 5, 25).weekNumber //=> 21

See:

public get weekYear: number: * source

Get the week year

Return:

number

Example:

DateTime.local(2014, 11, 31).weekYear //=> 2015

See:

public get weekday: number: * source

Get the day of the week. 1 is Monday and 7 is Sunday

Return:

number

Example:

DateTime.local(2014, 11, 31).weekday //=> 4

See:

public get weekdayLong: string: * source

Get the human readable long weekday, such as 'Monday'. Defaults to the system's locale if no locale has been specified

Return:

string

Example:

DateTime.local(2017, 10, 30).weekdayLong //=> Monday

public get weekdayShort: string: * source

Get the human readable short weekday, such as 'Mon'. Defaults to the system's locale if no locale has been specified

Return:

string

Example:

DateTime.local(2017, 10, 30).weekdayShort //=> Mon

public get year: number: * source

Get the year

Return:

number

Example:

DateTime.local(2017, 5, 25).year //=> 2017

public get zoneName: String: * source

Get the name of the time zone.

Return:

String

Private Members

private c: * source

private invalid: * source

private loc: * source

private o: * source

private ts: * source

private weekData: * source

private zone: * source

Public Methods

public diff(otherDateTime: DateTime, unit: string | string[], opts: Object): Duration source

Return the difference between two DateTimes as a Duration.

Params:

NameTypeAttributeDescription
otherDateTime DateTime

the DateTime to compare this one to

unit string | string[]
  • optional
  • default: ['milliseconds']

the unit or array of units (such as 'hours' or 'days') to include in the duration.

opts Object

options that affect the creation of the Duration

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

the conversion system to use

Return:

Duration

Example:

var i1 = DateTime.fromISO('1982-05-25T09:45'),
    i2 = DateTime.fromISO('1983-10-14T10:30');
i2.diff(i1).toObject() //=> { milliseconds: 43807500000 }
i2.diff(i1, 'hours').toObject() //=> { hours: 12168.75 }
i2.diff(i1, ['months', 'days']).toObject() //=> { months: 16, days: 19.03125 }
i2.diff(i1, ['months', 'days', 'hours']).toObject() //=> { months: 16, days: 19, hours: 0.75 }

public diffNow(unit: string | string[], opts: Object): Duration source

Return the difference between this DateTime and right now. See diff

Params:

NameTypeAttributeDescription
unit string | string[]
  • optional
  • default: ['milliseconds']

the unit or units units (such as 'hours' or 'days') to include in the duration

opts Object

options that affect the creation of the Duration

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

the conversion system to use

Return:

Duration

public endOf(unit: string): DateTime source

"Set" this DateTime to the end (i.e. the last millisecond) of a unit of time

Params:

NameTypeAttributeDescription
unit string

The unit to go to the end of. Can be 'year', 'month', 'day', 'hour', 'minute', 'second', or 'millisecond'.

Return:

DateTime

Example:

DateTime.local(2014, 3, 3).endOf('month').toISO(); //=> '2014-03-03T00:00:00.000-05:00'
DateTime.local(2014, 3, 3).endOf('year').toISO(); //=> '2014-12-31T23:59:59.999-05:00'
DateTime.local(2014, 3, 3, 5, 30).endOf('day').toISO(); //=> '2014-03-03T23:59:59.999-05:00'
DateTime.local(2014, 3, 3, 5, 30).endOf('hour').toISO(); //=> '2014-03-03T05:59:59.999-05:00'

public equals(other: DateTime): boolean source

Equality check Two DateTimes are equal iff they represent the same millisecond

Params:

NameTypeAttributeDescription
other DateTime

the other DateTime

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:

DateTime.local(2017, 7, 4).get('month'); //=> 7
DateTime.local(2017, 7, 4).get('day'); //=> 4

public hasSame(otherDateTime: DateTime, unit: string): boolean source

Return whether this DateTime is in the same unit of time as another DateTime

Params:

NameTypeAttributeDescription
otherDateTime DateTime

the other DateTime

unit string

the unit of time to check sameness on

Return:

boolean

Example:

DateTime.local().hasSame(otherDT, 'day'); //~> true if both the same calendar day

public inspect(): string source

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

Return:

string

public minus(duration: Duration | number | object): DateTime source

Subtract a period of time to this DateTime and return the resulting DateTime See plus

Params:

NameTypeAttributeDescription
duration Duration | number | object

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

Return:

DateTime

public plus(duration: Duration | number | object): DateTime source

Add a period of time to this DateTime and return the resulting DateTime

Adding hours, minutes, seconds, or milliseconds increases the timestamp by the right number of milliseconds. Adding days, months, or years shifts the calendar, accounting for DSTs and leap years along the way. Thus, dt.plus({ hours: 24 }) may result in a different time than dt.plus({ days: 1 }) if there's a DST shift in between.

Params:

NameTypeAttributeDescription
duration Duration | number | object

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

Return:

DateTime

Example:

DateTime.local().plus(123) //~> in 123 milliseconds
DateTime.local().plus({ minutes: 15 }) //~> in 15 minutes
DateTime.local().plus({ days: 1 }) //~> this time tomorrow
DateTime.local().plus({ days: -1 }) //~> this time yesterday
DateTime.local().plus({ hours: 3, minutes: 13 }) //~> in 1 hr, 13 min
DateTime.local().plus(Duration.fromObject({ hours: 3, minutes: 13 })) //~> in 1 hr, 13 min

public reconfigure(properties: object): DateTime source

"Set" the locale, numberingSystem, or outputCalendar. Returns a newly-constructed DateTime.

Params:

NameTypeAttributeDescription
properties object

the properties to set

Return:

DateTime

Example:

DateTime.local(2017, 5, 25).reconfigure({ locale: 'en-GB' })

public resolvedLocaleOpts(opts: object): object source

Returns the resolved Intl options for this DateTime. This is useful in understanding the behavior of formatting methods

Params:

NameTypeAttributeDescription
opts object

the same options as toLocaleString

Return:

object

public set(values: object): DateTime source

"Set" the values of specified units. Returns a newly-constructed DateTime.

Params:

NameTypeAttributeDescription
values object

a mapping of units to numbers

Return:

DateTime

Example:

dt.set({ year: 2017 })
dt.set({ hour: 8, minute: 30 })
dt.set({ weekday: 5 })
dt.set({ year: 2005, ordinal: 234 })
dt.set({ outputCalendar: 'beng', zone: 'utc' })

public setLocale(locale: *): DateTime source

"Set" the locale. Returns a newly-constructed DateTime. Just a convenient alias for reconfigure({ locale })

Params:

NameTypeAttributeDescription
locale *

Return:

DateTime

Example:

DateTime.local(2017, 5, 25).setLocale('en-GB')

public setZone(zone: string | Zone, opts: object): DateTime source

"Set" the DateTime's zone to specified zone. Returns a newly-constructed DateTime.

By default, the setter keeps the underlying time the same (as in, the same UTC timestamp), but the new instance will report different local times and consider DSTs when making computations, as with plus. You may wish to use toLocal and toUTC which provide simple convenience wrappers for commonly used zones.

Params:

NameTypeAttributeDescription
zone string | Zone
  • optional
  • default: 'local'

a zone identifier. As a string, that can be any IANA zone supported by the host environment, or a fixed-offset name of the form 'utc+3', or the strings 'local' or 'utc'. You may also supply an instance of a Zone class.

opts object

options

opts.keepCalendarTime boolean
  • optional
  • default: false

If true, adjust the underlying time so that the local time stays the same, but in the target zone. You should rarely need this.

Return:

DateTime

public startOf(unit: string): DateTime source

"Set" this DateTime to the beginning of a unit of time.

Params:

NameTypeAttributeDescription
unit string

The unit to go to the beginning of. Can be 'year', 'month', 'day', 'hour', 'minute', 'second', or 'millisecond'.

Return:

DateTime

Example:

DateTime.local(2014, 3, 3).startOf('month').toISODate(); //=> '2014-03-01'
DateTime.local(2014, 3, 3).startOf('year').toISODate(); //=> '2014-01-01'
DateTime.local(2014, 3, 3, 5, 30).startOf('day').toISOTime(); //=> '00:00.000-05:00'
DateTime.local(2014, 3, 3, 5, 30).startOf('hour').toISOTime(); //=> '05:00:00.000-05:00'

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

Returns a string representation of this DateTime formatted according to the specified format string. You may not want this. See toLocaleString for a more flexible formatting tool. See the documentation for the specific format tokens supported. Defaults to en-US if no locale has been specified, regardless of the system's locale

Params:

NameTypeAttributeDescription
fmt string

the format string

opts object

options

opts.round boolean

round numerical values

Return:

string

Example:

DateTime.local().toFormat('yyyy LLL dd') //=> '2017 avr. 22'
DateTime.local().setLocale('fr').toFormat('yyyy LLL dd') //=> '2017 Apr 22'
DateTime.local().toFormat("HH 'hours and' mm 'minutes'") //=> '20 hours and 55 minutes'

public toHTTP(): string source

Returns a string representation of this DateTime appropriate for use in HTTP headers. Specifically, the string conforms to RFC 1123.

Return:

string

Example:

DateTime.utc(2014, 7, 13).toHTTP() //=> 'Sun, 13 Jul 2014 00:00:00 GMT'
DateTime.utc(2014, 7, 13, 19).toHTTP() //=> 'Sun, 13 Jul 2014 19:00:00 GMT'

See:

public toISO(opts: object): string source

Returns an ISO 8601-compliant string representation of this DateTime

Params:

NameTypeAttributeDescription
opts object

options

opts.suppressMilliseconds boolean
  • optional
  • default: false

exclude milliseconds from the format if they're 0

opts.suppressSeconds boolean
  • optional
  • default: false

exclude seconds from the format if they're 0

opts.includeOffset boolean
  • optional
  • default: true

include the offset, such as 'Z' or '-04:00'

Return:

string

Example:

DateTime.utc(1982, 5, 25).toISO() //=> '1982-05-25T00:00:00.000Z'
DateTime.local().toISO() //=> '2017-04-22T20:47:05.335-04:00'
DateTime.local().toISO({ includeOffset: false }) //=> '2017-04-22T20:47:05.335'

public toISODate(): string source

Returns an ISO 8601-compliant string representation of this DateTime's date component

Return:

string

Example:

DateTime.utc(1982, 5, 25).toISODate() //=> '1982-05-25'

public toISOTime(opts: object): string source

Returns an ISO 8601-compliant string representation of this DateTime's time component

Params:

NameTypeAttributeDescription
opts object

options

opts.suppressMilliseconds boolean
  • optional
  • default: false

exclude milliseconds from the format if they're 0

opts.suppressSeconds boolean
  • optional
  • default: false

exclude seconds from the format if they're 0

opts.includeOffset boolean
  • optional
  • default: true

include the offset, such as 'Z' or '-04:00'

Return:

string

Example:

DateTime.utc().hour(7).minute(34).toISOTime() //=> '07:34:19.361Z'
DateTime.utc().hour(7).minute(34).toISOTime({ suppressSeconds: true }) //=> '07:34Z'

public toISOWeekDate(): string source

Returns an ISO 8601-compliant string representation of this DateTime's week date

Return:

string

Example:

DateTime.utc(1982, 5, 25).toISOWeekDate() //=> '1982-W21-2'

public toJSDate(): object source

Returns a Javascript Date equivalent to this DateTime.

Return:

object

public toJSON(): string source

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

Return:

string

public toLocal(): DateTime source

"Set" the DateTime's zone to the host's local zone. Returns a newly-constructed DateTime.

Equivalent to setZone('local')

Return:

DateTime

public toLocaleParts(opts: *): * source

Returns an array of format "parts", i.e. individual tokens along with metadata. This is allows callers to post-process individual sections of the formatted output. Defaults to the system's locale if no locale has been specified

Params:

NameTypeAttributeDescription
opts *

{object} - Intl.DateTimeFormat constructor options, same as toLocaleString.

Return:

*

Example:

DateTime.local().toLocaleString(); //=> [
                                   //=>   { type: 'day', value: '25' },
                                   //=>   { type: 'literal', value: '/' },
                                   //=>   { type: 'month', value: '05' },
                                   //=>   { type: 'literal', value: '/' },
                                   //=>   { type: 'year', value: '1982' }
                                   //=> ]

See:

public toLocaleString(opts: *): string source

Returns a localized string representing this date. Accepts the same options as the Intl.DateTimeFormat constructor and any presets defined by Luxon, such as DateTime.DATE_FULL or DateTime.TIME_SIMPLE. The exact behavior of this method is browser-specific, but in general it will return an appropriate representation. of the DateTime in the assigned locale. Defaults to the system's locale if no locale has been specified

Params:

NameTypeAttributeDescription
opts *

{object} - Intl.DateTimeFormat constructor options

Return:

string

Example:

DateTime.local().toLocaleString(); //=> 4/20/2017
DateTime.local().setLocale('en-gb').toLocaleString(); //=> '20/04/2017'
DateTime.local().toLocaleString(DateTime.DATE_FULL); //=> 'April 20, 2017'
DateTime.local().toLocaleString(DateTime.TIME_SIMPLE); //=> '11:32 AM'
DateTime.local().toLocaleString(DateTime.DATETIME_SHORT); //=> '4/20/2017, 11:32 AM'
DateTime.local().toLocaleString({weekday: 'long', month: 'long', day: '2-digit'}); //=> 'Thu, Apr 20'
DateTime.local().toLocaleString({weekday: 'long', month: 'long', day: '2-digit', hour: '2-digit', minute: '2-digit'}); //=> 'Thu, Apr 20, 11:27'
DateTime.local().toLocaleString({hour: '2-digit', minute: '2-digit'}); //=> '11:32'

See:

public toObject(opts: *): object source

Returns a Javascript object with this DateTime's year, month, day, and so on.

Params:

NameTypeAttributeDescription
opts *

options for generating the object

opts.includeConfig boolean
  • optional
  • default: false

include configuration attributes in the output

Return:

object

Example:

DateTime.local().toObject() //=> { year: 2017, month: 4, day: 22, hour: 20, minute: 49, second: 42, millisecond: 268 }

public toRFC2822(): string source

Returns an RFC 2822-compatible string representation of this DateTime, always in UTC

Return:

string

Example:

DateTime.utc(2014, 7, 13).toRFC2822() //=> 'Sun, 13 Jul 2014 00:00:00 +0000'
DateTime.local(2014, 7, 13).toRFC2822() //=> 'Sun, 13 Jul 2014 00:00:00 -0400'

public toSQL(opts: object): string source

Returns a string representation of this DateTime appropriate for use in SQL DateTime

Params:

NameTypeAttributeDescription
opts object

options

opts.includeZone boolean
  • optional
  • default: false

include the zone, such as 'America/New_York'. Overrides includeOffset.

opts.includeOffset boolean
  • optional
  • default: true

include the offset, such as 'Z' or '-04:00'

Return:

string

Example:

DateTime.utc(2014, 7, 13).toSQL() //=> '2014-07-13 00:00:00.000 Z'
DateTime.local(2014, 7, 13).toSQL() //=> '2014-07-13 00:00:00.000 -04:00'
DateTime.local(2014, 7, 13).toSQL({ includeOffset: false }) //=> '2014-07-13 00:00:00.000'
DateTime.local(2014, 7, 13).toSQL({ includeZone: false }) //=> '2014-07-13 00:00:00.000 America/New_York'

public toSQLDate(): string source

Returns a string representation of this DateTime appropriate for use in SQL Date

Return:

string

Example:

DateTime.utc(2014, 7, 13).toSQLDate() //=> '2014-07-13'

public toSQLTime(opts: object): string source

Returns a string representation of this DateTime appropriate for use in SQL Time

Params:

NameTypeAttributeDescription
opts object

options

opts.includeZone boolean
  • optional
  • default: false

include the zone, such as 'America/New_York'. Overides includeOffset.

opts.includeOffset boolean
  • optional
  • default: true

include the offset, such as 'Z' or '-04:00'

Return:

string

Example:

DateTime.utc().toSQL() //=> '05:15:16.345'
DateTime.local().toSQL() //=> '05:15:16.345 -04:00'
DateTime.local().toSQL({ includeOffset: false }) //=> '05:15:16.345'
DateTime.local().toSQL({ includeZone: false }) //=> '05:15:16.345 America/New_York'

public toString(): string source

Returns a string representation of this DateTime appropriate for debugging

Return:

string

public toUTC(offset: number, opts: object): DateTime source

"Set" the DateTime's zone to UTC. Returns a newly-constructed DateTime.

Equivalent to setZone('utc')

Params:

NameTypeAttributeDescription
offset number
  • optional
  • default: 0

optionally, an offset from UTC in minutes

opts object
  • optional
  • default: {}

options to pass to setZone()

Return:

DateTime

public until(otherDateTime: DateTime): Duration source

Return an Interval spanning between this DateTime and another DateTime

Params:

NameTypeAttributeDescription
otherDateTime DateTime

the other end point of the Interval

Return:

Duration

public valueOf(): number source

Returns the epoch milliseconds of this DateTime

Return:

number