jupyter-ijavascript-utils 1.6.4 → 1.6.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jupyter-ijavascript-utils",
-  "version": "1.6.4",
+  "version": "1.6.5",
   "description": "Utilities for working with iJavaScript - a Jupyter Kernel",
   "homepage": "https://jupyter-ijavascript-utils.onrender.com/",
   "main": "src/index.js",

package/src/format.js

@@ -11,6 +11,11 @@
  *   * {@link module:format.divideR|format.divideR}   - Divides a number to provide { integer, remainder } - ex: 5/3 as ( 1, remainder 2 )
  * * Formatting Time
  *   * {@link module:format.millisecondDuration|format.millisecondDuration}
+ * * Mapping Values
+ *   * {@link module:format.mapDomain|format.mapDomain} - projects a value from a domain of expected values to a range of output values, ex: 10% of 2 Pi
+ * * Identifying Time Periods
+ *   * {@link module:format.timePeriod|format.timePeriod} - Converts a time to a time period, very helpful for animations
+ *   * {@link module:format.timePeriodPercent|format.timePeriodPercent} - Determines the percent complete of the current time period
  * 
  * @module format
  * @exports format
@@ -285,9 +290,137 @@ module.exports.millisecondDuration = function millisecondDuration(milliseconds)
   return result;
 };
 
+/**
+ * Ellipsifies a string (but only if it is longer than maxLen)
+ * 
+ * @param {String} str - string to be ellipsified
+ * @param {Integer} [maxLen = 50] - the maximum length of str before getting ellipsified
+ * @returns {String}
+ * @example
+ * format.ellipsify('longName') // 'longName' (as maxLen is 50)
+ * format.ellipsify('longName', 8) // 'longName' (as maxLen is 8)
+ * format.ellipsify('longName', 4) // 'long…' (as str is longer than maxLen)
+ */
 module.exports.ellipsify = function ellipsify(str, maxLen = 50) {
   if (str && str.length > maxLen) {
     return `${str.substring(0, maxLen)}…`;
   }
   return str;
 };
+
+/**
+ * projects a value from a domain of expected values to a range of output values, ex: 10% of 2 Pi.
+ * 
+ * This is SUPER helpful in normalizing values, or converting values from one "range" of values to another.
+ * 
+ * @param {Number} val - value to be mapped
+ * @param {Array} domain - [min, max] - domain of possible input values
+ * @param {Array} domain.domainMin - minimum input value (anything at or below maps to rangeMin)
+ * @param {Array} domain.domainMax - maximum input value (anything at or above maps to rangeMax)
+ * @param {Array} range - [min, max] - range of values to map to
+ * @param {Array} range.rangeMin - minimum output value
+ * @param {Array} range.rangeMax - maximum output value
+ * @returns Number
+ * @example
+ * 
+ * format.mapDomain(-2, [0, 10], [0, 1])
+ * // 0   - since it is below the minimum value
+ * format.mapDomain(0, [0, 10], [0, 1])
+ * // 0   - since it is the minimum value
+ * format.mapDomain(5, [0, 10], [0, 1])
+ * // 0.5 - since it is 5/10
+ * format.mapDomain(12, [0, 10], [0, 1])
+ * // 1   - since it is above the maximum value
+ * 
+ * format.mapDomain(0.5, [0, 1], [0, 10])
+ * // 5 - since it is half of 0-1, and half of 1-10
+ * format.mapDomain(0.5, [0, 1], [0, Math.PI + Math.PI])
+ * // 3.1415 or Math.PI - since it is half of 2 PI
+ */
+module.exports.mapDomain = function mapDomain(val, [domainMin, domainMax], [rangeMin = 0, rangeMax = 1]) {
+  if (val < domainMin) {
+    return rangeMin;
+  } else if (val > domainMax) {
+    return rangeMax;
+  }
+  // domainMin / val / domainMax = rangeMin / result / rangeMax
+  // (val - domainMin) / (domainMax - domainMin) = (result - rangeMin) / (rangeMax - rangeMin)
+  // (val - domainMin) * (rangeMax - rangeMin) / (domainMax - domainMin) = result - rangeMin;
+  // (val - domainMin) * (rangeMax - rangeMin) / (domainMax - domainMin) + rangeMin = result
+  return (((val - domainMin) * (rangeMax - rangeMin)) / (domainMax - domainMin)) + rangeMin;
+};
+
+/**
+ * Given that a period of time is millisecondPeriod number of milliseconds long,
+ * determines which period of time we are currently in (timeEpoch / millisecondPeriod)
+ * 
+ * This is especially handy for animations or cyclical time measuring.
+ * 
+ * **NOTE: consider sending the timeEpoch relative to a separate start time**,
+ * it is rarely ever needed to know how many 10 second intervals occurred since 1970...
+ * 
+ * Likely, we care more that the animation should have cycled 40 times since the page loaded though.
+ * 
+ * @param {Integer} millisecondPeriod - Number of Milliseconds in a Period of time
+ * @param {Integer} [timeMilli = now] - optional time to check - in epoch milliseconds
+ * @param {Integer} [startMilli = null] - optional starting epoch
+ * @returns {Number} - (timeEpoch - startEpoch) / millisecondPeriod - number of periods 
+ * 
+ * @example
+ * const startTime = new Date().getTime();
+ * 
+ * format.timePeriod(1000)
+ * // 164955061.3 - using the current time and epoch starting point
+ * 
+ * format.timePeriod(1000, new Date().getTime(), startTime);
+ * // 0.0 - using the starting point instead
+ * 
+ * // - wait 3 seconds
+ * 
+ * format.timePeriod(10000, new Date().getTime(), startTime); // 0.3
+ * format.timePeriod(10000, null, startTime); // 0.3
+ * 
+ * // - wait another 14 seconds
+ * 
+ * format.timePeriod(10000, new Date().getTime(), startTime); // 1.7
+ * 
+ * //-- wait 8 seconds
+ * 
+ * format.timePeriod(10000, new Date().getTime(), startTime) // 2.5
+ */
+module.exports.timePeriod = function mapTime(millisecondPeriod, timeMilli = null, startMilli = null) {
+  let updatedMilli = !timeMilli
+    ? new Date().getTime()
+    : timeMilli;
+  
+  if (startMilli) {
+    updatedMilli -= startMilli;
+  }
+
+  return updatedMilli / millisecondPeriod;
+};
+
+/**
+ * Given that a period of time is millisecondPeriod number of milliseconds long,
+ * determines how far along in the CURRENT PERIOD.
+ * 
+ * This is especially handy for animations or cyclical time measuring.
+ * 
+ * @param {Integer} millisecondPeriod - Number of Milliseconds in a Period of time
+ * @param {Integer} [timeEpoch = now] - time to check - in epoch milliseconds
+ * @returns {Number} - percentage through the current millisecond period (0 <= x < 1)
+ * 
+ * @example
+ * format.timePeriodPercent(10000, new Date().getTime()) // 0.3
+ * 
+ * //-- wait 14 seconds
+ * 
+ * format.timePeriodPercent(10000, new Date().getTime()) // 0.7
+ * 
+ * //-- wait 8 seconds
+ * 
+ * format.timePeriodPercent(10000, new Date().getTime()) // 0.5
+ */
+module.exports.timePeriodPercent = function mapEpochInPeriod(millisecondPeriod, timeEpoch = new Date().getTime()) {
+  return (timeEpoch % millisecondPeriod) / millisecondPeriod;
+};