@jetblack/date

import { endOfDay, tzUtc } from '@jetblack/date'

const d1 = tzUtc.makeDate(2000, 1, 1)
const d2 = endOfDay(d1, tzUtc)
console.log(d2.toISOString())
// 2000-02-01T23:59:59.999Z

import { endOfHour, tzUtc } from '@jetblack/date'

const d1 = tzUtc.makeDate(2000, 1, 1)
const d2 = endOfHour(d1, tzUtc)
console.log(d2.toISOString())
// 2000-02-01T00:59:59.999Z

import { endOfMinute, tzUtc } from '@jetblack/date'

const d1 = tzUtc.makeDate(2000, 1, 1)
const d2 = endOfMinute(d1, tzUtc)
console.log(d2.toISOString())
// 2000-02-01T00:00:59.999Z

import { endOfMonth, tzUtc } from '@jetblack/date'

const days1 = endOfMonth(new Date('2022-03-25T00:00:00Z'), tzUtc)
console.log(days1.toISOString())
// 2022-03-31T23:59:59.999Z

// Compare with lastDayOfMonth.
const days2 = lastDayOfMonth(new Date('2022-03-25T00:00:00Z'), tzUtc)
console.log(days2.toISOString())
// 2022-03-31T00:00:00.000Z

import { endOfSecond, tzUtc } from '@jetblack/date'

const d1 = tzUtc.makeDate(2000, 1, 1)
const d2 = endOfSecond(d1, tzUtc)
console.log(d2.toISOString())
// 2000-02-01T00:00:00.999Z

Weeks start on Sunday and end on Saturday.

import { endOfWeek, tzUtc } from '@jetblack/date'

const days1 = endOfWeek(new Date('2022-03-25T00:00:00Z'), tzUtc)
console.log(days1.toISOString())
// 2022-03-26T23:59:59.999Z

// Compare to lastDayOfWeek
const days2 = lastDayOfWeek(new Date('2022-03-25T00:00:00Z'), tzUtc)
console.log(days2.toISOString())
// 2022-03-26T00:00:00.000Z

import { endOfWeekday, tzUtc } from '@jetblack/date'

const days1 = endOfWeekday(new Date('2022-03-25T00:00:00Z'), 1, tzUtc)
console.log(days1.toISOString())
// 2022-03-27T23:59:59.999Z

// Compare to lastDayOfWeekday
const days2 = lastDayOfWeekday(new Date('2022-03-25T00:00:00Z'), 1, tzUtc)
console.log(days2.toISOString())
// 2022-03-27T00:00:00.000Z

import { endOfYear, tzUtc } from '@jetblack/date'

const days1 = endOfYear(new Date('2022-03-25T00:00:00Z'), tzUtc)
console.log(days1.toISOString())
// 2022-12-31T23:59:59.999Z

// Compare with lastDayOfYear.
const days2 = lastDayOfYear(new Date('2022-03-25T00:00:00Z'), tzUtc)
console.log(days2.toISOString())
// 2022-12-31T00:00:00.000Z

import { lastDayOfMonth, tzUtc } from '@jetblack/date'

const days2 = lastDayOfMonth(new Date('2022-03-25T00:00:00Z'), tzUtc)
console.log(days2.toISOString())
// 2022-03-31T00:00:00.000Z

// Compare with endOfMonth.
const days1 = endOfMonth(new Date('2022-03-25T00:00:00Z'), tzUtc)
console.log(days1.toISOString())
// 2022-03-31T23:59:59.999Z

import { lastDayOfQuarter, tzLocal } from '@jetblack/date'

console.log(
  tzLocal.toISOString(lastDayOfQuarter(tzLocal.makeDate(2000, 1, 2), tzLocal))
)
// returns 2000-03-31T00:00:00-??:??

Note: weeks start on Sunday and end on Saturday.

import { lastDayOfWeek, tzUtc } from '@jetblack/date'

const days2 = lastDayOfWeek(new Date('2022-03-25T00:00:00Z'), tzUtc)
console.log(days2.toISOString())
// 2022-03-26T00:00:00.000Z

// Compare to endOfWeek
const days1 = endOfWeek(new Date('2022-03-25T00:00:00Z'), tzUtc)
console.log(days1.toISOString())
// 2022-03-26T23:59:59.999Z

import { endOfWeekday, lastDayOfWeekday, tzUtc } from '@jetblack/date'

const days2 = lastDayOfWeekday(new Date('2022-03-25T00:00:00Z'), 1, tzUtc)
console.log(days2.toISOString())
// 2022-03-27T00:00:00.000Z

// Compare to endOfWeekday
const days1 = endOfWeekday(new Date('2022-03-25T00:00:00Z'), 1, tzUtc)
console.log(days1.toISOString())
// 2022-03-27T23:59:59.999Z

import { endOfYear, lastDayOfYear, tzUtc } from '@jetblack/date'

const days2 = lastDayOfYear(new Date('2022-03-25T00:00:00Z'), tzUtc)
console.log(days2.toISOString())
// 2022-12-31T00:00:00.000Z

// Compare with endOfYear.
const days1 = endOfYear(new Date('2022-03-25T00:00:00Z'), tzUtc)
console.log(days1.toISOString())
// 2022-12-31T23:59:59.999Z

import { startOfDay, tzLocal } from '@jetblack/date'

const date = tzLocal.makeDate(2000, 0, 1, 10, 30)
console.log(tzLocal.toISOString(startOfDay(date, tzLocal)))
// returns "2000-01-01T00:00:00+??:??"

ISO weeks start on a Monday.

If a calendar is not specified the calWeekends calendar is used.

import { addBusinessDays } from '@jetblack/date'

// Fri 7 Jan 2000
const date = addBusinessDays(new Date('2000-01-07T00:00:00Z'), 1)
console.log(date.getTime() === new Date('2000-01-10T00:00:00Z').getTime())

Daylight savings time (DST) presents an issue for date arithmetic.

The following example adds three days to the Saturday before the clocks change using the local timezone (London) and UTC (which does not have DST).

When using the local timezone the "naturally correct" answer is returned. However, the elapsed time will be an hour less than when using UTC.

Keeping the time change constant (as with UTC) can be useful when plotting data, or doing time series calculations (rolling averages, resampling, etc.).

import { addDays, tzLocal, tzUtc } from '@jetblack/date'

// The local timezone here is London.
// In London on Sunday March 26 2000 the clocks go forward 1 hour.
const d1 = new Date('2000-03-25T12:00:00')
const d2 = addDays(d1, 3, tzLocal)
const d3 = addDays(d1, 3, tzUtc)
console.log(d1.toString()) // Sat Mar 25 2000 12:00:00 GMT+0000 (Greenwich Mean Time)
console.log(d2.toString()) // Tue Mar 28 2000 12:00:00 GMT+0100 (British Summer Time)
console.log(d3.toString()) // Tue Mar 28 2000 13:00:00 GMT+0100 (British Summer Time)

import { Duration, tzLocal } from '@jetblack/date'

const duration = new Duration('P1DT3H')
const date = addDuration(tzLocal.makeDate(2000, 0, 1), duration, tzLocal)

Daylight savings time is handled appropriately.

import { addHours } from '@jetblack/date'

// The local timezone here is London.
// In London on Sunday March 26 2000 the clocks go forward 1 hour.
const d1 = new Date('2000-03-26T00:00:00')
console.log(d1)
// Sun Mar 26 2000 00:00:00 GMT+0000 (Greenwich Mean Time)
const d2 = addHours(d1, 1)
console.log(d2)
// Sun Mar 26 2000 02:00:00 GMT+0100 (British Summer Time)

import { addMilliseconds } from '@jetblack/date'

const d1 = addMilliseconds(new Date('2000-01-01T00:00:00.000'), 111)
console.log(d1.toISOString())
// 2000-01-01T00:00:00.111Z

import { addMinutes } from '@jetblack/date'

const d1 = addMinutes(new Date('2000-01-01T00:00:00.000'), 5)
console.log(d1.toISOString())
// 2000-01-01T00:05:00.000Z

The day of the month is kept constant if possible. Where the destination has less days at the end of the month, the surplus days are added.

import { addMonths, tzUtc } from '@jetblack/date'

// The day of the month is kept constant if possible.
const d1 = new Date('2000-01-12')
console.log(d1.toString(), tzUtc)
// Wed Jan 12 2000 00:00:00 GMT+0000 (Greenwich Mean Time)
const d2 = addMonths(d1, 1, tzUtc)
console.log(d2.toString())
// Sat Feb 12 2000 00:00:00 GMT+0000 (Greenwich Mean Time)

// If there are less days in the following month the surplus days are added.
const d3 = new Date('2000-01-31')
console.log(d3.toString())
// Mon Jan 31 2000 00:00:00 GMT+0000 (Greenwich Mean Time)
const d4 = addMonths(d3, 1, tzUtc)
console.log(d4.toString())
// Thu Mar 02 2000 00:00:00 GMT+0000 (Greenwich Mean Time)

If the start date lies on the specified day of the week and the strictly different flag is false, the current date would be considered the first day of the week.

Note that the JavaScript Date object treats 0 as Sunday and 6 as Saturday.

import { addNthDayOfWeek } from '@jetblack/date'

// Saturday 1 January 1990
const d1 = new Date('2000-01-01T00:00:00Z')

// The third Thursday of the month.
const d2 = addNthDayOfWeek(d1, 3, 4, false)
console.log(d2)
// Thu Jan 20 2000 00:00:00 GMT+0000 (Greenwich Mean Time)

// The last Friday of the month
const d3 = addNthDayOfWeek(endOfMonth(d1), -1, 5, false)
console.log(d3)
// Fri Jan 28 2000 00:00:00 GMT+0000 (Greenwich Mean Time)

The day of the quarter is kept constant if possible. Where the destination has less days at the end of the month, the surplus days are added.

import { addSeconds } from '@jetblack/date'

const d1 = addSeconds(new Date('2000-01-01T00:00:00.000'), 61)
console.log(d1.toISOString())
// 2000-01-01T00:01:01.000Z

Note how surplus days for a leap year are added.

import { addYears, tzUtc } from '@jetblack/date'

// There is no 29 February in 2001.
const d1 = addYears(new Date('2000-02-29'), 1, tzUtc)
console.log(d1.toString())
// Thu Mar 01 2001 00:00:00 GMT+0000 (Greenwich Mean Time)

// 2004 is also a leap year.
const d2 = addYears(new Date('2000-02-29'), 4, tzUtc)
console.log(d2.toString())
// Sun Feb 29 2004 00:00:00 GMT+0000 (Greenwich Mean Time)

import { daysInMonth } from '@jetblack/date'

console.log(daysInMonth(2000, 0))
// 31

console.log(daysInMonth(2000, 1))
// 29

console.log(daysInMonth(2001, 1))
// 28

import { daysInYear } from '@jetblack/date'

console.log(daysInYear(2000))
// 366

console.log(daysInYear(2001))
// 365

The time component is ignored.

Any time component is ignored.

import { tzLocal, isLastDayOfQuarter } from '@jetblack/date'

const jan30 = tzLocal.makeDate(2008, 0, 30)
console.log(isLastDayOfQuarter(jan30, tzLocal))
// returns false

const mar31 = tzLocal.makeDate(2008, 2, 31)
console.log(isLastDayOfQuarter(mar31, tzLocal))
// returns true

import { isLeapYear } from '@jetblack/date'

// 2000 was a century leap year.
console.log(isLeapYear(2000) === true)

// 1900 was not.
console.log(isLeapYear(1900) !== true)

import { quarterOfYear } from '@jetblack/date'

console.log(quarterOfYear(new Date('2000-04-01')))
// 2

import { areInSameQuarter } from '@jetblack/date'

console.log(areInSameQuarter(new Date('2000-01-01'), new Date('2000-02-01')))
// true
console.log(areInSameQuarter(new Date('2000-01-01'), new Date('2000-04-01')))
// false

import { compareDateAsc } from '@jetblack/date'

const a = [
  new Date('2000-07-01'),
  new Date('2000-05-01'),
  new Date('2000-06-01')
]
console.log(a.sort(compareDateAsc))
// 0: Mon May 01 2000 01:00:00 GMT+0100 (British Summer Time)
// 1: Thu Jun 01 2000 01:00:00 GMT+0100 (British Summer Time)
// 2: Sat Jul 01 2000 01:00:00 GMT+0100 (British Summer Time)

import { compareDateDesc } from '@jetblack/date'

const a = [
  new Date('2000-07-01'),
  new Date('2000-05-01'),
  new Date('2000-06-01')
]
console.log(a.sort(compareDateDesc))
// 0: Sat Jul 01 2000 01:00:00 GMT+0100 (British Summer Time)
// 1: Thu Jun 01 2000 01:00:00 GMT+0100 (British Summer Time)
// 2: Mon May 01 2000 01:00:00 GMT+0100 (British Summer Time)

import { isDateAfter } from '@jetblack/date'

console.log(isDateAfter(new Date('2000-01-02'), new Date('2000-01-01')))
// returns true
console.log(isDateAfter(new Date('2000-01-01'), new Date('2000-01-02')))
// returns false
console.log(isDateAfter(new Date('2000-01-01'), new Date('2000-01-01')))
// returns false

import { isDateNotEqual } from '@jetblack/date'

console.log(isDateNotEqual(new Date('2000-01-02'), new Date('2000-01-01')))
// returns true
console.log(isDateNotEqual(new Date('2000-01-01'), new Date('2000-01-02')))
// returns true
console.log(isDateNotEqual(new Date('2000-01-01'), new Date('2000-01-01')))
// returns false

import { isDateOnOrAfter } from '@jetblack/date'

console.log(isDateOnOrAfter(new Date('2000-01-02'), new Date('2000-01-01')))
// returns true
console.log(isDateOnOrAfter(new Date('2000-01-01'), new Date('2000-01-02')))
// returns false
console.log(isDateOnOrAfter(new Date('2000-01-01'), new Date('2000-01-01')))
// returns true

import { isDateOnOrBefore } from '@jetblack/date'

console.log(isDateOnOrBefore(new Date('2000-01-02'), new Date('2000-01-01')))
// returns false
console.log(isDateOnOrBefore(new Date('2000-01-01'), new Date('2000-01-02')))
// returns true
console.log(isDateOnOrBefore(new Date('2000-01-01'), new Date('2000-01-01')))
// returns true

import { maxDate } from '@jetblack/date'

const d1 = maxDate(
  new Date('2000-01-31T00:00:00Z'),
  new Date('2000-01-01T00:00:00Z'),
  new Date('2000-01-10T00:00:00Z')
)
console.log(d1.toISOString())
// 2000-01-31T00:00:00.000Z

const dates = [
  new Date('2000-01-31T00:00:00Z'),
  new Date('2000-01-01T00:00:00Z'),
  new Date('2000-01-10T00:00:00Z')
]
const d2 = maxDate(...dates) // use the spread operator for an array.
console.log(d2.toISOString())
// 2000-01-31T00:00:00.000Z

import { minDate } from '@jetblack/date'

const d1 = minDate(
  new Date('2000-01-31T00:00:00Z'),
  new Date('2000-01-01T00:00:00Z'),
  new Date('2000-01-10T00:00:00Z')
)
console.log(d1.toISOString())
// 2000-01-01T00:00:00.000Z

const dates = [
  new Date('2000-01-31T00:00:00Z'),
  new Date('2000-01-01T00:00:00Z'),
  new Date('2000-01-10T00:00:00Z')
]
const d2 = minDate(...dates) // use the spread operator for an array
console.log(d2.toISOString())
// 2000-01-01T00:00:00.000Z

import { diffInCalDays, tzUtc } from '@jetblack/date'

const days1 = diffInCalDays(
  new Date('2022-03-25T00:00:00Z'),
  new Date('2022-01-25T00:00:00Z'),
  tzUtc
)
console.log(days1)
// 59

// The time part is discarded.
const days2 = diffInCalDays(
  new Date('2022-03-25T12:00:00Z'),
  new Date('2022-01-25T00:00:00Z'),
  tzUtc
)
console.log(days2)
// 59

import { diffInDays, tzUtc } from '@jetblack/date'

const days1 = diffInDays(
  new Date('2022-03-25T00:00:00Z'),
  new Date('2022-01-25T00:00:00Z'),
  tzUtc
)
console.log(days1)
// 59

// The time part is retained.
const days2 = diffInDays(
  new Date('2022-03-25T12:00:00Z'),
  new Date('2022-01-25T00:00:00Z'),
  tzUtc
)
console.log(days2)
// 59.5

import { formatDate } from '@jetblack/date'

const d = new Date("2000-01-01")
const s = formatDate(d, "d-mmm-yy")
console.log(s)
> 1-Jan-00

If the timezone offset is absent the dates will be according to the local timezone.

import { parseDate } from '@jetblack/date'

const d = parseDate('12 March, 1998', 'dd mmm, yyyy')

Weeks start on 1 January of any given year.

import { weekOfYear, tzUtc } from '@jetblack/date'

console.log(weekOfYear(new Date('1999-12-31T00:00:00Z'), tzUtc))
// 53
console.log(weekOfYear(new Date('2000-01-01T00:00:00Z'), tzUtc))
// 1
console.log(weekOfYear(new Date('2000-01-07T00:00:00Z'), tzUtc))
// 1
console.log(weekOfYear(new Date('2000-01-08T00:00:00Z'), tzUtc))
// 2
console.log(weekOfYear(new Date('2000-12-31T00:00:00Z'), tzUtc))
// 53

import { adjustBusinessDay, BusinessDayConvention } from '@jetblack/date'

const d1 = new Date('2000-01-01')
console.log(d1)
// Sat Jan 01 2000 00:00:00 GMT+0000 (Greenwich Mean Time)

const d2 = adjustBusinessDay(d1, BusinessDayConvention.FOLLOWING)
console.log(d2.toString())
// Mon Jan 03 2000 00:00:00 GMT+0000 (Greenwich Mean Time)

const d3 = adjustBusinessDay(d1, BusinessDayConvention.PRECEDING)
console.log(d3.toString())
// Fri Dec 31 1999 00:00:00 GMT+0000 (Greenwich Mean Time)

import { dayOfYear, tzUtc } from '@jetblack/date'

const d = new Date('2020-07-12T00:00:00Z')
const day = dayOfYear(d, tzUtc)
console.log(day)
// 94

import { isValidDate } from '@jetblack/date'

> const value = new Date("foo")
> console.log(isValidDate(value))
false