Add roundToNearestMinutes function (#928) (closes #787)

CHANGELOG.md

@@ -160,6 +160,8 @@ for the list of changes made since `v2.0.0-alpha.1`.
 
   - `lastDayOfDecade`
 
+- Added `roundToNearestMinutes`
+
 ### Changed
 
 - **BREAKING**: new format string API for `format` function

src/esm/fp/index.js

@@ -220,6 +220,8 @@ export {default as min} from './min/index.js'
 export {default as minWithOptions} from './minWithOptions/index.js'
 export {default as parse} from './parse/index.js'
 export {default as parseWithOptions} from './parseWithOptions/index.js'
+export {default as roundToNearestMinutes} from './roundToNearestMinutes/index.js'
+export {default as roundToNearestMinutesWithOptions} from './roundToNearestMinutesWithOptions/index.js'
 export {default as setDate} from './setDate/index.js'
 export {default as setDateWithOptions} from './setDateWithOptions/index.js'
 export {default as setDay} from './setDay/index.js'

src/esm/index.js

@@ -110,6 +110,7 @@ export {default as lastDayOfYear} from './lastDayOfYear/index.js'
 export {default as max} from './max/index.js'
 export {default as min} from './min/index.js'
 export {default as parse} from './parse/index.js'
+export {default as roundToNearestMinutes} from './roundToNearestMinutes/index.js'
 export {default as setDate} from './setDate/index.js'
 export {default as setDay} from './setDay/index.js'
 export {default as setDayOfYear} from './setDayOfYear/index.js'

src/esm/locale/index.js

@@ -1,5 +1,6 @@
 // This file is generated automatically by `scripts/build/indices.js`. Please, don't change it.
 
+export {default as af} from './af/index.js'
 export {default as bn} from './bn/index.js'
 export {default as de} from './de/index.js'
 export {default as enCA} from './en-CA/index.js'
@@ -9,6 +10,7 @@ export {default as eo} from './eo/index.js'
 export {default as es} from './es/index.js'
 export {default as et} from './et/index.js'
 export {default as fr} from './fr/index.js'
+export {default as gl} from './gl/index.js'
 export {default as he} from './he/index.js'
 export {default as hu} from './hu/index.js'
 export {default as it} from './it/index.js'

src/fp/index.js

@@ -221,6 +221,8 @@ module.exports = {
   minWithOptions: require('./minWithOptions/index.js'),
   parse: require('./parse/index.js'),
   parseWithOptions: require('./parseWithOptions/index.js'),
+  roundToNearestMinutes: require('./roundToNearestMinutes/index.js'),
+  roundToNearestMinutesWithOptions: require('./roundToNearestMinutesWithOptions/index.js'),
   setDate: require('./setDate/index.js'),
   setDateWithOptions: require('./setDateWithOptions/index.js'),
   setDay: require('./setDay/index.js'),

src/fp/index.js.flow

@@ -282,6 +282,8 @@ declare module.exports: {
   minWithOptions: CurriedFn2<Options, (Date | string | number)[], Date>,
   parse: CurriedFn3<Date | string | number, string, string, Date>,
   parseWithOptions: CurriedFn4<Options, Date | string | number, string, string, Date>,
+  roundToNearestMinutes: CurriedFn2<number, Date | string | number, Date>,
+  roundToNearestMinutesWithOptions: CurriedFn3<Options, number, Date | string | number, Date>,
   setDate: CurriedFn2<number, Date | string | number, Date>,
   setDateWithOptions: CurriedFn3<Options, number, Date | string | number, Date>,
   setDay: CurriedFn2<number, Date | string | number, Date>,

src/fp/roundToNearestMinutes/index.d.ts

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

src/fp/roundToNearestMinutes/index.js

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

src/fp/roundToNearestMinutes/index.js.flow

@@ -0,0 +1,55 @@
+// @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',
+  awareOfUnicodeTokens?: boolean
+}
+
+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<number, Date | string | number, Date>

src/fp/roundToNearestMinutesWithOptions/index.d.ts

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

src/fp/roundToNearestMinutesWithOptions/index.js

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

src/fp/roundToNearestMinutesWithOptions/index.js.flow

@@ -0,0 +1,59 @@
+// @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',
+  awareOfUnicodeTokens?: boolean
+}
+
+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
+
+type CurriedFn3<A, B, C, R> = <A>(a: A) => CurriedFn2<B, C, R>
+  | <A,B>(a: A, b: B) => CurriedFn1<C, R>
+  | <A,B,C>(a: A, b: B, c: C) => R
+
+declare module.exports: CurriedFn3<Options, number, Date | string | number, Date>

src/fp/test.js

@@ -1307,6 +1307,22 @@ describe('FP functions', function () {
     assert.deepEqual(result, new Date(2016, 10 /* Nov */, 5, 4, 4, 4, 0))
   })
 
+  it('roundToNearestMinutes', function () {
+    var result = fp.roundToNearestMinutes(5)(new Date(2014, 6 /* Jul */, 10, 12, 11, 34, 99))
+    assert.deepEqual(result, new Date(2014, 6 /* Jul */, 10, 12, 10))
+
+    var result = fp.roundToNearestMinutes()(new Date(2014, 6 /* Jul */, 10, 12, 11, 34, 99))
+    assert.deepEqual(result, new Date(2014, 6 /* Jul */, 10, 12, 11))
+  })
+
+  it('roundToNearestMinutesWithOptions', function () {
+    var result = fp.roundToNearestMinutesWithOptions({})(5)(new Date(2014, 6 /* Jul */, 10, 12, 11, 34, 99))
+    assert.deepEqual(result, new Date(2014, 6 /* Jul */, 10, 12, 10))
+
+    var result = fp.roundToNearestMinutesWithOptions({})()(new Date(2014, 6 /* Jul */, 10, 12, 11, 34, 99))
+    assert.deepEqual(result, new Date(2014, 6 /* Jul */, 10, 12, 11))
+  })
+
   it('setDate', function () {
     var result = fp.setDate(30)(new Date(2014, 8 /* Sep */, 1))
     assert.deepEqual(result, new Date(2014, 8 /* Sep */, 30))

src/index.js

@@ -111,6 +111,7 @@ module.exports = {
   max: require('./max/index.js'),
   min: require('./min/index.js'),
   parse: require('./parse/index.js'),
+  roundToNearestMinutes: require('./roundToNearestMinutes/index.js'),
   setDate: require('./setDate/index.js'),
   setDay: require('./setDay/index.js'),
   setDayOfYear: require('./setDayOfYear/index.js'),

src/index.js.flow

@@ -651,6 +651,12 @@ declare module.exports: {
     options?: Options
   ) => Date,
 
+  roundToNearestMinutes: (
+    date: Date | string | number,
+    nearestTo?: number,
+    options?: Options
+  ) => Date,
+
   setDate: (
     date: Date | string | number,
     dayOfMonth: number,

src/locale/index.js

@@ -1,6 +1,7 @@
 // This file is generated automatically by `scripts/build/indices.js`. Please, don't change it.
 
 module.exports = {
+  af: require('./af/index.js'),
   bn: require('./bn/index.js'),
   de: require('./de/index.js'),
   enCA: require('./en-CA/index.js'),
@@ -10,6 +11,7 @@ module.exports = {
   es: require('./es/index.js'),
   et: require('./et/index.js'),
   fr: require('./fr/index.js'),
+  gl: require('./gl/index.js'),
   he: require('./he/index.js'),
   hu: require('./hu/index.js'),
   it: require('./it/index.js'),

src/roundToNearestMinutes/index.d.ts

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

src/roundToNearestMinutes/index.js

@@ -0,0 +1,49 @@
+import toDate from '../toDate/index.js'
+import toInteger from '../_lib/toInteger/index.js'
+
+/**
+ * @name roundToNearestMinutes
+ * @category Minute Helpers
+ * @summary Rounds the given date to the nearest minute
+ *
+ * @description
+ * Rounds the given date to the nearest minute
+ *
+ * @param {Date|String|Number} date - the date to round
+ * @param {Number} [nearestTo=1] - the closest minute to round to, must be between 1 and 30 inclusive
+ * @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}
+ * @returns {Date} the new date rounded to the closest minute
+ * @throws {TypeError} 1 argument required
+ * @throws {RangeError} `nearestTo` must be between 1 and 30
+ *
+ * @example
+ * // Round 10 July 2014 12:12:34 to nearest minute:
+ * var result = roundToNearestMinutes(new Date(2014, 6, 10, 12, 12, 34))
+ * //=> Thu Jul 10 2014 12:13:00
+ */
+export default function roundToNearestMinutes (dirtyDate, dirtyNearestTo, dirtyOptions) {
+  if (arguments.length < 1) {
+    throw new TypeError('1 argument required, but only none provided present')
+  }
+
+  var nearestTo = arguments.length === 1 ? 1 : toInteger(dirtyNearestTo)
+
+  if (arguments.length === 2 && typeof dirtyNearestTo !== 'number' && typeof dirtyNearestTo !== 'string') {
+    dirtyOptions = dirtyNearestTo
+    nearestTo = 1
+  }
+
+  if (!nearestTo || nearestTo > 30 || nearestTo < 1) {
+    throw new RangeError('nearestTo must be between 1 and 30')
+  }
+
+  var date = toDate(dirtyDate, dirtyOptions)
+  var seconds = date.getSeconds() // relevant if nearestTo is 1, which is the default case
+  var minutes = date.getMinutes() + seconds / 60
+  var roundedMinutes = Math.floor(minutes / nearestTo) * nearestTo
+  var remainderMinutes = minutes % nearestTo
+  var addedMinutes = Math.round(remainderMinutes / nearestTo) * nearestTo
+
+  return new Date(date.getFullYear(), date.getMonth(), date.getDate(), date.getHours(), roundedMinutes + addedMinutes)
+}

src/roundToNearestMinutes/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',
+  awareOfUnicodeTokens?: boolean
+}
+
+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,
+  nearestTo?: number,
+  options?: Options
+) => Date