Interface: DateTime<IsValid>

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 consists of the following parts:

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 affect how output strings are formatted, such as locale, numberingSystem, and outputCalendar.

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

Creation: To create a DateTime from its components, use one of its factory class methods: DateTime.local, DateTime.utc, and (most flexibly) DateTime.fromObject. To create one from a standard string format, use DateTime.fromISO, DateTime.fromHTTP, and DateTime.fromRFC2822. To create one from a custom string format, use DateTime.fromFormat. To create one from a native JS date, use DateTime.fromJSDate.
Gregorian calendar and time: To examine the Gregorian properties of a DateTime individually (i.e. as opposed to collectively through DateTime#toObject), use the DateTime#year, DateTime#month, DateTime#day, DateTime#hour, DateTime#minute, DateTime#second, DateTime#millisecond accessors.
Week calendar: For ISO week calendar attributes, see the DateTime#weekYear, DateTime#weekNumber, and DateTime#weekday accessors.
Configuration See the DateTime#locale and DateTime#numberingSystem accessors.
Transformation: To transform the DateTime into other DateTimes, use DateTime#set, DateTime#reconfigure, DateTime#setZone, DateTime#setLocale, DateTime.plus, DateTime#minus, DateTime#endOf, DateTime#startOf, DateTime#toUTC, and DateTime#toLocal.
Output: To convert the DateTime to other representations, use the DateTime#toRelative, DateTime#toRelativeCalendar, DateTime#toJSON, DateTime#toISO, DateTime#toHTTP, DateTime#toObject, DateTime#toRFC2822, DateTime#toString, DateTime#toLocaleString, DateTime#toFormat, DateTime#toMillis and DateTime#toJSDate.

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.

Type Parameters

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

Accessors

day

Get Signature

get day(): IfValid<DayNumbers, number, IsValid>;

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

Example

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

Returns

IfValid<DayNumbers, number, IsValid>

daysInMonth

Get Signature

get daysInMonth(): IfValid<PossibleDaysInMonth, undefined, IsValid>;

Returns the number of days in this DateTime's month

Examples

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

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

Returns

IfValid<PossibleDaysInMonth, undefined, IsValid>

daysInYear

Get Signature

get daysInYear(): IfValid<PossibleDaysInYear, number, IsValid>;

Returns the number of days in this DateTime's year

Examples

DateTime.local(2016).daysInYear; //=> 366

DateTime.local(2013).daysInYear; //=> 365

Returns

IfValid<PossibleDaysInYear, number, IsValid>

hour

Get Signature

get hour(): IfValid<HourNumbers, number, IsValid>;

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

Example

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

Returns

IfValid<HourNumbers, number, IsValid>

invalidExplanation

Get Signature

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

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

Returns

IfValid<null, string | null, IsValid>

invalidReason

Get Signature

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

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

Returns

IfValid<null, string, IsValid>

isInDST

Get Signature

get isInDST(): IfValid<boolean, false, IsValid>;

Get whether the DateTime is in a DST.

Returns

IfValid<boolean, false, IsValid>

isInLeapYear

Get Signature

get isInLeapYear(): boolean;

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

Examples

DateTime.local(2016).isInLeapYear; //=> true

DateTime.local(2013).isInLeapYear; //=> false

Returns

boolean

isOffsetFixed

Get Signature

get isOffsetFixed(): IfValid<boolean, null, IsValid>;

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

Returns

IfValid<boolean, null, IsValid>

isValid

Get Signature

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

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

Returns

IfValid<true, false, IsValid>

isWeekend

Get Signature

get isWeekend(): IfValid<boolean, false, IsValid>;

Returns true if this date is on a weekend, according to the locale, false otherwise

Returns

IfValid<boolean, false, IsValid>

locale

Get Signature

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

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

Returns

IfValid<string, null, IsValid>

localWeekday

Get Signature

get localWeekday(): IfValid<WeekdayNumbers, number, IsValid>;

Get the day of the week, according to the locale. 1 is the first day of the week, and 7 is the last day of the week. If the locale assigns Sunday as the first day of the week, then a date which is a Sunday will return 1.

Returns

IfValid<WeekdayNumbers, number, IsValid>

localWeekNumber

Get Signature

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

Get the week number of the week year, according to the locale. Different locales assign week numbers differently. The week can start on different days of the week (see localWeekday), and because a different number of days is required for a week to count as the first week of a year.

Returns

IfValid<number, number, IsValid>

localWeekYear

Get Signature

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

Get the week year, according to the locale. Different locales assign week numbers (and therefore week years) differently, see localWeekNumber.

Returns

IfValid<number, number, IsValid>

millisecond

Get Signature

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

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

Example

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

Returns

IfValid<number, number, IsValid>

minute

Get Signature

get minute(): IfValid<SecondNumbers, number, IsValid>;

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

Example

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

Returns

IfValid<SecondNumbers, number, IsValid>

month

Get Signature

get month(): IfValid<MonthNumbers, number, IsValid>;

Get the month (1-12).

Example

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

Returns

IfValid<MonthNumbers, number, IsValid>

monthLong

Get Signature

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

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

Example

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

Returns

IfValid<string, null, IsValid>

monthShort

Get Signature

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

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

Example

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

Returns

IfValid<string, null, IsValid>

numberingSystem

Get Signature

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

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

Returns

IfValid<string, null, IsValid>

offset

Get Signature

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

Get the UTC offset of this DateTime in minutes

Examples

DateTime.now().offset; //=> -240

DateTime.utc().offset; //=> 0

Returns

IfValid<number, number, IsValid>

offsetNameLong

Get Signature

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

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

Returns

IfValid<string, null, IsValid>

offsetNameShort

Get Signature

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

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

Returns

IfValid<string, null, IsValid>

ordinal

Get Signature

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

Get the ordinal (meaning the day of the year)

Example

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

Returns

IfValid<number, number, IsValid>

outputCalendar

Get Signature

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

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

Returns

IfValid<string, null, IsValid>

quarter

Get Signature

get quarter(): IfValid<QuarterNumbers, number, IsValid>;

Get the quarter

Example

DateTime.local(2017, 5, 25).quarter; //=> 2

Returns

IfValid<QuarterNumbers, number, IsValid>

second

Get Signature

get second(): IfValid<SecondNumbers, number, IsValid>;

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

Example

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

Returns

IfValid<SecondNumbers, number, IsValid>

weekday

Get Signature

get weekday(): IfValid<WeekdayNumbers, number, IsValid>;

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

See

https://en.wikipedia.org/wiki/ISO_week_date

Example

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

Returns

IfValid<WeekdayNumbers, number, IsValid>

weekdayLong

Get Signature

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

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

Example

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

Returns

IfValid<string, null, IsValid>

weekdayShort

Get Signature

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

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

Example

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

Returns

IfValid<string, null, IsValid>

weekNumber

Get Signature

get weekNumber(): IfValid<WeekNumbers, number, IsValid>;

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

See

https://en.wikipedia.org/wiki/ISO_week_date

Example

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

Returns

IfValid<WeekNumbers, number, IsValid>

weeksInLocalWeekYear

Get Signature

get weeksInLocalWeekYear(): IfValid<PossibleWeeksInYear, number, IsValid>;

Returns the number of weeks in this DateTime's local week year

Examples

DateTime.local(2020, 6, { locale: "en-US" }).weeksInLocalWeekYear; //=> 52

DateTime.local(2020, 6, { locale: "de-DE" }).weeksInLocalWeekYear; //=> 53

Returns

IfValid<PossibleWeeksInYear, number, IsValid>

weeksInWeekYear

Get Signature

get weeksInWeekYear(): IfValid<PossibleWeeksInYear, number, IsValid>;

Returns the number of weeks in this DateTime's year

See

https://en.wikipedia.org/wiki/ISO_week_date

Examples

DateTime.local(2004).weeksInWeekYear; //=> 53

DateTime.local(2013).weeksInWeekYear; //=> 52

Returns

IfValid<PossibleWeeksInYear, number, IsValid>

weekYear

Get Signature

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

Get the week year

See

https://en.wikipedia.org/wiki/ISO_week_date

Example

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

Returns

IfValid<number, number, IsValid>

year

Get Signature

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

Get the year

Example

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

Returns

IfValid<number, number, IsValid>

zone

Get Signature

get zone(): Zone<IsValid>;

Get the time zone associated with this DateTime.

Returns

Zone<IsValid>

zoneName

Get Signature

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

Get the name of the time zone.

Returns

IfValid<string, null, IsValid>

Methods

diff()

diff(
   otherDateTime: DateTime,
   unit?: DurationUnits,
opts?: DiffOptions): Duration<IsValid>;

Return the difference between two DateTimes as a Duration.

Parameters

Parameter	Type	Description
`otherDateTime`	`DateTime`	the DateTime to compare this one to
`unit?`	`DurationUnits`	the unit or array of units to include in the duration. Defaults to ['milliseconds'].
`opts?`	`DiffOptions`	options that affect the creation of the Duration

Returns

Duration<IsValid>

Example

let 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 }

diffNow()

diffNow(unit?: DurationUnits, opts?: DiffOptions): Duration<true>;

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

Parameters

Parameter	Type	Description
`unit?`	`DurationUnits`	the unit(s) to include in the duration. Defaults to ['milliseconds'].
`opts?`	`DiffOptions`	options that affect the creation of the Duration

Returns

Duration<true>

endOf()

endOf(unit: DateTimeUnit, opts?: _UseLocaleWeekOption): this;

"Set" this DateTime to the end (meaning the last millisecond) of a unit of time

Parameters

Parameter	Type	Description
`unit`	`DateTimeUnit`	The unit to go to the end of. Can be 'year', 'quarter', 'month', 'week', 'day', 'hour', 'minute', 'second', or 'millisecond'.
`opts?`	`_UseLocaleWeekOption`	options

Returns

this

Examples

DateTime.local(2014, 3, 3).endOf("month").toISO(); //=> '2014-03-31T23:59:59.999-05:00'

DateTime.local(2014, 3, 3).endOf("year").toISO(); //=> '2014-12-31T23:59:59.999-05:00'

DateTime.local(2014, 3, 3).endOf("week").toISO(); // => '2014-03-09T23:59:59.999-05:00', weeks start on Mondays

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'

equals()

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

An equality check. Two DateTimes are equal if and only if they represent the same millisecond, have the same zone and location, and are both valid. To compare just the millisecond values, use +dt1 === +dt2.

Parameters

Parameter	Type	Description
`other`	`DateTime`	the other DateTime

Returns

IfValid<boolean, false, IsValid>

get()

get(unit: keyof DateTime<boolean>): number;

Get the value of unit.

Parameters

Parameter	Type	Description
`unit`	keyof `DateTime`<`boolean`>	a unit such as 'minute' or 'day'

Returns

number

Examples

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

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

getPossibleOffsets()

getPossibleOffsets(): DateTime<IsValid>[];

Get those DateTimes which have the same local time as this DateTime, but a different offset from UTC in this DateTime's zone. During DST changes local time can be ambiguous, for example 2023-10-29T02:30:00 in Europe/Berlin can have offset +01:00 or +02:00. This method will return both possible DateTimes if this DateTime's local time is ambiguous.

Returns

DateTime<IsValid>[]

hasSame()

hasSame(
   otherDateTime: DateTime,
   unit: DateTimeUnit,
opts?: _UseLocaleWeekOption): IfValid<boolean, false, IsValid>;

Return whether this DateTime is in the same unit of time as another DateTime. Note that time zones are ignored in this comparison, which compares the local calendar time. Use DateTime.setZone to convert one of the dates if needed.

Parameters

Parameter	Type	Description
`otherDateTime`	`DateTime`	the other DateTime
`unit`	`DateTimeUnit`	the unit of time to check sameness on
`opts?`	`_UseLocaleWeekOption`	-

Returns

IfValid<boolean, false, IsValid>

Example

DateTime.now().hasSame(otherDT, "day"); //~> true if otherDT is in the same current calendar day

minus()

minus(duration: DurationLike): this;

See DateTime.plus

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

plus()

plus(duration: DurationLike): this;

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.

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

Examples

DateTime.now().plus(123); //~> in 123 milliseconds

DateTime.now().plus({ minutes: 15 }); //~> in 15 minutes

DateTime.now().plus({ days: 1 }); //~> this time tomorrow

DateTime.now().plus({ days: -1 }); //~> this time yesterday

DateTime.now().plus({ hours: 3, minutes: 13 }); //~> in 3 hr, 13 min

DateTime.now().plus(Duration.fromObject({ hours: 3, minutes: 13 })); //~> in 3 hr, 13 min

reconfigure()

reconfigure(properties: LocaleOptions): this;

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

Parameters

Parameter	Type	Description
`properties`	`LocaleOptions`	the properties to set

Returns

this

Example

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

resolvedLocaleOptions()

resolvedLocaleOptions(opts?: LocaleOptions | DateTimeFormatOptions): ResolvedLocaleOptions;

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

Parameters

Parameter	Type	Description
`opts?`	`LocaleOptions` \| `DateTimeFormatOptions`	the same options as toLocaleString

Returns

ResolvedLocaleOptions

set()

set(values: DateObjectUnits): this;

"Set" the values of specified units. Returns a newly-constructed DateTime. You can only set units with this method; for "setting" metadata, see DateTime.reconfigure and DateTime.setZone.

This method also supports setting locale-based week units, i.e. localWeekday, localWeekNumber and localWeekYear. They cannot be mixed with ISO-week units like weekday.

Parameters

Parameter	Type
`values`	`DateObjectUnits`

Returns

this

Examples

dt.set({ year: 2017 });

dt.set({ hour: 8, minute: 30 });

dt.set({ weekday: 5 });

dt.set({ year: 2005, ordinal: 234 });

setLocale()

setLocale(locale: string): this;

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

Parameters

Parameter	Type
`locale`	`string`

Returns

this

Example

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

setZone()

setZone(zone?: string | Zone<boolean>, opts?: ZoneOptions): DateTime<true> | DateTime<false>;

"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 timestamp), but the new instance will report different local times and consider DSTs when making computations, as with DateTime.plus. You may wish to use DateTime.toLocal and DateTime.toUTC which provide simple convenience wrappers for commonly used zones.

Parameters

Parameter	Type	Description
`zone?`	`string` \| `Zone`<`boolean`>	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. Defaults to 'local'.
`opts?`	`ZoneOptions`	options

Returns

DateTime<true> | DateTime<false>

startOf()

startOf(unit: DateTimeUnit, opts?: _UseLocaleWeekOption): this;

"Set" this DateTime to the beginning of the given unit.

Parameters

Parameter	Type	Description
`unit`	`DateTimeUnit`	The unit to go to the beginning of. Can be 'year', 'quarter', 'month', 'week', 'day', 'hour', 'minute', 'second', or 'millisecond'.
`opts?`	`_UseLocaleWeekOption`	options

Returns

this

Examples

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).startOf("week").toISODate(); //=> '2014-03-03', weeks always start on Mondays

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'

toBSON()

toBSON(): Date;

Returns a BSON-serializable equivalent to this DateTime.

Returns

Date

toFormat()

toFormat(format: string, options?: LocaleOptions): IfValid<string, "Invalid DateTime", IsValid>;

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

Parameters

Parameter	Type	Description
`format`	`string`	the format string - see Tokens
`options?`	`LocaleOptions`	opts to override the configuration options on this DateTime

Returns

IfValid<string, "Invalid DateTime", IsValid>

Examples

DateTime.now().toFormat("yyyy LLL dd"); //=> '2017 Apr 22'

DateTime.now().setLocale("fr").toFormat("yyyy LLL dd"); //=> '2017 avr. 22'

DateTime.now().toFormat("yyyy LLL dd", { locale: "fr" }); //=> '2017 avr. 22'

DateTime.now().toFormat("HH 'hours and' mm 'minutes'"); //=> '20 hours and 55 minutes'

toHTTP()

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

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

Returns

IfValid<string, null, IsValid>

See

https://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.3.1

Examples

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'

toISO()

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

Returns an ISO 8601-compliant string representation of this DateTime

Parameters

Parameter	Type
`opts?`	`ToISOTimeOptions`

Returns

IfValid<string, null, IsValid>

Examples

DateTime.utc(1982, 5, 25).toISO(); //=> '1982-05-25T00:00:00.000Z'

DateTime.now().toISO(); //=> '2017-04-22T20:47:05.335-04:00'

DateTime.now().toISO({ includeOffset: false }); //=> '2017-04-22T20:47:05.335'

DateTime.now().toISO({ format: "basic" }); //=> '20170422T204705.335-0400'

DateTime.now().toISO({ precision: "day" }); //=> '2017-04-22Z'

DateTime.now().toISO({ precision: "minute" }); //=> '2017-04-22T20:47Z'

toISODate()

toISODate(opts?: ToISODateOptions): IfValid<string, null, IsValid>;

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

Parameters

Parameter	Type
`opts?`	`ToISODateOptions`

Returns

IfValid<string, null, IsValid>

Examples

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

DateTime.utc(1982, 5, 25).toISODate({ format: "basic" }); //=> '19820525'

DateTime.utc(1982, 5, 25).toISODate({ precision: "month" }); //=> '1982-05'

toISOTime()

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

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

Parameters

Parameter	Type
`opts?`	`ToISOTimeOptions`

Returns

IfValid<string, null, IsValid>

Examples

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

DateTime.utc()
  .set({ hour: 7, minute: 34, seconds: 0, milliseconds: 0 })
  .toISOTime({ suppressSeconds: true }); //=> '07:34Z'

DateTime.utc().set({ hour: 7, minute: 34 }).toISOTime({ format: "basic" }); //=> '073419.361Z'

DateTime.utc().set({ hour: 7, minute: 34 }).toISOTime({ includePrefix: true }); //=> 'T07:34:19.361Z'

DateTime.utc()
  .set({ hour: 7, minute: 34, second: 56 })
  .toISOTime({ precision: "minute" }); //=> '07:34Z'

toISOWeekDate()

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

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

Returns

IfValid<string, null, IsValid>

Example

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

toJSDate()

toJSDate(): Date;

Returns a JavaScript Date equivalent to this DateTime.

Returns

Date

toJSON()

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

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

Returns

IfValid<string, null, IsValid>

toLocal()

toLocal(): this;

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

Equivalent to setZone('local')

Returns

this

toLocaleParts()

toLocaleParts(opts?: DateTimeFormatOptions): DateTimeFormatPart[];

Returns an array of format "parts", meaning 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

Parameters

Parameter	Type
`opts?`	`DateTimeFormatOptions`

Returns

DateTimeFormatPart[]

See

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat/formatToParts

Examples

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

DateTime.invalid("").toLocaleParts(); //=> []

toLocaleString()

toLocaleString(formatOpts?: DateTimeFormatOptions, opts?: LocaleOptions): IfValid<string, "Invalid DateTime", IsValid>;

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 of the DateTime in the assigned locale. Defaults to the system's locale if no locale has been specified

Parameters

Parameter	Type	Description
`formatOpts?`	`DateTimeFormatOptions`	Intl.DateTimeFormat constructor options and configuration options
`opts?`	`LocaleOptions`	opts to override the configuration options on this DateTime

Returns

IfValid<string, "Invalid DateTime", IsValid>

See

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat

Examples

DateTime.now().toLocaleString(); //=> 4/20/2017

DateTime.now().setLocale("en-gb").toLocaleString(); //=> '20/04/2017'

DateTime.now().toLocaleString({ locale: "en-gb" }); //=> '20/04/2017'

DateTime.now().toLocaleString(DateTime.DATE_FULL); //=> 'April 20, 2017'

DateTime.now().toLocaleString(DateTime.TIME_SIMPLE); //=> '11:32 AM'

DateTime.now().toLocaleString(DateTime.DATETIME_SHORT); //=> '4/20/2017, 11:32 AM'

DateTime.now().toLocaleString({
  weekday: "long",
  month: "long",
  day: "2-digit",
}); //=> 'Thursday, April 20'

DateTime.now().toLocaleString({
  weekday: "short",
  month: "short",
  day: "2-digit",
  hour: "2-digit",
  minute: "2-digit",
}); //=> 'Thu, Apr 20, 11:27 AM'

DateTime.now().toLocaleString({
  hour: "2-digit",
  minute: "2-digit",
  hourCycle: "h23",
}); //=> '11:32'

toMillis()

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

Returns the epoch milliseconds of this DateTime.

Returns

IfValid<number, number, IsValid>

toObject()

toObject<IncludeConfig>(opts?: {
  includeConfig?: IncludeConfig;
}): ToObjectOutput<IncludeConfig, IsValid>;

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

Type Parameters

Type Parameter
`IncludeConfig` extends `boolean` \| `undefined`

Parameters

Parameter	Type	Description
`opts?`	{ `includeConfig?`: `IncludeConfig`; }	options for generating the object
`opts.includeConfig?`	`IncludeConfig`	Include configuration attributes in the output

Returns

ToObjectOutput<IncludeConfig, IsValid>

Example

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

toRelative()

toRelative(options?: ToRelativeOptions): IfValid<string, null, IsValid>;

Returns a string representation of this time relative to now, such as "in two days". Can only internationalize if your platform supports Intl.RelativeTimeFormat. Rounds towards zero by default.

Parameters

Parameter	Type
`options?`	`ToRelativeOptions`

Returns

IfValid<string, null, IsValid>

Examples

DateTime.now().plus({ days: 1 }).toRelative(); //=> "in 1 day"

DateTime.now().setLocale("es").toRelative({ days: 1 }); //=> "dentro de 1 día"

DateTime.now().plus({ days: 1 }).toRelative({ locale: "fr" }); //=> "dans 23 heures"

DateTime.now().minus({ days: 2 }).toRelative(); //=> "2 days ago"

DateTime.now().minus({ days: 2 }).toRelative({ unit: "hours" }); //=> "48 hours ago"

DateTime.now().minus({ hours: 36 }).toRelative({ round: false }); //=> "1.5 days ago"

toRelativeCalendar()

toRelativeCalendar(options?: ToRelativeCalendarOptions): IfValid<string, null, IsValid>;

Returns a string representation of this date relative to today, such as "yesterday" or "next month". Only internationalizes on platforms that support Intl.RelativeTimeFormat.

Parameters

Parameter	Type
`options?`	`ToRelativeCalendarOptions`

Returns

IfValid<string, null, IsValid>

Examples

DateTime.now().plus({ days: 1 }).toRelativeCalendar(); //=> "tomorrow"

DateTime.now().setLocale("es").plus({ days: 1 }).toRelative(); //=> ""mañana"

DateTime.now().plus({ days: 1 }).toRelativeCalendar({ locale: "fr" }); //=> "demain"

DateTime.now().minus({ days: 2 }).toRelativeCalendar(); //=> "2 days ago"

toRFC2822()

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

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

Returns

IfValid<string, null, IsValid>

Examples

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'

toSeconds()

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

Returns the epoch seconds of this DateTime.

Returns

IfValid<number, number, IsValid>

toSQL()

toSQL(opts?: ToSQLOptions): IfValid<string, null, IsValid>;

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

Parameters

Parameter	Type
`opts?`	`ToSQLOptions`

Returns

IfValid<string, null, IsValid>

Examples

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: true }); //=> '2014-07-13 00:00:00.000 America/New_York'

toSQLDate()

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

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

Returns

IfValid<string, null, IsValid>

Example

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

toSQLTime()

toSQLTime(opts?: ToSQLOptions): IfValid<string, null, IsValid>;

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

Parameters

Parameter	Type
`opts?`	`ToSQLOptions`

Returns

IfValid<string, null, IsValid>

Examples

DateTime.utc().toSQL(); //=> '05:15:16.345'

DateTime.now().toSQL(); //=> '05:15:16.345 -04:00'

DateTime.now().toSQL({ includeOffset: false }); //=> '05:15:16.345'

DateTime.now().toSQL({ includeZone: false }); //=> '05:15:16.345 America/New_York'

toString()

toString(): IfValid<string, "Invalid DateTime", IsValid>;

Returns a string representation of this DateTime appropriate for debugging

Returns

IfValid<string, "Invalid DateTime", IsValid>

toUnixInteger()

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

Returns the epoch seconds (as a whole number) of this DateTime.

Returns

IfValid<number, number, IsValid>

toUTC()

toUTC(offset?: number, opts?: ZoneOptions): this;

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

Equivalent to DateTime.setZone('utc')

Parameters

Parameter	Type	Description
`offset?`	`number`	optionally, an offset from UTC in minutes. Defaults to 0.
`opts?`	`ZoneOptions`	options to pass to `setZone()`. Defaults to {}.

Returns

this

until()

until(otherDateTime: DateTime): IfValid<Interval<true>, DateTime<false>, IsValid>;

Return an Interval spanning between this DateTime and another DateTime

Parameters

Parameter	Type	Description
`otherDateTime`	`DateTime`	the other end point of the Interval

Returns

IfValid<Interval<true>, DateTime<false>, IsValid>

valueOf()

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

Returns the epoch milliseconds of this DateTime. Alias of DateTime.toMillis

Returns

IfValid<number, number, IsValid>

Interface: DateTime<IsValid> ​

Type Parameters ​

Accessors ​

day ​

Get Signature ​

Example ​

Returns ​

daysInMonth ​

Get Signature ​

Examples ​

Returns ​

daysInYear ​

Get Signature ​

Examples ​

Returns ​

hour ​

Get Signature ​

Example ​

Returns ​

invalidExplanation ​

Get Signature ​

Returns ​

invalidReason ​

Get Signature ​

Returns ​

isInDST ​

Get Signature ​

Returns ​

isInLeapYear ​

Get Signature ​

Examples ​

Returns ​

isOffsetFixed ​

Get Signature ​

Returns ​

isValid ​

Get Signature ​

Returns ​

isWeekend ​

Get Signature ​

Returns ​

locale ​

Get Signature ​

Returns ​

localWeekday ​

Get Signature ​

Returns ​

localWeekNumber ​

Get Signature ​

Returns ​

localWeekYear ​

Get Signature ​

Returns ​

millisecond ​

Get Signature ​

Example ​

Returns ​

minute ​

Get Signature ​

Example ​

Returns ​

month ​

Get Signature ​

Example ​

Returns ​

monthLong ​

Get Signature ​

Example ​

Returns ​

monthShort ​

Get Signature ​

Example ​

Returns ​

numberingSystem ​

Get Signature ​

Returns ​

offset ​

Get Signature ​

Examples ​

Returns ​

Interface: DateTime<IsValid>

Type Parameters

Accessors

day

Get Signature

Example

Returns

daysInMonth

Get Signature

Examples

Returns

daysInYear

Get Signature

Examples

Returns

hour

Get Signature

Example

Returns

invalidExplanation

Get Signature

Returns

invalidReason

Get Signature

Returns

isInDST

Get Signature

Returns

isInLeapYear

Get Signature

Examples

Returns

isOffsetFixed

Get Signature

Returns

isValid

Get Signature

Returns

isWeekend

Get Signature

Returns

locale

Get Signature

Returns

localWeekday

Get Signature

Returns

localWeekNumber

Get Signature

Returns

localWeekYear

Get Signature

Returns

millisecond

Get Signature

Example

Returns

minute

Get Signature

Example

Returns

month

Get Signature

Example

Returns

monthLong

Get Signature

Example

Returns

monthShort

Get Signature

Example

Returns

numberingSystem

Get Signature

Returns

offset

Get Signature

Examples

Returns