Class: DateLib

A wrapper class around date-fns sharing the same options.

Since

9.2.0

Example

const dateLib = new DateLib({ locale: es });
  const newDate = dateLib.addDays(new Date(), 5);

Constructors

Constructor

new DateLib(options?, overrides?): DateLib

Defined in: src/classes/DateLib.ts:115

Creates an instance of DateLib.

Parameters

Parameter	Type	Description
`options?`	`DateLibOptions`	The options for the date library.
`overrides?`	`Partial`<`DateLib`>	Overrides for the date library functions.

Returns

DateLib

Methods

formatNumber()

formatNumber(value): string

Defined in: src/classes/DateLib.ts:162

Format number using the custom numbering system.

Parameters

Parameter	Type	Description
`value`	`number`	The number to format.

Returns

string

The formatted number.

Since

9.5.0

newDate()

newDate(year, monthIndex, date): Date

Defined in: src/classes/DateLib.ts:198

Creates a new date object with the specified year, month and date.

Parameters

Parameter	Type	Description
`year`	`number`	The year.
`monthIndex`	`number`	The month (0-11).
`date`	`number`	The day of the month.

Returns

Date

The new date object.

Since

9.5.0

today()

today(): Date

Defined in: src/classes/DateLib.ts:179

Creates a new date object to the today's date.

Returns

Date

The new date object.

Since

9.5.0

Properties

Common Helpers

format()

format: (date, formatStr, options?) => string

Defined in: src/classes/DateLib.ts:378

Formats the given date using the specified format string.

Parameters

Parameter	Type	Description
`date`	`string` \| `number` \| `Date`	The original date
`formatStr`	`string`	-
`options?`	`FormatOptions`	An object with options

Returns

string

The formatted date string

Name

format

Alias

formatDate

Description

Return the formatted date string in the given format. The result may vary by locale.

⚠️ Please note that the format tokens differ from Moment.js and other libraries. See: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md

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:

Unit	Pattern	Result examples	Notes
Era	G..GGG	AD, BC
	GGGG	Anno Domini, Before Christ	2
	GGGGG	A, B
Calendar year	y	44, 1, 1900, 2017	5
	yo	44th, 1st, 0th, 17th	5,7
	yy	44, 01, 00, 17	5
	yyy	044, 001, 1900, 2017	5
	yyyy	0044, 0001, 1900, 2017	5
	yyyyy	...	3,5
Local week-numbering year	Y	44, 1, 1900, 2017	5
	Yo	44th, 1st, 1900th, 2017th	5,7
	YY	44, 01, 00, 17	5,8
	YYY	044, 001, 1900, 2017	5
	YYYY	0044, 0001, 1900, 2017	5,8
	YYYYY	...	3,5
ISO week-numbering year	R	-43, 0, 1, 1900, 2017	5,7
	RR	-43, 00, 01, 1900, 2017	5,7
	RRR	-043, 000, 001, 1900, 2017	5,7
	RRRR	-0043, 0000, 0001, 1900, 2017	5,7
	RRRRR	...	3,5,7
Extended year	u	-43, 0, 1, 1900, 2017	5
	uu	-43, 01, 1900, 2017	5
	uuu	-043, 001, 1900, 2017	5
	uuuu	-0043, 0001, 1900, 2017	5
	uuuuu	...	3,5
Quarter (formatting)	Q	1, 2, 3, 4
	Qo	1st, 2nd, 3rd, 4th	7
	QQ	01, 02, 03, 04
	QQQ	Q1, Q2, Q3, Q4
	QQQQ	1st quarter, 2nd quarter, ...	2
	QQQQQ	1, 2, 3, 4	4
Quarter (stand-alone)	q	1, 2, 3, 4
	qo	1st, 2nd, 3rd, 4th	7
	qq	01, 02, 03, 04
	qqq	Q1, Q2, Q3, Q4
	qqqq	1st quarter, 2nd quarter, ...	2
	qqqqq	1, 2, 3, 4	4
Month (formatting)	M	1, 2, ..., 12
	Mo	1st, 2nd, ..., 12th	7
	MM	01, 02, ..., 12
	MMM	Jan, Feb, ..., Dec
	MMMM	January, February, ..., December	2
	MMMMM	J, F, ..., D
Month (stand-alone)	L	1, 2, ..., 12
	Lo	1st, 2nd, ..., 12th	7
	LL	01, 02, ..., 12
	LLL	Jan, Feb, ..., Dec
	LLLL	January, February, ..., December	2
	LLLLL	J, F, ..., D
Local week of year	w	1, 2, ..., 53
	wo	1st, 2nd, ..., 53th	7
	ww	01, 02, ..., 53
ISO week of year	I	1, 2, ..., 53	7
	Io	1st, 2nd, ..., 53th	7
	II	01, 02, ..., 53	7
Day of month	d	1, 2, ..., 31
	do	1st, 2nd, ..., 31st	7
	dd	01, 02, ..., 31
Day of year	D	1, 2, ..., 365, 366	9
	Do	1st, 2nd, ..., 365th, 366th	7
	DD	01, 02, ..., 365, 366	9
	DDD	001, 002, ..., 365, 366
	DDDD	...	3
Day of week (formatting)	E..EEE	Mon, Tue, Wed, ..., Sun
	EEEE	Monday, Tuesday, ..., Sunday	2
	EEEEE	M, T, W, T, F, S, S
	EEEEEE	Mo, Tu, We, Th, Fr, Sa, Su
ISO day of week (formatting)	i	1, 2, 3, ..., 7	7
	io	1st, 2nd, ..., 7th	7
	ii	01, 02, ..., 07	7
	iii	Mon, Tue, Wed, ..., Sun	7
	iiii	Monday, Tuesday, ..., Sunday	2,7
	iiiii	M, T, W, T, F, S, S	7
	iiiiii	Mo, Tu, We, Th, Fr, Sa, Su	7
Local day of week (formatting)	e	2, 3, 4, ..., 1
	eo	2nd, 3rd, ..., 1st	7
	ee	02, 03, ..., 01
	eee	Mon, Tue, Wed, ..., Sun
	eeee	Monday, Tuesday, ..., Sunday	2
	eeeee	M, T, W, T, F, S, S
	eeeeee	Mo, Tu, We, Th, Fr, Sa, Su
Local day of week (stand-alone)	c	2, 3, 4, ..., 1
	co	2nd, 3rd, ..., 1st	7
	cc	02, 03, ..., 01
	ccc	Mon, Tue, Wed, ..., Sun
	cccc	Monday, Tuesday, ..., Sunday	2
	ccccc	M, T, W, T, F, S, S
	cccccc	Mo, Tu, We, Th, Fr, Sa, Su
AM, PM	a..aa	AM, PM
	aaa	am, pm
	aaaa	a.m., p.m.	2
	aaaaa	a, p
AM, PM, noon, midnight	b..bb	AM, PM, noon, midnight
	bbb	am, pm, noon, midnight
	bbbb	a.m., p.m., noon, midnight	2
	bbbbb	a, p, n, mi
Flexible day period	B..BBB	at night, in the morning, ...
	BBBB	at night, in the morning, ...	2
	BBBBB	at night, in the morning, ...
Hour [1-12]	h	1, 2, ..., 11, 12
	ho	1st, 2nd, ..., 11th, 12th	7
	hh	01, 02, ..., 11, 12
Hour [0-23]	H	0, 1, 2, ..., 23
	Ho	0th, 1st, 2nd, ..., 23rd	7
	HH	00, 01, 02, ..., 23
Hour [0-11]	K	1, 2, ..., 11, 0
	Ko	1st, 2nd, ..., 11th, 0th	7
	KK	01, 02, ..., 11, 00
Hour [1-24]	k	24, 1, 2, ..., 23
	ko	24th, 1st, 2nd, ..., 23rd	7
	kk	24, 01, 02, ..., 23
Minute	m	0, 1, ..., 59
	mo	0th, 1st, ..., 59th	7
	mm	00, 01, ..., 59
Second	s	0, 1, ..., 59
	so	0th, 1st, ..., 59th	7
	ss	00, 01, ..., 59
Fraction of second	S	0, 1, ..., 9
	SS	00, 01, ..., 99
	SSS	000, 001, ..., 999
	SSSS	...	3
Timezone (ISO-8601 w/ Z)	X	-08, +0530, Z
	XX	-0800, +0530, Z
	XXX	-08:00, +05:30, Z
	XXXX	-0800, +0530, Z, +123456	2
	XXXXX	-08:00, +05:30, Z, +12:34:56
Timezone (ISO-8601 w/o Z)	x	-08, +0530, +00
	xx	-0800, +0530, +0000
	xxx	-08:00, +05:30, +00:00	2
	xxxx	-0800, +0530, +0000, +123456
	xxxxx	-08:00, +05:30, +00:00, +12:34:56
Timezone (GMT)	O...OOO	GMT-8, GMT+5:30, GMT+0
	OOOO	GMT-08:00, GMT+05:30, GMT+00:00	2
Timezone (specific non-locat.)	z...zzz	GMT-8, GMT+5:30, GMT+0	6
	zzzz	GMT-08:00, GMT+05:30, GMT+00:00	2,6
Seconds timestamp	t	`5129695`	7
	tt	...	3,7
Milliseconds timestamp	T	`5129695`	7
	TT	...	3,7
Long localized date	P	04/29/1453	7
	PP	Apr 29, 1453	7
	PPP	April 29th, 1453	7
	PPPP	Friday, April 29th, 1453	2,7
Long localized time	p	12:00 AM	7
	pp	12:00:00 AM	7
	ppp	12:00:00 AM GMT+2	7
	pppp	12:00:00 AM GMT+02:00	2,7
Combination of date and time	Pp	04/29/1453, 12:00 AM	7
	PPpp	Apr 29, 1453, 12:00:00 AM	7
	PPPppp	April 29th, 1453 at ...	7
	PPPPpppp	Friday, April 29th, 1453 at ...	2,7
Notes:

"Formatting" units (e.g. formatting quarter) in the default en-US locale are the same as "stand-alone" units, but are different in some languages. "Formatting" units are declined according to the rules of the language in the context of a date. "Stand-alone" units are always nominative singular:

format(new Date(2017, 10, 6), 'do LLLL', {locale: cs}) //=> '6. listopad'

format(new Date(2017, 10, 6), 'do MMMM', {locale: cs}) //=> '6. listopadu'
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(new Date(2017, 10, 6), 'MMM') //=> 'Nov'

format(new Date(2017, 10, 6), 'MMMM') //=> 'November'

format(new Date(2017, 10, 6), 'MMMMM') //=> 'N'

format(new Date(2017, 10, 6), 'MMMMMM') //=> 'November'

format(new Date(2017, 10, 6), 'MMMMMMM') //=> 'November'
Some patterns could be unlimited length (such as yyyyyyyy). The output will be padded with zeros to match the length of the pattern.

format(new Date(2017, 10, 6), 'yyyyyyyy') //=> '00002017'
QQQQQ and qqqqq could be not strictly numerical in some locales. These tokens represent the shortest form of the quarter.
The main difference between y and u patterns are B.C. years:

Year y u
AC 1 1 1
BC 1 1 0
BC 2 2 -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:

Year yy uu
1 01 01
14 14 14
376 76 376
1453 53 1453

The same difference is true for local and ISO week-numbering years (Y and R), except local week-numbering years are dependent on options.weekStartsOn and options.firstWeekContainsDate (compare getISOWeekYear and getWeekYear).
Specific non-location timezones are currently unavailable in date-fns, so right now these tokens fall back to GMT timezones.
These patterns are not in the Unicode Technical Standard #35:
- i: ISO day of week
- I: ISO week of year
- R: ISO week-numbering year
- t: seconds timestamp
- T: milliseconds timestamp
- o: ordinal number modifier
- P: long localized date
- p: long localized time
YY and YYYY tokens represent week-numbering years but they are often confused with years. You should enable options.useAdditionalWeekYearTokens to use them. See: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md
D and DD tokens represent days of the year but they are often confused with days of the month. You should enable options.useAdditionalDayOfYearTokens to use them. See: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md

Year	`y`	`u`
AC 1	1	1
BC 1	1	0
BC 2	2	-1

Year	`yy`	`uu`
1	01	01
14	14	14
376	76	376
1453	53	1453

Throws

date must not be Invalid Date

Throws

options.locale must contain localize property

Throws

options.locale must contain formatLong property

Throws

use yyyy instead of YYYY for formatting years using [format provided] to the input [input provided]; see: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md

Throws

use yy instead of YY for formatting years using [format provided] to the input [input provided]; see: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md

Throws

use d instead of D for formatting days of the month using [format provided] to the input [input provided]; see: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md

Throws

use dd instead of DD for formatting days of the month using [format provided] to the input [input provided]; see: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md

Throws

format string contains an unescaped latin alphabet character

Examples

// Represent 11 February 2014 in middle-endian format:
const result = format(new Date(2014, 1, 11), 'MM/dd/yyyy')
//=> '02/11/2014'

// Represent 2 July 2014 in Esperanto:
import { eoLocale } from 'date-fns/locale/eo'
const result = format(new Date(2014, 6, 2), "do 'de' MMMM yyyy", {
  locale: eoLocale
})
//=> '2-a de julio 2014'

// Escape string by single quote characters:
const result = format(new Date(2014, 6, 2, 15), "h 'o''clock'")
//=> "3 o'clock"

Param

The date to format.

Param

The format string.

Returns

The formatted date string.

isAfter()

isAfter: (date, dateToCompare) => boolean

Defined in: src/classes/DateLib.ts:443

Checks if the first date is after the second date.

Parameters

Parameter	Type	Description
`date`	`string` \| `number` \| `Date`	The date that should be after the other one to return true
`dateToCompare`	`string` \| `number` \| `Date`	The date to compare with

Returns

boolean

The first date is after the second date

Name

isAfter

Description

Is the first date after the second one?

Example

// Is 10 July 1989 after 11 February 1987?
const result = isAfter(new Date(1989, 6, 10), new Date(1987, 1, 11))
//=> true

Param

The date to compare.

Param

The date to compare with.

Returns

True if the first date is after the second date.

isBefore()

isBefore: (date, dateToCompare) => boolean

Defined in: src/classes/DateLib.ts:456

Checks if the first date is before the second date.

Parameters

Parameter	Type	Description
`date`	`string` \| `number` \| `Date`	The date that should be before the other one to return true
`dateToCompare`	`string` \| `number` \| `Date`	The date to compare with

Returns

boolean

The first date is before the second date

Name

isBefore

Description

Is the first date before the second one?

Example

// Is 10 July 1989 before 11 February 1987?
const result = isBefore(new Date(1989, 6, 10), new Date(1987, 1, 11))
//=> false

Param

The date to compare.

Param

The date to compare with.

Returns

True if the first date is before the second date.

max()

max: <DateType, ResultDate>(dates, options?) => ResultDate

Defined in: src/classes/DateLib.ts:519

Returns the latest date in the given array of dates.

Type Parameters

Type Parameter	Default type	Description
`DateType` extends `Date`	-	The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like `UTCDate`.
`ResultDate` extends `Date`	`DateType`	The result `Date` type, it is the type returned from the context function if it is passed, or inferred from the arguments.

Parameters

Parameter	Type	Description
`dates`	`DateArg`<`DateType`>[]	The dates to compare
`options?`	`MaxOptions`<`ResultDate`>	-

Returns

ResultDate

The latest of the dates

Name

max

Description

Return the latest of the given dates.

Example

// Which of these dates is the latest?
const result = max([
  new Date(1989, 6, 10),
  new Date(1987, 1, 11),
  new Date(1995, 6, 2),
  new Date(1990, 0, 1)
])
//=> Sun Jul 02 1995 00:00:00

Param

The array of dates to compare.

Returns

The latest date.

min()

min: <DateType, ResultDate>(dates, options?) => ResultDate

Defined in: src/classes/DateLib.ts:529

Returns the earliest date in the given array of dates.

Type Parameters

Type Parameter	Default type	Description
`DateType` extends `Date`	-	The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like `UTCDate`.
`ResultDate` extends `Date`	`DateType`	The result `Date` type, it is the type returned from the context function if it is passed, or inferred from the arguments.

Parameters

Parameter	Type	Description
`dates`	`DateArg`<`DateType`>[]	The dates to compare
`options?`	`MinOptions`<`ResultDate`>	-

Returns

ResultDate

The earliest of the dates

Name

min

Description

Returns the earliest of the given dates.

Example

// Which of these dates is the earliest?
const result = min([
  new Date(1989, 6, 10),
  new Date(1987, 1, 11),
  new Date(1995, 6, 2),
  new Date(1990, 0, 1)
])
//=> Wed Feb 11 1987 00:00:00

Param

The array of dates to compare.

Returns

The earliest date.

Day Helpers

addDays()

addDays: <DateType, ResultDate>(date, amount, options?) => ResultDate

Defined in: src/classes/DateLib.ts:215

Adds the specified number of days to the given date.

Type Parameters

Type Parameter	Default type	Description
`DateType` extends `Date`	-	The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like `UTCDate`.
`ResultDate` extends `Date`	`DateType`	The result `Date` type, it is the type returned from the context function if it is passed, or inferred from the arguments.

Parameters

Parameter	Type	Description
`date`	`DateArg`<`DateType`>	The date to be changed
`amount`	`number`	The amount of days to be added.
`options?`	`AddDaysOptions`<`ResultDate`>	An object with options

Returns

ResultDate

The new date with the days added

Name

addDays

Description

Add the specified number of days to the given date.

Example

// Add 10 days to 1 September 2014:
const result = addDays(new Date(2014, 8, 1), 10)
//=> Thu Sep 11 2014 00:00:00

Param

The date to add days to.

Param

The number of days to add.

Returns

The new date with the days added.

differenceInCalendarDays()

differenceInCalendarDays: (laterDate, earlierDate, options?) => number

Defined in: src/classes/DateLib.ts:267

Returns the number of calendar days between the given dates.

Parameters

Parameter	Type	Description
`laterDate`	`string` \| `number` \| `Date`	The later date
`earlierDate`	`string` \| `number` \| `Date`	The earlier date
`options?`	`DifferenceInCalendarDaysOptions`	The options object

Returns

number

The number of calendar days

Name

differenceInCalendarDays

Description

Get the number of calendar days between the given dates. This means that the times are removed from the dates and then the difference in days is calculated.

Example

// How many calendar days are between
// 2 July 2011 23:00:00 and 2 July 2012 00:00:00?
const result = differenceInCalendarDays(
  new Date(2012, 6, 2, 0, 0),
  new Date(2011, 6, 2, 23, 0)
)
//=> 366
// How many calendar days are between
// 2 July 2011 23:59:00 and 3 July 2011 00:01:00?
const result = differenceInCalendarDays(
  new Date(2011, 6, 3, 0, 1),
  new Date(2011, 6, 2, 23, 59)
)
//=> 1

Param

The later date.

Param

The earlier date.

Returns

The number of calendar days between the dates.

isSameDay()

isSameDay: (laterDate, earlierDate, options?) => boolean

Defined in: src/classes/DateLib.ts:481

Checks if the given dates are on the same day.

Parameters

Parameter	Type	Description
`laterDate`	`string` \| `number` \| `Date`	The first date to check
`earlierDate`	`string` \| `number` \| `Date`	The second date to check
`options?`	`IsSameDayOptions`	An object with options

Returns

boolean

The dates are in the same day (and year and month)

Name

isSameDay

Description

Are the given dates in the same day (and year and month)?

Examples

// Are 4 September 06:00:00 and 4 September 18:00:00 in the same day?
const result = isSameDay(new Date(2014, 8, 4, 6, 0), new Date(2014, 8, 4, 18, 0))
//=> true

// Are 4 September and 4 October in the same day?
const result = isSameDay(new Date(2014, 8, 4), new Date(2014, 9, 4))
//=> false

// Are 4 September, 2014 and 4 September, 2015 in the same day?
const result = isSameDay(new Date(2014, 8, 4), new Date(2015, 8, 4))
//=> false

Param

The first date to compare.

Param

The second date to compare.

Returns

True if the dates are on the same day.

startOfDay()

startOfDay: <DateType, ResultDate>(date, options?) => ResultDate

Defined in: src/classes/DateLib.ts:577

Returns the start of the day for the given date.

Type Parameters

Type Parameter	Default type	Description
`DateType` extends `Date`	-	The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like `UTCDate`.
`ResultDate` extends `Date`	`DateType`	The result `Date` type, it is the type returned from the context function if it is passed, or inferred from the arguments.

Parameters

Parameter	Type	Description
`date`	`DateArg`<`DateType`>	The original date
`options?`	`StartOfDayOptions`<`ResultDate`>	The options

Returns

ResultDate

The start of a day

Name

startOfDay

Description

Return the start of a day for the given date. The result will be in the local timezone.

Example

// The start of a day for 2 September 2014 11:55:00:
const result = startOfDay(new Date(2014, 8, 2, 11, 55, 0))
//=> Tue Sep 02 2014 00:00:00

Param

The original date.

Returns

The start of the day.

ISO Week Helpers

endOfISOWeek()

endOfISOWeek: <DateType, ResultDate>(date, options?) => ResultDate

Defined in: src/classes/DateLib.ts:321

Returns the end of the ISO week for the given date.

Type Parameters

Type Parameter	Default type	Description
`DateType` extends `Date`	-	The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like `UTCDate`.
`ResultDate` extends `Date`	`DateType`	The result `Date` type, it is the type returned from the context function if it is passed, or inferred from the arguments.

Parameters

Parameter	Type	Description
`date`	`DateArg`<`DateType`>	The original date
`options?`	`EndOfISOWeekOptions`<`ResultDate`>	An object with options

Returns

ResultDate

The end of an ISO week

Name

endOfISOWeek

Description

Return the end of an ISO week for the given date. The result will be in the local timezone.

ISO week-numbering year: http://en.wikipedia.org/wiki/ISO_week_date

Example

// The end of an ISO week for 2 September 2014 11:55:00:
const result = endOfISOWeek(new Date(2014, 8, 2, 11, 55, 0))
//=> Sun Sep 07 2014 23:59:59.999

Param

The original date.

Returns

The end of the ISO week.

getISOWeek()

getISOWeek: (date, options?) => number

Defined in: src/classes/DateLib.ts:394

Returns the ISO week number for the given date.

Parameters

Parameter	Type	Description
`date`	`string` \| `number` \| `Date`	The given date
`options?`	`GetISOWeekOptions`	The options

Returns

number

The ISO week

Name

getISOWeek

Description

Get the ISO week of the given date.

ISO week-numbering year: http://en.wikipedia.org/wiki/ISO_week_date

Example

// Which week of the ISO-week numbering year is 2 January 2005?
const result = getISOWeek(new Date(2005, 0, 2))
//=> 53

Param

The date to get the ISO week number for.

Returns

The ISO week number.

startOfISOWeek()

startOfISOWeek: <DateType, ResultDate>(date, options?) => ResultDate

Defined in: src/classes/DateLib.ts:589

Returns the start of the ISO week for the given date.

Type Parameters

Type Parameter	Default type	Description
`DateType` extends `Date`	-	The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like `UTCDate`.
`ResultDate` extends `Date`	`DateType`	The result `Date` type, it is the type returned from the context function if it is passed, or inferred from the arguments.

Parameters

Parameter	Type	Description
`date`	`DateArg`<`DateType`>	The original date
`options?`	`StartOfISOWeekOptions`<`ResultDate`>	An object with options

Returns

ResultDate

The start of an ISO week

Name

startOfISOWeek

Description

Return the start of an ISO week for the given date. The result will be in the local timezone.

ISO week-numbering year: http://en.wikipedia.org/wiki/ISO_week_date

Example

// The start of an ISO week for 2 September 2014 11:55:00:
const result = startOfISOWeek(new Date(2014, 8, 2, 11, 55, 0))
//=> Mon Sep 01 2014 00:00:00

Param

The original date.

Returns

The start of the ISO week.

Interval Helpers

eachMonthOfInterval()

eachMonthOfInterval: <IntervalType, Options>(interval, options?) => EachMonthOfIntervalResult<IntervalType, Options>

Defined in: src/classes/DateLib.ts:297

Returns the months between the given dates.

Type Parameters

Type Parameter	Default type	Description
`IntervalType` extends `Interval`<`DateArg`<`Date`>, `DateArg`<`Date`>>	-	Interval type.
`Options` extends `undefined` \| `EachMonthOfIntervalOptions`<`Date`>	`undefined`	Options type.

Parameters

Parameter	Type	Description
`interval`	`IntervalType`	The interval.
`options?`	`Options`	An object with options.

Returns

EachMonthOfIntervalResult<IntervalType, Options>

The array with starts of months from the month of the interval start to the month of the interval end

Name

eachMonthOfInterval

Description

Return the array of months within the specified time interval.

Example

// Each month between 6 February 2014 and 10 August 2014:
const result = eachMonthOfInterval({
  start: new Date(2014, 1, 6),
  end: new Date(2014, 7, 10)
})
//=> [
//   Sat Feb 01 2014 00:00:00,
//   Sat Mar 01 2014 00:00:00,
//   Tue Apr 01 2014 00:00:00,
//   Thu May 01 2014 00:00:00,
//   Sun Jun 01 2014 00:00:00,
//   Tue Jul 01 2014 00:00:00,
//   Fri Aug 01 2014 00:00:00
// ]

Param

The interval to get the months for.

Month Helpers

addMonths()

addMonths: <DateType, ResultDate>(date, amount, options?) => ResultDate

Defined in: src/classes/DateLib.ts:228

Adds the specified number of months to the given date.

Type Parameters

Type Parameter	Default type	Description
`DateType` extends `Date`	-	The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like `UTCDate`.
`ResultDate` extends `Date`	`DateType`	The result `Date` type, it is the type returned from the context function if it is passed, or inferred from the arguments.

Parameters

Parameter	Type	Description
`date`	`DateArg`<`DateType`>	The date to be changed
`amount`	`number`	The amount of months to be added.
`options?`	`AddMonthsOptions`<`ResultDate`>	The options object

Returns

ResultDate

The new date with the months added

Name

addMonths

Description

Add the specified number of months to the given date.

Example

// Add 5 months to 1 September 2014:
const result = addMonths(new Date(2014, 8, 1), 5)
//=> Sun Feb 01 2015 00:00:00

// Add one month to 30 January 2023:
const result = addMonths(new Date(2023, 0, 30), 1)
//=> Tue Feb 28 2023 00:00:00

Param

The date to add months to.

Param

The number of months to add.

Returns

The new date with the months added.

differenceInCalendarMonths()

differenceInCalendarMonths: (laterDate, earlierDate, options?) => number

Defined in: src/classes/DateLib.ts:283

Returns the number of calendar months between the given dates.

Parameters

Parameter	Type	Description
`laterDate`	`string` \| `number` \| `Date`	The later date
`earlierDate`	`string` \| `number` \| `Date`	The earlier date
`options?`	`DifferenceInCalendarMonthsOptions`	An object with options

Returns

number

The number of calendar months

Name

differenceInCalendarMonths

Description

Get the number of calendar months between the given dates.

Example

// How many calendar months are between 31 January 2014 and 1 September 2014?
const result = differenceInCalendarMonths(
  new Date(2014, 8, 1),
  new Date(2014, 0, 31)
)
//=> 8

Param

The later date.

Param

The earlier date.

Returns

The number of calendar months between the dates.

endOfMonth()

endOfMonth: <DateType, ResultDate>(date, options?) => ResultDate

Defined in: src/classes/DateLib.ts:333

Returns the end of the month for the given date.

Type Parameters

Type Parameter	Default type	Description
`DateType` extends `Date`	-	The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like `UTCDate`.
`ResultDate` extends `Date`	`DateType`	The result `Date` type, it is the type returned from the context function if it is passed, or inferred from the arguments.

Parameters

Parameter	Type	Description
`date`	`DateArg`<`DateType`>	The original date
`options?`	`EndOfMonthOptions`<`ResultDate`>	An object with options

Returns

ResultDate

The end of a month

Name

endOfMonth

Description

Return the end of a month for the given date. The result will be in the local timezone.

Example

// The end of a month for 2 September 2014 11:55:00:
const result = endOfMonth(new Date(2014, 8, 2, 11, 55, 0))
//=> Tue Sep 30 2014 23:59:59.999

Param

The original date.

Returns

The end of the month.

getMonth()

getMonth: (date, options?) => number

Defined in: src/classes/DateLib.ts:406

Returns the month of the given date.

Parameters

Parameter	Type	Description
`date`	`string` \| `number` \| `Date`	The given date
`options?`	`GetMonthOptions`	An object with options

Returns

number

The month index (0-11)

Name

getMonth

Description

Get the month of the given date.

Example

// Which month is 29 February 2012?
const result = getMonth(new Date(2012, 1, 29))
//=> 1

Param

The date to get the month for.

Returns

The month.

isSameMonth()

isSameMonth: (laterDate, earlierDate, options?) => boolean

Defined in: src/classes/DateLib.ts:494

Checks if the given dates are in the same month.

Parameters

Parameter	Type	Description
`laterDate`	`string` \| `number` \| `Date`	The first date to check
`earlierDate`	`string` \| `number` \| `Date`	The second date to check
`options?`	`IsSameMonthOptions`	An object with options

Returns

boolean

The dates are in the same month (and year)

Name

isSameMonth

Description

Are the given dates in the same month (and year)?

Examples

// Are 2 September 2014 and 25 September 2014 in the same month?
const result = isSameMonth(new Date(2014, 8, 2), new Date(2014, 8, 25))
//=> true

// Are 2 September 2014 and 25 September 2015 in the same month?
const result = isSameMonth(new Date(2014, 8, 2), new Date(2015, 8, 25))
//=> false

Param

The first date to compare.

Param

The second date to compare.

Returns

True if the dates are in the same month.

setMonth()

setMonth: <DateType, ResultDate>(date, month, options?) => ResultDate

Defined in: src/classes/DateLib.ts:540

Sets the month of the given date.

Type Parameters

Type Parameter	Default type	Description
`DateType` extends `Date`	-	The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like `UTCDate`.
`ResultDate` extends `Date`	`DateType`	The result `Date` type, it is the type returned from the context function if it is passed, or inferred from the arguments.

Parameters

Parameter	Type	Description
`date`	`DateArg`<`DateType`>	The date to be changed
`month`	`number`	The month index to set (0-11)
`options?`	`SetMonthOptions`<`ResultDate`>	The options

Returns

ResultDate

The new date with the month set

Name

setMonth

Description

Set the month to the given date.

Example

// Set February to 1 September 2014:
const result = setMonth(new Date(2014, 8, 1), 1)
//=> Sat Feb 01 2014 00:00:00

Param

The date to set the month on.

Param

The month to set (0-11).

Returns

The new date with the month set.

startOfMonth()

startOfMonth: <DateType, ResultDate>(date, options?) => ResultDate

Defined in: src/classes/DateLib.ts:601

Returns the start of the month for the given date.

Type Parameters

Type Parameter	Default type	Description
`DateType` extends `Date`	-	The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like `UTCDate`.
`ResultDate` extends `Date`	`DateType`	The result `Date` type, it is the type returned from the context function if it is passed, or inferred from the arguments.

Parameters

Parameter	Type	Description
`date`	`DateArg`<`DateType`>	The original date
`options?`	`StartOfMonthOptions`<`ResultDate`>	An object with options

Returns

ResultDate

The start of a month

Name

startOfMonth

Description

Return the start of a month for the given date. The result will be in the local timezone.

Example

// The start of a month for 2 September 2014 11:55:00:
const result = startOfMonth(new Date(2014, 8, 2, 11, 55, 0))
//=> Mon Sep 01 2014 00:00:00

Param

The original date.

Returns

The start of the month.

Other

Date

Date: DateConstructor

Defined in: src/classes/DateLib.ts:171

Reference to the built-in Date constructor.

Deprecated

Use newDate() or today().

endOfBroadcastWeek()

endOfBroadcastWeek: (date, dateLib) => Date

Defined in: src/classes/DateLib.ts:309

Returns the end of the broadcast week for the given date.

Return the end date of the week in the broadcast calendar.

Parameters

Parameter	Type
`date`	`Date`
`dateLib`	`DateLib`

Returns

Date

Since

9.4.0

Param

The original date.

Returns

The end of the broadcast week.

isDate()

isDate: (value) => value is Date

Defined in: src/classes/DateLib.ts:468

Checks if the given value is a Date object.

Parameters

Parameter	Type	Description
`value`	`unknown`	The value to check.

Returns

value is Date

True if the value is a Date object.

options

readonly options: DateLibOptions

Defined in: src/classes/DateLib.ts:104

The options for the date library.

overrides?

readonly optional overrides: Partial<DateLib>

Defined in: src/classes/DateLib.ts:107

Overrides for the date library functions.

startOfBroadcastWeek()

startOfBroadcastWeek: (date, dateLib) => Date

Defined in: src/classes/DateLib.ts:565

Returns the start of the broadcast week for the given date.

Return the start date of the week in the broadcast calendar.

Parameters

Parameter	Type
`date`	`Date`
`dateLib`	`DateLib`

Returns

Date

Since

9.4.0

Param

The original date.

Returns

The start of the broadcast week.

Week Helpers

addWeeks()

addWeeks: <DateType, ResultDate>(date, amount, options?) => ResultDate

Defined in: src/classes/DateLib.ts:241

Adds the specified number of weeks to the given date.

Type Parameters

Type Parameter	Default type	Description
`DateType` extends `Date`	-	The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like `UTCDate`.
`ResultDate` extends `Date`	`DateType`	The result `Date` type, it is the type returned from the context function if it is passed, or inferred from the arguments.

Parameters

Parameter	Type	Description
`date`	`DateArg`<`DateType`>	The date to be changed
`amount`	`number`	The amount of weeks to be added.
`options?`	`AddWeeksOptions`<`ResultDate`>	An object with options

Returns

ResultDate

The new date with the weeks added

Name

addWeeks

Description

Add the specified number of weeks to the given date.

Example

// Add 4 weeks to 1 September 2014:
const result = addWeeks(new Date(2014, 8, 1), 4)
//=> Mon Sep 29 2014 00:00:00

Param

The date to add weeks to.

Param

The number of weeks to add.

Returns

The new date with the weeks added.

endOfWeek()

endOfWeek: <DateType, ResultDate>(date, options?) => ResultDate

Defined in: src/classes/DateLib.ts:345

Returns the end of the week for the given date.

Type Parameters

Type Parameter	Default type	Description
`DateType` extends `Date`	-	The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like `UTCDate`.
`ResultDate` extends `Date`	`DateType`	The result `Date` type, it is the type returned from the context function if it is passed, or inferred from the arguments.

Parameters

Parameter	Type	Description
`date`	`DateArg`<`DateType`>	The original date
`options?`	`EndOfWeekOptions`<`ResultDate`>	An object with options

Returns

ResultDate

The end of a week

Name

endOfWeek

Description

Return the end of a week for the given date. The result will be in the local timezone.

Examples

// The end of a week for 2 September 2014 11:55:00:
const result = endOfWeek(new Date(2014, 8, 2, 11, 55, 0))
//=> Sat Sep 06 2014 23:59:59.999

// If the week starts on Monday, the end of the week for 2 September 2014 11:55:00:
const result = endOfWeek(new Date(2014, 8, 2, 11, 55, 0), { weekStartsOn: 1 })
//=> Sun Sep 07 2014 23:59:59.999

Param

The original date.

Returns

The end of the week.

getWeek()

getWeek: (date, options?) => number

Defined in: src/classes/DateLib.ts:430

Returns the local week number for the given date.

Parameters

Parameter	Type	Description
`date`	`string` \| `number` \| `Date`	The given date
`options?`	`GetWeekOptions`	An object with options

Returns

number

The week

Name

getWeek

Description

Get the local week index of the given date. The exact calculation depends on the values of options.weekStartsOn (which is the index of the first day of the week) and options.firstWeekContainsDate (which is the day of January, which is always in the first week of the week-numbering year)

Week numbering: https://en.wikipedia.org/wiki/Week#The_ISO_week_date_system

Examples

// Which week of the local week numbering year is 2 January 2005 with default options?
const result = getWeek(new Date(2005, 0, 2))
//=> 2

// Which week of the local week numbering year is 2 January 2005,
// if Monday is the first day of the week,
// and the first week of the year always contains 4 January?
const result = getWeek(new Date(2005, 0, 2), {
  weekStartsOn: 1,
  firstWeekContainsDate: 4
})
//=> 53

Param

The date to get the week number for.

Returns

The week number.

startOfWeek()

startOfWeek: <DateType, ResultDate>(date, options?) => ResultDate

Defined in: src/classes/DateLib.ts:613

Returns the start of the week for the given date.

Type Parameters

Type Parameter	Default type	Description
`DateType` extends `Date`	-	The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like `UTCDate`.
`ResultDate` extends `Date`	`DateType`	The result `Date` type, it is the type returned from the context function if it is passed, or inferred from the arguments.

Parameters

Parameter	Type	Description
`date`	`DateArg`<`DateType`>	The original date
`options?`	`StartOfWeekOptions`<`ResultDate`>	An object with options

Returns

ResultDate

The start of a week

Name

startOfWeek

Description

Return the start of a week for the given date. The result will be in the local timezone.

Examples

// The start of a week for 2 September 2014 11:55:00:
const result = startOfWeek(new Date(2014, 8, 2, 11, 55, 0))
//=> Sun Aug 31 2014 00:00:00

// If the week starts on Monday, the start of the week for 2 September 2014 11:55:00:
const result = startOfWeek(new Date(2014, 8, 2, 11, 55, 0), { weekStartsOn: 1 })
//=> Mon Sep 01 2014 00:00:00

Param

The original date.

Returns

The start of the week.

Year Helpers

addYears()

addYears: <DateType, ResultDate>(date, amount, options?) => ResultDate

Defined in: src/classes/DateLib.ts:254

Adds the specified number of years to the given date.

Type Parameters

Type Parameter	Default type	Description
`DateType` extends `Date`	-	The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like `UTCDate`.
`ResultDate` extends `Date`	`DateType`	The result `Date` type.

Parameters

Parameter	Type	Description
`date`	`DateArg`<`DateType`>	The date to be changed
`amount`	`number`	The amount of years to be added.
`options?`	`AddYearsOptions`<`ResultDate`>	The options

Returns

ResultDate

The new date with the years added

Name

addYears

Description

Add the specified number of years to the given date.

Example

// Add 5 years to 1 September 2014:
const result = addYears(new Date(2014, 8, 1), 5)
//=> Sun Sep 01 2019 00:00:00

Param

The date to add years to.

Param

The number of years to add.

Returns

The new date with the years added.

endOfYear()

endOfYear: <DateType, ResultDate>(date, options?) => ResultDate

Defined in: src/classes/DateLib.ts:365

Returns the end of the year for the given date.

Type Parameters

Type Parameter	Default type	Description
`DateType` extends `Date`	-	The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like `UTCDate`.
`ResultDate` extends `Date`	`DateType`	The result `Date` type, it is the type returned from the context function if it is passed, or inferred from the arguments.

Parameters

Parameter	Type	Description
`date`	`DateArg`<`DateType`>	The original date
`options?`	`EndOfYearOptions`<`ResultDate`>	The options

Returns

ResultDate

The end of a year

Name

endOfYear

Description

Return the end of a year for the given date. The result will be in the local timezone.

Example

// The end of a year for 2 September 2014 11:55:00:
const result = endOfYear(new Date(2014, 8, 2, 11, 55, 0))
//=> Wed Dec 31 2014 23:59:59.999

Param

The original date.

Returns

The end of the year.

getYear()

getYear: (date, options?) => number

Defined in: src/classes/DateLib.ts:418

Returns the year of the given date.

Parameters

Parameter	Type	Description
`date`	`string` \| `number` \| `Date`	The given date
`options?`	`GetYearOptions`	An object with options

Returns

number

The year

Name

getYear

Description

Get the year of the given date.

Example

// Which year is 2 July 2014?
const result = getYear(new Date(2014, 6, 2))
//=> 2014

Param

The date to get the year for.

Returns

The year.

isSameYear()

isSameYear: (laterDate, earlierDate, options?) => boolean

Defined in: src/classes/DateLib.ts:507

Checks if the given dates are in the same year.

Parameters

Parameter	Type	Description
`laterDate`	`string` \| `number` \| `Date`	The first date to check
`earlierDate`	`string` \| `number` \| `Date`	The second date to check
`options?`	`IsSameYearOptions`	An object with options

Returns

boolean

The dates are in the same year

Name

isSameYear

Description

Are the given dates in the same year?

Example

// Are 2 September 2014 and 25 September 2014 in the same year?
const result = isSameYear(new Date(2014, 8, 2), new Date(2014, 8, 25))
//=> true

Param

The first date to compare.

Param

The second date to compare.

Returns

True if the dates are in the same year.

setYear()

setYear: <DateType, ResultDate>(date, year, options?) => ResultDate

Defined in: src/classes/DateLib.ts:553

Sets the year of the given date.

Type Parameters

Type Parameter	Default type	Description
`DateType` extends `Date`	-	The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like `UTCDate`.
`ResultDate` extends `Date`	`DateType`	The result `Date` type, it is the type returned from the context function if it is passed, or inferred from the arguments.

Parameters

Parameter	Type	Description
`date`	`DateArg`<`DateType`>	The date to be changed
`year`	`number`	The year of the new date
`options?`	`SetYearOptions`<`ResultDate`>	An object with options.

Returns

ResultDate

The new date with the year set

Name

setYear

Description

Set the year to the given date.

Example

// Set year 2013 to 1 September 2014:
const result = setYear(new Date(2014, 8, 1), 2013)
//=> Sun Sep 01 2013 00:00:00

Param

The date to set the year on.

Param

The year to set.

Returns

The new date with the year set.

startOfYear()

startOfYear: <DateType, ResultDate>(date, options?) => ResultDate

Defined in: src/classes/DateLib.ts:633

Returns the start of the year for the given date.

Type Parameters

Type Parameter	Default type	Description
`DateType` extends `Date`	-	The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like `UTCDate`.
`ResultDate` extends `Date`	`DateType`	The result `Date` type, it is the type returned from the context function if it is passed, or inferred from the arguments.

Parameters

Parameter	Type	Description
`date`	`DateArg`<`DateType`>	The original date
`options?`	`StartOfYearOptions`<`ResultDate`>	The options

Returns

ResultDate

The start of a year

Name

startOfYear

Description

Return the start of a year for the given date. The result will be in the local timezone.

Example

// The start of a year for 2 September 2014 11:55:00:
const result = startOfYear(new Date(2014, 8, 2, 11, 55, 00))
//=> Wed Jan 01 2014 00:00:00

Param

The original date.

Returns

The start of the year.

Since​

Example​

Constructors​

Constructor​

Parameters​

Returns​

Methods​

formatNumber()​

Parameters​

Returns​

Since​

newDate()​

Parameters​

Returns​

Since​

today()​

Returns​

Since​

Properties​

Common Helpers​

format()​

Parameters​

Returns​

Name​

Alias​

Description​

Throws​

Throws​

Throws​

Throws​

Throws​

Throws​

Throws​

Throws​

Examples​

Param​

Param​

Returns​

isAfter()​

Parameters​

Returns​

Name​

Description​

Example​

Param​

Param​

Returns​

isBefore()​

Parameters​

Returns​

Name​

Description​

Example​

Param​

Param​

Returns​

max()​

Type Parameters​

Parameters​

Returns​

Name​

Description​

Example​

Param​

Returns​

min()​

Type Parameters​

Parameters​

Returns​

Name​

Description​

Example​

Param​

Returns​

Day Helpers​

addDays()​

Type Parameters​

Parameters​

Returns​

Name​

Since

Example

Constructors

Constructor

Parameters

Returns

Methods

formatNumber()

Parameters

Returns

Since

newDate()

Parameters

Returns

Since

today()

Returns

Since

Properties

Common Helpers

format()

Parameters

Returns

Name

Alias

Description

Throws

Throws

Throws

Throws

Throws

Throws

Throws

Throws

Examples

Param

Param

Returns

isAfter()

Parameters

Returns

Name

Description

Example

Param

Param

Returns

isBefore()

Parameters

Returns

Name

Description

Example

Param

Param

Returns

max()

Type Parameters

Parameters

Returns

Name

Description

Example

Param

Returns

min()

Type Parameters

Parameters

Returns

Name

Description

Example

Param

Returns

Day Helpers

addDays()

Type Parameters

Parameters

Returns

Name