Add ability to format a pre-calculated number of milliseconds

README.md

@@ -38,7 +38,7 @@ Formats difference between two dates as a human-readable string in almost any la
 
 ### Node.js
 
-In Node.js environment library will load requested locales automatically.
+In Node.js environment library will load requested locales automatically from a relative path.
 
 ```js
 const timeDelta = require('time-delta');
@@ -47,12 +47,21 @@ const instance = timeDelta.create({
   locale: 'en', // default
 });
 
+// Show the difference between two date objects
 const date1 = new Date('2015-04-01T21:00:00');
 const date2 = new Date('2015-04-01T23:17:10');
 
 // Outputs: "2 hours, 17 minutes".
 console.log(instance.format(date1, date2));
 
+
+// Show the difference when calculated in milliseconds
+const diff_in_ms = date2 - date1;
+
+// Outputs: "2 hours, 17 minutes".
+console.log(instance.format_ms(date1, date2));
+
+
 ```
 
 ### Browser
@@ -63,20 +72,27 @@ This ensures minimal size of your application bundle.
 ```js
 // Importing the library
 import * as timeDelta from 'time-delta';
+import * as numerous from 'numerous';
 
 // Importing locales that you want to use
 import enLocale from 'time-delta/locales/en';
+import numerousEnLocale from 'numerous/locales/en';
 import ruLocale from 'time-delta/locales/ru';
+import numerousRuLocale from 'numerous/locales/ru';
 
 // Registering locale
 timeDelta.addLocale(enLocale);
+numerous.addLocale(numerousEnLocale);
+
 
 // You can register multiple locales
 timeDelta.addLocale([enLocale, ruLocale]);
+numerous.registerLocale([numerousEnLocale, numerousRuLocale]);
 
 // Creating an instance
 const instance = timeDelta.create({
-  locale: 'en', // default
+  locale: 'en',
+  autoloadLocales: false
 });
 
 const date1 = new Date('2015-04-01T21:00:00');

lib/time-delta.js

@@ -106,6 +106,23 @@ function timeDeltaFactory(config) {
 
       return format(firstDate, secondDate, options);
 
+    },
+
+    /**
+     * Public proxy for internal format_ms function.
+     *
+     * @param {number} msDifference
+     * @param {object?} options
+     *
+     * @returns {string}
+     */
+    format_ms: function (msDifference, options) {
+
+      // Allowing to override config with each individual call
+      options = Object.assign({}, config, options || {});
+
+      return format_ms(msDifference, options);
+
     }
 
   };
@@ -114,35 +131,23 @@ function timeDeltaFactory(config) {
 
 
 /**
- * Returns difference between two dates as a text string.
+ * Returns the length of time in milliseconds as a text string.
  *
- * @param {Date} firstDate
- * @param {Date} secondDate
+ * @param {number} msDifference
  * @param {object} config
  *
  * @returns {string}
  */
-function format(firstDate, secondDate, config) {
+function format_ms(msDifference, config) {
 
   ensureLocaleLoadedOrThrow(config.locale, {
     autoload: config.autoloadLocales,
   });
 
-  // Handling input arguments
-  // -----
-
-  if (!firstDate) {
-    throw new Error('Missing first date argument');
-  }
-
-  if (!secondDate) {
-    throw new Error('Missing second date argument');
-  }
-
   // Calculating
   // -----
 
-  const difference = getDifference(firstDate, secondDate);
+  const difference = convMillisecsToTimeUnits(msDifference);
   const parts = [];
 
   for (const unit of difference) {
@@ -161,6 +166,35 @@ function format(firstDate, secondDate, config) {
 }
 
 
+/**
+ * Returns difference between two dates as a text string.
+ *
+ * @param {Date} firstDate
+ * @param {Date} secondDate
+ * @param {object} config
+ *
+ * @returns {string}
+ */
+function format(firstDate, secondDate, config) {
+  // Handling input arguments
+  // -----
+
+  if (!firstDate) {
+    throw new Error('Missing first date argument');
+  }
+
+  if (!secondDate) {
+    throw new Error('Missing second date argument');
+  }
+
+  // Calculating
+  // -----
+
+  let difference = (secondDate - firstDate);
+  return format_ms(difference, config);
+}
+
+
 /**
  * Checks if locale is loaded. If not, tries to load it in Node.js,
  * or throws and error in Browser.
@@ -211,22 +245,23 @@ function requireLocale(localeId) {
     );
 
   } catch (error) {
-    throw Error(`Failed to load locale: ${localeId}`);
+    throw Error(
+      `Failed to load locale: ${localeId} from ../locales/${localeId}.js. If using a bundled time-delta, set 'autoloadLocales: false' in the config: ${error}`
+    );
 
   }
 }
 
 
 /**
- * Returns difference as separate time units.
+ * Converts a number of milliseconds to an array of time units.
  *
- * @param {Date} firstDate
- * @param {Date} secondDate
+ * @param {number} msDifference
  *
  * @returns {Array}
  */
-function getDifference(firstDate, secondDate) {
-  let difference = (secondDate - firstDate);
+function convMillisecsToTimeUnits(msDifference) {
+  let difference = msDifference;
   const results = [];
   timeUnits.some(function (unit) {
     const name = unit[0];