jupyter-ijavascript-utils 1.51.0 → 1.52.1

package/DOCS.md

@@ -74,6 +74,8 @@ Give it a try here:
 [![Binder:what can I do with this](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/paulroth3d/jupyter-ijavascript-utils/main?labpath=example.ipynb)
 
 ## What's New
+* 1.52 - print a date to ISO in local time with {@link module:date.toLocalISO|date.toLocalISO}
+* 1.51 - added in {@link module:date|date} - and addressed issue #69, #68, #67, #66
 * 1.50 - added in {@link module:color|color/colour} - and addressed issue #65
 * 1.49 - Additional documentation for issues #18, #63, #62, #61 (like table.generateObjectCollection)
 * 1.48 - Correct table rendering html if filter was used ({@link https://github.com/paulroth3d/jupyter-ijavascript-utils/issues/64|#64})

package/Dockerfile

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

package/README.md

@@ -53,7 +53,9 @@ This is not intended to be the only way to accomplish many of these tasks, and a
 
 ![Screenshot of example notebook](docResources/img/mainExampleNotebook.png)
 
-# What's New
+# What's New 
+* 1.52 - print a date to ISO in local time with date.toLocalISO
+* 1.51 - added in date - and addressed issues #69, #68, #67, #66
 * 1.50 - added in color/colour - and addressed issue #65
 * 1.49 - Additional documentation for issues #18, #63, #62, #61 (like table.generateObjectCollection)
 * 1.48 - Correct table rendering html if filter was used (#46)

package/package.json

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

package/src/date.js

@@ -7,6 +7,7 @@
  * * 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.toLocalISO|date.toLocalISO} - prints in 8601 format with timezone offset based on a tz entry - like america/chicago
  *   * {@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
@@ -15,6 +16,10 @@
  *   * {@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
+ * * Print
+ *   * {@link module:date.durationLong|date.durationLong(epoch)} - displays duration in legible form:
+ *      `D days, H hours, M minutes, S.MMM seconds`
+ *   * {@link module:date.durationISO|date.durationISO(epoch)} - displays duration in condensed forme:
  * 
  * --------
  * 
@@ -35,6 +40,8 @@
 module.exports = {};
 const DateUtils = module.exports;
 
+module.exports.divideRemainder = (val, denominator) => ({ value: Math.floor(val / denominator), remainder: val % denominator });
+
 /**
  * Collection of time durations in milliseconds
  */
@@ -99,55 +106,151 @@ module.exports.parse = (dateStr) => {
   return result;
 };
 
-module.exports.timeZoneOffsets = new Map();
+/**
+ * Prints the duration in ISO format: `D:HH:MM:SS.MMM`
+ * 
+ * ```
+ * start = new Date(Date.ISO(2024, 12, 26, 12, 0, 0));
+ * end = new Date(Date.ISO(2024, 12, 26, 13, 0, 0));
+ * 
+ * duration = end.getTime() - start.getTime();
+ * 
+ * utils.date.durationLong(duration); // '0 days, 1 hours, 0 minutes, 0.00 seconds'
+ * 
+ * @param {Number} epochDifference - difference in milliseconds between two dates
+ * @returns {String} `D days, H hours, M minutes,S.MMMM seconds`
+ * @see {@link module:date.DateRange.duration|DateRange.duration}
+ */
+module.exports.durationISO = function durationISO(epochDifference) {
+  const signStr = epochDifference < 0 ? '-' : '';
+  let result = DateUtils.divideRemainder(Math.abs(epochDifference), DateUtils.TIME.DAY);
+  const days = String(result.value);
+  result = DateUtils.divideRemainder(result.remainder, DateUtils.TIME.HOUR);
+  const hours = String(result.value).padStart(2, '0');
+  result = DateUtils.divideRemainder(result.remainder, DateUtils.TIME.MINUTE);
+  const minutes = String(result.value).padStart(2, '0');
+  result = DateUtils.divideRemainder(result.remainder, DateUtils.TIME.SECOND);
+  const seconds = String(result.value).padStart(2, '0');
+  const milli = String(result.remainder).padStart(3, '0');
+  return `${signStr}${days}:${hours}:${minutes}:${seconds}.${milli}`;
+};
 
 /**
- * Determines the number of milliseconds difference between
- * a given timezone and UTC.
+ * Prints the duration in long format: `D days, H hours, M minutes, S.MMM seconds`
  * 
- * (Note: these values are cached, and optimized for repeated use on the same value)
+ * ```
+ * start = new Date(Date.ISO(2024, 12, 26, 12, 0, 0));
+ * end = new Date(Date.ISO(2024, 12, 27, 13, 0, 0));
  * 
- * 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.
+ * duration = end.getTime() - start.getTime();
  * 
- * @param {String} timeZoneStr - a timezone string like "America/Toronto"
- * @returns {Number} - the number of milliseconds between UTC and that timezone
+ * utils.date.durationLong(duration); // '1 days, 1 hours, 0 minutes, 0.00 seconds'
+ * 
+ * @param {Number} epochDifference - difference in milliseconds between two dates
+ * @returns {String} `D days, H hours, M minutes,S.MMMM seconds`
+ * @see {@link module:date.DateRange.duration|DateRange.duration}
  */
-module.exports.getTimezoneOffset = function getTimezoneOffset(timeZoneStr) {
-  if (DateUtils.timeZoneOffsets.has(timeZoneStr)) {
-    return DateUtils.timeZoneOffsets.get(timeZoneStr);
+module.exports.durationLong = function durationLong(epochDifference) {
+  const signStr = epochDifference < 0 ? '-' : '';
+  let result = DateUtils.divideRemainder(Math.abs(epochDifference), DateUtils.TIME.DAY);
+  const days = result.value;
+  result = DateUtils.divideRemainder(result.remainder, DateUtils.TIME.HOUR);
+  const hours = result.value;
+  result = DateUtils.divideRemainder(result.remainder, DateUtils.TIME.MINUTE);
+  const minutes = result.value;
+  result = DateUtils.divideRemainder(result.remainder, DateUtils.TIME.SECOND);
+  const seconds = result.value;
+  const milli = result.remainder;
+  return `${signStr}${days} days, ${hours} hours, ${minutes} minutes, ${seconds}.${milli} seconds`;
+};
+
+/**
+ * @typedef {Object} TimeZoneEntry
+ * @property {String} tz - the name of the timezone
+ * @property {Function} formatter - formats a date to that local timezone
+ * @property {Number} epoch - the difference in milliseconds from that tz to UTC
+ * @property {String} offset - ISO format for how many hours and minutes offset to UTC '+|-' HH:MMM 
+ */
+
+/**
+ * Collection of TimeZoneEntries by the tz string
+ * @private
+ * @type {Map<String,TimeZoneEntry>}
+ */
+module.exports.timeZoneOffsetMap = new Map();
+
+/**
+ * Fetches or creates a TimeZoneEntry
+ * @private
+ * @param {String} timeZoneStr - tz database entry for the timezone
+ * @returns {TimeZoneEntry}
+ */
+module.exports.getTimezoneEntry = function getTimezoneEntry(timeZoneStr) {
+  const cleanTz = String(timeZoneStr).toLowerCase();
+  if (DateUtils.timeZoneOffsetMap.has(cleanTz)) {
+    return DateUtils.timeZoneOffsetMap.get(cleanTz);
   }
   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 formatter = (dateValue) => {
+    const dtFormat = new Intl.DateTimeFormat('en-us', {
+      year: 'numeric',
+      month: 'numeric',
+      day: 'numeric',
+      hour: 'numeric',
+      minute: 'numeric',
+      second: 'numeric',
+      hour12: false,
+      fractionalSecondDigits: 3,
+      timeZone: cleanTz
+    });
+    const dm = dtFormat.formatToParts(dateValue)
+      .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)}`;
+    return dateStr;
+  };
+  
+  const impactedDateStr = formatter(d);
+  const impactedDate = new Date(impactedDateStr);
 
   const diff = d.getTime() - impactedDate.getTime();
 
-  DateUtils.timeZoneOffsets.set(timeZoneStr, diff);
+  const diffSign = diff > 0 ? '-' : '+';
+  let remainder = DateUtils.divideRemainder(Math.abs(diff), DateUtils.TIME.HOUR);
+  const diffHours = remainder.value;
+  remainder = DateUtils.divideRemainder(remainder.remainder, DateUtils.TIME.MINUTE);
+  const diffMinutes = remainder.value;
+  const offset = `${diffSign}${DateUtils.padTime(diffHours)}:${DateUtils.padTime(diffMinutes)}`;
 
-  return diff;
+  const result = ({ tz: cleanTz, formatter, epoch: diff, offset });
+
+  DateUtils.timeZoneOffsetMap.set(cleanTz, result);
+
+  return result;
+};
+
+/**
+ * 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 {TimeZoneEntry} - the number of milliseconds between UTC and that timezone
+ */
+module.exports.getTimezoneOffset = function getTimezoneOffset(timeZoneStr) {
+  return DateUtils.getTimezoneEntry(timeZoneStr).epoch;
 };
 
 /**
@@ -181,8 +284,8 @@ module.exports.getTimezoneOffset = function getTimezoneOffset(timeZoneStr) {
  * @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);
+  const { epoch } = DateUtils.getTimezoneEntry(timeZoneStr);
+  return new Date(date.getTime() + epoch);
 };
 
 /**
@@ -194,10 +297,33 @@ module.exports.correctForTimezone = function correctForTimezone(date, timeZoneSt
  * @param {Date} date - date to shift
  * @param {String} timeZoneStr - the tz database name of the timezone
  * @returns {Date}
+ * @see {@link module:date.toLocalISO|date.toLocalISO} - consider as an alternative.
+ *    This prints the correct time, without updating the date object.
  */
 module.exports.epochShift = function epochShift(date, timeZoneStr) {
-  const offsetMilli = DateUtils.getTimezoneOffset(timeZoneStr);
-  return new Date(date.getTime() - offsetMilli);
+  const { epoch } = DateUtils.getTimezoneEntry(timeZoneStr);
+  return new Date(date.getTime() - epoch);
+};
+
+/**
+ * Prints a date in 8601 format to a timezone (with +H:MM offset)
+ * 
+ * Consider this as an alternative to epochShifting.
+ * 
+ * ```
+ * d = Date.parse('2024-12-27 13:30:00');
+ * 
+ * utils.date.toLocalISO(d, 'america/Chicago'); // '2024-12-27T07:30:00.000-06:00'
+ * utils.date.toLocalISO(d, 'europe/paris'); //    '2024-12-27T14:30:00.000+01:00'
+ * ```
+ * 
+ * @param {Date} date - date to print
+ * @param {String} timeZoneStr - the tz database name of the timezone
+ * @returns {String} - ISO format with timezone offset
+ */
+module.exports.toLocalISO = function toLocalISO(date, timeZoneStr) {
+  const { formatter, offset } = DateUtils.getTimezoneEntry(timeZoneStr);
+  return `${formatter(date)}${offset}`;
 };
 
 /**
@@ -336,10 +462,10 @@ class 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));
+   * overlapA = new Date(Date.UTC(2024, 11, 26, 12, 0, 0));
+   * overlapB = new Date(Date.UTC(2024, 11, 26, 13, 0, 0));
+   * overlapC = new Date(Date.UTC(2024, 11, 26, 14, 0, 0));
+   * overlapD = new Date(Date.UTC(2024, 11, 26, 15, 0, 0));
    * 
    * rangeBefore = new utils.DateRange(overlapA, overlapB);
    * rangeAfter = new utils.DateRange(overlapC, overlapD);
@@ -365,10 +491,10 @@ class DateRange {
    * @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));
+   * withinA = new Date(Date.UTC(2024, 11, 26, 12, 0, 0));
+   * withinB = new Date(Date.UTC(2024, 11, 26, 13, 0, 0));
+   * withinC = new Date(Date.UTC(2024, 11, 26, 14, 0, 0));
+   * withinD = new Date(Date.UTC(2024, 11, 26, 15, 0, 0));
    * 
    * range = new utils.DateRange(withinB, withinD);
    * range.contains(withinA); // false - it was before the range
@@ -387,8 +513,8 @@ class DateRange {
    * 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));
+   * durationA = new Date(Date.UTC(2024, 11, 26, 12, 0, 0));
+   * durationB = new Date(Date.UTC(2024, 11, 26, 13, 0, 0));
    * range = new utils.DateRange(durationA, durationB);
    * 
    * range.durationString(); // 1 hour in milliseconds; 1000 * 60 * 60;
@@ -404,8 +530,8 @@ class DateRange {
    * 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));
+   * durationA = new Date(Date.UTC(2024, 11, 26, 12, 0, 0));
+   * durationB = new Date(Date.UTC(2024, 11, 26, 13, 0, 0));
    * range = new utils.DateRange(durationA, durationB);
    * 
    * range.durationString(); // '0 days, 1 hours, 0 minutes, 0.0 seconds';
@@ -415,25 +541,15 @@ class DateRange {
    */
   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`;
+    return DateUtils.durationLong(dur);
   }
 
   /**
    * 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));
+   * durationA = new Date(Date.UTC(2024, 11, 26, 12, 0, 0));
+   * durationB = new Date(Date.UTC(2024, 11, 26, 13, 0, 0));
    * range = new utils.DateRange(durationA, durationB);
    * 
    * range.durationString(); // '0:01:00:00.0000';
@@ -443,17 +559,7 @@ class DateRange {
    */
   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}`;
+    return DateUtils.durationISO(dur);
   }
 
   /**
@@ -469,8 +575,8 @@ class DateRange {
    * 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));
+   * durationA = new Date(Date.UTC(2024, 11, 26, 12, 0, 0));
+   * durationB = new Date(Date.UTC(2024, 11, 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';
@@ -486,8 +592,8 @@ class DateRange {
    * 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));
+   * durationA = new Date(Date.UTC(2024, 11, 26, 12, 0, 0));
+   * durationB = new Date(Date.UTC(2024, 11, 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'