Add decade helpers (#839)

- getDecade
- startOfDecade
- endOfDecade
- lastDayOfDecade

src/endOfDecade/benchmark.js

@@ -0,0 +1,15 @@
+// @flow
+/* eslint-env mocha */
+/* global suite, benchmark */
+
+import endOfDecade from '.'
+
+suite('endOfDecade', function () {
+  benchmark('date-fns', function () {
+    return endOfDecade(this.date)
+  })
+}, {
+  setup: function () {
+    this.date = new Date()
+  }
+})

src/endOfDecade/index.d.ts

@@ -0,0 +1,4 @@
+// This file is generated automatically by `scripts/build/typings.js`. Please, don't change it.
+
+import {endOfDecade} from 'date-fns'
+export = endOfDecade

src/endOfDecade/index.js

@@ -0,0 +1,34 @@
+import toDate from '../toDate/index.js'
+
+/**
+ * @name endOfDecade
+ * @category Decade Helpers
+ * @summary Return the end of a decade for the given date.
+ *
+ * @description
+ * Return the end of a decade for the given date.
+ *
+ * @param {Date|String|Number} date - the original date
+ * @returns {Date} the end of a decade
+ * @param {Options} [options] - the object with options. See [Options]{@link https://date-fns.org/docs/Options}
+ * @param {0|1|2} [options.additionalDigits=2] - passed to `toDate`. See [toDate]{@link https://date-fns.org/docs/toDate}
+ * @throws {TypeError} 1 argument required
+ * @throws {RangeError} `options.additionalDigits` must be 0, 1 or 2
+ *
+ * @example
+ * // The end of a decade for 12 May 1984 00:00:00:
+ * var result = endOfDecade(new Date(1984, 4, 12, 00, 00, 00))
+ * //=> Dec 31 1989 23:59:59.999
+ */
+export default function endOfDecade (dirtyDate, dirtyOptions) {
+  if (arguments.length < 1) {
+    throw new TypeError('1 argument required, but only ' + arguments.length + ' present')
+  }
+
+  var date = toDate(dirtyDate, dirtyOptions)
+  var year = date.getFullYear()
+  var decade = 9 + Math.floor(year / 10) * 10
+  date.setFullYear(decade, 11, 31)
+  date.setHours(23, 59, 59, 999)
+  return date
+}

src/endOfDecade/index.js.flow

@@ -0,0 +1,52 @@
+// @flow
+// This file is generated automatically by `scripts/build/typings.js`. Please, don't change it.
+
+type Interval = {
+  start: Date | string | number,
+  end: Date | string | number
+}
+
+type Options = {
+  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6,
+  firstWeekContainsDate?: 1 | 2 | 3 | 4 | 5 | 6 | 7,
+  additionalDigits?: 0 | 1 | 2,
+  locale?: Locale,
+  includeSeconds?: boolean,
+  addSuffix?: boolean,
+  unit?: 'second' | 'minute' | 'hour' | 'day' | 'month' | 'year',
+  roundingMethod?: 'floor' | 'ceil' | 'round'
+}
+
+type Locale = {
+  formatDistance: Function,
+  formatRelative: Function,
+  localize: {
+    ordinalNumber: Function,
+    era: Function,
+    quarter: Function,
+    month: Function,
+    day: Function,
+    dayPeriod: Function
+  },
+  formatLong: Object,
+  date: Function,
+  time: Function,
+  dateTime: Function,
+  match: {
+    ordinalNumber: Function,
+    era: Function,
+    quarter: Function,
+    month: Function,
+    day: Function,
+    dayPeriod: Function
+  },
+  options?: {
+    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6,
+    firstWeekContainsDate?: 1 | 2 | 3 | 4 | 5 | 6 | 7
+  }
+}
+
+declare module.exports: (
+  date: Date | string | number,
+  options?: Options
+) => Date

src/endOfDecade/test.js

@@ -0,0 +1,53 @@
+// @flow
+/* eslint-env mocha */
+
+import assert from 'power-assert'
+import endOfDecade from '.'
+
+describe('endOfDecade', function () {
+  it('returns the date with the time setted to 23:59:59.999 and the date setted to the last millisecond of a decade', function () {
+    var date = new Date(2017, 3 /* Apr */, 10, 0, 0, 0)
+    var result = endOfDecade(date)
+    assert.deepEqual(result,
+      new Date(2019, 11 /* Dec */, 31, 23, 59, 59, 999)
+    )
+  })
+
+  it('accepts a string', function () {
+    var date = new Date(2004, 3 /* Apr */, 9, 0, 0, 0).toISOString()
+    var result = endOfDecade(date)
+    assert.deepEqual(result,
+      new Date(2009, 11 /* Dec */, 31, 23, 59, 59, 999)
+    )
+  })
+
+  it('accepts a timestamp', function () {
+    var date = new Date(2007, 9 /* Oct */, 10, 0, 0, 0).getTime()
+    var result = endOfDecade(date)
+    assert.deepEqual(result,
+      new Date(2009, 11 /* Dec */, 31, 23, 59, 59, 999)
+    )
+  })
+
+  it('does not mutate the original date', function () {
+    var date = new Date(2038, 0 /* Jan */, 19, 3, 14, 8)
+    endOfDecade(date)
+    assert.deepEqual(date, new Date(2038, 0 /* Jan */, 19, 3, 14, 8))
+  })
+
+  it('returns `Invalid Date` if the given date is invalid', function () {
+    var result = endOfDecade(new Date(NaN))
+    assert(result instanceof Date && isNaN(result))
+  })
+
+  it('throws `RangeError` if `options.additionalDigits` is not convertable to 0, 1, 2 or undefined`', function () {
+    var date = new Date(2018, 6 /* Jul */, 15, 0, 0, 0)
+    // $ExpectedMistake
+    var block = endOfDecade.bind(null, date, {additionalDigits: NaN})
+    assert.throws(block, RangeError)
+  })
+
+  it('throws TypeError exception if passed less than 1 argument', function () {
+    assert.throws(endOfDecade.bind(null), TypeError)
+  })
+})

src/esm/fp/index.js

@@ -70,6 +70,8 @@ export {default as eachWeekOfInterval} from './eachWeekOfInterval/index.js'
 export {default as eachWeekOfIntervalWithOptions} from './eachWeekOfIntervalWithOptions/index.js'
 export {default as endOfDay} from './endOfDay/index.js'
 export {default as endOfDayWithOptions} from './endOfDayWithOptions/index.js'
+export {default as endOfDecade} from './endOfDecade/index.js'
+export {default as endOfDecadeWithOptions} from './endOfDecadeWithOptions/index.js'
 export {default as endOfHour} from './endOfHour/index.js'
 export {default as endOfHourWithOptions} from './endOfHourWithOptions/index.js'
 export {default as endOfISOWeek} from './endOfISOWeek/index.js'
@@ -106,6 +108,8 @@ export {default as getDaysInMonth} from './getDaysInMonth/index.js'
 export {default as getDaysInMonthWithOptions} from './getDaysInMonthWithOptions/index.js'
 export {default as getDaysInYear} from './getDaysInYear/index.js'
 export {default as getDaysInYearWithOptions} from './getDaysInYearWithOptions/index.js'
+export {default as getDecade} from './getDecade/index.js'
+export {default as getDecadeWithOptions} from './getDecadeWithOptions/index.js'
 export {default as getHours} from './getHours/index.js'
 export {default as getHoursWithOptions} from './getHoursWithOptions/index.js'
 export {default as getISODay} from './getISODay/index.js'
@@ -196,6 +200,8 @@ export {default as isWeekend} from './isWeekend/index.js'
 export {default as isWeekendWithOptions} from './isWeekendWithOptions/index.js'
 export {default as isWithinInterval} from './isWithinInterval/index.js'
 export {default as isWithinIntervalWithOptions} from './isWithinIntervalWithOptions/index.js'
+export {default as lastDayOfDecade} from './lastDayOfDecade/index.js'
+export {default as lastDayOfDecadeWithOptions} from './lastDayOfDecadeWithOptions/index.js'
 export {default as lastDayOfISOWeek} from './lastDayOfISOWeek/index.js'
 export {default as lastDayOfISOWeekWithOptions} from './lastDayOfISOWeekWithOptions/index.js'
 export {default as lastDayOfISOWeekYear} from './lastDayOfISOWeekYear/index.js'
@@ -246,6 +252,8 @@ export {default as setYear} from './setYear/index.js'
 export {default as setYearWithOptions} from './setYearWithOptions/index.js'
 export {default as startOfDay} from './startOfDay/index.js'
 export {default as startOfDayWithOptions} from './startOfDayWithOptions/index.js'
+export {default as startOfDecade} from './startOfDecade/index.js'
+export {default as startOfDecadeWithOptions} from './startOfDecadeWithOptions/index.js'
 export {default as startOfHour} from './startOfHour/index.js'
 export {default as startOfHourWithOptions} from './startOfHourWithOptions/index.js'
 export {default as startOfISOWeek} from './startOfISOWeek/index.js'

src/esm/index.js

@@ -35,6 +35,7 @@ export {default as differenceInYears} from './differenceInYears/index.js'
 export {default as eachDayOfInterval} from './eachDayOfInterval/index.js'
 export {default as eachWeekOfInterval} from './eachWeekOfInterval/index.js'
 export {default as endOfDay} from './endOfDay/index.js'
+export {default as endOfDecade} from './endOfDecade/index.js'
 export {default as endOfHour} from './endOfHour/index.js'
 export {default as endOfISOWeek} from './endOfISOWeek/index.js'
 export {default as endOfISOWeekYear} from './endOfISOWeekYear/index.js'
@@ -53,6 +54,7 @@ export {default as getDay} from './getDay/index.js'
 export {default as getDayOfYear} from './getDayOfYear/index.js'
 export {default as getDaysInMonth} from './getDaysInMonth/index.js'
 export {default as getDaysInYear} from './getDaysInYear/index.js'
+export {default as getDecade} from './getDecade/index.js'
 export {default as getHours} from './getHours/index.js'
 export {default as getISODay} from './getISODay/index.js'
 export {default as getISOWeek} from './getISOWeek/index.js'
@@ -98,6 +100,7 @@ export {default as isValid} from './isValid/index.js'
 export {default as isWednesday} from './isWednesday/index.js'
 export {default as isWeekend} from './isWeekend/index.js'
 export {default as isWithinInterval} from './isWithinInterval/index.js'
+export {default as lastDayOfDecade} from './lastDayOfDecade/index.js'
 export {default as lastDayOfISOWeek} from './lastDayOfISOWeek/index.js'
 export {default as lastDayOfISOWeekYear} from './lastDayOfISOWeekYear/index.js'
 export {default as lastDayOfMonth} from './lastDayOfMonth/index.js'
@@ -123,6 +126,7 @@ export {default as setWeek} from './setWeek/index.js'
 export {default as setWeekYear} from './setWeekYear/index.js'
 export {default as setYear} from './setYear/index.js'
 export {default as startOfDay} from './startOfDay/index.js'
+export {default as startOfDecade} from './startOfDecade/index.js'
 export {default as startOfHour} from './startOfHour/index.js'
 export {default as startOfISOWeek} from './startOfISOWeek/index.js'
 export {default as startOfISOWeekYear} from './startOfISOWeekYear/index.js'

src/fp/endOfDecade/index.d.ts

@@ -0,0 +1,4 @@
+// This file is generated automatically by `scripts/build/typings.js`. Please, don't change it.
+
+import {endOfDecade} from 'date-fns/fp'
+export = endOfDecade

src/fp/endOfDecade/index.js

@@ -0,0 +1,8 @@
+// This file is generated automatically by `scripts/build/fp.js`. Please, don't change it.
+
+import fn from '../../endOfDecade/index.js'
+import convertToFP from '../_lib/convertToFP/index.js'
+
+var endOfDecade = convertToFP(fn, 1)
+
+export default endOfDecade

src/fp/endOfDecade/index.js.flow

@@ -0,0 +1,51 @@
+// @flow
+// This file is generated automatically by `scripts/build/typings.js`. Please, don't change it.
+
+type Interval = {
+  start: Date | string | number,
+  end: Date | string | number
+}
+
+type Options = {
+  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6,
+  firstWeekContainsDate?: 1 | 2 | 3 | 4 | 5 | 6 | 7,
+  additionalDigits?: 0 | 1 | 2,
+  locale?: Locale,
+  includeSeconds?: boolean,
+  addSuffix?: boolean,
+  unit?: 'second' | 'minute' | 'hour' | 'day' | 'month' | 'year',
+  roundingMethod?: 'floor' | 'ceil' | 'round'
+}
+
+type Locale = {
+  formatDistance: Function,
+  formatRelative: Function,
+  localize: {
+    ordinalNumber: Function,
+    era: Function,
+    quarter: Function,
+    month: Function,
+    day: Function,
+    dayPeriod: Function
+  },
+  formatLong: Object,
+  date: Function,
+  time: Function,
+  dateTime: Function,
+  match: {
+    ordinalNumber: Function,
+    era: Function,
+    quarter: Function,
+    month: Function,
+    day: Function,
+    dayPeriod: Function
+  },
+  options?: {
+    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6,
+    firstWeekContainsDate?: 1 | 2 | 3 | 4 | 5 | 6 | 7
+  }
+}
+
+type CurriedFn1<A, R> = <A>(a: A) => R
+
+declare module.exports: CurriedFn1<Date | string | number, Date>

src/fp/endOfDecadeWithOptions/index.d.ts

@@ -0,0 +1,4 @@
+// This file is generated automatically by `scripts/build/typings.js`. Please, don't change it.
+
+import {endOfDecadeWithOptions} from 'date-fns/fp'
+export = endOfDecadeWithOptions

src/fp/endOfDecadeWithOptions/index.js

@@ -0,0 +1,8 @@
+// This file is generated automatically by `scripts/build/fp.js`. Please, don't change it.
+
+import fn from '../../endOfDecade/index.js'
+import convertToFP from '../_lib/convertToFP/index.js'
+
+var endOfDecadeWithOptions = convertToFP(fn, 2)
+
+export default endOfDecadeWithOptions

src/fp/endOfDecadeWithOptions/index.js.flow

@@ -0,0 +1,54 @@
+// @flow
+// This file is generated automatically by `scripts/build/typings.js`. Please, don't change it.
+
+type Interval = {
+  start: Date | string | number,
+  end: Date | string | number
+}
+
+type Options = {
+  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6,
+  firstWeekContainsDate?: 1 | 2 | 3 | 4 | 5 | 6 | 7,
+  additionalDigits?: 0 | 1 | 2,
+  locale?: Locale,
+  includeSeconds?: boolean,
+  addSuffix?: boolean,
+  unit?: 'second' | 'minute' | 'hour' | 'day' | 'month' | 'year',
+  roundingMethod?: 'floor' | 'ceil' | 'round'
+}
+
+type Locale = {
+  formatDistance: Function,
+  formatRelative: Function,
+  localize: {
+    ordinalNumber: Function,
+    era: Function,
+    quarter: Function,
+    month: Function,
+    day: Function,
+    dayPeriod: Function
+  },
+  formatLong: Object,
+  date: Function,
+  time: Function,
+  dateTime: Function,
+  match: {
+    ordinalNumber: Function,
+    era: Function,
+    quarter: Function,
+    month: Function,
+    day: Function,
+    dayPeriod: Function
+  },
+  options?: {
+    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6,
+    firstWeekContainsDate?: 1 | 2 | 3 | 4 | 5 | 6 | 7
+  }
+}
+
+type CurriedFn1<A, R> = <A>(a: A) => R
+
+type CurriedFn2<A, B, R> = <A>(a: A) => CurriedFn1<B, R>
+  | <A, B>(a: A, b: B) => R
+
+declare module.exports: CurriedFn2<Options, Date | string | number, Date>

src/fp/getDecade/index.d.ts

@@ -0,0 +1,4 @@
+// This file is generated automatically by `scripts/build/typings.js`. Please, don't change it.
+
+import {getDecade} from 'date-fns/fp'
+export = getDecade

src/fp/getDecade/index.js

@@ -0,0 +1,8 @@
+// This file is generated automatically by `scripts/build/fp.js`. Please, don't change it.
+
+import fn from '../../getDecade/index.js'
+import convertToFP from '../_lib/convertToFP/index.js'
+
+var getDecade = convertToFP(fn, 1)
+
+export default getDecade