add new function roundToNearestHours

sakamossan · sakamossan · commit 59e54a232ace · 2021-11-07T12:59:34.000+09:00
diff --git a/src/fp/index.js b/src/fp/index.js
@@ -198,6 +198,8 @@ export { default as previousTuesday } from './previousTuesday/index'
 export { default as previousWednesday } from './previousWednesday/index'
 export { default as quartersToMonths } from './quartersToMonths/index'
 export { default as quartersToYears } from './quartersToYears/index'
+export { default as roundToNearestHours } from './roundToNearestHours/index'
+export { default as roundToNearestHoursWithOptions } from './roundToNearestHoursWithOptions/index'
 export { default as roundToNearestMinutes } from './roundToNearestMinutes/index'
 export { default as roundToNearestMinutesWithOptions } from './roundToNearestMinutesWithOptions/index'
 export { default as secondsToHours } from './secondsToHours/index'
diff --git a/src/fp/index.js.flow b/src/fp/index.js.flow
@@ -546,6 +546,14 @@ declare module.exports: {
   previousWednesday: CurriedFn1<Date | number, Date>,
   quartersToMonths: CurriedFn1<number, number>,
   quartersToYears: CurriedFn1<number, number>,
+  roundToNearestHours: CurriedFn1<Date | number, Date>,
+  roundToNearestHoursWithOptions: CurriedFn2<
+    {
+      nearestTo?: number,
+    },
+    Date | number,
+    Date
+  >,
   roundToNearestMinutes: CurriedFn1<Date | number, Date>,
   roundToNearestMinutesWithOptions: CurriedFn2<
     {
diff --git a/src/fp/roundToNearestHours/index.d.ts b/src/fp/roundToNearestHours/index.d.ts
@@ -0,0 +1,4 @@
+// This file is generated automatically by `scripts/build/typings.js`. Please, don't change it.
+
+import { roundToNearestHours } from 'date-fns/fp'
+export default roundToNearestHours
diff --git a/src/fp/roundToNearestHours/index.js b/src/fp/roundToNearestHours/index.js
@@ -0,0 +1,8 @@
+// This file is generated automatically by `scripts/build/fp.js`. Please, don't change it.
+
+import fn from '../../roundToNearestHours/index'
+import convertToFP from '../_lib/convertToFP/index'
+
+var roundToNearestHours = convertToFP(fn, 1)
+
+export default roundToNearestHours
diff --git a/src/fp/roundToNearestHours/index.js.flow b/src/fp/roundToNearestHours/index.js.flow
@@ -0,0 +1,54 @@
+// @flow
+// This file is generated automatically by `scripts/build/typings.js`. Please, don't change it.
+
+export type Interval = {
+  start: Date | number,
+  end: Date | number,
+}
+
+export type Locale = {
+  code?: string,
+  formatDistance?: (...args: Array<any>) => any,
+  formatRelative?: (...args: Array<any>) => any,
+  localize?: {
+    ordinalNumber: (...args: Array<any>) => any,
+    era: (...args: Array<any>) => any,
+    quarter: (...args: Array<any>) => any,
+    month: (...args: Array<any>) => any,
+    day: (...args: Array<any>) => any,
+    dayPeriod: (...args: Array<any>) => any,
+  },
+  formatLong?: {
+    date: (...args: Array<any>) => any,
+    time: (...args: Array<any>) => any,
+    dateTime: (...args: Array<any>) => any,
+  },
+  match?: {
+    ordinalNumber: (...args: Array<any>) => any,
+    era: (...args: Array<any>) => any,
+    quarter: (...args: Array<any>) => any,
+    month: (...args: Array<any>) => any,
+    day: (...args: Array<any>) => any,
+    dayPeriod: (...args: Array<any>) => any,
+  },
+  options?: {
+    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6,
+    firstWeekContainsDate?: 1 | 2 | 3 | 4 | 5 | 6 | 7,
+  },
+}
+
+export type Duration = {
+  years?: number,
+  months?: number,
+  weeks?: number,
+  days?: number,
+  hours?: number,
+  minutes?: number,
+  seconds?: number,
+}
+
+export type Day = 0 | 1 | 2 | 3 | 4 | 5 | 6
+
+type CurriedFn1<A, R> = <A>(a: A) => R
+
+declare module.exports: CurriedFn1<Date | number, Date>
diff --git a/src/fp/roundToNearestHoursWithOptions/index.d.ts b/src/fp/roundToNearestHoursWithOptions/index.d.ts
@@ -0,0 +1,4 @@
+// This file is generated automatically by `scripts/build/typings.js`. Please, don't change it.
+
+import { roundToNearestHoursWithOptions } from 'date-fns/fp'
+export default roundToNearestHoursWithOptions
diff --git a/src/fp/roundToNearestHoursWithOptions/index.js b/src/fp/roundToNearestHoursWithOptions/index.js
@@ -0,0 +1,8 @@
+// This file is generated automatically by `scripts/build/fp.js`. Please, don't change it.
+
+import fn from '../../roundToNearestHours/index'
+import convertToFP from '../_lib/convertToFP/index'
+
+var roundToNearestHoursWithOptions = convertToFP(fn, 2)
+
+export default roundToNearestHoursWithOptions
diff --git a/src/fp/roundToNearestHoursWithOptions/index.js.flow b/src/fp/roundToNearestHoursWithOptions/index.js.flow
@@ -0,0 +1,64 @@
+// @flow
+// This file is generated automatically by `scripts/build/typings.js`. Please, don't change it.
+
+export type Interval = {
+  start: Date | number,
+  end: Date | number,
+}
+
+export type Locale = {
+  code?: string,
+  formatDistance?: (...args: Array<any>) => any,
+  formatRelative?: (...args: Array<any>) => any,
+  localize?: {
+    ordinalNumber: (...args: Array<any>) => any,
+    era: (...args: Array<any>) => any,
+    quarter: (...args: Array<any>) => any,
+    month: (...args: Array<any>) => any,
+    day: (...args: Array<any>) => any,
+    dayPeriod: (...args: Array<any>) => any,
+  },
+  formatLong?: {
+    date: (...args: Array<any>) => any,
+    time: (...args: Array<any>) => any,
+    dateTime: (...args: Array<any>) => any,
+  },
+  match?: {
+    ordinalNumber: (...args: Array<any>) => any,
+    era: (...args: Array<any>) => any,
+    quarter: (...args: Array<any>) => any,
+    month: (...args: Array<any>) => any,
+    day: (...args: Array<any>) => any,
+    dayPeriod: (...args: Array<any>) => any,
+  },
+  options?: {
+    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6,
+    firstWeekContainsDate?: 1 | 2 | 3 | 4 | 5 | 6 | 7,
+  },
+}
+
+export type Duration = {
+  years?: number,
+  months?: number,
+  weeks?: number,
+  days?: number,
+  hours?: number,
+  minutes?: number,
+  seconds?: number,
+}
+
+export type Day = 0 | 1 | 2 | 3 | 4 | 5 | 6
+
+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<
+  {
+    nearestTo?: number,
+  },
+  Date | number,
+  Date
+>
diff --git a/src/index.js b/src/index.js
@@ -185,6 +185,7 @@ export { default as previousTuesday } from './previousTuesday/index'
 export { default as previousWednesday } from './previousWednesday/index'
 export { default as quartersToMonths } from './quartersToMonths/index'
 export { default as quartersToYears } from './quartersToYears/index'
+export { default as roundToNearestHours } from './roundToNearestHours/index'
 export { default as roundToNearestMinutes } from './roundToNearestMinutes/index'
 export { default as secondsToHours } from './secondsToHours/index'
 export { default as secondsToMilliseconds } from './secondsToMilliseconds/index'
diff --git a/src/index.js.flow b/src/index.js.flow
@@ -713,6 +713,13 @@ declare module.exports: {
 
   quartersToYears: (quarters: number) => number,
 
+  roundToNearestHours: (
+    date: Date | number,
+    options?: {
+      nearestTo?: number,
+    }
+  ) => Date,
+
   roundToNearestMinutes: (
     date: Date | number,
     options?: {
diff --git a/src/roundToNearestHours/index.d.ts b/src/roundToNearestHours/index.d.ts
@@ -0,0 +1,4 @@
+// This file is generated automatically by `scripts/build/typings.js`. Please, don't change it.
+
+import { roundToNearestHours } from 'date-fns'
+export default roundToNearestHours
diff --git a/src/roundToNearestHours/index.js.flow b/src/roundToNearestHours/index.js.flow
@@ -0,0 +1,57 @@
+// @flow
+// This file is generated automatically by `scripts/build/typings.js`. Please, don't change it.
+
+export type Interval = {
+  start: Date | number,
+  end: Date | number,
+}
+
+export type Locale = {
+  code?: string,
+  formatDistance?: (...args: Array<any>) => any,
+  formatRelative?: (...args: Array<any>) => any,
+  localize?: {
+    ordinalNumber: (...args: Array<any>) => any,
+    era: (...args: Array<any>) => any,
+    quarter: (...args: Array<any>) => any,
+    month: (...args: Array<any>) => any,
+    day: (...args: Array<any>) => any,
+    dayPeriod: (...args: Array<any>) => any,
+  },
+  formatLong?: {
+    date: (...args: Array<any>) => any,
+    time: (...args: Array<any>) => any,
+    dateTime: (...args: Array<any>) => any,
+  },
+  match?: {
+    ordinalNumber: (...args: Array<any>) => any,
+    era: (...args: Array<any>) => any,
+    quarter: (...args: Array<any>) => any,
+    month: (...args: Array<any>) => any,
+    day: (...args: Array<any>) => any,
+    dayPeriod: (...args: Array<any>) => any,
+  },
+  options?: {
+    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6,
+    firstWeekContainsDate?: 1 | 2 | 3 | 4 | 5 | 6 | 7,
+  },
+}
+
+export type Duration = {
+  years?: number,
+  months?: number,
+  weeks?: number,
+  days?: number,
+  hours?: number,
+  minutes?: number,
+  seconds?: number,
+}
+
+export type Day = 0 | 1 | 2 | 3 | 4 | 5 | 6
+
+declare module.exports: (
+  date: Date | number,
+  options?: {
+    nearestTo?: number,
+  }
+) => Date
diff --git a/src/roundToNearestHours/index.ts b/src/roundToNearestHours/index.ts
@@ -0,0 +1,62 @@
+import toDate from '../toDate/index'
+import toInteger from '../_lib/toInteger/index'
+
+/**
+ * @name roundToNearestHours
+ * @category Hour Helpers
+ * @summary Rounds the given date to the nearest hour
+ *
+ * @description
+ * Rounds the given date to the nearest hour (or number of hours).
+ * Rounds up when the given date is exactly between the nearest rounded hour.
+ *
+ * @param {Date|Number} date - the date to round
+ * @param {Object} [options] - an object with options.
+ * @param {Number} [options.nearestTo=1] - nearest number of hours to round to. E.g. `6` round to {00:00, 06:00, 12:00, 18:00}
+ * @returns {Date} the new date rounded to the closest hour
+ * @throws {TypeError} 1 argument required
+ * @throws {RangeError} `options.nearestTo` must be between 1 and 12
+ *
+ * @example
+ * // Round 10 July 2014 12:12:34 to nearest hour:
+ * var result = roundToNearestHours(new Date(2014, 6, 10, 12, 12, 34))
+ * //=> Thu Jul 10 2014 12:00:00
+ *
+ * @example
+ * // Round 10 July 2014 13:12:34 to nearest quarter of day:
+ * var result = roundToNearestHours(new Date(2014, 6, 10, 13, 12, 34), { nearestTo: 6 })
+ * // rounds up because given date is exactly between 12:00:00 and 18:00:00
+ * //=> Thu Jul 9 2014 12:00:00
+ */
+export default function roundToNearestHours(
+  dirtyDate: Date | number,
+  options?: { nearestTo: number }
+): Date {
+  if (arguments.length < 1) {
+    throw new TypeError(
+      '1 argument is required, but only none provided present'
+    )
+  }
+
+  const nearestTo =
+    options && 'nearestTo' in options ? toInteger(options.nearestTo) : 1
+
+  if (nearestTo < 1 || nearestTo > 12) {
+    throw new RangeError('`options.nearestTo` must be between 1 and 12')
+  }
+
+  const date = toDate(dirtyDate)
+  const minutes = date.getMinutes() // relevant if nearestTo is 1, which is the default case
+  const hours = date.getHours() + minutes / 60
+  const roundedHour = Math.floor(hours / nearestTo) * nearestTo
+  const remainderHour = hours % nearestTo
+  const addedHour = Math.round(remainderHour / nearestTo) * nearestTo
+
+  return new Date(
+    date.getFullYear(),
+    date.getMonth(),
+    date.getDate(),
+    roundedHour + addedHour,
+    0
+  )
+}
diff --git a/src/roundToNearestHours/test.ts b/src/roundToNearestHours/test.ts
@@ -0,0 +1,70 @@
+// @flow
+/* eslint-env mocha */
+
+import assert from 'power-assert'
+import roundToNearestHours from '.'
+
+describe('roundToNearestHours', function () {
+  it('rounds given date to the nearest hour by default', function () {
+    const result = roundToNearestHours(
+      new Date(2014, 6 /* Jul */, 10, 12, 16, 16)
+    )
+    assert.deepEqual(result, new Date(2014, 6 /* Jul */, 10, 12, 0, 0))
+  })
+
+  it('accepts a timestamp', function () {
+    const result = roundToNearestHours(
+      new Date(2014, 6 /* Jul */, 10, 12, 13, 16).getTime()
+    )
+    assert.deepEqual(result, new Date(2014, 6 /* Jul */, 10, 12, 0, 0))
+  })
+
+  it('rounds to the closest x hours if nearestTo is provided', function () {
+    const result = roundToNearestHours(
+      new Date(2014, 6 /* Jul */, 10, 10, 10, 30),
+      { nearestTo: 4 }
+    )
+    assert.deepEqual(result, new Date(2014, 6 /* Jul */, 10, 12, 0, 0))
+  })
+
+  it('rounds up >=30 minutes for nearestTo=1', function () {
+    const result = roundToNearestHours(
+      new Date(2014, 6 /* Jul */, 10, 12, 30, 0)
+    )
+    assert.deepEqual(result, new Date(2014, 6 /* Jul */, 10, 13, 0, 0))
+  })
+
+  it('rounds down <30 minutes for nearestTo=1', function () {
+    const result = roundToNearestHours(
+      new Date(2014, 6 /* Jul */, 10, 12, 13, 29, 999)
+    )
+    assert.deepEqual(result, new Date(2014, 6 /* Jul */, 10, 12, 0, 0))
+  })
+
+  it('does not mutate the original date', function () {
+    const date = new Date(2014, 6 /* Jul */, 10, 12, 10, 10, 99)
+    roundToNearestHours(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 () {
+    const result = roundToNearestHours(new Date(NaN))
+    assert(result instanceof Date && isNaN(result.getTime()))
+  })
+
+  it('throws `TypeError` exception if passed less than 1 argument', function () {
+    assert.throws(roundToNearestHours.bind(null), TypeError)
+  })
+
+  it('throws `RangeError` if nearestTo is not between 1 and 12', function () {
+    const date = new Date(2014, 6 /* Jul */, 10, 12, 10, 30)
+    assert.throws(
+      roundToNearestHours.bind(null, date, { nearestTo: 13 }),
+      RangeError
+    )
+    assert.throws(
+      roundToNearestHours.bind(null, date, { nearestTo: 0 }),
+      RangeError
+    )
+  })
+})
diff --git a/typings.d.ts b/typings.d.ts
