Add unit conversion functions (#2433)

Added:

- Added 18 new conversion functions:
  - `daysToWeeks`
  - `hoursToMilliseconds`
  - `hoursToMinutes`
  - `hoursToSeconds`
  - `millisecondsToHours`
  - `millisecondsToMinutes`
  - `millisecondsToSeconds`
  - `minutesToHours`
  - `minutesToMilliseconds`
  - `minutesToSeconds`
  - `monthsToQuarters`
  - `monthsToYears`
  - `quartersToMonths`
  - `quartersToYears`
  - `secondsToHours`
  - `secondsToMilliseconds`
  - `secondsToMinutes`
  - `weeksToDays`
  - `yearsToMonths`
  - `yearsToQuarters`

docs/index.js

@@ -5,6 +5,7 @@ module.exports = {
     'General',
     'Types',
     'Common Helpers',
+    'Conversion Helpers',
     'Interval Helpers',
     'Timestamp Helpers',
     'Millisecond Helpers',

src/constants/index.ts

@@ -1,13 +1,48 @@
 /**
- * Maximum allowed time.
+ *  Days in 1 week.
  *
- * @name maxTime
- * @constant
- * @type {number}
- * @default
+ *  @constant
+ *  @type {number}
+ *  @default
+ */
+export const daysInWeek = 7
+
+/**
+ *  Maximum allowed time.
+ *
+ *  @constant
+ *  @type {number}
+ *  @default
  */
 export const maxTime = Math.pow(10, 8) * 24 * 60 * 60 * 1000
 
+/**
+ *  Milliseconds in 1 minute
+ *
+ *  @constant
+ *  @type {number}
+ *  @default
+ */
+export const millisecondsInMinute = 60000
+
+/**
+ *  Milliseconds in 1 hour
+ *
+ *  @constant
+ *  @type {number}
+ *  @default
+ */
+export const millisecondsInHour = 3600000
+
+/**
+ *  Milliseconds in 1 second
+ *
+ *  @constant
+ *  @type {number}
+ *  @default
+ */
+export const millisecondsInSecond = 1000
+
 /**
  * Minimum allowed time.
  *
@@ -17,3 +52,57 @@ export const maxTime = Math.pow(10, 8) * 24 * 60 * 60 * 1000
  * @default
  */
 export const minTime = -maxTime
+
+/**
+ *  Minutes in 1 hour
+ *
+ *  @constant
+ *  @type {number}
+ *  @default
+ */
+export const minutesInHour = 60
+
+/**
+ *  Months in 1 quarter
+ *
+ *  @constant
+ *  @type {number}
+ *  @default
+ */
+export const monthsInQuarter = 3
+
+/**
+ *  Months in 1 year
+ *
+ *  @constant
+ *  @type {number}
+ *  @default
+ */
+export const monthsInYear = 12
+
+/**
+ *  Quarters in 1 year
+ *
+ *  @constant
+ *  @type {number}
+ *  @default
+ */
+export const quartersInYear = 4
+
+/**
+ *  Seconds in 1 hour
+ *
+ *  @constant
+ *  @type {number}
+ *  @default
+ */
+export const secondsInHour = 3600
+
+/**
+ *  Seconds in 1 minute
+ *
+ *  @constant
+ *  @type {number}
+ *  @default
+ */
+export const secondsInMinute = 60

src/daysToWeeks/index.ts

@@ -0,0 +1,31 @@
+import requiredArgs from '../_lib/requiredArgs/index'
+import { daysInWeek } from '../constants/index'
+
+/**
+ * @name daysToWeeks
+ * @category Conversion Helpers
+ * @summary Convert days to weeks.
+ *
+ * @description
+ * Convert a number of days to a full number of weeks.
+ *
+ * @param {number} days - number of days to be converted
+ *
+ * @returns {number} the number of days converted in weeks
+ * @throws {TypeError} 1 argument required
+ *
+ * @example
+ * // Convert 14 days to weeks:
+ * const result = daysToWeeks(14)
+ * //=> 2
+ *
+ * @example
+ * // It uses floor rounding:
+ * const result = daysToWeeks(13)
+ * //=> 1
+ */
+export default function daysToWeeks(days: number): number {
+  requiredArgs(1, arguments)
+  const weeks = days / daysInWeek
+  return Math.floor(weeks)
+}

src/daysToWeeks/test.ts

@@ -0,0 +1,21 @@
+/* eslint-env mocha */
+
+import assert from 'assert'
+import daysToWeeks from '.'
+
+describe('daysToWeeks', () => {
+  it('converts days to weeks', function () {
+    assert(daysToWeeks(7) === 1)
+    assert(daysToWeeks(14) === 2)
+  })
+
+  it('uses floor rounding', () => {
+    assert(daysToWeeks(8) === 1)
+    assert(daysToWeeks(6) === 0)
+  })
+
+  it('handles border values', () => {
+    assert(daysToWeeks(7.5) === 1)
+    assert(daysToWeeks(0) === 0)
+  })
+})

src/hoursToMilliseconds/index.ts

@@ -0,0 +1,25 @@
+import requiredArgs from '../_lib/requiredArgs/index'
+import { millisecondsInHour } from '../constants/index'
+
+/**
+ * @name hoursToMilliseconds
+ * @category  Conversion Helpers
+ * @summary Convert hours to milliseconds.
+ *
+ * @description
+ * Convert a number of hours to a full number of milliseconds.
+ *
+ * @param {number} hours - number of hours to be converted
+ *
+ * @returns {number} the number of hours converted to milliseconds
+ * @throws {TypeError} 1 argument required
+ *
+ * @example
+ * // Convert 2 hours to milliseconds:
+ * const result = hoursToMilliseconds(2)
+ * //=> 7200000
+ */
+export default function hoursToMilliseconds(hours: number): number {
+  requiredArgs(1, arguments)
+  return Math.floor(hours * millisecondsInHour)
+}

src/hoursToMilliseconds/test.ts

@@ -0,0 +1,20 @@
+/* eslint-env mocha */
+
+import assert from 'assert'
+import hoursToMilliseconds from '.'
+
+describe('hoursToMilliseconds', function () {
+  it('converts hours to milliseconds', function () {
+    assert(hoursToMilliseconds(1) === 3600000)
+    assert(hoursToMilliseconds(2) === 7200000)
+  })
+
+  it('uses floor rounding', () => {
+    assert(hoursToMilliseconds(0.123456) === 444441)
+  })
+
+  it('handles border values', () => {
+    assert(hoursToMilliseconds(1.5) === 5400000)
+    assert(hoursToMilliseconds(0) === 0)
+  })
+})

src/hoursToMinutes/index.ts

@@ -0,0 +1,25 @@
+import requiredArgs from '../_lib/requiredArgs/index'
+import { minutesInHour } from '../constants/index'
+
+/**
+ * @name hoursToMinutes
+ * @category Conversion Helpers
+ * @summary Convert hours to minutes.
+ *
+ * @description
+ * Convert a number of hours to a full number of minutes.
+ *
+ * @param {number} hours - number of hours to be converted
+ *
+ * @returns {number} the number of hours converted in minutes
+ * @throws {TypeError} 1 argument required
+ *
+ * @example
+ * // Convert 2 hours to minutes:
+ * const result = hoursToMinutes(2)
+ * //=> 120
+ */
+export default function hoursToMinutes(hours: number): number {
+  requiredArgs(1, arguments)
+  return Math.floor(hours * minutesInHour)
+}

src/hoursToMinutes/test.ts

@@ -0,0 +1,20 @@
+/* eslint-env mocha */
+
+import assert from 'assert'
+import hoursToMinutes from '.'
+
+describe('hoursToMinutes', function () {
+  it('converts hours to minutes', function () {
+    assert(hoursToMinutes(1) === 60)
+    assert(hoursToMinutes(2) === 120)
+  })
+
+  it('uses floor rounding', () => {
+    assert(hoursToMinutes(0.123) === 7)
+  })
+
+  it('handles border values', () => {
+    assert(hoursToMinutes(1.5) === 90)
+    assert(hoursToMinutes(0) === 0)
+  })
+})

src/hoursToSeconds/index.ts

@@ -0,0 +1,25 @@
+import requiredArgs from '../_lib/requiredArgs/index'
+import { secondsInHour } from '../constants/index'
+
+/**
+ * @name hoursToSeconds
+ * @category Conversion Helpers
+ * @summary Convert hours to seconds.
+ *
+ * @description
+ * Convert a number of hours to a full number of seconds.
+ *
+ * @param {number} hours - number of hours to be converted
+ *
+ * @returns {number} the number of hours converted in seconds
+ * @throws {TypeError} 1 argument required
+ *
+ * @example
+ * // Convert 2 hours to seconds:
+ * const result = hoursToSeconds(2)
+ * //=> 7200
+ */
+export default function hoursToSeconds(hours: number): number {
+  requiredArgs(1, arguments)
+  return Math.floor(hours * secondsInHour)
+}

src/hoursToSeconds/test.ts

@@ -0,0 +1,20 @@
+/* eslint-env mocha */
+
+import assert from 'assert'
+import hoursToSeconds from '.'
+
+describe('hoursToSeconds', function () {
+  it('converts hours to seconds', function () {
+    assert(hoursToSeconds(1) === 3600)
+    assert(hoursToSeconds(2) === 7200)
+  })
+
+  it('uses floor rounding', () => {
+    assert(hoursToSeconds(0.123) === 442)
+  })
+
+  it('handles border values', () => {
+    assert(hoursToSeconds(1.5) === 5400)
+    assert(hoursToSeconds(0) === 0)
+  })
+})

src/index.js

@@ -207,4 +207,24 @@ export { default as subSeconds } from './subSeconds/index'
 export { default as subWeeks } from './subWeeks/index'
 export { default as subYears } from './subYears/index'
 export { default as toDate } from './toDate/index'
+export { default as daysToWeeks } from './daysToWeeks/index'
+export { default as hoursToMilliseconds } from './hoursToMilliseconds/index'
+export { default as hoursToMinutes } from './hoursToMinutes/index'
+export { default as hoursToSeconds } from './hoursToSeconds/index'
+export { default as millisecondsToHours } from './millisecondsToHours/index'
+export { default as millisecondsToMinutes } from './millisecondsToMinutes/index'
+export { default as millisecondsToSeconds } from './millisecondsToSeconds/index'
+export { default as minutesToHours } from './minutesToHours/index'
+export { default as minutesToMilliseconds } from './minutesToMilliseconds/index'
+export { default as minutesToSeconds } from './minutesToSeconds/index'
+export { default as monthsToQuarters } from './monthsToQuarters/index'
+export { default as monthsToYears } from './monthsToYears/index'
+export { default as quartersToMonths } from './quartersToMonths/index'
+export { default as quartersToYears } from './quartersToYears/index'
+export { default as secondsToHours } from './secondsToHours/index'
+export { default as secondsToMilliseconds } from './secondsToMilliseconds/index'
+export { default as secondsToMinutes } from './secondsToMinutes/index'
+export { default as weeksToDays } from './weeksToDays/index'
+export { default as yearsToMonths } from './yearsToMonths/index'
+export { default as yearsToQuarters } from './yearsToQuarters/index'
 export * from './constants/index'

src/milliseconds/index.ts

@@ -3,7 +3,7 @@ import { Duration } from '../types'
 
 // Leap year occures every 4 years, except for years that are divisable by 100 and not divisable by 400.
 // 1 mean year = (365+1/4-1/100+1/400) days = 365.2425 days
-const yearInDays = 365.2425
+const daysInYear = 365.2425
 
 /**
  * @name milliseconds
@@ -47,8 +47,8 @@ export default function milliseconds({
 
   let totalDays = 0
 
-  if (years) totalDays += years * yearInDays
-  if (months) totalDays += months * (yearInDays / 12)
+  if (years) totalDays += years * daysInYear
+  if (months) totalDays += months * (daysInYear / 12)
   if (weeks) totalDays += weeks * 7
   if (days) totalDays += days
 

src/millisecondsToHours/index.ts

@@ -0,0 +1,31 @@
+import requiredArgs from '../_lib/requiredArgs/index'
+import { millisecondsInHour } from '../constants/index'
+
+/**
+ * @name millisecondsToHours
+ * @category Conversion Helpers
+ * @summary Convert milliseconds to hours.
+ *
+ * @description
+ * Convert a number of milliseconds to a full number of hours.
+ *
+ * @param {number} milliseconds - number of milliseconds to be converted
+ *
+ * @returns {number} the number of milliseconds converted in hours
+ * @throws {TypeError} 1 argument required
+ *
+ * @example
+ * // Convert 7200000 milliseconds to hours:
+ * const result = millisecondsToHours(7200000)
+ * //=> 2
+ *
+ * @example
+ * // It uses floor rounding:
+ * const result = millisecondsToHours(7199999)
+ * //=> 1
+ */
+export default function millisecondsToHours(milliseconds: number): number {
+  requiredArgs(1, arguments)
+  const hours = milliseconds / millisecondsInHour
+  return Math.floor(hours)
+}