jupyter-ijavascript-utils 1.50.0 → 1.51.0

package/Dockerfile

@@ -1,3 +1,3 @@
 # syntax=docker/dockerfile:1
 
-FROM darkbluestudios/jupyter-ijavascript-utils:binder_1.50.0
+FROM darkbluestudios/jupyter-ijavascript-utils:binder_1.51.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jupyter-ijavascript-utils",
-  "version": "1.50.0",
+  "version": "1.51.0",
   "description": "Utilities for working with iJavaScript - a Jupyter Kernel",
   "homepage": "https://jupyter-ijavascript-utils.onrender.com/",
   "license": "MIT",

package/src/array.js

@@ -13,6 +13,7 @@ require('./_types/global');
  *   * {@link module:array.arrange|array.arrange(size, start, step)} - generate array of a size, and INCREASING default value
  *   * {@link module:array.arrangeMulti|array.arrangeMulti(n, m, ...)} - generate a multi-dimensional array
  *   * {@link module:array.clone|array.clone(array)} - deep clones arrays
+ *   * {@link module:array.zip|array.zip(arrayleft, arrayRight)} - zips two arrays to join values at the same index together.
  * * Sorting
  *   * {@link module:array.createSort|array.createSort(sortIndex, sortIndex, ...)} - generates a sorting function
  *   * {@link module:array.SORT_ASCENDING|array.SORT_ASCENDING} - common ascending sorting function for array.sort()
@@ -21,6 +22,7 @@ require('./_types/global');
  * * Rearrange Array
  *   * {@link module:array.reshape|array.reshape} - reshapes an array to a size of rows and columns
  *   * {@link module:array.transpose|array.transpose} - transposes (flips - the array along the diagonal)
+ *   * {@link module:array.resize|array.resize} - repeats or truncates to change the size of an array.
  * * Picking Values
  *   * {@link module:array.peekFirst|array.peekFirst} - peeks at the first value in the list
  *   * {@link module:array.peekLast|array.peekLast} - peeks at the last value in the list
@@ -36,6 +38,8 @@ require('./_types/global');
  *        {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substring|Substring}
  *        from a multi-line string or array of strings
  *   * {@link module:array.multiStepReduce|array.multiStepReduce} - Performs reduce, and returns the value of reduce at each step
+ *   * {@link module:array.extractFromHardSpacedTable|array.extractFromHardSpacedTable} - Extract values where each line has no delimiter,
+ *      but instead a column index (ex: column 13)
  * * Applying a value
  *   * {@link module:array.applyArrayValue|array.applyArrayValue} - applies a value deeply into an array safely
  *   * {@link module:array.applyArrayValues|array.applyArrayValues} - applies a value / multiple values deeply into an array safely
@@ -607,8 +611,8 @@ module.exports.transpose = function transpose(matrix) {
 };
 
 /**
- * Resizes an NxM dimensional array by number of columns
- * @param {any[]} sourceArray - an array to resize
+ * Re-shapes an NxM dimensional array by number of columns
+ * @param {any[]} sourceArray - an array to reshape
  * @param {Number} numColumns - number of columns
  * @returns {any[][]} - 2 dimensinal array
  * @example
@@ -618,14 +622,14 @@ module.exports.transpose = function transpose(matrix) {
  *    0,  1, 2, 3, 4, 5,  6, 7, 8, 9, 10, 11
  * ]
  * 
- * //-- resize the 1d array based on 3 columns
+ * //-- reshape the 1d array based on 3 columns
  * newArray = utils.array.reshape(baseArray, 3)
  * [ [ 0, 1, 2 ],
  *   [ 3, 4, 5 ],
  *   [ 6, 7, 8 ],
  *   [ 9, 10, 11 ] ];
  * 
- * //-- now resize the 4x3 array to 3x4
+ * //-- now reshape the 4x3 array to 3x4
  * utils.array.reshape(newArray, 4);
  * [ [ 0, 1, 2, 3 ],
  *   [ 4, 5, 6, 7 ],
@@ -1447,3 +1451,118 @@ module.exports.asyncWaitAndChain = (seconds, fn, rows) => {
     return callNext();
   });
 };
+
+/**
+ * Resizes an array - if shorter (truncates), if longer cycles values.
+ * 
+ * ```
+ * categoryValues = ['rock', 'paper', 'scissors'];
+ * 
+ * utils.array.resize(categoryValues, 2); // ['rock', 'paper']
+ * utils.array.resize(categoryValues, 7); // ['rock', 'paper', 'scissors',
+ * 'rock', 'paper', 'scissors', 'rock];
+ * ```
+ * 
+ * @param {Array} sourceList - array of values
+ * @param {Number} length - new number of items in the list
+ */
+module.exports.resize = function resize(sourceList, length) {
+  if (!sourceList || !Array.isArray(sourceList)) return [];
+  if (length < 1 || sourceList.length < 1) return [];
+  return new Array(length)
+    .fill(0)
+    .map((_, index) => sourceList[index % sourceList.length]);
+};
+
+/**
+ * Combines arrays together by joining the values at the same index.
+ * 
+ * Similar to Panda's zip
+ * 
+ * This can be very helpful for joining multiple value lists.
+ * 
+ * ```
+ * first = ['john', 'paul', 'george', 'ringo'];
+ * last = ['lennon', 'mccartney', 'harrison', 'starr'];
+ * phrase = ['imagine', 'yesterday', 'taxman', 'walrus'];
+ * 
+ * names = utils.array.zip(first, last);
+ * // [['john', 'lennon'], ['paul', 'mccartney'],
+ * //  ['george', 'harrison'], ['ringo', 'starr']];
+ * ```
+ * 
+ * You can also zip together existing arrays
+ * 
+ * ```
+ * utils.array.zip(names, phrase);
+ * // [['john', 'lennon', 'imagine'],
+ * //   ['paul', 'mccartney', 'yesterday'],
+ * //   ['george', 'harrison', 'taxman'],
+ * //   ['ringo', 'starr', 'walrus']]
+ * ```
+ * 
+ * or you can zip them together all at once
+ * 
+ * ```
+ * utils.array.zip(first, last, phrase);
+ * // [['john', 'lennon', 'imagine'],
+ * //   ['paul', 'mccartney', 'yesterday'],
+ * //   ['george', 'harrison', 'taxman'],
+ * //   ['ringo', 'starr', 'walrus']]
+ * ```
+ * 
+ * @param {Array} arrayLeft - one array to combine with the array on the right
+ * @param {Array} arrayRight - another array to combine at the same indices on the left
+ * @param  {...any} rest - additional arrays to combine
+ * @returns {Array<Array>}
+ */
+module.exports.zip = function zip(arrayLeft, arrayRight, ...rest) {
+  if (!arrayLeft || !arrayLeft[Symbol.iterator]) {
+    throw new Error('zip: left must be iterable');
+  }
+  if (!arrayRight || !arrayRight[Symbol.iterator]) {
+    throw new Error('zip: right must be iterable');
+  }
+
+  const cleanLeft = Array.isArray(arrayLeft) ? arrayLeft : [...arrayLeft];
+  const cleanRight = Array.isArray(arrayRight) ? arrayRight : [...arrayRight];
+
+  let result;
+
+  if (cleanLeft.length === 0 && cleanRight.length === 0) {
+    result = [[]];
+  } else if (cleanLeft.length === 0) {
+    result = cleanRight.map((val) => Array.isArray(val) ? val : [val]);
+  } else if (cleanRight.length === 0) {
+    result = cleanLeft.map((val) => Array.isArray(val) ? val : [val]);
+  } else {
+    const cleanLeftLen = cleanLeft.length;
+    const cleanRightLen = cleanRight.length;
+    const zipLen = Math.min(cleanLeftLen, cleanRightLen);
+
+    result = new Array(zipLen).fill(0);
+
+    for (let i = 0; i < zipLen; i += 1) {
+      const leftVal = cleanLeft[i];
+      const rightVal = cleanRight[i];
+      const leftValArray = Array.isArray(leftVal);
+      const rightValArray = Array.isArray(rightVal);
+      if (leftValArray && rightValArray) {
+        result[i] = [...leftVal, ...rightVal];
+      } else if (leftValArray) {
+        result[i] = [...leftVal, rightVal];
+      } else if (rightValArray) {
+        result[i] = [leftVal, ...rightVal];
+      } else {
+        result[i] = [leftVal, rightVal];
+      }
+    }
+  }
+
+  if (rest && rest.length > 0) {
+    const [newRight, ...newRest] = rest;
+    result = ArrayUtils.zip(result, newRight, ...newRest);
+  }
+
+  return result;
+};

package/src/color.js

@@ -21,6 +21,8 @@
  * 
  * See other common libraries for working with color on NPM:
  * like [d3/color](https://d3js.org/d3-color)
+ * or [d3-scale-chromatic scales](https://d3js.org/d3-scale-chromatic)
+ * or [d3-color-interpolation](https://d3js.org/d3-interpolate/color)
  * 
  * * Parsing color formats
  *   * {@link module:color.parse|color.parse(string|array|object, optionalAlpha 0-1)} - intelligently parse any of the types to an array format
@@ -41,6 +43,8 @@
  *      with properties: {r:Number[0-255], g: Number[0-255], b: Number[0-255], a: Number[0-1]}
  * * interpolate
  *   * {@link module:color.interpolate|color.interpolate(fromColor, toColor, percent, formatType)} - gradually converts one color to another
+ *   * {@link module:color.interpolator|color.interpolator} - create a function you can then call with a percentage over and over again.
+ *   * {@link module:color.generateSequence|color.generateSequence} - generate a sequence of colors from one to another, in X number of steps
  *   * {@link module:color.interpolationStrategy|color.interpolationStrategy} - the function to use for interpolation,
  *      a function of signature (fromColor:Number[0-255], toColor:Number[0-255], percentage:Number[0-1]):Number[0-255]
  *   * {@link module:color.INTERPOLATION_STRATEGIES|color.INTERPOLATION_STRATEGIES} - a list of strategies for interpolation you can choose from
@@ -568,6 +572,7 @@ module.exports.convert = function convert(target, formatType = ColorUtils.defaul
  * @see {@link module:color.interpolationStrategy|color.interpolationStrategy} - the default interpolation
  *    used to calculate how the percentages come up with the color
  * @see {@link module:color.defaultFormat|color.defaultFormat} - the default format to use if not specified
+ * @see {@link module:format.mapArrayDomain|format.mapArrayDomain}
  */
 module.exports.interpolate = function interpolate(
   fromColor,
@@ -588,3 +593,97 @@ module.exports.interpolate = function interpolate(
   newColor[2] = Math.round(newColor[2]);
   return ColorUtils.convert(newColor, formatType);
 };
+
+/**
+ * Curried function for color interpolation, so only the percent between [0-1] inclusive is needed.
+ * 
+ * Meaning that you can do something like this:
+ * 
+ * ```
+ * black = `#000000`;
+ * white = `#FFFFFF`;
+ * 
+ * colorFn = utils.color.interpolator(black, white);
+ * 
+ * colorFn(0);   // '#000000';
+ * colorFn(0.5); // '#808080';
+ * colorFn(1);   // '#FFFFFF;
+ * 
+ * ```
+ * 
+ * Instead of something like this with the interpolate function
+ * 
+ * ```
+ * utils.color.interpolate(black, white, 0); // `#000000`
+ * utils.color.interpolate(black, white, 0.5); // `#808080`
+ * utils.color.interpolate(black, white, 1); // `#FFFFFF`
+ * ```
+ * 
+ * @param {string|array|object} fromColor -the color to interpolate from
+ * @param {string|array|object} toColor - the color to interpolate to
+ * @param {Number} percent - value from 0-1 on where we should be on the sliding scale
+ * @param {Function} [interpolationFn = ColorUtils.interpolationStrategy] - function of
+ *  signature (fromVal:Number[0-255], toVal:Number[0-255], pct:Number[0-1]):Number[0-255]
+ * @param {String} [formatType = ColorUtils.defaultFormat] - the format to convert the result to 
+ * @returns {Function} - of signature: (Number) => {string|array|object}
+ * @see {@link module:color.interpolate|color.interpolate} - as this is a curried version of that function.
+ * @see {@link module:format.mapArrayDomain|format.mapArrayDomain}
+ */
+module.exports.interpolator = function interpolator(
+  fromColor,
+  toColor,
+  interpolationFn = ColorUtils.interpolationStrategy,
+  formatType = ColorUtils.defaultFormat
+) {
+  return function interpolatorImpl(pct) {
+    return ColorUtils.interpolate(fromColor, toColor, pct, interpolationFn, formatType);
+  };
+};
+
+/**
+ * Generates a sequential array of colors interpolating fromColor to toColor, 
+ * 
+ * ```
+ * black = `#000000`;
+ * white = `#FFFFFF`;
+ * 
+ * categoricalColors = utils.color.generateSequence(black, white, 5);
+ * // [' #000000' ,' #404040' ,' #808080' ,' #bfbfbf' ,' #ffffff' ]
+ * ```
+ * 
+ * @param {string|array|object} fromColor -the color to interpolate from
+ * @param {string|array|object} toColor - the color to interpolate to
+ * @param {Number} lengthOfSequence - how many steps in the sequence to generate
+ * @param {Function} [interpolationFn = ColorUtils.interpolationStrategy] - function of
+ *  signature (fromVal:Number[0-255], toVal:Number[0-255], pct:Number[0-1]):Number[0-255]
+ * @param {String} [formatType = ColorUtils.defaultFormat] - the format to convert the result to 
+ * @returns {Function} - of signature: (Number) => {string|array|object}
+ * @see {@link module:color.interpolate|color.interpolate} - as this is a curried version of that function.
+ */
+module.exports.generateSequence = function generateSequence(
+  fromColor,
+  toColor,
+  lengthOfSequence,
+  interpolationFn = ColorUtils.interpolationStrategy,
+  formatType = ColorUtils.defaultFormat
+) {
+  if (lengthOfSequence <= 0) return [];
+  const cleanLengthOSequence = Math.floor(lengthOfSequence);
+  const maxIndex = cleanLengthOSequence - 1;
+  const result = new Array(lengthOfSequence).fill(0)
+    .map((_, index) => index / maxIndex)
+    .map((pct) => ColorUtils.interpolate(fromColor, toColor, pct, interpolationFn, formatType));
+  return result;
+};
+
+/**
+ * Simple sequence of colors to use when plotting categorical values.
+ * 
+ * Used based on the Tableau color scheme.
+ * 
+ * For example:
+ *
+ * ```
+ * utils.color.SEQUENCE[0]
+ */
+ColorUtils.SEQUENCE = ['#4e79a7', '#f28e2c', '#e15759', '#76b7b2', '#59a14f', '#edc949', '#af7aa1', '#ff9da7', '#9c755f', '#bab0ab'];

package/src/date.js

@@ -0,0 +1,503 @@
+/**
+ * Utility methods for working with dates and date ranges
+ * 
+
+ * * Valiate
+ *   * {@link module:date.isValid|date.isValid(date)} - whether the date provided is an invalid date
+ * * Parse
+ *   * {@link module:date.parse|date.parse(String)} - parse a date and throw an exception if it is not a valid date
+ * * TimeZones
+ *   * {@link module:date.getTimezoneOffset|date.getTimezoneOffset(String)} - gets the number of milliseconds offset for a given timezone
+ *   * {@link module:date.correctForTimezone|date.correctForTimezone(Date, String)} - meant to correct a date already off from UTC to the correct time
+ *   * {@link module:date.epochShift|date.epochShift(Date, String)} - offsets a date from UTC to a given time amount
+ * - knowing some methods might behave incorrectly
+ * * Add
+ *   * {@link module:date.add|date.add(Date, {days, hours, minutes, seconds)} - shift a date by a given amount
+ *   * {@link module:date.endOfDay|date.endOfDay(Date)} - finds the end of day UTC for a given date
+ *   * {@link module:date.startOfDay|date.startOfDay(Date)} - finds the end of day UTC for a given date
+ * 
+ * --------
+ * 
+ * See other libraries for more complete functionality:
+ * 
+ * * [Luxon](https://moment.github.io/luxon/index.html) - successor to [Moment.js](https://momentjs.com/)
+ * * [date-fns-tz](https://github.com/marnusw/date-fns-tz) extension for [date-fns](https://date-fns.org/)
+ * 
+ * also watch the [TC39 Temporal Proposal](https://github.com/tc39/proposal-temporal)
+ * - also found under caniuse: https://caniuse.com/temporal
+ * 
+ * @module date
+ * @exports date
+ * @see {@link https://stackoverflow.com/questions/15141762/how-to-initialize-a-javascript-date-to-a-particular-time-zone}
+ * @see {@link https://www.youtube.com/watch?v=2rnIHsqABfM&t=750s|epochShifting}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/getTimeZones|MDN TimeZone Names}
+ */
+module.exports = {};
+const DateUtils = module.exports;
+
+/**
+ * Collection of time durations in milliseconds
+ */
+module.exports.TIME = { MILLI: 1 };
+module.exports.TIME.SECOND = DateUtils.TIME.MILLI * 1000;
+module.exports.TIME.MINUTE = DateUtils.TIME.SECOND * 60;
+module.exports.TIME.HOUR = DateUtils.TIME.MINUTE * 60;
+module.exports.TIME.DAY = DateUtils.TIME.HOUR * 24;
+
+module.exports.padTime = function padTime(num, size = 2) {
+  return String(num).padStart(size, '0');
+};
+
+/**
+ * Simple check on whether the a JavaScript Date object is - or is not - an 'Invalid Date' instance.
+ * 
+ * ```
+ * d = new Date('2024-12-1');
+ * utils.date.isValid(d); // true
+ * 
+ * d = new Date('2024-12-1T');
+ * utils.date.isValid(d); // false
+ * 
+ * d = new Date('some string');
+ * utils.date.isValid(d); // false
+ * ```
+ * 
+ * @param {Date} testDate - JavaScript date to validate
+ * @returns {boolean} - whether the Date object is an 'invalid date' instance
+ */
+module.exports.isValid = (testDate) => {
+  if (!testDate) return false;
+  if (!(testDate instanceof Date)) return false;
+  return !Number.isNaN(testDate.getTime());
+};
+
+/**
+ * Harshly parses a JavaScript Date.
+ * 
+ * If the testValue is null, undefined then the same value is returned.
+ * 
+ * if the testValue is a valid Date - then the parsed Date object is returned.
+ * 
+ * If the testValue is not a valid Date, then throws an Error.
+ * 
+ * ```
+ * d = utils.date.parse('2024-12-01'); // returns Date object
+ * d = utils.date.parse(0); // returns Date object
+ * 
+ * d = utils.date.parse(null); // returns null
+ * 
+ * @param {String} dateStr - value passed to Date.parse
+ * @returns {Date}
+ * @see {@link module:date.isValid|date.isValid} - in checking for invalid dates
+ */
+module.exports.parse = (dateStr) => {
+  if (dateStr === undefined || dateStr === null) return dateStr;
+  const result = new Date(Date.parse(dateStr));
+  if (!DateUtils.isValid(result)) {
+    throw new Error(`Could not parse date: ${dateStr}`);
+  }
+  return result;
+};
+
+module.exports.timeZoneOffsets = new Map();
+
+/**
+ * Determines the number of milliseconds difference between
+ * a given timezone and UTC.
+ * 
+ * (Note: these values are cached, and optimized for repeated use on the same value)
+ * 
+ * See {@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones|the list of TZ database time zones}
+ * for the full list of options.
+ * 
+ * @param {String} timeZoneStr - a timezone string like "America/Toronto"
+ * @returns {Number} - the number of milliseconds between UTC and that timezone
+ */
+module.exports.getTimezoneOffset = function getTimezoneOffset(timeZoneStr) {
+  if (DateUtils.timeZoneOffsets.has(timeZoneStr)) {
+    return DateUtils.timeZoneOffsets.get(timeZoneStr);
+  }
+  const d = new Date();
+
+  const format = new Intl.DateTimeFormat('en-us', {
+    year: 'numeric',
+    month: 'numeric',
+    day: 'numeric',
+    hour: 'numeric',
+    minute: 'numeric',
+    second: 'numeric',
+    hour12: false,
+    fractionalSecondDigits: 3,
+    timeZone: timeZoneStr
+  });
+  const dm = format.formatToParts(d)
+    .filter(({ type }) => type !== 'literal')
+    .reduce((result, { type, value }) => {
+      // eslint-disable-next-line no-param-reassign
+      result[type] = value;
+      return result;
+    }, {});
+  //   const impactedDate = new Date(d.toLocaleString('en-US', { timeZone: timeZoneStr }));
+  const dateStr = `${dm.year}-${DateUtils.padTime(dm.month)}-${DateUtils.padTime(dm.day)}T${
+    DateUtils.padTime(dm.hour)}:${DateUtils.padTime(dm.minute)}:${DateUtils.padTime(dm.second)}.${
+    DateUtils.padTime(dm.fractionalSecond, 3)}`;
+  const impactedDate = new Date(dateStr);
+
+  const diff = d.getTime() - impactedDate.getTime();
+
+  DateUtils.timeZoneOffsets.set(timeZoneStr, diff);
+
+  return diff;
+};
+
+/**
+ * JavaScript always stores dates in UTC, but the data you imported may have lost the timezone information.
+ * 
+ * Use this to correct the timezone to the correct time UTC.
+ * 
+ * For Example:
+ * 
+ * ```
+ * // the date we originally pulled from the database
+ * // but thetimezone of the database was america/Toronto but not in UTC
+ * dateStr = '2024-12-06 18:00';
+ * 
+ * // we may have done this:
+ * myDate = new Date(dateStr);
+ * 
+ * // but now calling toISOString() is incorrect
+ * myDate.toISOString(); // '2024-12-06T18:00:00.0000' 
+ * 
+ * // it should be:
+ * correctedDate = utils.date.correctForTimezone('america/Toronto');
+ * correctedDate.toISOString(); // '2024-12-06T13:00:00.00.000' -- the correct time UTC
+ * ```
+ * 
+ * See {@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones|the list of TZ database time zones}
+ * for the full list of timezone options.
+ * 
+ * @param {Date} date - the date to be corrected in a new instance
+ * @param {String} timeZoneStr - tz database name for the timezone
+ * @returns {Date} - copy of the date corrected 
+ */
+module.exports.correctForTimezone = function correctForTimezone(date, timeZoneStr) {
+  const offsetMilli = DateUtils.getTimezoneOffset(timeZoneStr);
+  return new Date(date.getTime() + offsetMilli);
+};
+
+/**
+ * Epoch shift a date, so the utcDate is no longer correct,
+ * but many other functions behave closer to expected.
+ * 
+ * See {@link https://stackoverflow.com/a/15171030|here why this might not be what you want}
+ * 
+ * @param {Date} date - date to shift
+ * @param {String} timeZoneStr - the tz database name of the timezone
+ * @returns {Date}
+ */
+module.exports.epochShift = function epochShift(date, timeZoneStr) {
+  const offsetMilli = DateUtils.getTimezoneOffset(timeZoneStr);
+  return new Date(date.getTime() - offsetMilli);
+};
+
+/**
+ * Clones a date.
+ * 
+ * (Doesn't seem needed currently)
+ * 
+ * (NOTE: the timezone information is lost)
+ * 
+ * @param {Date} targetDate - the date to be cloned
+ * @returns {Date}
+ */
+/*
+module.exports.clone = function clone(targetDate) {
+  return new Date(targetDate.getTime());
+};
+*/
+
+/**
+ * Adds an amount to a date: days, hours, minutes, seconds
+ * 
+ * ```
+ * d = new Date('2024-12-26 6:00:00');
+ * d30 = utils.date.add(d, { minutes: 30 }); // Date('2024-12-26 6:00:00')
+ * ```
+ * 
+ * @param {Date} dateValue - date to add to
+ * @param {Object} options - options of what to add
+ * @param {Number} [options.days=0] - number of days to add
+ * @param {Number} [options.minutes=0] - number of minutes to add
+ * @param {Number} [options.hours=0] - number of minutes to add 
+ * @param {Number} [options.seconds=0] - number of seconds to add 
+ * @returns {Date} - 
+ */
+module.exports.add = function add(dateValue, options = null) {
+  if (!options) return dateValue;
+
+  const { days = 0, minutes = 0, hours = 0, seconds = 0 } = options;
+  return new Date(dateValue.getTime()
+    + DateUtils.TIME.DAY * days
+    + DateUtils.TIME.HOUR * hours
+    + DateUtils.TIME.MINUTE * minutes
+    + DateUtils.TIME.SECOND * seconds);
+};
+
+/**
+ * Creates a new date that is at the end of the day (in UTC)
+ * 
+ * ```
+ * d = new Date('2024-12-26 6:00:00');
+ * dEnd = utils.date.endOfDay(d); // Date('2024-12-26 23:59:59.9999')
+ * ```
+ * 
+ * @param {Date} dateValue - Date where only the year,month,day is used
+ * @returns {Date} - new date set to the end of the day for dateValue's date
+ */
+module.exports.endOfDay = function endOfDay(dateValue) {
+  const startDate = Math.floor(dateValue.getTime() / DateUtils.TIME.DAY) * DateUtils.TIME.DAY;
+  return new Date(startDate + DateUtils.TIME.DAY - 1);
+};
+
+/**
+ * Creates a new date that is at the start of the day (in UTC)
+ * 
+ * ```
+ * d = new Date('2024-12-26 6:00:00');
+ * dEnd = utils.date.startOfDay(d); // Date('2024-12-26 0:00:00.0000')
+ * ```
+ * 
+ * @param {Date} dateValue - Date where only the year,month,day is used
+ * @returns {Date} - new date set to the end of the day for dateValue's date
+ */
+module.exports.startOfDay = function endOfDay(dateValue) {
+  const startDate = Math.floor(dateValue.getTime() / DateUtils.TIME.DAY) * DateUtils.TIME.DAY;
+  return new Date(startDate);
+};
+
+/**
+ * Represents a Range between two times
+ */
+class DateRange {
+  /**
+   * The starting date
+   * @type {Date}
+   */
+  startDate;
+
+  /**
+   * The ending date
+   * @type {Date}
+   */
+  endDate;
+
+  /**
+   * @param {Date} startDate - the starting datetime of the range
+   * @param {Date} endDate - the ending datetime of the range
+   */
+  constructor(startDate, endDate) {
+    this.reinitialize(startDate, endDate);
+  }
+
+  /**
+   * Reinitializes the object
+   * 
+   * (Sometimes useful for shifting times after the fact)
+   * 
+   * @param {Date} startDate - the starting date
+   * @param {Date} endDate - the ending date
+   */
+  reinitialize(startDate, endDate) {
+    if (startDate > endDate) {
+      this.startDate = endDate;
+      this.endDate = startDate;
+    } else {
+      this.startDate = startDate;
+      this.endDate = endDate;
+    }
+  }
+
+  /**
+   * Creates a DateRange based on the start and end of the day UTC.
+   * 
+   * This is very useful for determining overlapping dates.
+   * 
+   * @param {Date} targetDate - date to use to find the start and end UTC for
+   * @returns {DateRange}
+   */
+  static startAndEndOfDay(targetDate) {
+    const startDate = DateUtils.startOfDay(targetDate);
+    const endDate = DateUtils.endOfDay(targetDate);
+    return new DateRange(startDate, endDate);
+  }
+
+  /**
+   * Whether this dateRange overlaps with a target dateRange.
+   * @param {DateRange} targetDateRange - dateRange to compare
+   * @returns {Boolean}
+   * @example
+   * overlapA = new Date(Date.UTC(2024, 12, 26, 12, 0, 0));
+   * overlapB = new Date(Date.UTC(2024, 12, 26, 13, 0, 0));
+   * overlapC = new Date(Date.UTC(2024, 12, 26, 14, 0, 0));
+   * overlapD = new Date(Date.UTC(2024, 12, 26, 15, 0, 0));
+   * 
+   * rangeBefore = new utils.DateRange(overlapA, overlapB);
+   * rangeAfter = new utils.DateRange(overlapC, overlapD);
+   * 
+   * rangeBefore.overlaps(rangeAfter); // false
+   * rangeAfter.overlaps(rangeBefore); // false
+   * 
+   * rangeBefore = new utils.DateRange(overlapA, overlapC);
+   * rangeAfter = new utils.DateRange(overlapB, overlapD);
+   * 
+   * rangeBefore.overlaps(rangeAfter); // true
+   * rangeAfter.overlaps(rangeBefore); // true
+   */
+  overlaps(targetDateRange) {
+    return (this.endDate > targetDateRange.startDate
+        && this.startDate < targetDateRange.endDate);
+  }
+
+  /**
+   * Determines if a datetime is within the range
+   * 
+   * @param {Date} dateToCheck - the value to test if it is within the date range
+   * @returns {Boolean} - if the value is within the range (true) or not (false)
+   * 
+   * @example
+   * withinA = new Date(Date.UTC(2024, 12, 26, 12, 0, 0));
+   * withinB = new Date(Date.UTC(2024, 12, 26, 13, 0, 0));
+   * withinC = new Date(Date.UTC(2024, 12, 26, 14, 0, 0));
+   * withinD = new Date(Date.UTC(2024, 12, 26, 15, 0, 0));
+   * 
+   * range = new utils.DateRange(withinB, withinD);
+   * range.contains(withinA); // false - it was before the range
+   * 
+   * range.contains(withinB); // true
+   * range.contains(withinC); // true
+   * range.contains(withinD); // true
+   * 
+   */
+  contains(dateToCheck) {
+    const testTime = dateToCheck.getTime();
+    return testTime >= this.startDate.getTime() && testTime <= this.endDate.getTime();
+  }
+
+  /**
+   * Determines the millisecond duration between the end and start time.
+   * 
+   * ```
+   * durationA = new Date(Date.UTC(2024, 12, 26, 12, 0, 0));
+   * durationB = new Date(Date.UTC(2024, 12, 26, 13, 0, 0));
+   * range = new utils.DateRange(durationA, durationB);
+   * 
+   * range.durationString(); // 1 hour in milliseconds; 1000 * 60 * 60;
+   * ```
+   * 
+   * @returns {Number}
+   */
+  duration() {
+    return this.endDate.getTime() - this.startDate.getTime();
+  }
+
+  /**
+   * Determines the duration in a clear and understandable string;
+   * 
+   * ```
+   * durationA = new Date(Date.UTC(2024, 12, 26, 12, 0, 0));
+   * durationB = new Date(Date.UTC(2024, 12, 26, 13, 0, 0));
+   * range = new utils.DateRange(durationA, durationB);
+   * 
+   * range.durationString(); // '0 days, 1 hours, 0 minutes, 0.0 seconds';
+   * ```
+   * 
+   * @returns {String}
+   */
+  durationString() {
+    const dur = this.duration();
+    const divideRemainder = (val, denominator) => ({ value: Math.floor(val / denominator), remainder: val % denominator });
+    let result = divideRemainder(dur, DateUtils.TIME.DAY);
+    const days = result.value;
+    result = divideRemainder(result.remainder, DateUtils.TIME.HOUR);
+    const hours = result.value;
+    result = divideRemainder(result.remainder, DateUtils.TIME.MINUTE);
+    const minutes = result.value;
+    result = divideRemainder(result.remainder, DateUtils.TIME.SECOND);
+    const seconds = result.value;
+    const milli = result.remainder;
+    return `${days} days, ${hours} hours, ${minutes} minutes, ${seconds}.${milli} seconds`;
+  }
+
+  /**
+   * Determines the duration in days:hours:minutes:seconds.milliseconds
+   * 
+   * ```
+   * durationA = new Date(Date.UTC(2024, 12, 26, 12, 0, 0));
+   * durationB = new Date(Date.UTC(2024, 12, 26, 13, 0, 0));
+   * range = new utils.DateRange(durationA, durationB);
+   * 
+   * range.durationString(); // '0:01:00:00.0000';
+   * ```
+   * 
+   * @returns {String}
+   */
+  durationISO() {
+    const dur = this.duration();
+    const divideRemainder = (val, denominator) => ({ value: Math.floor(val / denominator), remainder: val % denominator });
+    let result = divideRemainder(dur, DateUtils.TIME.DAY);
+    const days = String(result.value);
+    result = divideRemainder(result.remainder, DateUtils.TIME.HOUR);
+    const hours = String(result.value).padStart(2, '0');
+    result = divideRemainder(result.remainder, DateUtils.TIME.MINUTE);
+    const minutes = String(result.value).padStart(2, '0');
+    result = divideRemainder(result.remainder, DateUtils.TIME.SECOND);
+    const seconds = String(result.value).padStart(2, '0');
+    const milli = String(result.remainder).padStart(4, '0');
+    return `${days}:${hours}:${minutes}:${seconds}.${milli}`;
+  }
+
+  /**
+   * Determines if both the startDate and endDate are valid dates.
+   * 
+   * @returns {Boolean}
+   */
+  isValid() {
+    return DateUtils.isValid(this.startDate) && DateUtils.isValid(this.endDate);
+  }
+
+  /**
+   * Converts the daterange to a string value
+   * 
+   * ```
+   * durationA = new Date(Date.UTC(2024, 12, 26, 12, 0, 0));
+   * durationB = new Date(Date.UTC(2024, 12, 26, 13, 0, 0));
+   * range = new utils.DateRange(durationA, durationB);
+   * 
+   * range.toString(); // '2025-01-26T12:00:00.000Z to 2025-01-26T13:00:00.000Z';
+   * ```
+   * 
+   * @returns {String}
+   */
+  toString() {
+    return `${this.startDate.toISOString()} to ${this.endDate.toISOString()}`;
+  }
+
+  /**
+   * Converts the daterange to a local string value
+   * 
+   * ```
+   * durationA = new Date(Date.UTC(2024, 12, 26, 12, 0, 0));
+   * durationB = new Date(Date.UTC(2024, 12, 26, 13, 0, 0));
+   * range = new utils.DateRange(durationA, durationB);
+   * 
+   * range.toLocaleString(); // '1/26/2025, 12:00:00 PM to 1/26/2025, 1:00:00 PM'
+   * ```
+   * 
+   * @returns {String}
+   */
+  toLocaleString() {
+    return `${this.startDate.toLocaleString()} to ${this.endDate.toLocaleString()}`;
+  }
+}
+
+module.exports.DateRange = DateRange;

package/src/format.js

@@ -1347,3 +1347,19 @@ module.exports.extractWords = function extractWords(strToExtractFrom, additional
   
   return cleanStrings.reduce((result, str) => [...result, ...((str || '').match(regex) || [])], []);
 };
+
+/**
+ * A function that returns the value provided
+ * 
+ * ```
+ * alwaysBlack = utils.format.constantFn('#000000');
+ * alwaysBlack(); // '#000000'
+ * alwaysBlack(); // '#000000'
+ * ```
+ * 
+ * @param {any} val - Any value
+ * @returns {Function} - a function that accepts no parameters, and always returns value provided
+ */
+module.exports.constantFn = function constantFn(val) {
+  return () => val;
+};

package/src/hashMap.js

@@ -216,3 +216,27 @@ module.exports.fromObject = function fromObject(target) {
   return [...Object.keys(target)]
     .reduce((result, key) => HashMapUtil.add(result, key, target[key]), new Map());
 };
+
+/**
+ * Simple and safe Map accessing function.
+ * 
+ * ```
+ * styleMap = new Map(['1', 'background-color: #FF0000'], ['2', 'background-color: #00FF00']]);
+ * styleFn = utils.map.mappingFn(styleMap, 'background-color: #aaaaaa');
+ * 
+ * styleFn('1'); // 'background-color: #FF0000';
+ * styleFn('2'); // 'background-color: #00FF00';
+ * styleFn('somethingElse'); // 'background-color: #aaaaaa' - because it was not found
+ * 
+ * @param {Map} map - map to use when checking the subsequent function
+ * @param {any} [defaultValue=''] - default value to return if key is not found
+ * @returns {Function} - (key) => map.get(key) || defaultValue
+ */
+module.exports.mappingFn = function mappingFn(map, defaultValue = '') {
+  return function mappingFnImpl(key) {
+    if (map.has(key)) {
+      return map.get(key);
+    }
+    return defaultValue;
+  };
+};

package/src/index.js

@@ -4,6 +4,7 @@ const base64 = require('./base64');
 const chain = require('./chain');
 const color = require('./color');
 const datasets = require('./datasets');
+const date = require('./date');
 const describe = require('./describe');
 const group = require('./group');
 const hashMap = require('./hashMap');
@@ -50,6 +51,9 @@ module.exports = {
   /** @see {@link module:datasets} */
   datasets,
   dataset: datasets,
+  /** @see {@link module:date} */
+  date,
+  DateRange: date.DateRange,
   /** @see {@link module:describe} */
   describe,
   /** @see {@link module:file} */

package/src/object.js

@@ -217,6 +217,7 @@ module.exports.augment = function augment(objCollection, mappingFn, inPlace = fa
  * @param {Function | String} propertyOrFn - Name of the property or Function to return a value
  * @returns {Map<String, Object>} - map using the propertyName as the key
  * @see {@link module:group.by|group(collection, propertyOrFn)} - if there is a possibility the records are not unique
+ * @see {@link module:object.join|object.join()} - join two objects by a shared index
  * @example
  * const data = [{ id: '123', name: 'jim' },
  *    { id: '456', name: 'mary' },
@@ -1248,6 +1249,7 @@ module.exports.generateSchema = function generateSchema(targetObj) {
  * @param {Function} joinFn - function to call each time an objectArray object, has an indexField found in targetMap <br />
  *      Signature: `(sourceObj:Object, mappedObject:Object) => {Object}`
  * @returns {Array<Object>} - Array of results returned from `joinFn`
+ * @see {@link module:object.mapByProperty|object.mapByProperty}
  */
 module.exports.join = function join(objectArray, indexField, targetMap, joinFn) {
   const cleanArray = !objectArray