Class DateTime

DateTime class which is time zone-aware and which can be mocked for testing purposes.

Constructors

constructor

new DateTime(): DateTime
Constructor. Creates current time in local timezone.

Returns DateTime
Throws
nothing
- Defined in datetime.ts:223
new DateTime(isoString, timeZone?): DateTime
Constructor. Parses ISO timestamp string. Non-existing local times are normalized by rounding up to the next DST offset.
Parameters
- isoString: string
  String in ISO 8601 format. Instead of ISO time zone, it may include a space and then and IANA time zone. e.g. "2007-04-05T12:30:40.500" (no time zone, naive date) e.g. "2007-04-05T12:30:40.500+01:00" (UTC offset without daylight saving time) or "2007-04-05T12:30:40.500Z" (UTC) or "2007-04-05T12:30:40.500 Europe/Amsterdam" (IANA time zone, with daylight saving time if applicable)
- Optional timeZone: null | TimeZone
  if given, the date in the string is assumed to be in this time zone. Note that it is NOT CONVERTED to the time zone. Useful for strings without a time zone
Returns DateTime
Throws
timezonecomplete.Argument.S if the given string is invalid

Throws
timezonecomplete.Argument.TimeZone if the given time zone is invalid
- Defined in datetime.ts:240
new DateTime(dateString, formatString, timeZone?): DateTime
Constructor. Parses string in given LDML format. NOTE: does not handle eras/quarters/weeks/weekdays. Non-existing local times are normalized by rounding up to the next DST offset.
Parameters
- dateString: string
  Date+Time string.
- formatString: string
  The LDML format that the string is assumed to be in
- Optional timeZone: null | TimeZone
  if given, the date in the string is assumed to be in this time zone. Note that it is NOT CONVERTED to the time zone. Useful for strings without a time zone
Returns DateTime
Throws
timezonecomplete.ParseError if the given dateTimeString is wrong or not according to the pattern

Throws
timezonecomplete.Argument.FormatString if the given format string is invalid

Throws
timezonecomplete.Argument.Timezone if the given time zone is invalid
- Defined in datetime.ts:255
new DateTime(date, getFuncs, timeZone?): DateTime
Constructor. You provide a date, then you say whether to take the date.getYear()/getXxx methods or the date.getUTCYear()/date.getUTCXxx methods, and then you state which time zone that date is in. Non-existing local times are normalized by rounding up to the next DST offset. Note that the Date class has bugs and inconsistencies when constructing them with times around DST changes.
Parameters
- date: Date
  A date object.
- getFuncs: DateFunctions
- Optional timeZone: null | TimeZone
  The time zone that the given date is assumed to be in (may be undefined or null for unaware dates)
Returns DateTime
Throws
timezonecomplete.Argument.GetFuncs if the getFuncs argument is invalid

Throws
timezonecomplete.Argument.TimeZone if the time zone argument is invalid
- Defined in datetime.ts:271
new DateTime(tm, timeZone?): DateTime
Get a date from a TimeStruct
Parameters
- tm: TimeStruct
- Optional timeZone: null | TimeZone
Returns DateTime
Throws
timezonecomplete.Argument.TimeZone if the given time zone argument is invalid
- Defined in datetime.ts:276
new DateTime(year, month, day, hour?, minute?, second?, millisecond?, timeZone?): DateTime
Constructor. Note that unlike JavaScript dates we require fields to be in normal ranges. Use the add(duration) or sub(duration) for arithmetic.
Parameters
- year: number
  The full year (e.g. 2014)
- month: number
  The month [1-12] (note this deviates from JavaScript Date)
- day: number
  The day of the month [1-31]
- Optional hour: number
  The hour of the day [0-24)
- Optional minute: number
  The minute of the hour [0-59]
- Optional second: number
  The second of the minute [0-59]
- Optional millisecond: number
  The millisecond of the second [0-999]
- Optional timeZone: null | TimeZone
  The time zone, or null/undefined (for unaware dates)
Returns DateTime
Throws
timezonecomplete.Argument.Year if year invalid

Throws
timezonecomplete.Argument.Month if month invalid

Throws
timezonecomplete.Argument.Day if day invalid

Throws
timezonecomplete.Argument.Hour if hour invalid

Throws
timezonecomplete.Argument.Minute if minute invalid

Throws
timezonecomplete.Argument.Second if second invalid

Throws
timezonecomplete.Argument.Milli if milliseconds invalid
- Defined in datetime.ts:296
new DateTime(unixTimestamp, timeZone?): DateTime
Constructor
Parameters
- unixTimestamp: number
  milliseconds since 1970-01-01T00:00:00.000
- Optional timeZone: null | TimeZone
  the time zone that the timestamp is assumed to be in (usually UTC).
Returns DateTime
Throws
timezonecomplete.Argument.TimeZone if the given time zone is invalid

Throws
timezonecomplete.Argument.UnixMillis if the given unix timestamp is not finite
- Defined in datetime.ts:308

Properties

kind

kind: string = "DateTime"

Allow not using instanceof

`Static` timeSource

timeSource: TimeSource = ...

Actual time source in use. Setting this property allows to fake time in tests. DateTime.nowLocal() and DateTime.nowUtc() use this property for obtaining the current time.

Methods

add

add(duration): DateTime
Add a time duration relative to UTC. Returns a new DateTime
Parameters
- duration: Duration
Returns DateTime
this + duration

Throws
timezonecomplete.NotFound.Zone if the UTC time zone doesn't exist in the time zone database
- Defined in datetime.ts:888
add(amount, unit): DateTime
Add an amount of time relative to UTC, as regularly as possible. Returns a new DateTime

Adding e.g. 1 hour will increment the utcHour() field, adding 1 month increments the utcMonth() field. Adding an amount of units leaves lower units intact. E.g. adding a month will leave the day() field untouched if possible.

Note adding Months or Years will clamp the date to the end-of-month if the start date was at the end of a month, i.e. contrary to JavaScript Date#setUTCMonth() it will not overflow into the next month

In case of DST changes, the utc time fields are still untouched but local time fields may shift.
Parameters
- amount: number
- unit: TimeUnit
Returns DateTime
Throws
Argument.Amount if amount is not a finite number or if you're trying to add a non-integer amount of years or months

Throws
Argument.Unit for invalid time unit

Throws
timezonecomplete.NotFound.Zone if the UTC time zone doesn't exist in the time zone database
- Defined in datetime.ts:907

addLocal

addLocal(duration): DateTime
Add an amount of time to the zone time, as regularly as possible. Returns a new DateTime

Adding e.g. 1 hour will increment the hour() field of the zone date by one. In case of DST changes, the time fields may additionally increase by the DST offset, if a non-existing local time would be reached otherwise.

Adding a unit of time will leave lower-unit fields intact, unless the result would be a non-existing time. Then an extra DST offset is added.

Note adding Months or Years will clamp the date to the end-of-month if the start date was at the end of a month, i.e. contrary to JavaScript Date#setUTCMonth() it will not overflow into the next month
Parameters
- duration: Duration
Returns DateTime
Throws
nothing
- Defined in datetime.ts:942
addLocal(amount, unit): DateTime
Add an amount of time to the zone time, as regularly as possible. Returns a new DateTime

Adding e.g. 1 hour will increment the hour() field of the zone date by one. In case of DST changes, the time fields may additionally increase by the DST offset, if a non-existing local time would be reached otherwise.

Adding a unit of time will leave lower-unit fields intact, unless the result would be a non-existing time. Then an extra DST offset is added.

Note adding Months or Years will clamp the date to the end-of-month if the start date was at the end of a month, i.e. contrary to JavaScript Date#setUTCMonth() it will not overflow into the next month
Parameters
- amount: number
- unit: TimeUnit
Returns DateTime
Throws
Argument.Amount if amount is not a finite number or if you're trying to add a non-integer amount of years or months

Throws
Argument.Unit for invalid time unit
- Defined in datetime.ts:962

clone

clone(): DateTime
Returns DateTime
a copy of this object

Throws
nothing
- Defined in datetime.ts:475

convert

convert(zone?): DateTime
Convert this date to the given time zone (in-place).
Parameters
- Optional zone: null | TimeZone
Returns DateTime
this (for chaining)

Throws
timezonecomplete.UnawareToAwareConversion if you try to convert a datetime without a zone to a datetime with a zone
- Defined in datetime.ts:781

day

day(): number
Returns number
The day of the month 1-31

Throws
nothing
- Defined in datetime.ts:548

dayOfYear

dayOfYear(): number
Returns the day number within the year: Jan 1st has number 0, Jan 2nd has number 1 etc.

Returns number
the day-of-year [0-366]

Throws
nothing
- Defined in datetime.ts:600

diff

diff(other): Duration
Time difference between two DateTimes
Parameters
- other: DateTime
Returns Duration
this - other

Throws
nothing
- Defined in datetime.ts:1101

equals

equals(other): boolean
Parameters
- other: DateTime
Returns boolean
True iff this and other represent the same moment in time in UTC

Throws
nothing
- Defined in datetime.ts:1152

format

format(formatString, locale?): string
Return a string representation of the DateTime according to the specified format. See LDML.md for supported formats.
Parameters
- formatString: string
  The format specification (e.g. "dd/MM/yyyy HH:mm:ss")
- Optional locale: PartialLocale
  Optional, non-english format month names etc.
Returns string
The string representation of this DateTime

Throws
timezonecomplete.Argument.FormatString for invalid format pattern
- Defined in datetime.ts:1243

greaterEqual

greaterEqual(other): boolean
Parameters
- other: DateTime
Returns boolean
True iff this >= other

Throws
nothing
- Defined in datetime.ts:1179

greaterThan

greaterThan(other): boolean
Parameters
- other: DateTime
Returns boolean
True iff this > other

Throws
nothing
- Defined in datetime.ts:1171

hour

hour(): number
Returns number
The hour 0-23

Throws
nothing
- Defined in datetime.ts:556

identical

identical(other): boolean
Parameters
- other: DateTime
Returns boolean
True iff this and other represent the same time and the same zone

Throws
nothing
- Defined in datetime.ts:1160

lessEqual

lessEqual(other): boolean
Parameters
- other: DateTime
Returns boolean
True iff (this <= other)

Throws
nothing
- Defined in datetime.ts:1144

lessThan

lessThan(other): boolean
Parameters
- other: DateTime
Returns boolean
True iff (this < other)

Throws
nothing
- Defined in datetime.ts:1136

max

max(other): DateTime
Parameters
- other: DateTime
Returns DateTime
The maximum of this and other

Throws
nothing
- Defined in datetime.ts:1198

millisecond

millisecond(): number
Returns number
the milliseconds 0-999

Throws
nothing
- Defined in datetime.ts:580

min

min(other): DateTime
Parameters
- other: DateTime
Returns DateTime
The minimum of this and other

Throws
nothing
- Defined in datetime.ts:1187

minute

minute(): number
Returns number
the minutes 0-59

Throws
nothing
- Defined in datetime.ts:564

month

month(): number
Returns number
The month 1-12 (note this deviates from JavaScript Date)

Throws
nothing
- Defined in datetime.ts:540

offset

offset(): number
Returns number
the offset including DST w.r.t. UTC in minutes. Returns 0 for unaware dates and for UTC dates.

Throws
nothing
- Defined in datetime.ts:505

offsetDuration

offsetDuration(): Duration
Returns Duration
the offset including DST w.r.t. UTC as a Duration.

Throws
nothing
- Defined in datetime.ts:513

second

second(): number
Returns number
the seconds 0-59

Throws
nothing
- Defined in datetime.ts:572

secondOfDay

secondOfDay(): number
Returns the number of seconds that have passed on the current day Does not consider leap seconds

Returns number
seconds [0-86399]

Throws
nothing
- Defined in datetime.ts:635

standardOffsetDuration

standardOffsetDuration(): Duration
Returns Duration
the standard offset WITHOUT DST w.r.t. UTC as a Duration.

Throws
nothing
- Defined in datetime.ts:521

startOfDay

startOfDay(): DateTime
Chops off the time part, yields the same date at 00:00:00.000

Returns DateTime
a new DateTime

Throws
nothing
- Defined in datetime.ts:1110

startOfMonth

startOfMonth(): DateTime
Returns the first day of the month at 00:00:00

Returns DateTime
a new DateTime

Throws
nothing
- Defined in datetime.ts:1119

startOfYear

startOfYear(): DateTime
Returns the first day of the year at 00:00:00

Returns DateTime
a new DateTime

Throws
nothing
- Defined in datetime.ts:1128

sub

sub(duration): DateTime
Same as add(-1*duration); Returns a new DateTime
Parameters
- duration: Duration
Returns DateTime
Throws
timezonecomplete.NotFound.Zone if the UTC time zone doesn't exist in the time zone database
- Defined in datetime.ts:1057
sub(amount, unit): DateTime
Same as add(-1*amount, unit); Returns a new DateTime
Parameters
- amount: number
- unit: TimeUnit
Returns DateTime
Throws
Argument.Amount if amount is not a finite number or if you're trying to add a non-integer amount of years or months

Throws
Argument.Unit for invalid time unit

Throws
timezonecomplete.NotFound.Zone if the UTC time zone doesn't exist in the time zone database
- Defined in datetime.ts:1064

subLocal

subLocal(duration): DateTime
Same as addLocal(-1*amount, unit); Returns a new DateTime
Parameters
- duration: Duration
Returns DateTime
Throws
nothing
- Defined in datetime.ts:1079
subLocal(amount, unit): DateTime
Same as addLocal(-1*amount, unit); Returns a new DateTime
Parameters
- amount: number
- unit: TimeUnit
Returns DateTime
Throws
Argument.Amount if amount is not a finite number or if you're trying to add a non-integer amount of years or months

Throws
Argument.Unit for invalid time unit
- Defined in datetime.ts:1087

toDate

toDate(): Date
Convert to JavaScript date with the zone time in the getX() methods. Unless the timezone is local, the Date.getUTCX() methods will NOT be correct. This is because Date calculates getUTCX() from getX() applying local time zone.

Returns Date
Throws
nothing
- Defined in datetime.ts:835

toExcel

toExcel(timeZone?): number
Create an Excel timestamp for this datetime converted to the given zone. Does not work for dates < 1900
Parameters
- Optional timeZone: null | TimeZone
  Optional. Zone to convert to, default the zone the datetime is already in.
Returns number
an Excel date/time number i.e. days since 1-1-1900 where 1900 is incorrectly seen as leap year

Throws
timezonecomplete.UnawareToAwareConversion if you try to convert a naive datetime to an aware one.
- Defined in datetime.ts:849

toIsoString

toIsoString(): string
Proper ISO 8601 format string with any IANA zone converted to ISO offset E.g. "2014-01-01T23:15:33+01:00" for Europe/Amsterdam Unaware dates have no zone information at the end.

Returns string
Throws
nothing
- Defined in datetime.ts:1211

toString

toString(): string
Modified ISO 8601 format string with IANA name if applicable. E.g. "2014-01-01T23:15:33.000 Europe/Amsterdam"

Returns string
Throws
nothing
- Defined in datetime.ts:1274

toUtcExcel

toUtcExcel(): number
Create an Excel timestamp for this datetime converted to UTC Does not work for dates < 1900

Returns number
an Excel date/time number i.e. days since 1-1-1900 where 1900 is incorrectly seen as leap year

Throws
nothing
- Defined in datetime.ts:865

toUtcIsoString

toUtcIsoString(): string
Convert to UTC and then return ISO string ending in 'Z'. This is equivalent to Date#toISOString() e.g. "2014-01-01T23:15:33 Europe/Amsterdam" becomes "2014-01-01T22:15:33Z". Unaware dates are assumed to be in UTC

Returns string
Throws
timezonecomplete.NotFound.Zone if the UTC time zone doesn't exist in the time zone database
- Defined in datetime.ts:1226

toUtcString

toUtcString(): string
Modified ISO 8601 format string in UTC without time zone info

Returns string
Throws
nothing
- Defined in datetime.ts:1299

toZone

toZone(zone?): DateTime
Returns this date converted to the given time zone. Unaware dates can only be converted to unaware dates (clone) Converting an unaware date to an aware date throws an exception. Use the constructor if you really need to do that.
Parameters
- Optional zone: null | TimeZone
  The new time zone. This may be null or undefined to create unaware date.
Returns DateTime
The converted date

Throws
timezonecomplete.UnawareToAwareConversion if you try to convert a naive datetime to an aware one.
- Defined in datetime.ts:817

unixUtcMillis

unixUtcMillis(): number
Returns number
Milliseconds since 1970-01-01T00:00:00.000Z

Throws
nothing
- Defined in datetime.ts:643

utcDay

utcDay(): number
Returns number
The UTC day of the month 1-31

Throws
nothing
- Defined in datetime.ts:667

utcDayOfYear

utcDayOfYear(): number
Returns the UTC day number within the year: Jan 1st has number 0, Jan 2nd has number 1 etc.

Returns number
the day-of-year [0-366]

Throws
nothing
- Defined in datetime.ts:702

utcHour

utcHour(): number
Returns number
The UTC hour 0-23

Throws
nothing
- Defined in datetime.ts:675

utcMillisecond

utcMillisecond(): number
Returns number
The UTC milliseconds 0-999

Throws
nothing
- Defined in datetime.ts:710

utcMinute

utcMinute(): number
Returns number
The UTC minutes 0-59

Throws
nothing
- Defined in datetime.ts:683

utcMonth

utcMonth(): number
Returns number
The UTC month 1-12 (note this deviates from JavaScript Date)

Throws
nothing
- Defined in datetime.ts:659

utcSecond

utcSecond(): number
Returns number
The UTC seconds 0-59

Throws
nothing
- Defined in datetime.ts:691

utcSecondOfDay

utcSecondOfDay(): number
Returns the number of seconds that have passed on the current day Does not consider leap seconds

Returns number
seconds [0-86399]

Throws
nothing
- Defined in datetime.ts:754

utcWeekDay

utcWeekDay(): WeekDay
Returns WeekDay
the UTC day-of-week (the enum values correspond to JavaScript week day numbers)

Throws
nothing
- Defined in datetime.ts:719

utcWeekNumber

utcWeekNumber(): number
The ISO 8601 UTC week number. Week 1 is the week that has January 4th in it, and it starts on Monday. See https://en.wikipedia.org/wiki/ISO_week_date

Returns number
Week number [1-53]

Throws
nothing
- Defined in datetime.ts:731

utcWeekOfMonth

utcWeekOfMonth(): number
The week of this month. There is no official standard for this, but we assume the same rules for the weekNumber (i.e. week 1 is the week that has the 4th day of the month in it)

Returns number
Week number [1-5]

Throws
nothing
- Defined in datetime.ts:743

utcYear

utcYear(): number
Returns number
The full year e.g. 2014

Throws
nothing
- Defined in datetime.ts:651

valueOf

valueOf(): number
The valueOf() method returns the primitive value of the specified object.

Returns number
Throws
nothing
- Defined in datetime.ts:1291

weekDay

weekDay(): WeekDay
Returns WeekDay
the day-of-week (the enum values correspond to JavaScript week day numbers)

Throws
nothing
- Defined in datetime.ts:589

weekNumber

weekNumber(): number
The ISO 8601 week number. Week 1 is the week that has January 4th in it, and it starts on Monday. See https://en.wikipedia.org/wiki/ISO_week_date

Returns number
Week number [1-53]

Throws
nothing
- Defined in datetime.ts:612

weekOfMonth

weekOfMonth(): number
The week of this month. There is no official standard for this, but we assume the same rules for the weekNumber (i.e. week 1 is the week that has the 4th day of the month in it)

Returns number
Week number [1-5]

Throws
nothing
- Defined in datetime.ts:624

withZone

withZone(zone?): DateTime
Returns a new DateTime which is the date+time reinterpreted as in the new zone. So e.g. 08:00 America/Chicago can be set to 08:00 Europe/Brussels. No conversion is done, the value is just assumed to be in a different zone. Works for naive and aware dates. The new zone may be null.
Parameters
- Optional zone: null | TimeZone
  The new time zone
Returns DateTime
A new DateTime with the original timestamp and the new zone.

Throws
nothing
- Defined in datetime.ts:768

year

year(): number
Returns number
The full year e.g. 2014

Throws
nothing
- Defined in datetime.ts:532

zone

zone(): undefined | TimeZone
Returns undefined | TimeZone
The time zone that the date is in. May be undefined for unaware dates.

Throws
nothing
- Defined in datetime.ts:483

zoneAbbreviation

zoneAbbreviation(dstDependent?): string
Zone name abbreviation at this time
Parameters
- dstDependent: boolean = true
  (default true) set to false for a DST-agnostic abbreviation
Returns string
The abbreviation

Throws
nothing
- Defined in datetime.ts:493

`Static` exists

exists(year, month?, day?, hour?, minute?, second?, millisecond?, zone?, allowPre1970?): boolean
Check whether a given date exists in the given time zone. E.g. 2015-02-29 returns false (not a leap year) and 2015-03-29T02:30:00 returns false (daylight saving time missing hour) and 2015-04-31 returns false (April has 30 days). By default, pre-1970 dates also return false since the time zone database does not contain accurate info before that. You can change that with the allowPre1970 flag.
Parameters
- year: number
- month: number = 1
- day: number = 1
- hour: number = 0
- minute: number = 0
- second: number = 0
- millisecond: number = 0
- Optional zone: null | TimeZone
- allowPre1970: boolean = false
  (optional, default false): return true for pre-1970 dates
Returns boolean
Throws
nothing
- Defined in datetime.ts:196

`Static` fromExcel

fromExcel(n, timeZone?): DateTime
Create a DateTime from a Lotus 123 / Microsoft Excel date-time value i.e. a double representing days since 1-1-1900 where 1900 is incorrectly seen as leap year Does not work for dates < 1900
Parameters
- n: number
  excel date/time number
- Optional timeZone: null | TimeZone
  Time zone to assume that the excel value is in
Returns DateTime
a DateTime

Throws
timezonecomplete.Argument.N if n is not a finite number

Throws
timezonecomplete.Argument.TimeZone if the given time zone is invalid
- Defined in datetime.ts:179

`Static` now

now(timeZone?): DateTime
Current date+time in the given time zone
Parameters
- timeZone: undefined | null | TimeZone = ...
  The desired time zone (optional, defaults to UTC).
Returns DateTime
Throws
timezonecomplete.NotFound.Zone if the UTC time zone doesn't exist in the time zone database
- Defined in datetime.ts:165

`Static` nowLocal

nowLocal(): DateTime
Current date+time in local time

Returns DateTime
Throws
nothing
- Defined in datetime.ts:147

`Static` nowUtc

nowUtc(): DateTime
Current date+time in UTC time

Returns DateTime
Throws
timezonecomplete.NotFound.Zone if the UTC time zone doesn't exist in the time zone database
- Defined in datetime.ts:156

`Static` parse

parse(s, format, zone?, locale?, allowTrailing?): DateTime
Parse a date in a given format
Parameters
- s: string
  the string to parse
- format: string
  the format the string is in. See LDML.md for supported formats.
- Optional zone: TimeZone
  Optional, the zone to add (if no zone is given in the string)
- Optional locale: PartialLocale
  Optional, different settings for constants like 'AM' etc
- Optional allowTrailing: boolean
  Allow trailing characters in the source string
Returns DateTime
Throws
timezonecomplete.ParseError if the given dateTimeString is wrong or not according to the pattern

Throws
timezonecomplete.Argument.FormatString if the given format string is invalid
- Defined in datetime.ts:1257

Class DateTime

Index

Constructors

Properties

Methods

Constructors

constructor

Returns DateTime

Throws

Parameters

Returns DateTime

Throws

Throws

Parameters

Returns DateTime

Throws

Throws

Throws

Parameters

Returns DateTime

Throws

Throws

Parameters

Returns DateTime

Throws

Parameters

Returns DateTime

Throws

Throws

Throws

Throws

Throws

Throws

Throws

Parameters

Returns DateTime

Throws

Throws

Properties

kind

Static timeSource

Methods

add

Parameters

Returns DateTime

Throws

Parameters

Returns DateTime

Throws

Throws

Throws

addLocal

Parameters

Returns DateTime

Throws

Parameters

Returns DateTime

Throws

Throws

clone

Returns DateTime

Throws

convert

Parameters

Returns DateTime

Throws

day

Returns number

Throws

dayOfYear

Returns number

Throws

diff

Parameters

Returns Duration

Throws

equals

Parameters

Returns boolean

Throws

`Static` timeSource