DateTimeUtils

DateTimeUtils

Class to deal with dates and times together. Generally, date/times can be represented in any of the following formats: - Date objects - Epoch timestamps (in milliseconds) - Numeric in the form YYYYMMDDHHMM (ymdhm)

Constructor

new DateTimeUtils()

Source:

Methods

(static) addDays(ymdhm, days, zoneId) → {number}

Source:
Adds a specified number of days to a date-time in YYYYMMDDHHMM format
Parameters:
Name Type Description
ymdhm number date-time in YYYYMMDDHHMM format
days number number of days to add
zoneId string IANA time zone name (e.g. "America/New_York")
Returns:
date-time after adding days in YYYYMMDDHHMM format
Type
number

(static) addHours(dt, hours) → {Date}

Source:
Add hours to a date.
Parameters:
Name Type Description
dt Date | number | string
hours number
Returns:
Type
Date

(static) addHours(ymdhm, hours, zoneId) → {number}

Source:
Adds a specified number of hours to a date-time in YYYYMMDDHHMM format
Parameters:
Name Type Description
ymdhm number date-time in YYYYMMDDHHMM format
hours number number of hours to add
zoneId string IANA time zone name (e.g. "America/New_York")
Returns:
date-time after adding hours in YYYYMMDDHHMM format
Type
number

(static) addMinutes(dt, minutes) → {Date}

Source:
Add minutes to a date.
Parameters:
Name Type Description
dt Date | number | string
minutes number
Returns:
Type
Date

(static) addMinutes(ymdhm, minutes, zoneId) → {number}

Source:
Adds a specified number of minutes to a date-time in YYYYMMDDHHMM format
Parameters:
Name Type Description
ymdhm number date-time in YYYYMMDDHHMM format
minutes number number of minutes to add
zoneId string IANA time zone name (e.g. "America/New_York")
Returns:
date-time after adding minutes in YYYYMMDDHHMM format
Type
number

(static) addMonths(ymdhm, months, zoneId) → {number}

Source:
Adds a specified number of months to a date-time in YYYYMMDDHHMM format
Parameters:
Name Type Description
ymdhm number date-time in YYYYMMDDHHMM format
months number number of months to add
zoneId string IANA time zone name (e.g. "America/New_York")
Returns:
date-time after adding months in YYYYMMDDHHMM format
Type
number

(static) addYears(ymdhm, years, zoneId) → {number}

Source:
Adds a specified number of years to a date-time in YYYYMMDDHHMM format
Parameters:
Name Type Description
ymdhm number date-time in YYYYMMDDHHMM format
years number number of years to add
zoneId string IANA time zone name (e.g. "America/New_York")
Returns:
date-time after adding years in YYYYMMDDHHMM format
Type
number

(static) create(dt, tm) → {number}

Source:
Creates an int date/time out of an int date and int time.
Parameters:
Name Type Description
dt YYYYMMDD
tm HHMM
Returns:
YYYYMMDDHHMM
Type
number

(static) createDate(dt, tm) → {Date}

Source:
Convert an integer date and integer time into a Date object in the local timezone.
Parameters:
Name Type Description
dt YYYYMMDD
tm HHMM
Returns:
Type
Date

(static) dateOnlyEpoch(epochMillis) → {number}

Source:
Takes an epoch time and returns an epoch time that only has the date portion (midnight local time)
Parameters:
Name Type Description
epochMillis number the epoch time in milliseconds since Jan 1, 1970
Returns:
the date portion of the epoch time in milliseconds since Jan 1, 1970
Type
number

(static) dateToStd(dt, tzopt) → {string}

Source:
Convert a Date into the canonical interchange string yyyy-MM-dd HH:mm:ss
Parameters:
Name Type Attributes Description
dt Date | number | string – Date object, millis, or numeric string
tz string <optional>
 – IANA zone name (e.g. "America/New_York"); omit/falsy ⇒ use the host’s local zone
Returns:
Type
string

(static) diffMinutes(fromYmdhm, subYmdhm, zoneId) → {number}

Source:
Calculate the difference in minutes between two YYYYMMDDHHMM date-time values in the same time zone.
Parameters:
Name Type Description
fromYmdhm number starting date-time in YYYYMMDDHHMM format
subYmdhm number date-time in YYYYMMDDHHMM format to subtract
zoneId string IANA time zone name (e.g. "America/New_York")
Returns:
difference in minutes between the two date-time values
Type
number

(static) displayEpochToEpoch(x, realTimezone, displayTimezoneopt) → {number}

Source:
Compute the epoch timestamp for a given display epoch and IANA timezone. The result is the epoch timestamp that, when converted to a wall clock time in the specified time zone, yields the same wall clock time as the input display epoch when converted to a wall clock time in the local time zone.
Parameters:
Name Type Attributes Description
x number display epoch in milliseconds since 1970 UTC
realTimezone string IANA time zone name (e.g. "America/New_York")
displayTimezone string <optional>
 IANA time zone name; omit/falsy ⇒ use the host’s local zone
Returns:
the epoch timestamp in milliseconds since 1970 UTC This function takes into account both DST transitions and the base UTC offset. The returned value is the epoch timestamp that, when converted to a wall clock time in the specified time zone, yields the same wall clock time as the input display epoch when converted to a wall clock time in the local time zone.
Type
number

(static) epochFromDateAndTime(dateInt, timeInt, timezone) → {number}

Source:
Takes a date (YYYYMMDD) and time (HHMM) and returns the epoch time (milliseconds since Jan 1, 1970) dateInt and timeInt are assumed in the local timezone. If timezone is passed, the epoch time is converted to that timezone.
Parameters:
Name Type Description
dateInt number date in YYYYMMDD format
timeInt number time in HHMM format
timezone string optional IANA time zone name (e.g. "America/New_York")
Returns:
epoch time in milliseconds since Jan 1, 1970
Type
number

(static) epochToDisplayEpoch(t, realTimezone, displayTimezoneopt) → {number}

Source:
Compute the display epoch for a given epoch timestamp and IANA timezone. The result is the epoch timestamp that, when converted to a wall clock time in the given time zone, yields the same wall clock time as the input epoch timestamp when converted to a wall clock time in the local time zone.
Parameters:
Name Type Attributes Description
t number timestamp in milliseconds since 1970 UTC
realTimezone string IANA time zone name (e.g. "America/New_York")
displayTimezone string <optional>
 IANA time zone name; omit/falsy ⇒ use the host’s local zone
Returns:
the display epoch in milliseconds since 1970 UTC This function takes into account both DST transitions and the base UTC offset. The returned value is the epoch timestamp that, when converted to a wall clock time in the specified time zone, yields the same wall clock time as the input epoch timestamp when converted to a wall clock time in the local time zone.
Type
number

(static) formatDate(dt, tzopt) → {string}

Source:
Format a Date or milliseconds-since-epoch value to a string "mm/dd/yyyy hh:mm AM/PM" or "dd/mm/yyyy hh:mm AM/PM"
Parameters:
Name Type Attributes Description
dt Date | string | number – Date object, millis, ymdhm,or numeric string
tz string <optional>
 – IANA zone (e.g. "America/New_York"); omit or pass falsy to use the local zone
Returns:
Type
string

(static) formatDateLong(dt, tzopt) → {string}

Source:
Format a moment as "Wed Jan 4, 2022 12:31 PM CST".
Parameters:
Name Type Attributes Description
dt Date | number | string – Date object, epoch-millis, YYYYMMDDHHMM, or numeric string
tz string <optional>
 – IANA zone name (e.g. "America/Chicago"); omit/falsy → host’s local zone
Returns:
Type
string

(static) formatDateTime(dt, time, tzopt) → {string}

Source:
Format a date (YYYYMMDD) and a time (HHMM) as "mm/dd/yyyy hh:mm AM/PM" or "dd/mm/yyyy hh:mm AM/PM"
Parameters:
Name Type Attributes Description
dt number | string – calendar date, e.g. 20250508
time number | string – clock time, e.g. 1145
tz string <optional>
 – IANA zone name; omit/falsy ⇒ host’s zone
Returns:
Type
string

(static) getDate(dt) → {number}

Source:
Extracts the date in YYYYMMDD format from a date-time in YYYYMMDDHHMM format.
Parameters:
Name Type Description
dt number date-time in YYYYMMDDHHMM format
Returns:
date in YYYYMMDD format
Type
number

(static) getLocalTimezoneLongText() → {string}

Source:
Returns the local long timezone text. For example "American/Chicago"
Returns:
Type
string

(static) getLocalTimezoneShortText() → {string}

Source:
Returns the local short timezone text. For example "CST"
Returns:
Type
string

(static) getTime(dt) → {number}

Source:
Extracts the time in HHMM format from a date-time in YYYYMMDDHHMM format.
Parameters:
Name Type Description
dt number date-time in YYYYMMDDHHMM format
Returns:
time in HHMM format
Type
number

(static) getTimeZoneOffsetMs(epochMs, timeZone) → {number}

Source:
Compute the timezone offset in milliseconds for a given epoch timestamp and IANA timezone.
Parameters:
Name Type Description
epochMs number timestamp in milliseconds since 1970 UTC
timeZone string IANA time zone name (e.g. "America/New_York")
Returns:
the timezone offset in milliseconds This function takes into account both DST transitions and the base UTC offset. The returned value is the difference between the given epoch timestamp and the wall clock time in the specified time zone. This value can be used to convert a timestamp in milliseconds since 1970 UTC to a wall clock time in a given time zone.
Type
number

(static) localZone() → {string}

Source:
Return the local timezone (IANA string) e.g. "America/New_York".
Returns:
Type
string

(static) newYmdhm(date, time) → {number}

Source:
Converts a date (YYYYMMDD) and a time (HHMM) into a compact local date-time representation as YYYYMMDDHHMM (number).
Parameters:
Name Type Description
date number date in YYYYMMDD format
time number time in HHMM format
Returns:
date-time representation in YYYYMMDDHHMM format
Type
number

(static) now(timeZone) → {number}

Source:
Returns the current date/time as an integer in the format YYYYMMDDHHMM for the specified timezone. If timezone is null or undefined, the system's local timezone is used.
Parameters:
Name Type Description
timeZone string | null | undefined IANA timezone string, e.g. "America/New_York". If null, the local timezone is used.
Returns:
- Current date/time as yyyymmddhhmm.
Type
number

(static) stdToDate(sdt) → {Date}

Source:
Parse a standard string date format into a Date object. Expected standard date format looks like this: 2022-06-08 03:27:44 300 The 300 is minutes offset from GMT - the timezone This routine parses a date from any timezone and returns a Date object in the local timezone.
Parameters:
Name Type Description
sdt string
Returns:
Type
Date

(static) timeOnlyEpoch(epochMillis) → {number}

Source:
Takes an epoch time and returns an epoch time that only represents the time portion of the epoch time (i.e. milliseconds since midnight local time)
Parameters:
Name Type Description
epochMillis number the epoch time in milliseconds since Jan 1, 1970
Returns:
the time portion of the epoch time in milliseconds since midnight local time
Type
number

(static) toDate(dt) → {Date}

Source:
Converts a given epoch or YYYYMMDDHHMM date/time into a Date object.
Parameters:
Name Type Description
dt number | Date the date to convert
Returns:
- the converted date
Type
Date

(static) toEpoch(dt, zoneId) → {number}

Source:
Converts a date-time to an epoch timestamp in milliseconds (UTC).
Parameters:
Name Type Description
dt number date-time in YYYYMMDDHHMM format or a Date object
zoneId string IANA time zone name (e.g. "America/New_York")
Returns:
epoch timestamp in milliseconds (UTC)
Type
number

(static) toIntDate(dt, zoneIdopt) → {number}

Source:
Extract the calendar date as an integer (YYYYMMDD).
Parameters:
Name Type Attributes Description
dt Date | number – Date object *or* milliseconds since epoch.
zoneId string <optional>
 – optional IANA time-zone, e.g. "America/New_York". Omit/falsy ⇒ use the host’s local zone.
Returns:
– YYYYMMDD, or NaN on invalid input.
Type
number

(static) toIntTime(dt, zoneIdopt) → {number}

Source:
Convert a moment in time to an integer clock value (HHMM). The date portion is ignored.
Parameters:
Name Type Attributes Description
dt Date | number – Date instance or milliseconds-since-epoch or YYYYMMDDHHMM
zoneId string <optional>
 – optional IANA time-zone (e.g. "America/New_York"); omit or falsy → use the host’s local zone
Returns:
– integer HHMM, or NaN on bad input
Type
number

(static) toMilliseconds(date, time) → {number}

Source:
See:
  • DateUtils.millsToInt()
  • TimeUtils.millsToInt()
Combine a date and time into the number of milliseconds since 1970 UTC. This is very valuable when trying to transmit a DateTime to a backend without losing timezone info.
Parameters:
Name Type Description
date number | Date YYYYMMDD (time portion of a Date is not used)
time number | null | undefined HHMM
Returns:
Type
number

(static) toYmdhm(input, zoneId) → {number}

Source:
Convert a Date objects or epoch timestamps (in milliseconds or seconds) into a compact local date-time representation as YYYYMMDDHHMM (number).
Parameters:
Name Type Description
input Date | number date-time to convert, either a Date object or an epoch timestamp
zoneId string IANA time zone name (e.g. "America/New_York")
Returns:
date-time representation in YYYYMMDDHHMM format
Type
number