Skip to main content

An Iso.DateTime represents a calendar date and wall-clock time, without any time zone.

Accessors and arithmetic operate at millisecond precision, but the string representation itself preserves whatever fractional-second precision was parsed (including sub-millisecond), matching the underlying Temporal behavior.

For use cases that require a time zone, especially using arithmetic or other derived values, consider using Iso.ZonedDateTime instead because that type automatically adjusts for Daylight Saving Time. A Iso.DateTime can be converted to a Iso.ZonedDateTime using a Iso.TimeZone.

Iso.Date, Iso.Time, Iso.YearMonth, and Iso.MonthDay all carry less information and should be used when complete information is not required.

A Iso.DateTime can be converted into any of the types mentioned above using conversion methods like toZonedDateTime or toDate.

Because Iso.DateTime does not represent an exact point in time, most date/time use cases are better handled using exact time types like Iso.ZonedDateTime and Iso.Instant. But there are cases where Iso.DateTime is the correct type to use:

  • Representing timezone-specific events where the time zone is not stored together with the date/time data. In this case, Iso.DateTime is an intermediate step before converting to/from Iso.ZonedDateTime or Iso.Instant using the separate time zone. Examples:
    • When the time zone is stored separately in a separate database column or a per-user setting.
    • Implicit time zones, e.g. stock exchange data that is always America/New_York
    • Interacting with poorly-designed legacy systems that record data in the server's non-UTC time zone.
  • Passing data to/from a component that is unaware of time zones, e.g. a UI date/time picker.
  • Modeling events that happen at the same local time in every time zone. For example, the British Commonwealth observes a two minute silence every November 11th at 11:00AM in local time.
  • When time zone is irrelevant, e.g. a sleep tracking device that only cares about the local time you went to sleep and woke up, regardless of where in the world you are.
  • Parsing local time from ISO 8601 strings like 2020-04-09T16:08-08:00 that have a numeric offset without an IANA time zone like America/Los_Angeles. These strings can also be parsed by Iso.Instant, but to parse the local date and time then dateTimeFns.from is required.
  • Performing arithmetic that deliberately ignores DST. Example: in a day-planner UI, the visual height of a meeting may be the same even if DST skips or repeats an hour. To learn more about time zones and DST best practices, visit Time Zones and Resolving Ambiguity.

now()​

now(timeZone?): DateTime

This method gets the current calendar date and wall-clock time according to the system settings. Optionally a time zone can be given in which the time is computed, instead of the current system time zone.

Parameters​

timeZone?​

string

The time zone to get the current date and time in, as a string. If not given, the current system time zone will be used.

Returns​

DateTime

an Iso.DateTime string representing the date and time.

fromNumbers()​

fromNumbers(year, month, day, hour?, minute?, second?, millisecond?): DateTime

Parameters​

year​

number

month​

number

day​

number

hour?​

number

minute?​

number

second?​

number

millisecond?​

number

Returns​

DateTime

isValid()​

isValid(dateTime): dateTime is DateTime

Parameters​

dateTime​

unknown

Returns​

dateTime is DateTime

assertIsValid()​

assertIsValid(dateTime): asserts dateTime is DateTime

Parameters​

dateTime​

unknown

Returns​

asserts dateTime is DateTime

getYear()​

getYear(dateTime): number

Parameters​

dateTime​

DateTime

Returns​

number

getMonth()​

getMonth(dateTime): number

Parameters​

dateTime​

DateTime

Returns​

number

getDay()​

getDay(dateTime): number

Parameters​

dateTime​

DateTime

Returns​

number

getHour()​

getHour(dateTime): number

Parameters​

dateTime​

DateTime

Returns​

number

getMinute()​

getMinute(dateTime): number

Parameters​

dateTime​

DateTime

Returns​

number

getSecond()​

getSecond(dateTime): number

Parameters​

dateTime​

DateTime

Returns​

number

getMillisecond()​

getMillisecond(dateTime): number

Parameters​

dateTime​

DateTime

Returns​

number

getDayOfWeek()​

getDayOfWeek(dateTime): number

Parameters​

dateTime​

DateTime

Returns​

number

getDayOfYear()​

getDayOfYear(dateTime): number

Parameters​

dateTime​

DateTime

Returns​

number

getWeekOfYear()​

getWeekOfYear(dateTime): number

Parameters​

dateTime​

DateTime

Returns​

number

getDaysInYear()​

getDaysInYear(dateTime): number

Parameters​

dateTime​

DateTime

Returns​

number

getDaysInMonth()​

getDaysInMonth(dateTime): number

Parameters​

dateTime​

DateTime

Returns​

number

inLeapYear()​

inLeapYear(dateTime): boolean

Parameters​

dateTime​

DateTime

Returns​

boolean

with()​

with(dateTime, temporalDateTimeLike, options?): DateTime

Parameters​

dateTime​

DateTime

temporalDateTimeLike​

day?​

number

hour?​

number

millisecond?​

number

minute?​

number

month?​

number

second?​

number

year?​

number

options?​

overflow?​

"constrain" | "reject"

Returns​

DateTime

withTime()​

withTime(dateTime, time?): DateTime

Parameters​

dateTime​

DateTime

time?​

Time

Returns​

DateTime

withDate()​

withDate(dateTime, temporalDate): DateTime

Parameters​

dateTime​

DateTime

temporalDate​

Date

Returns​

DateTime

add()​

add(dateTime, temporalDurationLike, options?): DateTime

Parameters​

dateTime​

DateTime

temporalDurationLike​

Duration | { years?: number; months?: number; weeks?: number; days?: number; hours?: number; minutes?: number; seconds?: number; milliseconds?: number; }

options?​

overflow?​

"constrain" | "reject"

Returns​

DateTime

subtract()​

subtract(dateTime, temporalDurationLike, options?): DateTime

Parameters​

dateTime​

DateTime

temporalDurationLike​

Duration | { years?: number; months?: number; weeks?: number; days?: number; hours?: number; minutes?: number; seconds?: number; milliseconds?: number; }

options?​

overflow?​

"constrain" | "reject"

Returns​

DateTime

until()​

until(from, until, options?): Duration

Parameters​

from​

DateTime

until​

DateTime

options?​

largestUnit?​

LargestUnit\<DateTimeUnit>

smallestUnit?​

SmallestUnit\<DateTimeUnit>

roundingIncrement?​

number

roundingMode?​

RoundingMode

Returns​

Duration

since()​

since(dateTime, other, options?): Duration

Parameters​

dateTime​

DateTime

other​

DateTime

options?​

largestUnit?​

LargestUnit\<DateTimeUnit>

smallestUnit?​

SmallestUnit\<DateTimeUnit>

roundingIncrement?​

number

roundingMode?​

RoundingMode

Returns​

Duration

round()​

round(dateTime, options): DateTime

Parameters​

dateTime​

DateTime

options​

smallestUnit​

SmallestUnit\<"day" | TimeUnit>

roundingIncrement?​

number

roundingMode?​

RoundingMode

Returns​

DateTime

equals()​

equals(dateTime, other): boolean

Parameters​

dateTime​

DateTime

other​

DateTime

Returns​

boolean

isEqual()​

isEqual(dateTime, other): boolean

alias for equals

Parameters​

dateTime​

DateTime

other​

DateTime

Returns​

boolean

isBefore()​

isBefore(dateTime, other): boolean

Parameters​

dateTime​

DateTime

other​

DateTime

Returns​

boolean

isAfter()​

isAfter(dateTime, other): boolean

Parameters​

dateTime​

DateTime

other​

DateTime

Returns​

boolean

isEqualOrBefore()​

isEqualOrBefore(dateTime, other): boolean

Parameters​

dateTime​

DateTime

other​

DateTime

Returns​

boolean

isEqualOrAfter()​

isEqualOrAfter(dateTime, other): boolean

Parameters​

dateTime​

DateTime

other​

DateTime

Returns​

boolean

toZonedDateTime()​

toZonedDateTime(dateTime, timeZone, options?): ZonedDateTime

Parameters​

dateTime​

DateTime

timeZone​

string

options?​

disambiguation​

"reject" | "compatible" | "earlier" | "later"

Returns​

ZonedDateTime

toDate()​

toDate(dateTime): Date

Parameters​

dateTime​

DateTime

Returns​

Date

toYearMonth()​

toYearMonth(dateTime): YearMonth

Parameters​

dateTime​

DateTime

Returns​

YearMonth

toMonthDay()​

toMonthDay(dateTime): MonthDay

Parameters​

dateTime​

DateTime

Returns​

MonthDay

toTime()​

toTime(dateTime): Time

Parameters​

dateTime​

DateTime

Returns​

Time

getFields()​

getFields(dateTime): DateTimeSlots

Parameters​

dateTime​

DateTime

Returns​

DateTimeSlots

from()​

from(item, options?): DateTime

Parameters​

item​

string | Partial\<DateTimeSlots & object>

options?​

overflow​

"constrain" | "reject"

Returns​

DateTime

compare()​

compare(one, two): number

Parameters​

one​

DateTime

two​

DateTime

Returns​

number

format()​

format(dateTime, formatString, options?): string

Parameters​

dateTime​

DateTime

the original date

formatString​

string

options?​

FormatOptions

Returns​

string

the formatted date string

Description​

Return the formatted ZonedDateTime string in the given format.

The characters wrapped between two single quotes characters (') are escaped. Two single quotes in a row, whether inside or outside a quoted sequence, represent a 'real' single quote. (see the last example)

Format of the string is based on Unicode Technical Standard #35: https://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table with a few additions (see note 7 below the table).

Accepted patterns:

UnitPatternResult examplesNotes
EraG..GGGAD, BC
GGGGAnno Domini, Before Christ1
GGGGGA, B
Calendar yeary44, 1, 1900, 20174
yo44th, 1st, 0th, 17th4,5
yy44, 01, 00, 174
yyy044, 001, 1900, 20174
yyyy0044, 0001, 1900, 20174
yyyyy...2,4
Extended yearu-43, 0, 1, 1900, 20174
uu-43, 01, 1900, 20174
uuu-043, 001, 1900, 20174
uuuu-0043, 0001, 1900, 20174
uuuuu...2,4
QuarterQ1, 2, 3, 4
Qo1st, 2nd, 3rd, 4th5
QQ01, 02, 03, 04
QQQQ1, Q2, Q3, Q4
QQQQ1st quarter, 2nd quarter, ...1
QQQQQ1, 2, 3, 43
MonthM1, 2, ..., 12
Mo1st, 2nd, ..., 12th5
MM01, 02, ..., 12
MMMJan, Feb, ..., Dec
MMMMJanuary, February, ..., December1
MMMMMJ, F, ..., D
ISO week of yearI1, 2, ..., 535
Io1st, 2nd, ..., 53th5
II01, 02, ..., 535
Day of monthd1, 2, ..., 31
do1st, 2nd, ..., 31st5
dd01, 02, ..., 31
ISO day of weeki1, 2, 3, ..., 75
io1st, 2nd, ..., 7th5
ii01, 02, ..., 075
iiiMon, Tue, Wed, ..., Sun5
iiiiMonday, Tuesday, ..., Sunday1,5
iiiiiM, T, W, T, F, S, S5
iiiiiiMo, Tu, We, Th, Fr, Sa, Su5
AM, PMa..aaAM, PM
aaaam, pm
aaaaa.m., p.m.1
aaaaaa, p
AM, PM, noon, midnightb..bbAM, PM, noon, midnight
bbbam, pm, noon, midnight
bbbba.m., p.m., noon, midnight1
bbbbba, p, n, mi
Flexible day periodB..BBBat night, in the morning, ...
BBBBat night, in the morning, ...1
BBBBBat night, in the morning, ...
Hour [1-12]h1, 2, ..., 11, 12
ho1st, 2nd, ..., 11th, 12th5
hh01, 02, ..., 11, 12
Hour [0-23]H0, 1, 2, ..., 23
Ho0th, 1st, 2nd, ..., 23rd5
HH00, 01, 02, ..., 23
Hour [0-11]K1, 2, ..., 11, 0
Ko1st, 2nd, ..., 11th, 0th5
KK01, 02, ..., 11, 00
Hour [1-24]k24, 1, 2, ..., 23
ko24th, 1st, 2nd, ..., 23rd5
kk24, 01, 02, ..., 23
Minutem0, 1, ..., 59
mo0th, 1st, ..., 59th5
mm00, 01, ..., 59
Seconds0, 1, ..., 59
so0th, 1st, ..., 59th5
ss00, 01, ..., 59
Fraction of secondS0, 1, ..., 9
SS00, 01, ..., 99
SSS000, 001, ..., 999
SSSS...2
Long localized dateP04/29/14535
PPApr 29, 14535
PPPApril 29th, 14535
PPPPFriday, April 29th, 14531,5
Long localized timep12:00 AM5
pp12:00:00 AM5
Combination of date and timePp04/29/1453, 12:00 AM5
PPppApr 29, 1453, 12:00:00 AM5

Notes:

  1. Any sequence of the identical letters is a pattern, unless it is escaped by the single quote characters (see below). If the sequence is longer than listed in table (e.g. EEEEEEEEEEE) the output will be the same as default pattern for this unit, usually the longest one (in case of ISO weekdays, EEEE). Default patterns for units are marked with "2" in the last column of the table.

    format("2017-11-06", 'MMM') //=> 'Nov'

    format("2017-11-06", 'MMMM') //=> 'November'

    format("2017-11-06", 'MMMMM') //=> 'N'

    format("2017-11-06", 'MMMMMM') //=> 'November'

    format("2017-11-06", 'MMMMMMM') //=> 'November'

  2. Some patterns could be unlimited length (such as yyyyyyyy). The output will be padded with zeros to match the length of the pattern.

    format("2017-11-06", 'yyyyyyyy') //=> '00002017'

  3. QQQQQ could be not strictly numerical in some locales. These tokens represent the shortest form of the quarter.

  4. The main difference between y and u patterns are B.C. years:

    Yearyu
    AC 111
    BC 110
    BC 22-1

    Also yy always returns the last two digits of a year, while uu pads single digit years to 2 characters and returns other years unchanged:

    Yearyyuu
    10101
    141414
    37676376
    1453531453

  5. These patterns are not in the Unicode Technical Standard #35:

    • i: ISO day of week
    • I: ISO week of year
    • o: ordinal number modifier
    • P: long localized date
    • p: long localized time
  • Characters are escaped using single quote symbols (').

Examples​

// Represent 11 February 2014 in middle-endian format:
var result = format("2014-02-11T00:00:00.000", 'MM/dd/yyyy')
//=> '02/11/2014'
// Escape string by single quote characters:
var result = format("2014-02-11T15:00:00.000", "h 'o''clock'")
//=> "3 o'clock"

chain()​

chain(dateTime): IDateTimeChain

Parameters​

dateTime​

DateTime

Returns​

IDateTimeChain