Class DateTime

A timezone and locale aware DateTime. This class assumes support for:

Intl.DateTimeFormat
Intl.RelativeTimeFormat

Index

Constructors

Methods

advance clone daysInMonth endOf endOfCalendarMonth endOfDay endOfMonth endOfWeek endOfYear format formatDate formatHours formatMonthYear formatMonthYearShort formatTime getDate getDay getFullYear getHours getMilliseconds getMinutes getMonth getSeconds getTime getTimezone getTimeZone getTimezoneOffset getTimeZoneOffset getUTCDate getUTCDay getUTCFullYear getUTCHours getUTCMilliseconds getUTCMinutes getUTCMonth getUTCSeconds getYear isEqual isInvalid isValid relative resetTime rewind set setArgs setDate setFullYear setHours setMilliseconds setMinutes setMonth setSeconds setTime setUTCDate setUTCFullYear setUTCHours setUTCMilliseconds setUTCMinutes setUTCMonth setUTCSeconds setUTCTime setYear setZone startOf startOfCalendarMonth startOfDay startOfMonth startOfWeek startOfYear toDate toISODate toISOString toISOTime toJSON toString toTime valueOf clamp getMeridiem getMonths getWeekdays max min setLocale setOptions setTimeZone

Constructors

constructor

new DateTime(...args: any[]): DateTime
Creates a DateTime from various input. A single argument may be date input or an options object. Two arguments represents input and an options object. If no arguments are passed the DateTime will be the current date.

If the input is a string that specifies a timezone or offset it will be used as is. Otherwise if the timeZone option is specified or a global timezone is set it will be parsed in that timezone. If no timezone can be derived the system offset will be used instead.
Parameters
- ...args: any[]
Returns DateTime
Example
```
new DateTime();
new DateTime('2025-01-01');
new DateTime(1735689600000);
new DateTime({
  locale: 'en-US',
  timeZone: 'America/New_York'
});
new DateTime('Jan 1 2025', {
  locale: 'en-US',
  timeZone: 'America/New_York'
});
```

Properties

date

date: Date

offset

offset: any

options

options: any

utc

utc: any

`Static`DATE_MED

DATE_MED: { day: string; month: string; year: string } = DATE_MED

`Static`DATE_MED_WEEKDAY

DATE_MED_WEEKDAY: { day: string; month: string; weekday: string; year: string } = DATE_MED_WEEKDAY

`Static`DATE_NARROW

DATE_NARROW: { day: string; month: string; year: string } = DATE_NARROW

`Static`DATE_SHORT

DATE_SHORT: { day: string; month: string; year: string } = DATE_SHORT

`Static`DATETIME_MED

DATETIME_MED: {
    day: string;
    hour: string;
    minute: string;
    month: string;
    year: string;
} = DATETIME_MED

`Static`DATETIME_MED_WEEKDAY

DATETIME_MED_WEEKDAY: {
    day: string;
    hour: string;
    minute: string;
    month: string;
    weekday: string;
    year: string;
} = DATETIME_MED_WEEKDAY

`Static`DATETIME_NARROW

DATETIME_NARROW: {
    day: string;
    hour: string;
    minute: string;
    month: string;
    year: string;
} = DATETIME_NARROW

`Static`DATETIME_SHORT

DATETIME_SHORT: {
    day: string;
    hour: string;
    minute: string;
    month: string;
    year: string;
} = DATETIME_SHORT

`Static`MONTH_YEAR

MONTH_YEAR: { month: string; year: string } = MONTH_YEAR

`Static`MONTH_YEAR_SHORT

MONTH_YEAR_SHORT: { month: string; year: string } = MONTH_YEAR_SHORT

`Static`options

options: {} = {}

`Static`TIME_HOUR

TIME_HOUR: { hour: string } = TIME_HOUR

`Static`TIME_MED

TIME_MED: { hour: string; minute: string } = TIME_MED

`Static`TIME_SHORT

TIME_SHORT: { hour: string; minute: string; shortDayPeriod: boolean } = TIME_SHORT

`Static`TIME_SHORT_HOUR

TIME_SHORT_HOUR: { hour: string; shortDayPeriod: boolean } = TIME_SHORT_HOUR

`Static`TIME_WITH_ZONE

TIME_WITH_ZONE: { hour: string; minute: string; timeZoneName: string } = TIME_WITH_ZONE

Methods

advance

advance(by: number | {}, unit?: TimeUnit): any
Advances the DateTime. When the first argument is a number it must be followed by a unit advancing by that many units. If the first argument is an object it will advance the date by multiple units.
Parameters
- by: number | {}
- Optionalunit: TimeUnit
Returns any
Example
```
new DateTime().advance(6, 'months')
new DateTime().advance({
  months: 6,
  days: 15
})
```

clone

clone(): DateTime
Returns a clone of the DateTime.

Returns DateTime

daysInMonth

daysInMonth(): number
Returns the number of days in the month.

Returns number

endOf

endOf(
unit: "day" | "hour" | "minute" | "month" | "second" | "year" | "week",
): any
Advances the DateTime to the end of the specified unit.
Parameters
- unit: "day" | "hour" | "minute" | "month" | "second" | "year" | "week"
Returns any

endOfCalendarMonth

endOfCalendarMonth(): any
Advances the DateTime to the end of the calendar month. This may push the date into the next month.

Returns any

endOfDay

endOfDay(): any
Advances the DateTime to the end of the day.

Returns any

endOfMonth

endOfMonth(): any
Advances the DateTime to the end of the month.

Returns any

endOfWeek

endOfWeek(): any
Advances the DateTime to the end of the week.

Returns any

endOfYear

endOfYear(): any
Advances the DateTime to the end of the year.

Returns any

format

format(format?: any, options: any): any
Formats the DateTime using various formats accessible as static members of the DateTime class.
Parameters
- format: any = DateTime.DATETIME_MED
- options: any
Returns any

formatDate

formatDate(): any
Formats the date component of the DateTime using a standard representation. The local or global locale will be used when specified.

Returns any
Example
```
January 1, 2025
```

formatHours

formatHours(): any
Formats the hours component of the DateTime. The local or global locale will be used when specified.

Returns any
Example
```
9am
```

formatMonthYear

formatMonthYear(): any
Formats the month and year components of the DateTime. The local or global locale will be used when specified.

Returns any
Example
```
January 2025
```

formatMonthYearShort

formatMonthYearShort(): any
Formats the month and year components of the DateTime in a shortened format. The local or global locale will be used when specified.

Returns any
Example
```
Jan 2025
```

formatTime

formatTime(): any
Formats the time component of the DateTime using a standard representation. The local or global locale will be used when specified.

Returns any
Example
```
9:00am
```

getDate

getDate(): number
Gets the date of the DateTime.

Returns number

getDay

getDay(): number
Gets the day of week of the DateTime from 0 to 6.

Returns number

getFullYear

getFullYear(): number
Gets the year of the DateTime.

Returns number

getHours

getHours(): number
Gets the hours of the DateTime.

Returns number

getMilliseconds

getMilliseconds(): number
Gets the milliseconds of the DateTime.

Returns number

getMinutes

getMinutes(): number
Gets the minutes of the DateTime.

Returns number

getMonth

getMonth(): number
Gets the month of the DateTime. Note that months are zero based so January is 0.

Returns number

getSeconds

getSeconds(): number
Gets the seconds of the DateTime.

Returns number

getTime

getTime(): number
Returns the unix timestamp of the DateTime.

Returns number

getTimezone

getTimezone(): string
Alias for getTimeZone.

Returns string

getTimeZone

getTimeZone(): string
Returns the IANA timezone.

Returns string

getTimezoneOffset

getTimezoneOffset(): any
Alias for getTimeZoneOffset.

Returns any

getTimeZoneOffset

getTimeZoneOffset(): number
Gets the timezone offset of the DateTime in minutes. This may be the offset of the local or global timezone if one is set, otherwise will be the system offset.

Returns number

getUTCDate

getUTCDate(): number
Gets the date in UTC.

Returns number

getUTCDay

getUTCDay(): number
Gets the day in UTC.

Returns number

getUTCFullYear

getUTCFullYear(): number
Gets the year in UTC.

Returns number

getUTCHours

getUTCHours(): number
Gets the hours in UTC.

Returns number

getUTCMilliseconds

getUTCMilliseconds(): number
Gets the milliseconds in UTC.

Returns number

getUTCMinutes

getUTCMinutes(): number
Gets the minutes in UTC.

Returns number

getUTCMonth

getUTCMonth(): number
Gets the month in UTC.

Returns number

getUTCSeconds

getUTCSeconds(): number
Gets the seconds in UTC.

Returns number

getYear

getYear(): number
Alias for getFullYear.

Returns number

isEqual

isEqual(arg: DateLike): boolean
Returns true if the DateTime is equivalent to the passed value..
Parameters
- arg: DateLike
Returns boolean

isInvalid

isInvalid(): boolean
Returns true if the DateTime is invalid.

Returns boolean

isValid

isValid(): boolean
Returns true if the DateTime is valid.

Returns boolean

relative

relative(
    options?: {
        max?: DateLike;
        min?: DateLike;
        now?: DateLike;
        numeric?: string;
    },
): string
Formats the DateTime in a relative format. Allowed options are:
- now - Offset to format relative to. Defaults to the current time.
- min - When set will return undefined if the DateTime is before this date.
- max - When set will return undefined if the DateTime is after this date.
- numeric - Passed to Intl.RelativeTimeFormat. Defaults to auto but may also be always.
Parameters
- Optionaloptions: { max?: DateLike; min?: DateLike; now?: DateLike; numeric?: string }
Returns string

resetTime

resetTime(): DateTime
Resets the time to 00:00:00.000. Equivalent to startOfDay.

Returns DateTime

rewind

rewind(by: number | {}, unit?: TimeUnit): any
Rewinds the DateTime. When the first argument is a number it must be followed by a unit rewinding by that many units. If the first argument is an object it will rewind the date by multiple units.
Parameters
- by: number | {}
- Optionalunit: TimeUnit
Returns any
Example
```
new DateTime().rewind(6, 'months')
new DateTime().rewind({
  months: 6,
  days: 15
})
```

set

set(
    components: {
        day?: number;
        hour?: number;
        hours?: number;
        millisecond?: number;
        milliseconds?: number;
        minute?: number;
        minutes?: number;
        month?: number;
        second?: number;
        seconds?: number;
        year?: number;
    },
): any
Sets components of the DateTime by name.
Parameters
- components: {
      day?: number;
      hour?: number;
      hours?: number;
      millisecond?: number;
      milliseconds?: number;
      minute?: number;
      minutes?: number;
      month?: number;
      second?: number;
      seconds?: number;
      year?: number;
  }
  - Optionalday?: number
    The day of the month to set.
  - Optionalhour?: number
    The hours to set.
  - Optionalhours?: number
    The hours to set.
  - Optionalmillisecond?: number
    The milliseconds to set.
  - Optionalmilliseconds?: number
    The milliseconds to set.
  - Optionalminute?: number
    The minutes to set.
  - Optionalminutes?: number
    The minutes to set.
  - Optionalmonth?: number
    The month to set.
  - Optionalsecond?: number
    The seconds to set.
  - Optionalseconds?: number
    The seconds to set.
  - Optionalyear?: number
    The year to set.
Returns any

setArgs

setArgs(...args: number[]): DateTime
Sets the arguments for the UTC time.
Parameters
- ...args: number[]
  A list of arguments representing the date components.
Returns DateTime

setDate

setDate(date: any): DateTime
Sets the date of the DateTime.
Parameters
- date: any
Returns DateTime

setFullYear

setFullYear(year: any): DateTime
Sets the year of the DateTime.
Parameters
- year: any
Returns DateTime

setHours

setHours(hours: any): DateTime
Sets the hours of the DateTime.
Parameters
- hours: any
Returns DateTime

setMilliseconds

setMilliseconds(milliseconds: any): DateTime
Sets the milliseconds of the DateTime.
Parameters
- milliseconds: any
Returns DateTime

setMinutes

setMinutes(minutes: any): DateTime
Sets the minutes of the DateTime.
Parameters
- minutes: any
Returns DateTime

setMonth

setMonth(month: any): DateTime
Sets the month of the DateTime. Note that months are zero based so January is 0.
Parameters
- month: any
Returns DateTime

setSeconds

setSeconds(seconds: any): DateTime
Sets the seconds of the DateTime.
Parameters
- seconds: any
Returns DateTime

setTime

setTime(time: number): DateTime
Sets the unix timestamp of the DateTime.
Parameters
- time: number
Returns DateTime

setUTCDate

setUTCDate(utcDate: any): DateTime
Sets date of the DateTime in UTC.
Parameters
- utcDate: any
Returns DateTime

setUTCFullYear

setUTCFullYear(year: any): DateTime
Sets full year of the DateTime in UTC.
Parameters
- year: any
Returns DateTime

setUTCHours

setUTCHours(hours: any): DateTime
Sets hours of the DateTime in UTC.
Parameters
- hours: any
Returns DateTime

setUTCMilliseconds

setUTCMilliseconds(milliseconds: any): DateTime
Sets milliseconds of the DateTime in UTC.
Parameters
- milliseconds: any
Returns DateTime

setUTCMinutes

setUTCMinutes(minutes: any): DateTime
Sets minutes of the DateTime in UTC.
Parameters
- minutes: any
Returns DateTime

setUTCMonth

setUTCMonth(month: any): DateTime
Sets month of the DateTime in UTC.
Parameters
- month: any
Returns DateTime

setUTCSeconds

setUTCSeconds(seconds: any): DateTime
Sets seconds of the DateTime in UTC.
Parameters
- seconds: any
Returns DateTime

setUTCTime

setUTCTime(time: any): DateTime
Parameters
- time: any
Returns DateTime

setYear

setYear(year: any): DateTime
Alias for setFullYear.
Parameters
- year: any
Returns DateTime

setZone

setZone(timeZone: string): DateTime
Sets the internal timezone of the DateTime.
Parameters
- timeZone: string
Returns DateTime

startOf

startOf(
unit: "day" | "hour" | "minute" | "month" | "second" | "year" | "week",
): any
Rewinds the DateTime to the start of the specified unit.
Parameters
- unit: "day" | "hour" | "minute" | "month" | "second" | "year" | "week"
Returns any

startOfCalendarMonth

startOfCalendarMonth(): any
Rewinds the DateTime to the start of the calendar month. This may push the date into the previous month.

Returns any

startOfDay

startOfDay(): any
Rewinds the DateTime to the start of the day.

Returns any

startOfMonth

startOfMonth(): any
Rewinds the DateTime to the start of the month.

Returns any

startOfWeek

startOfWeek(): any
Rewinds the DateTime to the start of the week.

Returns any

startOfYear

startOfYear(): any
Rewinds the DateTime to the start of the year.

Returns any

toDate

toDate(): string
Returns the date component of the DateTime. The result will be in the specified timezone, either that passed or set globally.

Returns string
Example
```
2025-01-01
```

toISODate

toISODate(): string
Returns the ISO-8601 representation of the date component of the DateTime in UTC.

Returns string
Example
```
2025-01-01
```

toISOString

toISOString(): string
Returns the ISO-8601 representation of the DateTime.

Returns string

toISOTime

toISOTime(): string
Returns the ISO-8601 representation of the time component of the DateTime in UTC.

Returns string
Example
```
12:30:00.000
```

toJSON

toJSON(): string
Equivalent to toISOString.

Returns string

toString

toString(): any
Returns a default formatted string that represents the DateTime.

Returns any

toTime

toTime(): string
Returns the time component of the DateTime. The result will be in the specified timezone, either that passed or set globally.

Returns string
Example
```
12:30:00.000
```

valueOf

valueOf(): number
Returns the numeric value of the DateTime instance.

Returns number

`Static`clamp

clamp(arg: DateLike, min: DateLike, max: DateLike): DateTime
Clamps the value passed to the minimum and maximum.
Parameters
- arg: DateLike
- min: DateLike
- max: DateLike
Returns DateTime
DateTime

`Static`getMeridiem

getMeridiem(
options?: { locale?: string; lower?: number; style?: "long" | "short" },
): string[]
Gets the meridiem tokens (am/pm) a given locale. Options are:
- locale - If not passed will use the global locale or fall back to the system locale.
- lower - Return the tokens in lower case.
- style - When "short" will return a/p for am/pm tokens only.
Parameters
- options: { locale?: string; lower?: number; style?: "long" | "short" } = {}
Returns string[]

`Static`getMonths

getMonths(
options?: { locale?: string; style?: "long" | "short" | "narrow" },
): string[]
Gets the months of the year for a given locale. Options are:
- locale - If not passed will use the global locale or fall back to the system locale.
- style - Will be passed as month to Intl.DateTimeFormat. Default long.
Parameters
- options: { locale?: string; style?: "long" | "short" | "narrow" } = {}
Returns string[]

`Static`getWeekdays

getWeekdays(
    options?: {
        locale?: string;
        start?: number;
        style?: "long" | "short" | "narrow";
    },
): string[]
Gets the weekday names for a given locale. Options are:
- locale - If not passed will use the global locale or fall back to the system locale.
- start - An explicit start day of the week, 0 for sunday, 6 for Saturday. Will fall back to the locale defined first day.
- style - Will be passed as weekday to Intl.DateTimeFormat. Default long.
Parameters
- options: { locale?: string; start?: number; style?: "long" | "short" | "narrow" } = {}
Returns string[]

`Static`max

max(...args: DateLike[]): DateTime
Returns the maximum value passed in as a DateTime.
Parameters
- ...args: DateLike[]
Returns DateTime
DateTime

`Static`min

min(...args: DateLike[]): DateTime
Returns the minimum value passed in as a DateTime.
Parameters
- ...args: DateLike[]
Returns DateTime
DateTime

`Static`setLocale

setLocale(locale: string): void
Sets the global locale.
Parameters
- locale: string
Returns void

`Static`setOptions

setOptions(options: any): void
Sets global options.
Parameters
- options: any
Returns void

`Static`setTimeZone

setTimeZone(timeZone: string): void
Sets the global timezone.
Parameters
- timeZone: string
Returns void

Class DateTime

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns DateTime

Example

Properties

date

offset

options

utc

StaticDATE_MED

StaticDATE_MED_WEEKDAY

StaticDATE_NARROW

StaticDATE_SHORT

StaticDATETIME_MED

StaticDATETIME_MED_WEEKDAY

StaticDATETIME_NARROW

StaticDATETIME_SHORT

StaticMONTH_YEAR

StaticMONTH_YEAR_SHORT

Staticoptions

StaticTIME_HOUR

StaticTIME_MED

StaticTIME_SHORT

StaticTIME_SHORT_HOUR

StaticTIME_WITH_ZONE

Methods

advance

Parameters

Returns any

Example

clone

Returns DateTime

daysInMonth

Returns number

endOf

Parameters

Returns any

endOfCalendarMonth

Returns any

endOfDay

Returns any

endOfMonth

Returns any

endOfWeek

Returns any

endOfYear

Returns any

format

Parameters

Returns any

formatDate

Returns any

Example

formatHours

Returns any

Example

formatMonthYear

Returns any

Example

formatMonthYearShort

Returns any

Example

formatTime

Returns any

Example

getDate

Returns number

getDay

Returns number

getFullYear

Returns number

getHours

Returns number

getMilliseconds

`Static`DATE_MED

`Static`DATE_MED_WEEKDAY

`Static`DATE_NARROW

`Static`DATE_SHORT

`Static`DATETIME_MED

`Static`DATETIME_MED_WEEKDAY

`Static`DATETIME_NARROW

`Static`DATETIME_SHORT

`Static`MONTH_YEAR

`Static`MONTH_YEAR_SHORT

`Static`options

`Static`TIME_HOUR

`Static`TIME_MED

`Static`TIME_SHORT

`Static`TIME_SHORT_HOUR

`Static`TIME_WITH_ZONE

`Optional`day?: number

`Optional`hour?: number

`Optional`hours?: number

`Optional`millisecond?: number

`Optional`milliseconds?: number

`Optional`minute?: number

`Optional`minutes?: number

`Optional`month?: number

`Optional`second?: number

`Optional`seconds?: number

`Optional`year?: number