@nhtio/lucid-resourceful

Appearance

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:

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 ParameterDefault type
IsValid extends booleanDefaultValidity

Accessors ​

day ​

Get Signature ​

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

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

Example ​
ts
DateTime.local(2017, 5, 25).day; //=> 25
Returns ​

IfValid<DayNumbers, number, IsValid>

daysInMonth ​

Get Signature ​

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

Returns the number of days in this DateTime's month

Examples ​
ts
DateTime.local(2016, 2).daysInMonth; //=> 29
ts
DateTime.local(2016, 3).daysInMonth; //=> 31
Returns ​

IfValid<PossibleDaysInMonth, undefined, IsValid>

daysInYear ​

Get Signature ​

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

Returns the number of days in this DateTime's year

Examples ​
ts
DateTime.local(2016).daysInYear; //=> 366
ts
DateTime.local(2013).daysInYear; //=> 365
Returns ​

IfValid<PossibleDaysInYear, number, IsValid>

hour ​

Get Signature ​

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

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

Example ​
ts
DateTime.local(2017, 5, 25, 9).hour; //=> 9
Returns ​

IfValid<HourNumbers, number, IsValid>

invalidExplanation ​

Get Signature ​

ts
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 ​

ts
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 ​

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

Get whether the DateTime is in a DST.

Returns ​

IfValid<boolean, false, IsValid>

isInLeapYear ​

Get Signature ​

ts
get isInLeapYear(): boolean;

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

Examples ​
ts
DateTime.local(2016).isInLeapYear; //=> true
ts
DateTime.local(2013).isInLeapYear; //=> false
Returns ​

boolean

isOffsetFixed ​

Get Signature ​

ts
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 ​

ts
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 ​

ts
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 ​

ts
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 ​

ts
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 ​

ts
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 ​

ts
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 ​

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

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

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

IfValid<number, number, IsValid>

minute ​

Get Signature ​

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

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

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

IfValid<SecondNumbers, number, IsValid>

month ​

Get Signature ​

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

Get the month (1-12).

Example ​
ts
DateTime.local(2017, 5, 25).month; //=> 5
Returns ​

IfValid<MonthNumbers, number, IsValid>

monthLong ​

Get Signature ​

ts
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 ​
ts
DateTime.local(2017, 10, 30).monthLong; //=> October
Returns ​

IfValid<string, null, IsValid>

monthShort ​

Get Signature ​

ts
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 ​
ts
DateTime.local(2017, 10, 30).monthShort; //=> Oct
Returns ​

IfValid<string, null, IsValid>

numberingSystem ​

Get Signature ​

ts
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 ​

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

Get the UTC offset of this DateTime in minutes

Examples ​
ts
DateTime.now().offset; //=> -240
ts
DateTime.utc().offset; //=> 0
Returns ​

IfValid<number, number, IsValid>

offsetNameLong ​

Get Signature ​

ts
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 ​

ts
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 ​

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

Get the ordinal (meaning the day of the year)

Example ​
ts
DateTime.local(2017, 5, 25).ordinal; //=> 145
Returns ​

IfValid<number, number, IsValid>

outputCalendar ​

Get Signature ​

ts
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 ​

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

Get the quarter

Example ​
ts
DateTime.local(2017, 5, 25).quarter; //=> 2
Returns ​

IfValid<QuarterNumbers, number, IsValid>

second ​

Get Signature ​

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

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

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

IfValid<SecondNumbers, number, IsValid>

weekday ​

Get Signature ​

ts
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 ​
ts
DateTime.local(2014, 11, 31).weekday; //=> 4
Returns ​

IfValid<WeekdayNumbers, number, IsValid>

weekdayLong ​

Get Signature ​

ts
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 ​
ts
DateTime.local(2017, 10, 30).weekdayLong; //=> Monday
Returns ​

IfValid<string, null, IsValid>

weekdayShort ​

Get Signature ​

ts
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 ​
ts
DateTime.local(2017, 10, 30).weekdayShort; //=> Mon
Returns ​

IfValid<string, null, IsValid>

weekNumber ​

Get Signature ​

ts
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 ​
ts
DateTime.local(2017, 5, 25).weekNumber; //=> 21
Returns ​

IfValid<WeekNumbers, number, IsValid>

weeksInLocalWeekYear ​

Get Signature ​

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

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

Examples ​
ts
DateTime.local(2020, 6, { locale: "en-US" }).weeksInLocalWeekYear; //=> 52
ts
DateTime.local(2020, 6, { locale: "de-DE" }).weeksInLocalWeekYear; //=> 53
Returns ​

IfValid<PossibleWeeksInYear, number, IsValid>

weeksInWeekYear ​

Get Signature ​

ts
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 ​
ts
DateTime.local(2004).weeksInWeekYear; //=> 53
ts
DateTime.local(2013).weeksInWeekYear; //=> 52
Returns ​

IfValid<PossibleWeeksInYear, number, IsValid>

weekYear ​

Get Signature ​

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

Get the week year

See ​

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

Example ​
ts
DateTime.local(2014, 12, 31).weekYear; //=> 2015
Returns ​

IfValid<number, number, IsValid>

year ​

Get Signature ​

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

Get the year

Example ​
ts
DateTime.local(2017, 5, 25).year; //=> 2017
Returns ​

IfValid<number, number, IsValid>

zone ​

Get Signature ​

ts
get zone(): Zone<IsValid>;

Get the time zone associated with this DateTime.

Returns ​

Zone<IsValid>

zoneName ​

Get Signature ​

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

Get the name of the time zone.

Returns ​

IfValid<string, null, IsValid>

Methods ​

diff() ​

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

Return the difference between two DateTimes as a Duration.

Parameters ​

ParameterTypeDescription
otherDateTimeDateTimethe DateTime to compare this one to
unit?DurationUnitsthe unit or array of units to include in the duration. Defaults to ['milliseconds'].
opts?DiffOptionsoptions that affect the creation of the Duration

Returns ​

Duration<IsValid>

Example ​

ts
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() ​

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

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

Parameters ​

ParameterTypeDescription
unit?DurationUnitsthe unit(s) to include in the duration. Defaults to ['milliseconds'].
opts?DiffOptionsoptions that affect the creation of the Duration

Returns ​

Duration<true>

endOf() ​

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

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

Parameters ​

ParameterTypeDescription
unitDateTimeUnitThe unit to go to the end of. Can be 'year', 'quarter', 'month', 'week', 'day', 'hour', 'minute', 'second', or 'millisecond'.
opts?_UseLocaleWeekOptionoptions

Returns ​

this

Examples ​

ts
DateTime.local(2014, 3, 3).endOf("month").toISO(); //=> '2014-03-31T23:59:59.999-05:00'
ts
DateTime.local(2014, 3, 3).endOf("year").toISO(); //=> '2014-12-31T23:59:59.999-05:00'
ts
DateTime.local(2014, 3, 3).endOf("week").toISO(); // => '2014-03-09T23:59:59.999-05:00', weeks start on Mondays
ts
DateTime.local(2014, 3, 3, 5, 30).endOf("day").toISO(); //=> '2014-03-03T23:59:59.999-05:00'
ts
DateTime.local(2014, 3, 3, 5, 30).endOf("hour").toISO(); //=> '2014-03-03T05:59:59.999-05:00'

equals() ​

ts
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 ​

ParameterTypeDescription
otherDateTimethe other DateTime

Returns ​

IfValid<boolean, false, IsValid>

get() ​

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

Get the value of unit.

Parameters ​

ParameterTypeDescription
unitkeyof DateTime<boolean>a unit such as 'minute' or 'day'

Returns ​

number

Examples ​

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

getPossibleOffsets() ​

ts
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() ​

ts
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 ​

ParameterTypeDescription
otherDateTimeDateTimethe other DateTime
unitDateTimeUnitthe unit of time to check sameness on
opts?_UseLocaleWeekOption-

Returns ​

IfValid<boolean, false, IsValid>

Example ​

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

minus() ​

ts
minus(duration: DurationLike): this;

See DateTime.plus

Parameters ​

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

Returns ​

this

plus() ​

ts
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 ​

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

Returns ​

this

Examples ​

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

reconfigure() ​

ts
reconfigure(properties: LocaleOptions): this;

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

Parameters ​

ParameterTypeDescription
propertiesLocaleOptionsthe properties to set

Returns ​

this

Example ​

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

resolvedLocaleOptions() ​

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

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

Parameters ​

ParameterTypeDescription
opts?DateTimeFormatOptions | LocaleOptionsthe same options as toLocaleString

Returns ​

ResolvedLocaleOptions

set() ​

ts
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 ​

ParameterType
valuesDateObjectUnits

Returns ​

this

Examples ​

ts
dt.set({ year: 2017 });
ts
dt.set({ hour: 8, minute: 30 });
ts
dt.set({ weekday: 5 });
ts
dt.set({ year: 2005, ordinal: 234 });

setLocale() ​

ts
setLocale(locale: string): this;

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

Parameters ​

ParameterType
localestring

Returns ​

this

Example ​

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

setZone() ​

ts
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 ​

ParameterTypeDescription
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?ZoneOptionsoptions

Returns ​

DateTime<true> | DateTime<false>

startOf() ​

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

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

Parameters ​

ParameterTypeDescription
unitDateTimeUnitThe unit to go to the beginning of. Can be 'year', 'quarter', 'month', 'week', 'day', 'hour', 'minute', 'second', or 'millisecond'.
opts?_UseLocaleWeekOptionoptions

Returns ​

this

Examples ​

ts
DateTime.local(2014, 3, 3).startOf("month").toISODate(); //=> '2014-03-01'
ts
DateTime.local(2014, 3, 3).startOf("year").toISODate(); //=> '2014-01-01'
ts
DateTime.local(2014, 3, 3).startOf("week").toISODate(); //=> '2014-03-03', weeks always start on Mondays
ts
DateTime.local(2014, 3, 3, 5, 30).startOf("day").toISOTime(); //=> '00:00.000-05:00'
ts
DateTime.local(2014, 3, 3, 5, 30).startOf("hour").toISOTime(); //=> '05:00:00.000-05:00'

toBSON() ​

ts
toBSON(): Date;

Returns a BSON-serializable equivalent to this DateTime.

Returns ​

Date

toFormat() ​

ts
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 ​

ParameterTypeDescription
formatstringthe format string - see Tokens
options?LocaleOptionsopts to override the configuration options on this DateTime

Returns ​

IfValid<string, "Invalid DateTime", IsValid>

Examples ​

ts
DateTime.now().toFormat("yyyy LLL dd"); //=> '2017 Apr 22'
ts
DateTime.now().setLocale("fr").toFormat("yyyy LLL dd"); //=> '2017 avr. 22'
ts
DateTime.now().toFormat("yyyy LLL dd", { locale: "fr" }); //=> '2017 avr. 22'
ts
DateTime.now().toFormat("HH 'hours and' mm 'minutes'"); //=> '20 hours and 55 minutes'

toHTTP() ​

ts
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 ​

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

toISO() ​

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

Returns an ISO 8601-compliant string representation of this DateTime

Parameters ​

ParameterType
opts?ToISOTimeOptions

Returns ​

IfValid<string, null, IsValid>

Examples ​

ts
DateTime.utc(1982, 5, 25).toISO(); //=> '1982-05-25T00:00:00.000Z'
ts
DateTime.now().toISO(); //=> '2017-04-22T20:47:05.335-04:00'
ts
DateTime.now().toISO({ includeOffset: false }); //=> '2017-04-22T20:47:05.335'
ts
DateTime.now().toISO({ format: "basic" }); //=> '20170422T204705.335-0400'
ts
DateTime.now().toISO({ precision: "day" }); //=> '2017-04-22Z'
ts
DateTime.now().toISO({ precision: "minute" }); //=> '2017-04-22T20:47Z'

toISODate() ​

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

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

Parameters ​

ParameterType
opts?ToISODateOptions

Returns ​

IfValid<string, null, IsValid>

Examples ​

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

toISOTime() ​

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

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

Parameters ​

ParameterType
opts?ToISOTimeOptions

Returns ​

IfValid<string, null, IsValid>

Examples ​

ts
DateTime.utc().set({ hour: 7, minute: 34 }).toISOTime(); //=> '07:34:19.361Z'
ts
DateTime.utc()
  .set({ hour: 7, minute: 34, seconds: 0, milliseconds: 0 })
  .toISOTime({ suppressSeconds: true }); //=> '07:34Z'
ts
DateTime.utc().set({ hour: 7, minute: 34 }).toISOTime({ format: "basic" }); //=> '073419.361Z'
ts
DateTime.utc().set({ hour: 7, minute: 34 }).toISOTime({ includePrefix: true }); //=> 'T07:34:19.361Z'
ts
DateTime.utc()
  .set({ hour: 7, minute: 34, second: 56 })
  .toISOTime({ precision: "minute" }); //=> '07:34Z'

toISOWeekDate() ​

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

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

Returns ​

IfValid<string, null, IsValid>

Example ​

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

toJSDate() ​

ts
toJSDate(): Date;

Returns a JavaScript Date equivalent to this DateTime.

Returns ​

Date

toJSON() ​

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

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

Returns ​

IfValid<string, null, IsValid>

toLocal() ​

ts
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() ​

ts
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 ​

ParameterType
opts?DateTimeFormatOptions

Returns ​

DateTimeFormatPart[]

See ​

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

Examples ​

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

toLocaleString() ​

ts
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 ​

ParameterTypeDescription
formatOpts?DateTimeFormatOptionsIntl.DateTimeFormat constructor options and configuration options
opts?LocaleOptionsopts 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 ​

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

toMillis() ​

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

Returns the epoch milliseconds of this DateTime.

Returns ​

IfValid<number, number, IsValid>

toObject() ​

ts
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 ​

ParameterTypeDescription
opts?{ includeConfig?: IncludeConfig; }options for generating the object
opts.includeConfig?IncludeConfigInclude configuration attributes in the output

Returns ​

ToObjectOutput<IncludeConfig, IsValid>

Example ​

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

toRelative() ​

ts
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 ​

ParameterType
options?ToRelativeOptions

Returns ​

IfValid<string, null, IsValid>

Examples ​

ts
DateTime.now().plus({ days: 1 }).toRelative(); //=> "in 1 day"
ts
DateTime.now().setLocale("es").toRelative({ days: 1 }); //=> "dentro de 1 día"
ts
DateTime.now().plus({ days: 1 }).toRelative({ locale: "fr" }); //=> "dans 23 heures"
ts
DateTime.now().minus({ days: 2 }).toRelative(); //=> "2 days ago"
ts
DateTime.now().minus({ days: 2 }).toRelative({ unit: "hours" }); //=> "48 hours ago"
ts
DateTime.now().minus({ hours: 36 }).toRelative({ round: false }); //=> "1.5 days ago"

toRelativeCalendar() ​

ts
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 ​

ParameterType
options?ToRelativeCalendarOptions

Returns ​

IfValid<string, null, IsValid>

Examples ​

ts
DateTime.now().plus({ days: 1 }).toRelativeCalendar(); //=> "tomorrow"
ts
DateTime.now().setLocale("es").plus({ days: 1 }).toRelative(); //=> ""mañana"
ts
DateTime.now().plus({ days: 1 }).toRelativeCalendar({ locale: "fr" }); //=> "demain"
ts
DateTime.now().minus({ days: 2 }).toRelativeCalendar(); //=> "2 days ago"

toRFC2822() ​

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

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

Returns ​

IfValid<string, null, IsValid>

Examples ​

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

toSeconds() ​

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

Returns the epoch seconds of this DateTime.

Returns ​

IfValid<number, number, IsValid>

toSQL() ​

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

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

Parameters ​

ParameterType
opts?ToSQLOptions

Returns ​

IfValid<string, null, IsValid>

Examples ​

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

toSQLDate() ​

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

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

Returns ​

IfValid<string, null, IsValid>

Example ​

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

toSQLTime() ​

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

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

Parameters ​

ParameterType
opts?ToSQLOptions

Returns ​

IfValid<string, null, IsValid>

Examples ​

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

toString() ​

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

Returns a string representation of this DateTime appropriate for debugging

Returns ​

IfValid<string, "Invalid DateTime", IsValid>

toUnixInteger() ​

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

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

Returns ​

IfValid<number, number, IsValid>

toUTC() ​

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

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

Equivalent to DateTime.setZone('utc')

Parameters ​

ParameterTypeDescription
offset?numberoptionally, an offset from UTC in minutes. Defaults to 0.
opts?ZoneOptionsoptions to pass to setZone(). Defaults to {}.

Returns ​

this

until() ​

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

Return an Interval spanning between this DateTime and another DateTime

Parameters ​

ParameterTypeDescription
otherDateTimeDateTimethe other end point of the Interval

Returns ​

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

valueOf() ​

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

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

Returns ​

IfValid<number, number, IsValid>

Copyright © 2025-present New Horizon Technology LTD