Class: DateLib

A wrapper class around date-fns sharing the same options. Methods of this class can be overridden using the PropsBase.dateLib prop.

Since

9.2.0

Example

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

Constructors

new DateLib()

new DateLib(options?, overrides?): DateLib

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

Defined in

src/classes/DateLib.ts:92

Properties

Common Helpers

format()

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

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

Summary

Format the date.

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.

Defined in

src/classes/DateLib.ts:262

isAfter()

isAfter: (date, dateToCompare) => boolean

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

Summary

Is the first date after the second one?

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.

Defined in

src/classes/DateLib.ts:299

isBefore()

isBefore: (date, dateToCompare) => boolean

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

Summary

Is the first date before the second one?

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.

Defined in

src/classes/DateLib.ts:312

max()

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

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

Summary

Return the latest of the given dates.

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.

Defined in

src/classes/DateLib.ts:375

min()

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

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

Summary

Returns the earliest of the given dates.

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.

Defined in

src/classes/DateLib.ts:385

Day Helpers

addDays()

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

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

Summary

Add the specified number of days to the given date.

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.

Defined in

src/classes/DateLib.ts:110

differenceInCalendarDays()

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

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

Summary

Get the number of calendar days between the given dates.

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.

Defined in

src/classes/DateLib.ts:162

isSameDay()

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

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

Summary

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

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.

Defined in

src/classes/DateLib.ts:337

startOfDay()

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

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

Summary

Return the start of a day for the given date.

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.

Defined in

src/classes/DateLib.ts:433

ISO Week Helpers

endOfISOWeek()

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

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

Summary

Return the end of an ISO week for the given date.

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.

Defined in

src/classes/DateLib.ts:205

getISOWeek()

getISOWeek: (date, options?) => number

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

Summary

Get the ISO week of the given date.

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.

Defined in

src/classes/DateLib.ts:274

startOfISOWeek()

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

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

Summary

Return the start of an ISO week for the given date.

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.

Defined in

src/classes/DateLib.ts:445

Month Helpers

addMonths()

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

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

Summary

Add the specified number of months to the given date.

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.

Defined in

src/classes/DateLib.ts:123

differenceInCalendarMonths()

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

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

Summary

Get the number of calendar months between the given dates.

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.

Defined in

src/classes/DateLib.ts:178

endOfMonth()

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

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

Summary

Return the end of a month for the given date.

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.

Defined in

src/classes/DateLib.ts:217

isSameMonth()

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

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

Summary

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

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.

Defined in

src/classes/DateLib.ts:350

setMonth()

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

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

Summary

Set the month to the given date.

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.

Defined in

src/classes/DateLib.ts:396

startOfMonth()

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

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

Summary

Return the start of a month for the given date.

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.

Defined in

src/classes/DateLib.ts:457

Other

Date

Date: DateConstructor

Reference to the built-in Date constructor.

Defined in

src/classes/DateLib.ts:101

endOfBroadcastWeek()

endOfBroadcastWeek: (date, dateLib) => Date

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.

Defined in

src/classes/DateLib.ts:193

isDate()

isDate: (value) => value is Date

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.

Defined in

src/classes/DateLib.ts:324

options

readonly options: DateLibOptions

The options for the date library.

Defined in

src/classes/DateLib.ts:81

overrides?

readonly optional overrides: Partial<DateLib>

Overrides for the date library functions.

Defined in

src/classes/DateLib.ts:84

startOfBroadcastWeek()

startOfBroadcastWeek: (date, dateLib) => Date

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.

Defined in

src/classes/DateLib.ts:421

Week Helpers

addWeeks()

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

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

Summary

Add the specified number of weeks to the given date.

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.

Defined in

src/classes/DateLib.ts:136

endOfWeek()

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

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

Summary

Return the end of a week for the given date.

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.

Defined in

src/classes/DateLib.ts:229

getWeek()

getWeek: (date, options?) => number

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

Summary

Get the local week index of the given date.

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.

Defined in

src/classes/DateLib.ts:286

startOfWeek()

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

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

Summary

Return the start of a week for the given date.

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.

Defined in

src/classes/DateLib.ts:469

Year Helpers

addYears()

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

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

Summary

Add the specified number of years to the given date.

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.

Defined in

src/classes/DateLib.ts:149

endOfYear()

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

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

Summary

Return the end of a year for the given date.

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.

Defined in

src/classes/DateLib.ts:249

isSameYear()

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

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

Summary

Are the given dates in the same year?

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.

Defined in

src/classes/DateLib.ts:363

setYear()

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

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

Summary

Set the year to the given date.

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.

Defined in

src/classes/DateLib.ts:409

startOfYear()

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

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

Summary

Return the start of a year for the given date.

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.

Defined in

src/classes/DateLib.ts:489

Since​

Example​

Constructors​

new DateLib()​

Parameters​

Returns​

Defined in​

Properties​

Common Helpers​

format()​

Parameters​

Returns​

Name​

Alias​

Summary​

Description​

Throws​

Throws​

Throws​

Throws​

Throws​

Throws​

Throws​

Throws​

Examples​

Param​

Param​

Returns​

Defined in​

isAfter()​

Parameters​

Returns​

Name​

Summary​

Description​

Example​

Param​

Param​

Returns​

Defined in​

isBefore()​

Parameters​

Returns​

Name​

Summary​

Description​

Example​

Param​

Param​

Returns​

Defined in​

max()​

Type Parameters​

Parameters​

Returns​

Name​

Summary​

Description​

Example​

Param​

Returns​

Defined in​

min()​

Type Parameters​

Parameters​

Returns​

Name​

Summary​

Description​

Example​

Param​

Returns​

Defined in​

Day Helpers​

addDays()​

Type Parameters​

Parameters​

Returns​

Name​

Summary​

Since

Example

Constructors

new DateLib()

Parameters

Returns

Defined in

Properties

Common Helpers

format()

Parameters

Returns

Name

Alias

Summary

Description

Throws

Throws

Throws

Throws

Throws

Throws

Throws

Throws

Examples

Param

Param

Returns

Defined in

isAfter()

Parameters

Returns

Name

Summary

Description

Example

Param

Param

Returns

Defined in

isBefore()

Parameters

Returns

Name

Summary

Description

Example

Param

Param

Returns

Defined in

max()

Type Parameters

Parameters

Returns

Name

Summary

Description

Example

Param

Returns

Defined in

min()

Type Parameters

Parameters

Returns

Name

Summary

Description

Example

Param

Returns

Defined in

Day Helpers

addDays()

Type Parameters

Parameters

Returns

Name

Summary