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
 *
 * ### v2.0.0 breaking changes:
 *
 * - [Changes that are common for the whole library](https://github.com/date-fns/date-fns/blob/master/docs/upgradeGuide.md#Common-Changes).
 *
 * @param {Date|Number} date - the date to round
 * @param {Object} [options] - an object with options.
 * @param {Number} [options.nearestTo=1] - 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.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, options) {
  if (arguments.length < 1) {
    throw new TypeError('1 argument required, but only none provided present')
  }

  var nearestTo =
    options && 'nearestTo' in options ? toInteger(options.nearestTo) : 1

  if (nearestTo < 1 || nearestTo > 30) {
    throw new RangeError('`options.nearestTo` must be between 1 and 30')
  }

  var date = toDate(dirtyDate)
  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
  )
}

@@ -265,25 +265,129 @@
 arest minute
+ (or number of minutes). %0A * Rounds up when the given date is exactly between the nearest round minutes.
 %0A
-
  *%0A * ### v2
@@ -706,80 +706,83 @@
 %5D - 
-passed to %60toDate%60. See %5BtoDate%5D%7B@link https://date-fns.org/docs/toDate%7D
+nearest number of minutes to round to. E.g. %6015%60 to round to quarter hours.
 %0A * 
@@ -1093,16 +1093,16 @@
 2, 34))%0A
-
  * //=%3E 
@@ -1126,16 +1126,291 @@
 2:13:00%0A
+ *%0A * @example%0A * // Round 10 July 2014 12:07:30 to nearest quarter hour:%0A * var result = roundToNearestMinutes(new Date(2014, 6, 10, 12, 12, 34), %7B nearestTo: 15 %7D)%0A * // rounds up because given date is exactly between 12:00:00 and 12:15:00%0A * //=%3E Thu Jul 10 2014 12:15:00%0A
  */%0Aexpo

Improve roundToNearestMinutes doc (#1516)