DateTime

DateTime

DateTime contains various date and time utility functions.

Methods

(static) addDays(date, days) → {date}

Source:

Adds (subtracts if days is negative) the given number of days to the given date. The supplied date object remains unchanged.

Example
const base = new Date('March 1, 2020 12:34:56');
const d1 = DateTime.addDays(base, 1);
const d2 = DateTime.addDays(base, -1);
// d1 is Mon Mar 02 2020 12:34:56 GMT+0000 (Greenwich Mean Time)
// d2 is Sat Feb 29 2020 12:34:56 GMT+0000 (Greenwich Mean Time)
Parameters:
Name Type Description
date date

Base date for calculation
days number

Number of days to add (or subtract if negative)
Returns:

Modified date

Type
date

(static) addMonths(date, months) → {date}

Source:

Adds (subtracts if months is negative) the given number of months to the given date. The supplied date object remains unchanged. It's smart about handling months of different lengths so e.g. 31 Oct + 1 month = 30 Nov and 31 March - 1 month = 28 (or 29) Feb.

Example
const base = new Date('March 31, 2020 12:34:56');
const d1 = DateTime.addMonths(base, 1);
const d2 = DateTime.addMonths(base, -1);
// d1 is Thu Apr 30 2020 12:34:56 GMT+0100 (British Summer Time)
// d2 is Sat Feb 29 2020 12:34:56 GMT+0000 (Greenwich Mean Time)
Parameters:
Name Type Description
date date

Base date for calculation
months number

Number of months to add or subtract if negative)
Returns:

Modified date

Type
date

(static) addYears(date, years) → {date}

Source:

Adds (subtracts if years is negative) the given number of years to the given date (subtracts if year is negative). The supplied date object remains unchanged. It handles leap years properly so 29 Feb 2020 - 1 year = 28 Feb 2019, but 29 Feb 2020 - 4 years = 29 Feb 2016

Example
const base = new Date('March 15, 2020 12:34:56');
const d1 = DateTime.addYears(base, 1);
const d2 = DateTime.addYears(base, -1);
// d1 is Mon Mar 15 2021 12:34:56 GMT+0000 (Greenwich Mean Time)
// d2 is Fri Mar 15 2019 12:34:56 GMT+0000 (Greenwich Mean Time)
Parameters:
Name Type Description
date date

Base date for calculation
years number

Number of years to add (or subtract if negative)
Returns:

Modified date

Type
date

(static) getAbsoluteDate(y, m, d, baseopt) → {date}

Source:

Returns a date with one or more elements set in the given base date. The supplied date object remains unchanged. NOTE: The m parameter is zero-based.

Example
const base = new Date('March 15, 2020 12:34:56');
const d1 = DateTime.getAbsoluteDate(1999, null, null, base);
const d2 = DateTime.getAbsoluteDate(null, 1, null, base);
const d3 = DateTime.getAbsoluteDate(null, null, 3, base);
// d1 is Mon Mar 15 1999 12:34:56 GMT+0000 (Greenwich Mean Time)
// d2 is Sat Feb 15 2020 12:34:56 GMT+0000 (Greenwich Mean Time)
// d3 is Tue Mar 03 2020 12:34:56 GMT+0000 (Greenwich Mean Time)
Parameters:
Name Type Attributes Default Description
y number | null

Set absolute year.
m number | null

Set absolute month index (0-based).
d number | null

Set absolute date.
base date <optional>
 today

Base date to apply the absolute values to.
Returns:

Modified date

Type
date

(static) getAllMonths(date, date) → {array}

Source:

Returns an array of formatted strings of the form 'YYYY-MM' across the required closed range [start, end].

Example
const months = getAllMonths(new Date('2022-02), new Date('2023-01)); 

// months is [
    '2022-02',
    '2022-03',
    '2022-04',
    '2022-05',
    '2022-06',
    '2022-07',
    '2022-08',
    '2022-09',
    '2022-10',
    '2022-11',
    '2022-12',
    '2023-01'
]
Parameters:
Name Type Description
date start

Start date of the range to be generated.
date end

End date of the range to be generated.
Returns:

Array of strings of the form 'YYYY-MM' across the required range.

Type
array

(static) getCurrentFinancialYear(dateopt, startsopt) → {object}

Source:

Returns a range object that defines the current financial year.

Example
const base = new Date('March 15, 2020 12:34:56'); // Sunday
const d1 = DateTime.getCurrentFinancialYear(base, DateTime.JANUARY);
const d2 = DateTime.getCurrentFinancialYear(base, DateTime.FEBRUARY);
const d3 = DateTime.getCurrentFinancialYear(base, DateTime.MARCH); 
const d4 = DateTime.getCurrentFinancialYear(base, DateTime.APRIL); 
const d5 = DateTime.getCurrentFinancialYear(base, DateTime.OCTOBER); 
const d6 = DateTime.getCurrentFinancialYear(base, DateTime.DECEMBER); 
// d1 is {starts: Wed Jan 01 2020 00:00:00 GMT+0000 (Greenwich Mean Time), ends: Thu Dec 31 2020 00:00:00 GMT+0000 (Greenwich Mean Time)}
// d2 is {starts: Sat Feb 01 2020 00:00:00 GMT+0000 (Greenwich Mean Time), ends: Sun Jan 31 2021 00:00:00 GMT+0000 (Greenwich Mean Time)
// d3 is {starts: Sun Mar 01 2020 00:00:00 GMT+0000 (Greenwich Mean Time), ends: Sun Feb 28 2021 00:00:00 GMT+0000 (Greenwich Mean Time)}
// d4 is {starts: Mon Apr 01 2019 00:00:00 GMT+0100 (British Summer Time), ends: Tue Mar 31 2020 00:00:00 GMT+0100 (British Summer Time)}
// d5 is {starts: Tue Oct 01 2019 00:00:00 GMT+0100 (British Summer Time), ends: Wed Sep 30 2020 00:00:00 GMT+0100 (British Summer Time)}
// d6 is {starts: Sun Dec 01 2019 00:00:00 GMT+0000 (Greenwich Mean Time), ends: Mon Nov 30 2020 00:00:00 GMT+0000 (Greenwich Mean Time)}
Parameters:
Name Type Attributes Default Description
date date <optional>
 today

Date to base the calculation on.
starts number <optional>

Month that the FY starts (0-based) - default 0 (January)
Returns:

Range object

Type
object

(static) getFirstOfMonth(dateopt) → {date}

Source:

Returns the date representing the first day of the given date's month (or the first day of the current month if no date is provided). The supplied date object remains unchanged.

Example
const base = new Date('March 15, 2020 12:34:56');
const d = DateTime.getFirstOfMonth(base);
// d is Sun Mar 01 2020 00:00:00 GMT+0000 (Greenwich Mean Time)
Parameters:
Name Type Attributes Default Description
date date <optional>
 today

Base date for calculation
Returns:

First day of the given date's month

Type
date

(static) getFirstOfYear(dateopt) → {date}

Source:

Returns the date representing the first day of the year in the given date (or the first day of the current year if no date is provided). The supplied date object remains unchanged.

Example
const base = new Date('March 15, 2020 12:34:56');
const d = DateTime.getFirstOfYear(base);
// d is Wed Jan 01 2020 00:00:00 GMT+0000 (Greenwich Mean Time)
Parameters:
Name Type Attributes Default Description
date date <optional>
 today

Base date for calculation
Returns:

First day of the year for the given date

Type
date

(static) getLastOfMonth(dateopt) → {date}

Source:

Returns the last day of the given date's month (or the current month if no date is provided). The supplied date object remains unchanged.

Example
const base = new Date('March 15, 2020 12:34:56');
const d = DateTime.getLastOfMonth(base);
// d is Tue Mar 31 2020 23:59:59 GMT+0100 (British Summer Time)
Parameters:
Name Type Attributes Default Description
date date <optional>
 today

Base date for calculation
Returns:

Last day of the given date's month

Type
date

(static) getLastOfMonthDate(month, year) → {number}

Source:

Returns the date of the last day of the given month in the given year.

Example
const d1 = DateTime.getLastOfMonthDate(1, 2020);
const d2 = DateTime.getLastOfMonthDate(1, 2021);
// d1 is 29
// d2 is 28
Parameters:
Name Type Description
month number

Zero-based month
year number

Year
Returns:

Last day of the given month in the given year

Type
number

(static) getLastOfYear(dateopt) → {date}

Source:

Returns the date representing the last day of the year in the given date (or the last day of the current year if no date is provided). The supplied date object remains unchanged.

Example
const base = new Date('March 15, 2020 12:34:56');
const d = DateTime.getLastOfYear(base);
// d is Thu Dec 31 2020 23:59:59 GMT+0000 (Greenwich Mean Time)
Parameters:
Name Type Attributes Default Description
date date <optional>
 today

Base date for calculation
Returns:

Last day of the year for the given date

Type
date

(static) getLongMonthName(date) → {string}

Source:

Returns the long name of the month in the given date.

Example
const base = new Date('March 15, 2020 12:34:56'); 
const d = DateTime.getLongMonthName(base);
// d is 'March'
Parameters:
Name Type Description
date date

Date to base the calculation on.
Returns:
Type
string

(static) getPresets(dateopt, quarterStartMonthopt) → {object}

Source:

Returns an object contaiing a set of preset date ranges, optionally based on the given date.

Example
const base = new Date('March 15, 2020 12:34:56');
const presets = DateTime.getPresets(base, 3);
// presets is:
// {
//   today: {starts: Sun Mar 15 2020 00:00:00 GMT+0000 (Greenwich Mean Time), ends: Sun Mar 15 2020 23:59:59 GMT+0000 (Greenwich Mean Time)},
//   yesterday: {starts: Sat Mar 14 2020 00:00:00 GMT+0000 (Greenwich Mean Time), ends: Sat Mar 14 2020 23:59:59 GMT+0000 (Greenwich Mean Time)},
//   thisWeek: {starts: Mon Mar 09 2020 00:00:00 GMT+0000 (Greenwich Mean Time), ends: Sun Mar 15 2020 23:59:59 GMT+0000 (Greenwich Mean Time)},
//   lastWeek: {starts: Mon Mar 02 2020 00:00:00 GMT+0000 (Greenwich Mean Time), ends: Sun Mar 08 2020 23:59:59 GMT+0000 (Greenwich Mean Time)},
//   thisMonth: {starts: Sun Mar 01 2020 00:00:00 GMT+0000 (Greenwich Mean Time), ends: Tue Mar 31 2020 23:59:59 GMT+0100 (British Summer Time)},
//   thisMonthLastYear: {starts: Fri Mar 01 2019 00:00:00 GMT+0000 (Greenwich Mean Time), ends: Sun Mar 31 2019 23:59:59 GMT+0100 (British Summer Time)},
//   lastMonth: {starts: Sat Feb 01 2020 00:00:00 GMT+0000 (Greenwich Mean Time), ends: Sat Feb 29 2020 23:59:59 GMT+0000 (Greenwich Mean Time)},
//   thisQuarter: {starts: Wed Jan 01 2020 00:00:00 GMT+0000 (Greenwich Mean Time), ends: Tue Mar 31 2020 23:59:59 GMT+0100 (British Summer Time)},
//   lastQuarter: {starts: Tue Oct 01 2019 00:00:00 GMT+0100 (British Summer Time), ends: Tue Dec 31 2019 23:59:59 GMT+0000 (Greenwich Mean Time)},
//   thisYear: {starts: Wed Jan 01 2020 00:00:00 GMT+0000 (Greenwich Mean Time), ends: Thu Dec 31 2020 23:59:59 GMT+0000 (Greenwich Mean Time)},
//   lastYear: {starts: Tue Jan 01 2019 00:00:00 GMT+0000 (Greenwich Mean Time), ends: Tue Dec 31 2019 23:59:59 GMT+0000 (Greenwich Mean Time)}
//   thisFinancialYear: {starts: Wed Apr 01 2019 00:00:00 GMT+0000 (Greenwich Mean Time), ends: Thu Mar 31 2020 23:59:59 GMT+0000 (Greenwich Mean Time)},
//   lastFinancialYear: {starts: Wed Apr 01 2018 00:00:00 GMT+0000 (Greenwich Mean Time), ends: Thu Mar 31 2019 23:59:59 GMT+0000 (Greenwich Mean Time)},
//   twoYearsAgoFinancialYear: {starts: Wed Apr 01 2017 00:00:00 GMT+0000 (Greenwich Mean Time), ends: Thu Mar 31 2018 23:59:59 GMT+0000 (Greenwich Mean Time)},
// }
Parameters:
Name Type Attributes Default Description
date date <optional>
 today

Base date for presets
quarterStartMonth date <optional>
 0

Zer-based month when a new quarter starts (default is 0 = Jan)
Returns:
Type
object

(static) getPreviousDay(date, weekday) → {date}

Source:

Returns the date of the previous weekday relative to the given date. If the base date's weekday matches the required weekday parameter then the returned result is the same as the base date. The supplied date object remains unchanged.

Example
const base = new Date('March 15, 2020 12:34:56'); // Sunday
const d1 = DateTime.getPreviousDay(base, DateTime.SUNDAY);
const d2 = DateTime.getPreviousDay(base, DateTime.MONDAY);
const d3 = DateTime.getPreviousDay(base, DateTime.SATURDAY); 
// d1 is Sun Mar 15 2020 12:34:56 GMT+0000 (Greenwich Mean Time)
// d2 is Mon Mar 09 2020 12:34:56 GMT+0000 (Greenwich Mean Time)
// d3 is Sat Mar 14 2020 12:34:56 GMT+0000 (Greenwich Mean Time)
Parameters:
Name Type Description
date date

Base date for calculation
weekday number

(0 = Sunday, 1 = Monday...)
Returns:

Date of the previous weekday relative to the given date.

Type
date

(static) getQuarter(quarteropt, startMonthopt, dateopt) → {object}

Source:

Returns a range object that defines the requested quarter.

Example
const base = new Date('March 15, 2020 12:34:56'); // Sunday
const curr = DateTime.getQuarter(0, DateTime.JANUARY, base);
const q1 = DateTime.getQuarter(1, DateTime.JANUARY, base);
const q2 = DateTime.getQuarter(2, DateTime.FEBRUARY, base);
const lq = DateTime.getQuarter(-1, DateTime.JANUARY, base);
// curr is {starts: Wed Jan 01 2020 00:00:00 GMT+0000 (Greenwich Mean Time), ends: Tue Mar 31 2020 23:59:59 GMT+0100 (British Summer Time)}
// q1 is {starts: Wed Jan 01 2020 00:00:00 GMT+0000 (Greenwich Mean Time), ends: Tue Mar 31 2020 23:59:59 GMT+0100 (British Summer Time)}
// q2 is {starts: Fri May 01 2020 00:00:00 GMT+0100 (British Summer Time), ends: Fri Jul 31 2020 23:59:59 GMT+0100 (British Summer Time)}
// lq is {starts: Tue Oct 01 2019 00:00:00 GMT+0100 (British Summer Time), ends: Tue Dec 31 2019 23:59:59 GMT+0000 (Greenwich Mean Time)}
Parameters:
Name Type Attributes Default Description
quarter number <optional>

If positive, returns the nth quarter (1 - 4); if 0 (default) returns the current quarter; if negative returns n quarters ago.
startMonth number <optional>

Calendar month corresponding to the start of the first quarter (0-based) - default January
date date <optional>
 today

Date to base the calculation on.
Returns:

Range object

Type
object

(static) getQuarterNumber(date, startMonth) → {number}

Source:

Returns the number of the quarter for the given date and start month.

Example
const base = new Date('March 15, 2020 12:34:56'); // Sunday
console.log(DateTime.getQuarterNumber(base, DateTime.JANUARY)); // Outputs 1
Parameters:
Name Type Description
date date

The input date for which we want to find the quarter number.
startMonth number

Calendar month corresponding to the start of the first quarter (0-based) - default January
Returns:

Quarter number in range 1 to 4

Type
number

(static) getShortMonthName(date) → {string}

Source:

Returns the short name of the month in the given date.

Example
const base = new Date('April 15, 2020 12:34:56'); 
const d = DateTime.getShortMonthName(base);
// d is 'Apr'
Parameters:
Name Type Description
date date

Date to base the calculation on.
Returns:

Month name

Type
string

(static) getSQLDate(date) → {string}

Source:

Returns a 'YYYY-MM-DD' formatted date string suitable for inclusion in an SQL query.

Example
const base = new Date('March 31, 2020 12:34:56');
const sql = DateTime.getSQLDate(base);
// sql is "2020-03-31"
Parameters:
Name Type Description
date date

Date to be formatted
Returns:

Formatted date

Type
string

(static) getSQLMonth(date) → {string}

Source:

Returns a 'YYYY-MM' formatted date string suitable for inclusion in an SQL query.

Example
const base = new Date('March 31, 2020 12:34:56');
const sql = DateTime.getSQLDate(base);
// sql is "2020-03"
Parameters:
Name Type Description
date date

Date to be formatted
Returns:

Formatted date

Type
string

(static) getSQLRange(from, to) → {string}

Source:

Returns an SQL BETWEEN clause to select all dates in the given range.

Example
const start = new Date('March 15, 2020 12:34:56');
const end = new Date('July 11, 2020 12:34:56');
const sql = DateTime.getSQLRange(start, end);
// sql is 'BETWEEN "2020-03-15 00:00:00" AND "2020-07-11 23:59:59"'
Parameters:
Name Type Description
from date

Start of date range
to date

End of date range
Returns:

SQL BETWEEN clause required to SELECT the given range

Type
string

(static) getThisDay(date, weekday) → {date}

Source:

Returns the date of 'this' weekday relative to the given date. The returned date may be in the future. If the given date is already on the requested weekday then it's returned, otherwise the date of the previous weekday is returned. The supplied date object remains unchanged.

Example
const base = new Date('March 15, 2020 12:34:56'); // Sunday
const d1 = DateTime.getThisDay(base, DateTime.SUNDAY);
const d2 = DateTime.getThisDay(base, DateTime.MONDAY);
const d3 = DateTime.getThisDay(base, DateTime.SATURDAY); 
// d1 is Sun Mar 15 2020 12:34:56 GMT+0000 (Greenwich Mean Time)
// d2 is Mon Mar 09 2020 12:34:56 GMT+0000 (Greenwich Mean Time)
// d3 is Sat Mar 14 2020 12:34:56 GMT+0000 (Greenwich Mean Time)
Parameters:
Name Type Description
date date

Base date for calculation
weekday number

(0 = Sunday, 1 = Monday...)
Returns:

Date of 'this' weekday relative to the given date

Type
date

(static) parseISO8601(s) → {date|null}

Source:

Parses a string in an ISO8601-compliant format i.e. YYYY-MM, YYYY-MM-DD, YYYY-MM-DDThh:mm:ss.ssssZ or YYYY-MM-DDThh:mm:ss.ssss+HH:MM
If the date is not in a supported format then null is returned. NOTE: If provided the timezone is parsed but its value is ignored.

Example
const d1 = DateTime.parseISO8601("2020-03");
const d2 = DateTime.parseISO8601("2020-03-15");
const d3 = DateTime.parseISO8601("2020-03-15T12:34:56Z");
const d4 = DateTime.parseISO8601("2020-03-15T12:34:56.789+01:00");
const d5 = DateTime.parseISO8601("2020-03-15T12:34:56-02:00");
// d1 is Sun Mar 01 2020 00:00:00 GMT+0000 (Greenwich Mean Time)
// d2 is Sun Mar 15 2020 00:00:00 GMT+0000 (Greenwich Mean Time)
// d2 is Sun Mar 15 2020 12:34:56 GMT+0000 (Greenwich Mean Time)
// d3 is Sun Mar 15 2020 12:34:56 GMT+0000 (Greenwich Mean Time)
// d4 is Sun Mar 15 2020 12:34:56 GMT+0000 (Greenwich Mean Time)
Parameters:
Name Type Description
s string

Date string to be parsed
Returns:

Parsed date

Type
date | null

(static) setEndOfDay(date) → {date}

Source:

Returns a new Date based on the given date with the time part set to 23:59:59. The supplied date object remains unchanged.

Example
const base = new Date('March 15, 2020 12:34:56'); 
const d = DateTime.setEndOfDay(base);
// d is Sun Mar 15 2020 23:59:59 GMT+0000 (Greenwich Mean Time)
Parameters:
Name Type Description
date date

Date to base the calculation on.
Returns:

New date

Type
date

(static) setStartOfDay(date) → {date}

Source:

Returns a new Date based on the given date with the time part set to 00:00:00. The supplied date object remains unchanged.

Example
const base = new Date('March 15, 2020 12:34:56'); 
const d = DateTime.setStartOfDay(base);
// d is Sun Mar 15 2020 00:00:00 GMT+0000 (Greenwich Mean Time)
Parameters:
Name Type Description
date date

Date to base the calculation on.
Returns:

New date

Type
date

(static) toQuarter(Date, startsopt) → {string}

Source:

Returns a 'Qn yyyy' formatted date string

Example
const base = new Date('March 31, 2020 12:34:56');
const s = DateTime.toQuarter(base);
// s is "Q1 2020"
Parameters:
Name Type Attributes Description
Date date | string

to be formatted
starts number <optional>

Month that Q1 starts (0-based) - default 0 (January)
Returns:

Formatted date

Type
string