add new function roundToNearestMinutes

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'
@@ -8,6 +9,7 @@ export {default as enUS} from './en-US/index.js'
 export {default as eo} from './eo/index.js'
 export {default as es} from './es/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: CurriedFn1<Date | string | number, Date>,
+  roundToNearestMinutesWithOptions: CurriedFn2<Options, 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/test.js

@@ -1307,6 +1307,16 @@ describe('FP functions', function () {
     assert.deepEqual(result, new Date(2016, 10 /* Nov */, 5, 4, 4, 4, 0))
   })
 
+  it('roundToNearestMinutes', function () {
+    var result = fp.roundToNearestMinutes()(new Date(2014, 6 /* Jul */, 10, 12, 10, 34, 99))
+    assert.deepEqual(result, new Date(2014, 6 /* Jul */, 10, 12, 11))
+  })
+
+  it('roundToNearestMinutesWithOptions', function () {
+    var result = fp.addMinutesWithOptions({})()(new Date(2014, 6 /* Jul */, 10, 12, 10, 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,11 @@ declare module.exports: {
     options?: Options
   ) => Date,
 
+  roundToNearestMinutes: (
+    date: Date | string | 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'),
@@ -9,6 +10,7 @@ module.exports = {
   eo: require('./eo/index.js'),
   es: require('./es/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.js

@@ -0,0 +1,32 @@
+import toDate from '../toDate'
+
+/**
+ * @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 {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} `options.additionalDigits` must be 0, 1 or 2
+ *
+ * @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, dirtyOptions) {
+  if (arguments.length < 1) {
+    throw new TypeError('1 argument required, but only none provided present')
+  }
+
+  var date = toDate(dirtyDate, dirtyOptions)
+  var addedMinute = date.getSeconds() >= 30 ? 1 : 0
+
+  return new Date(date.getFullYear(), date.getMonth(), date.getDate(), date.getHours(), date.getMinutes() + addedMinute)
+}

src/roundToNearestMinutes/test.js

@@ -0,0 +1,57 @@
+// @flow
+/* eslint-env mocha */
+
+import assert from 'power-assert'
+import roundToNearestMinutes from '.'
+
+describe('roundToNearestMinutes', function () {
+  it('rounds given date to the nearest minute', function () {
+    var result = roundToNearestMinutes(new Date(2014, 6 /* Jul */, 10, 12, 16, 16))
+    assert.deepEqual(result, new Date(2014, 6 /* Jul */, 10, 12, 16, 0))
+  })
+
+  it('accepts a string', function () {
+    var result = roundToNearestMinutes(
+      new Date(2014, 6 /* Jul */, 10, 12, 13, 16).toISOString()
+    )
+    assert.deepEqual(result, new Date(2014, 6 /* Jul */, 10, 12, 13, 0))
+  })
+
+  it('accepts a timestamp', function () {
+    var result = roundToNearestMinutes(
+      new Date(2014, 6 /* Jul */, 10, 12, 13, 16).getTime()
+    )
+    assert.deepEqual(result, new Date(2014, 6 /* Jul */, 10, 12, 13, 0))
+  })
+
+  it('rounds up 30 seconds and above', function () {
+    var result = roundToNearestMinutes(new Date(2014, 6 /* Jul */, 10, 12, 10, 30))
+    assert.deepEqual(result, new Date(2014, 6 /* Jul */, 10, 12, 11, 0))
+  })
+
+  it('rounds down <30 seconds', function () {
+    var result = roundToNearestMinutes(new Date(2014, 6 /* Jul */, 10, 12, 13, 29, 999))
+    assert.deepEqual(result, new Date(2014, 6 /* Jul */, 10, 12, 13, 0))
+  })
+
+  it('does not mutate the original date', function () {
+    var date = new Date(2014, 6 /* Jul */, 10, 12, 10, 10, 99)
+    roundToNearestMinutes(date)
+    assert.deepEqual(date, new Date(2014, 6 /* Jul */, 10, 12, 10, 10, 99))
+  })
+
+  it('returns `Invalid Date` if the given date is invalid', function () {
+    var result = roundToNearestMinutes(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 () {
+    // $ExpectedMistake
+    var block = roundToNearestMinutes.bind(null, new Date(2014, 6 /* Jul */, 10, 12, 10, 30), {additionalDigits: NaN})
+    assert.throws(block, RangeError)
+  })
+
+  it('throws TypeError exception if passed less than 1 argument', function () {
+    assert.throws(roundToNearestMinutes.bind(null), TypeError)
+  })
+})