@jetblack/date-tz

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

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

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

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

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

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

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

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

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

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

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

Weeks start on Sunday and end on Saturday.

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

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

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

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

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

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

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

const days1 = endOfYear(new DateTz(2022, 3, 25, tzUtc))
console.log(days1.toISOString())
// 2022-12-31T23:59:59.999Z

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

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

const days2 = lastDayOfMonth(new DateTz(2022, 3, 25, tzLocal))
console.log(days2.toISOString())
// 2022-03-31T00:00:00.000Z

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

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

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

Note: weeks start on Sunday and end on Saturday.

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

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

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

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

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

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

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

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

// Compare with endOfYear.
const days1 = endOfYear(new DateTz(2022, 3, 25, tzUtc))
console.log(days1.toISOString())
// 2022-12-31T23:59:59.999Z

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

const date = new DateTz(2000, 0, 1, 10, 30, tzLocal)
console.log(startOfDay(date).toISOString)
// 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, DateTz } from '@jetblack/date-tz'

// Fri 7 Jan 2000
const date = addBusinessDays(new DateTz(2000, 1, 7), 1)
console.log(date.getTime() === new Date(2000, 1, 10).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, DateTz } from '@jetblack/date-tz'

// 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(new DateTz(d1, tzLocal), 3)
const d3 = addDays(new DateTz(d1, tzUtc), 3)
console.log(d1.toString()) // Sat Mar 25 2000 12:00:00 GMT+0000 (Greenwich Mean Time)
console.log(d2.date.toString()) // Tue Mar 28 2000 12:00:00 GMT+0100 (British Summer Time)
console.log(d3.date.toString()) // Tue Mar 28 2000 13:00:00 GMT+0100 (British Summer Time)

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

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

Daylight savings time is handled appropriately.

import { addHours, DateTz } from '@jetblack/date-tz'

// The local timezone here is London.
// In London on Sunday March 26 2000 the clocks go forward 1 hour.
const d1 = new DateTz(2000, 3, 26)
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, DateTz } from '@jetblack/date-tz'

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

import { addMinutes, DateTz } from '@jetblack/date-tz'

const d1 = addMinutes(new DateTz(2000, 1, 1), 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, DateTz } from '@jetblack/date-tz'

// The day of the month is kept constant if possible.
const d1 = new DateTz(2000, 1, 12, tzUtc)
console.log(d1.toString())
// Wed Jan 12 2000 00:00:00 GMT+0000 (Greenwich Mean Time)
const d2 = addMonths(d1, 1)
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 DateTz(2000, 1, 31, tzUtc)
console.log(d3.toString())
// Mon Jan 31 2000 00:00:00 GMT+0000 (Greenwich Mean Time)
const d4 = addMonths(d3, 1)
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, DateTz } from '@jetblack/date-tz'

// Saturday 1 January 1990
const d1 = new DateTz(2000, 1, 1)

// 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, DateTz } from '@jetblack/date-tz'

const d1 = addSeconds(new DateTz(2000, 1, 1), 61)
console.log(d1.toISOString())
// 2000-01-01T00:01:01.000Z

Note how surplus days for a leap year are added.

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

// There is no 29 February in 2001.
const d1 = addYears(new DateTz('2000-02-29', tzUtc), 1)
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 DateTz(2000, 2, 29, tzUtc), 4)
console.log(d2.toString())
// Sun Feb 29 2004 00:00:00 GMT+0000 (Greenwich Mean Time)

import { daysInMonth } from '@jetblack/date-tz'

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

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

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

import { daysInYear } from '@jetblack/date-tz'

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

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

The time component is ignored.

Any time component is ignored.

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

const jan30 = new DateTz(2008, 1, 30, tzLocal)
console.log(isLastDayOfQuarter(jan30))
// returns false

const mar31 = new DateTz(2008, 3, 31, tzLocal)
console.log(isLastDayOfQuarter(mar31))
// returns true

import { isLeapYear } from '@jetblack/date-tz'

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

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

import { DateTz, quarterOfYear } from '@jetblack/date-tz'

console.log(quarterOfYear(new DateTz(2000, 4, 1)))
// 2

import { areInSameQuarter, DateTz } from '@jetblack/date-tz'

console.log(areInSameQuarter(new DateTz(2000, 1, 1), new DateTz(2000, 2, 1)))
// true
console.log(areInSameQuarter(new DateTz(2000, 1, 1), new DateTz(2000, 4, 1)))
// false

import { compareDateAsc, DateTz } from '@jetblack/date-tz'

const a = [
  new DateTz(2000, 7, 1),
  new DateTz(2000, 5, 1),
  new DateTz(2000, 6, 1)
]
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, DateTz } from '@jetblack/date-tz'

const a = [
  new DateTz(2000, 7, 1),
  new DateTz(2000, 5, 1),
  new DateTz(2000, 6, 1)
]
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 { DateTz, isDateAfter } from '@jetblack/date-tz'

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

import { DateTz, isDateNotEqual } from '@jetblack/date-tz'

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

import { DateTz, isDateOnOrAfter } from '@jetblack/date-tz'

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

import { DateTz, isDateOnOrBefore } from '@jetblack/date-tz'

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

import { DateTz, maxDate } from '@jetblack/date-tz'

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

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

import { DateTz, minDate } from '@jetblack/date-tz'

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

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

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

const days1 = diffInCalDays(
  new DateTz(2022, 3, 25, tzUtc),
  new DateTz(2022, 1, 25, tzUtc)
)
console.log(days1)
// 59

// The time part is discarded.
const days2 = diffInCalDays(
  new DateTz(2022, 3, 25),
  new DateTz(2022, 1, 25)
)
console.log(days2)
// 59

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

const days1 = diffInDays(
  new DateTz(2022, 3, 25, tzUtc),
  new DateTz(2022, 1, 25, tzUtc)
)
console.log(days1)
// 59

// The time part is retained.
const days2 = diffInDays(
  new DateTz(2022, 3, 25, 12, tzUtc),
  new DateTz(2022, 1, 25, tzUtc)
)
console.log(days2)
// 59.5

import { DateTz, formatDate } from '@jetblack/date-tz'

const d = new DateTz(2000, 1, 1)
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-tz'

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

Weeks start on 1 January of any given year.

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

console.log(weekOfYear(new DateTz(1999, 12, 31, tzUtc)))
// 53
console.log(weekOfYear(new DateTz(2000, 1, 1, tzUtc)))
// 1
console.log(weekOfYear(new DateTz(2000, 1, 7, tzUtc)))
// 1
console.log(weekOfYear(new DateTz(2000, 1, 8, tzUtc)))
// 2
console.log(weekOfYear(new DateTz(2000, 12, 31, tzUtc)))
// 53

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

const d1 = new DateTz(2000, 1, 1)
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 { DateTz, dayOfYear, tzUtc } from '@jetblack/date-tz'

const d = new DateTz(2020, 7, 12)
const day = dayOfYear(d, tzUtc)
console.log(day)
// 94

import { DateTz, isValidDate } from '@jetblack/date-tz'

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

import { DateTz, isoWeekDate } from '@jetblack/date-tz'

console.log(isoWeekDate(new DateTz(2000, 1, 1)))
// [1999, 52, 6]