Added the 'bignames' and 'onlytwo' exports, with tests.

Author: Cully Larson

package.json

@@ -1,6 +1,6 @@
 {
   "name": "formatmicro",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "Formats microseconds into a human consumable form.",
   "license": "MIT",
   "repository": "cullylarson/formatmicro",

readme.md

@@ -43,6 +43,79 @@ console.log(formatmicro(totalTimeMult))
 
 ```
 
+### bignames
+
+You can also import `bignames`, to output increments using their full names (e.g "days", "hours", etc.).
+For example:
+
+```js
+import {bignames} from 'formatmicro'
+
+const oneµs = 1
+const oneMs = 1000
+const oneS  = 1000*1000
+const oneM  = 60*1000*1000
+const oneH  = 60*60*1000*1000
+const oneD  = 24*60*60*1000*1000
+
+const totalTime = oneD + 12*oneH + 16*oneM + 59*oneS + oneMs + 6*oneµs
+
+console.log("Task completed in: " + bignames(totalTime))
+// Task completed in: 1 day 12 hours 16 minutes 59 seconds 1 millisecond 6 microseconds
+```
+
+The function signature is the same as `formatmicro`, so you could provide a custom reduce or custom
+increment names if you wanted.
+
+### onlytwo
+
+You can also import `onlytwo`, to output only the first two, non-zero increments.
+For example:
+
+```js
+import {onlytwo} from 'formatmicro'
+
+const oneµs = 1
+const oneMs = 1000
+const oneS  = 1000*1000
+const oneM  = 60*1000*1000
+const oneH  = 60*60*1000*1000
+const oneD  = 24*60*60*1000*1000
+
+const totalTime = oneD + 12*oneH + 16*oneM + 59*oneS + oneMs + 6*oneµs
+
+console.log("Task completed in: " + onlytwo(totalTime))
+// Task completed in: 1 d 12 h
+```
+
+The function signature is the same as `formatmicro`, so you could provide a custom reduce or custom
+increment names if you wanted. For example:
+
+```js
+import {onlytwo} from 'formatmicro'
+
+const oneµs = 1
+const oneMs = 1000
+const oneS  = 1000*1000
+const oneM  = 60*1000*1000
+const oneH  = 60*60*1000*1000
+const oneD  = 24*60*60*1000*1000
+
+const totalTime = 12*oneH + oneS + 9*oneMs + oneµs
+
+const incrementNames = {
+    'd' : ['day', 'days'],
+    'h' : ['hour', 'hours'],
+    'm' : ['minute', 'minutes'],
+    's' : ['second', 'seconds'],
+    'ms' : ['millisecond', 'milliseconds'],
+    'µs' : ['microsecond', 'microseconds'],
+}
+
+console.log("Task completed in: " + onlytwo(totalTime, incrementNames))
+// Task completed in: 12 hours 1 second
+```
+
 ## Options
 
 You can optionally pass the names of the increments (e.g hours, minutes, days, etc.) as the second
@@ -84,7 +157,7 @@ It accepts the following parameters:
 
 * __carry__ _(string)_ This is the return from the last call to the reducer function (starts
 as a empty string).
-* __incrementName__ _(string)_ This will be: d, h, m, s, ms, or µs
+* __incrementKey__ _(string)_ This will be: d, h, m, s, ms, or µs
 * __value__ _(int)_ The value for this increment (e.g. the number of seconds, or the number of minutes).
 
 Here are some examples:
@@ -111,12 +184,12 @@ const incrementNames = {
     'µs' : ['µs', 'µs'],
 }
 
-const formatReduce = (carry, incrementName, value) => {
+const formatReduce = (carry, incrementKey, value) => {
     if(value === 0) return carry
     else return carry +
         ((carry === "") ? "" : " ") +
         value.toString() + " " +
-        ((value === 1) ? incrementNames[incrementName][0] : incrementNames[incrementName][1])
+        ((value === 1) ? incrementNames[incrementKey][0] : incrementNames[incrementKey][1])
 }
 
 console.log("Task completed in: " + formatmicro(period, formatReduce))
@@ -126,7 +199,7 @@ console.log("Task completed in: " + formatmicro(period, formatReduce))
 
 ```js
 let foundNum = 0
-const formatReduce = (carry, incrementName, value) => {
+const formatReduce = (carry, incrementKey, value) => {
     if(foundNum >= 3) return carry
     if(value === 0) return carry
 
@@ -135,7 +208,7 @@ const formatReduce = (carry, incrementName, value) => {
     return carry +
         ((carry !== "") ? " " : "") +
         value.toString() + " " +
-        incrementName
+        incrementKey
 }
 ```
 

src/index.js

@@ -1,15 +1,26 @@
 'use strict'
+
+const defaultIncrementNames = {
+    'd': ['d', 'd'],
+    'h': ['h', 'h'],
+    'm': ['m', 'm'],
+    's': ['s', 's'],
+    'ms': ['ms', 'ms'],
+    'µs': ['µs', 'µs'],
+}
 /**
  * @module formatmicro
  */
 
 /**
+ * Formats microseconds into strings that look like:  1 d 3 h 7 m 28 s 500 ms 324 µs
+ *
  * @param {number} timeMicro
- * @param {object|function} incrementNames
+ * @param {object|function|undefined} incrementNames
  * @returns {string}
  * @throws {Error} If either argument isn't the correct type
  */
-export default function formatmicro(timeMicro, incrementNames) {
+const formatmicro = (timeMicro, incrementNames) => {
     if(Number(parseFloat(timeMicro)) !== timeMicro) throw new Error("First parameter must be a number.")
     if(incrementNames && (typeof incrementNames !== "function") && (typeof incrementNames !== "object")) throw new Error("Second parameter, if provided, must be a function or an object")
 
@@ -20,21 +31,16 @@ export default function formatmicro(timeMicro, incrementNames) {
     }
     else {
         incrementNames = {
-            'd' : ['d', 'd'],
-            'h' : ['h', 'h'],
-            'm' : ['m', 'm'],
-            's' : ['s', 's'],
-            'ms' : ['ms', 'ms'],
-            'µs' : ['µs', 'µs'],
+            ...defaultIncrementNames,
             ...incrementNames,
         }
 
-        formatReduce = (carry, incrementName, value) => {
+        formatReduce = (carry, incrementKey, value) => {
             if(value === 0) return carry
             else return carry +
                 ((carry === "") ? "" : " ") +
                 value.toString() + " " +
-                ((value === 1) ? incrementNames[incrementName][0] : incrementNames[incrementName][1])
+                ((value === 1) ? incrementNames[incrementKey][0] : incrementNames[incrementKey][1])
         }
     }
 
@@ -59,3 +65,70 @@ export default function formatmicro(timeMicro, incrementNames) {
         else return formatReduce(carry, key, parts[key])
     }, "")
 }
+
+/**
+ * Formats microseconds into strings that look like:  1 day 3 hours 7 minutes 28 seconds 500 milliseconds 324 microseconds
+ *
+ * @param {number} timeMicro
+ * @param {object|function|undefined} incrementNames
+ * @returns {string}
+ * @throws {Error} If either argument isn't the correct type
+ */
+const bignames = (timeMicro, incrementNames) => {
+    if(!incrementNames || (typeof incrementNames === "object")) {
+        incrementNames = {
+            'd' : ['day', 'days'],
+            'h' : ['hour', 'hours'],
+            'm' : ['minute', 'minutes'],
+            's' : ['second', 'seconds'],
+            'ms' : ['millisecond', 'milliseconds'],
+            'µs' : ['microsecond', 'microseconds'],
+            ...incrementNames,
+        }
+    }
+
+    return formatmicro(timeMicro, incrementNames)
+}
+
+/**
+ * Same as {@link formatmicro}, except it only returns the first two non-zero values.
+ *
+ * @param {number} timeMicro
+ * @param {object|function|undefined} incrementNames
+ * @returns {string}
+ * @throws {Error} If either argument isn't the correct type
+ */
+const onlytwo = (timeMicro, incrementNames) => {
+    if(!incrementNames || (typeof incrementNames === "object")) {
+        incrementNames = {
+            ...defaultIncrementNames,
+            ...incrementNames,
+        }
+    }
+    else if(typeof incrementNames === "function") {
+        return formatmicro(timeMicro, incrementNames)
+    }
+
+    let foundNum = 0
+    const takeFor = 2
+    const formatReduce = (carry, incrementKey, value) => {
+        if(foundNum >= takeFor) return carry
+        if(value === 0) return carry
+
+        foundNum++
+
+        return carry +
+            ((carry === "") ? "" : " ") +
+            value.toString() + " " +
+            ((value === 1) ? incrementNames[incrementKey][0] : incrementNames[incrementKey][1])
+    }
+
+    return formatmicro(timeMicro, formatReduce)
+}
+
+export {
+    formatmicro as default,
+    formatmicro,
+    bignames,
+    onlytwo,
+}

src/test.js

@@ -1,5 +1,5 @@
 import assert from 'assert'
-import formatmicro from "./../dist/index.js"
+import {default as formatmicro, bignames, onlytwo} from "./../dist/index.js"
 
 const oneµs = 1
 const oneMs = 1000
@@ -17,6 +17,15 @@ const customIncrementNames = {
     'µs' : ['microsecond', 'microseconds'],
 }
 
+const defaultIncrementNames = {
+    'd': ['d', 'd'],
+    'h': ['h', 'h'],
+    'm': ['m', 'm'],
+    's': ['s', 's'],
+    'ms': ['ms', 'ms'],
+    'µs': ['µs', 'µs'],
+}
+
 describe('Format Micro', () => {
     describe("For only one increment", () => {
         it("Should work with microseconds", () => {
@@ -202,3 +211,69 @@ describe('Format Micro', () => {
         })
     })
 })
+
+describe("Big Names", () => {
+    describe("For mixed increments", () => {
+        it("Should use the singular custom names", () => {
+            const totalTimeOne = oneD + oneH + oneM + oneS + oneMs + oneµs
+
+            assert.equal(bignames(totalTimeOne), "1 day 1 hour 1 minute 1 second 1 millisecond 1 microsecond")
+        })
+
+        it("Should use the plural custom names", () => {
+            const totalTimeMult = 4*oneD + 12*oneH + 16*oneM + 59*oneS + 9*oneMs + 6*oneµs
+
+            assert.equal(bignames(totalTimeMult), "4 days 12 hours 16 minutes 59 seconds 9 milliseconds 6 microseconds")
+        })
+
+        it("Should use the plural and singular custom names", () => {
+            const totalTimeMixed = oneD + 12*oneH + oneM + 59*oneS + 9*oneMs + oneµs
+
+            assert.equal(bignames(totalTimeMixed), "1 day 12 hours 1 minute 59 seconds 9 milliseconds 1 microsecond")
+        })
+    })
+
+    describe("For alternate increment names array", () => {
+        it("Should use the alternate names", () => {
+            const totalTimeMixed = oneD + 12*oneH + oneM + 59*oneS + 9*oneMs + oneµs
+
+            assert.equal(bignames(totalTimeMixed, defaultIncrementNames), "1 d 12 h 1 m 59 s 9 ms 1 µs")
+        })
+    })
+})
+
+describe("Only Two", () => {
+    describe("For all non-zero values", () => {
+        it("Should format only the first two", () => {
+            const totalTimeMult = 4*oneD + oneH + 16*oneM + 59*oneS + 9*oneMs + 6*oneµs
+
+            assert.equal(onlytwo(totalTimeMult), "4 d 1 h")
+        })
+    })
+    describe("For some zero values", () => {
+        it("Should format only the first two non-zero", () => {
+            const totalTimeMult = 4*oneD + 59*oneS + 9*oneMs + 6*oneµs
+
+            assert.equal(onlytwo(totalTimeMult), "4 d 59 s")
+        })
+    })
+    describe("For custom increment names array", () => {
+        it("Should use the singular custom names", () => {
+            const totalTimeOne = oneD + oneH + oneM + oneS + oneMs + oneµs
+
+            assert.equal(onlytwo(totalTimeOne, customIncrementNames), "1 day 1 hour")
+        })
+
+        it("Should use the plural custom names", () => {
+            const totalTimeMult = 4*oneD + 12*oneH + 16*oneM + 59*oneS + 9*oneMs + 6*oneµs
+
+            assert.equal(onlytwo(totalTimeMult, customIncrementNames), "4 days 12 hours")
+        })
+
+        it("Should use the plural and singular custom names", () => {
+            const totalTimeMixed = 12*oneH + oneS + 9*oneMs + oneµs
+
+            assert.equal(onlytwo(totalTimeMixed, customIncrementNames), "12 hours 1 second")
+        })
+    })
+})