jupyter-ijavascript-utils 1.55.0 → 1.57.0

package/DOCS.md

@@ -74,6 +74,12 @@ 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.57 - #86 - include examples on binning based on time series {@link https://github.com/paulroth3d/jupyter-ijavascript-utils/issues/86|see more here}
+    * #87 - add in {@link module:file.fileExists|file.fileExists} to make things easier for new people getting started
+    * #89 - allow {@link module:array.resize|array.resize} to work with defaults, if zipping arrays of different sizes
+    * #90 - correct issue with timezone offsets, so it is no longer possible to get a timezone offset +24:00 from any of the localizations - like {@link module:date.toLocalISO|date.toLocalISO}
+    * #92 - make it easier to handle big expensive calculations with a cache, see {@link module:ijs.useCache|ijs.useCache()} and {@link module:file.useCache|file.useCache()}
+* 1.56 - #84 (object.renamePropertiesFromList), #82 (date.getWeekday)
 * 1.55 - #76, #77, #74, #78
 * 1.54 - additional Date logic, and formatting. #70 #71 #72
 * 1.53 - additional docs and examples for {@link module:color|color/colour} package.

package/Dockerfile

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

package/README.md

@@ -54,6 +54,12 @@ 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 
+* 1.57 - #86 - include examples on binning based on time series
+    * #87 - add in fileExists to make things easier for new people getting started
+    * #89 - allow resizing arrays with defaults, if zipping arrays of different sizes
+    * #90 - correct issue with timezone offsets, so it is no longer possible to get a timezone offset +24:00
+    * #92 - make it easier to handle big expensive calculations with a cache
+* 1.56 - #84 (object.renamePropertiesFromList), #82 (date.getWeekday)
 * 1.55 - #76, #77, #74, #78
 * 1.54 - additional Date logic, and formatting. #70 #71 #72
 * 1.53 - additional docs and examples for color/colour package.

package/package.json

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

package/src/array.js

@@ -1460,18 +1460,25 @@ module.exports.asyncWaitAndChain = (seconds, fn, rows) => {
  * 
  * utils.array.resize(categoryValues, 2); // ['rock', 'paper']
  * utils.array.resize(categoryValues, 7); // ['rock', 'paper', 'scissors',
- * 'rock', 'paper', 'scissors', 'rock];
+ * undefined, undefined, undefined, undefined];
  * ```
  * 
  * @param {Array} sourceList - array of values
- * @param {Number} length - new number of items in the list
+ * @param {Number} length - new length of the list
  */
-module.exports.resize = function resize(sourceList, length) {
+module.exports.resize = function resize(sourceList, length, defaultValue = undefined) {
   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]);
+
+  const result = new Array(length)
+    .fill(defaultValue);
+
+  sourceList.forEach((val, index) => {
+    if (index >= length) return;
+    result[index] = val;
+  });
+
+  return result;
 };
 
 /**
@@ -1532,9 +1539,9 @@ module.exports.zip = function zip(arrayLeft, arrayRight, ...rest) {
   if (cleanLeft.length === 0 && cleanRight.length === 0) {
     result = [[]];
   } else if (cleanLeft.length === 0) {
-    result = cleanRight.map((val) => Array.isArray(val) ? val : [val]);
+    result = cleanRight.map((val) => Array.isArray(val) ? val : (typeof val === 'string') ? [val] : [...val]);
   } else if (cleanRight.length === 0) {
-    result = cleanLeft.map((val) => Array.isArray(val) ? val : [val]);
+    result = cleanLeft.map((val) => Array.isArray(val) ? val : (typeof val === 'string') ? [val] : [...val]);
   } else {
     const cleanLeftLen = cleanLeft.length;
     const cleanRightLen = cleanRight.length;

package/src/date.js

@@ -8,6 +8,7 @@
  *   * {@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.localISOFormatter|date.localISOFormatter} - prints in 8601 format - slightly improved performance for large scale use
  *   * {@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
@@ -180,12 +181,22 @@ module.exports.durationLong = function durationLong(epochDifference) {
   return `${signStr}${days} days, ${hours} hours, ${minutes} minutes, ${seconds}.${milli} seconds`;
 };
 
+/**
+ * Function that is passed a date for formatting
+ * 
+ * @callback dateFormatter
+ * @param {Date} dateToFormat - the date to format
+ */
+
 /**
  * @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 
+ * @property {dateFormatter} toLocalISO - formatter function that formats a date to local ISO
+ * @property {dateFormatter} toLocalISOWeekday - formatter function that formats a date to local ISO + weekday
+ * @property {dateFormatter} getWeekday - formatter function that determines the day of week for a date
  */
 
 /**
@@ -220,6 +231,12 @@ module.exports.getTimezoneEntry = function getTimezoneEntry(timezoneStr) {
     timeZone: cleanTz
   });
 
+  const dayOfWeekFormat = new Intl.DateTimeFormat('en-us', {
+    weekday: 'short',
+    timeZone: cleanTz
+  });
+  const getWeekday = (date) => dayOfWeekFormat.format(date);
+
   const getOffset = (dateValue) => {
     const dm = dtFormat.formatToParts(dateValue)
       .filter(({ type }) => type !== 'literal')
@@ -249,7 +266,8 @@ module.exports.getTimezoneEntry = function getTimezoneEntry(timezoneStr) {
   
   const impactedDate = getOffset(d);
 
-  const diff = d.getTime() - impactedDate.getTime();
+  //-- avoid +24:00 or -24:00 - the number of seconds within a day
+  const diff = (d.getTime() - impactedDate.getTime()) % 86400000;
 
   const diffSign = diff > 0 ? '-' : '+';
   let remainder = DateUtils.divideRemainder(Math.abs(diff), DateUtils.TIME.HOUR);
@@ -258,7 +276,10 @@ module.exports.getTimezoneEntry = function getTimezoneEntry(timezoneStr) {
   const diffMinutes = remainder.value;
   const offset = `${diffSign}${DateUtils.padTime(diffHours)}:${DateUtils.padTime(diffMinutes)}`;
 
-  const result = ({ tz: cleanTz, formatter, epoch: diff, offset });
+  const toLocalISO = (date) => `${formatter(date)}${offset}`;
+  const toLocalISOWeekday = (date) => `${formatter(date)}${offset} - ${getWeekday(date)}`;
+
+  const result = ({ tz: cleanTz, formatter, toLocalISO, toLocalISOWeekday, getWeekday, epoch: diff, offset });
 
   DateUtils.timezoneOffsetMap.set(cleanTz, result);
 
@@ -381,27 +402,14 @@ module.exports.correctForOtherTimezone = function correctForTimezones(date, sour
  * 
  * Use this if you somehow have a date that needs to be shifted by the timezone offset.
  * 
- * This is rarely useful in itself, but in combination with the {@link module:date.correctForTimezone|date.correctForTimezone}
- * you can use this to correct for "local dates" but are in another timezone than you are in.
- * 
- * (For example, you got a local date for 2:15 PM EST, but your current computer is in CST)
+ * For example, if you have a time that is already in GMT, and want the date shifted by a timezone.
  * 
- * JavaScript dates only have three ways of importing dates:
- * 
- * * Parse the date assuming local timezone
- * * Parse the date using [ISO 8601 formats](https://www.iso.org/iso-8601-date-and-time-format.html)
- *    * This option DOES provide an option for providing a timezone offset (ex: `-0500`)
- * 
- * Since this is the opposite of {@link module:date.correctForTimezone|date.correctForTimezone}, this can be useful.
- * 
- * But most likely, you'd like to use either:
- * 
- * * {@link module:date.correctForTimezone|date.correctForTimezone} or
- * * {@link module:date.correctForTimezones|date.correctForTimezones}.
+ * This is used internally for {@link module:date.correctForOtherTimezone|date.correctForOtherTimezone}
+ * if local dates are provided - but for a different timezone you yourself are not in.
  * 
  * ---
  * 
- * Epoch shift a date, so the utcDate is no longer correct,
+ * Epoch shift changes the internals of a JavaScript date, so the utcDate is no longer correct,
  * but many other functions behave closer to expected.
  * 
  * Once you epoch shift the date, then time stored in the date is incorrect (because it always points to GMT)
@@ -410,20 +418,8 @@ module.exports.correctForOtherTimezone = function correctForTimezones(date, sour
  * 
  * See {@link https://stackoverflow.com/a/15171030|here why this might not be what you want}
  * 
- * --
- * 
- * Sometimes though, some libraries use the "getMonth()", "getDate()" of the date, and do not support using timezones.
- * 
- * That is when this shines.
- * 
- * ```
- * timeStamp = 1738437341000;
- * d = new Date(timeStamp);
- * d.toIsoString(); // 2025-02-01T19:15:41.000Z
- * `current time is: ${d.getFullYear()}-${d.getMonth() + 1}-${d.getDate()}` // 'current time is: 2025-2-1'
- * 
- * 
- * ```
+ * * {@link module:date.correctForTimezone|date.correctForTimezone} or
+ * * {@link module:date.correctForTimezones|date.correctForTimezones}.
  * 
  * @param {Date} date - date to shift
  * @param {String} timezoneStr - the tz database name of the timezone
@@ -456,13 +452,66 @@ module.exports.epochShift = function epochShift(date, timezoneStr) {
  * utils.date.toLocalISO(d, 'europe/paris'); //    '2024-12-27T14:30:00.000+01:00'
  * ```
  * 
+ * Sometimes it is helpful to have the weekday to make sense of things
+ * 
+ * ```
+ * utils.date.toLocalISO(d, 'america/Chicago', true); // '2024-12-27T07:30:00.000-06:00 FRI' 
+ * utils.date.toLocalISO(d, 'europe/paris', true); //    '2024-12-27T14:30:00.000+01:00 FRI'
+ * ```
+ * 
  * @param {Date} date - date to print
  * @param {String} timezoneStr - the tz database name of the timezone
+ * @param {Boolean} [includeWeekday=false] - whether to include the weekday
+ * @see {@link module:date.localISOFormatter|date.localISOFormatter} - if you're converting to string frequently
  * @returns {String} - ISO format with timezone offset
  */
-module.exports.toLocalISO = function toLocalISO(date, timezoneStr) {
-  const { formatter, offset } = DateUtils.getTimezoneEntry(timezoneStr);
-  return `${formatter(date)}${offset}`;
+module.exports.toLocalISO = function toLocalISO(date, timezoneStr, includeWeekday = false) {
+  if (includeWeekday) {
+    return DateUtils.getTimezoneEntry(timezoneStr).toLocalISOWeekday(date);
+  }
+  return DateUtils.getTimezoneEntry(timezoneStr).toLocalISO(date);
+};
+
+/**
+ * If repeatedly asking for a local time, use this method instead.
+ * 
+ * ```
+ * myDate = new Date('2025-01-15T06:00:00.000Z');
+ * centralFormatter = utils.date.localISOFormatter('us/central');
+ * centralFormatter(myDate); // '2025-01-15T00:00:00.000Z'
+ * ```
+ * 
+ * as opposed to
+ * 
+ * ```
+ * myDate = new Date('2025-01-15T06:00:00.000Z');
+ * utils.date.toLocalISO(myDate, 'us/central'); // '2025-01-15T00:00:00.000Z'
+ * ```
+ * 
+ * @param {String} timezoneStr 
+ * @returns {dateFormatter} - (date) => {String} 'yyyy-mm-ddThh:mm:ss.MMM[+-]TZOFFSET'
+ * @see {@link module:date.toLocalISO|date.toLocalISO}
+ */
+module.exports.localISOFormatter = function localISOFormatter(timezoneStr, includeWeekday = false) {
+  if (includeWeekday) {
+    return DateUtils.getTimezoneEntry(timezoneStr).toLocalISOWeekday;
+  }
+  return DateUtils.getTimezoneEntry(timezoneStr).toLocalISO;
+};
+
+/**
+ * Determines the weekday of a date
+ * @param {Date} date - date to print
+ * @param {String} timezoneStr - the tz database name of the timezone
+ * @returns {String} - Currently returns `en-us` formatted day of week of a date
+ * @see {@link module:date.toLocalISO|date.toLocalISO}
+ * @example
+ * date = new Date('2025-01-15T06:00:00.000Z');
+ * utils.date.getWeekday(date, 'us/pacific'); // Tue
+ * utils.date.getWeekday(date, 'us/eastern'); // Wed
+ */
+module.exports.getWeekday = function weekdayFormatter(date, timezoneStr) {
+  return DateUtils.getTimezoneEntry(timezoneStr).getWeekday(date);
 };
 
 module.exports.toIsoStringNoTimezone = function toIsoStringNoTimezone(date) {
@@ -771,12 +820,19 @@ class DateRange {
    */
   endDate;
 
+  /**
+   * Data attached to the DateTime
+   * @type {any}
+   */
+  data;
+
   /**
    * @param {Date|String} startDate - the starting date
    * @param {Date|String} endDate - the ending date
+   * @param {any} [data] - any data to store
    */
-  constructor(startDate, endDate) {
-    this.reinitialize(startDate, endDate);
+  constructor(startDate, endDate, data = null) {
+    this.reinitialize(startDate, endDate, data);
   }
 
   /**
@@ -794,6 +850,31 @@ class DateRange {
   * //  {start: 2025-03-01TT00:00:00, end: 2025-04-01TT00:00:00}]
   * ```
   * 
+  * Often though, we want to remember something about the DateRange,
+  * like which dates that it collected.
+  * 
+  * ```
+  * arrayGenerator = function() { return [] };
+  * rangeList = utils.DateRange.fromList(dates, arrayGenerator);
+  * // [{start: 2025-01-01T00:00:00, end: 2025-02-01TT00:00:00},
+  * //  {start: 2025-02-01TT00:00:00, end: 2025-03-01TT00:00:00},
+  * //  {start: 2025-03-01TT00:00:00, end: 2025-04-01TT00:00:00}]
+  * 
+  * dates.forEach((date) => rangeList
+  *   .find(rl => rl.contains(date))
+  *   .data.push(date)
+  * );
+  * 
+  * rangeList
+  *   .map(rl => `${rl.toString()}: has ${rl.data.length}`)
+  *   .join('\n');
+  * 
+  * // 2025-01-01T00:00:00.000Z to 2025-02-01T00:00:00.000Z: has 2
+  * // 2025-02-01T00:00:00.000Z to 2025-03-01T00:00:00.000Z: has 1
+  * // 2025-03-01T00:00:00.000Z to 2025-04-01T00:00:00.000Z: has 1
+  * 
+  * ```
+  * 
   * (Note: you can also use {@link module:date.arrange|date.arrange} or
   * {@link module:date.generateDateSequence|date.generateDateSequence}
   * to come up with the list of those dates)
@@ -802,18 +883,27 @@ class DateRange {
   * the simplest is to remove the dates from the resulting list.)
   * 
   * @param {Date[]} dateList - list of dates
+  * @param {Function} [dataCreationFn] - optional generator for data to be stored in each DataRange in the sequence
   * @returns {DateRange[]} - list of dateList.length-1 dateRanges,
   *   where the end of the firstRange is the start of the next.
   * @see {@link module:date.arrange|date.arrange} - to create dates by adding a value multiple times
   * @see {@link module:date.generateDateSequence|date.generateDateSequence} - to create dates between a start and an end date
   */
-  static fromList(dateSequence) {
+  static fromList(dateSequence, dataCreationFn) {
     if (dateSequence.length < 2) return [];
 
     const results = new Array(dateSequence.length - 2);
-    for (let i = 0; i < dateSequence.length - 1; i += 1) {
-      results[i] = new DateRange(dateSequence[i], dateSequence[i + 1]);
+
+    if (dataCreationFn) {
+      for (let i = 0; i < dateSequence.length - 1; i += 1) {
+        results[i] = new DateRange(dateSequence[i], dateSequence[i + 1], dataCreationFn());
+      }
+    } else {
+      for (let i = 0; i < dateSequence.length - 1; i += 1) {
+        results[i] = new DateRange(dateSequence[i], dateSequence[i + 1]);
+      }
     }
+    
     return results;
   }
 
@@ -824,8 +914,9 @@ class DateRange {
    * 
    * @param {Date|String} startDate - the starting date
    * @param {Date|String} endDate - the ending date
+   * @param {any} [data] - any data to store
    */
-  reinitialize(startDate, endDate) {
+  reinitialize(startDate, endDate, data = null) {
     const cleanStart = startDate instanceof Date
       ? startDate
       : new Date(Date.parse(startDate));
@@ -840,6 +931,8 @@ class DateRange {
       this.startDate = cleanStart;
       this.endDate = cleanEnd;
     }
+
+    this.data = data;
   }
 
   /**

package/src/file.js

@@ -29,6 +29,9 @@ const logger = require('./logger');
  *   * {@link module:file.matchFiles|matchFiles(path, matchingFn)} - find files or directories based on type of file or name
  * * checking files exist
  *   * {@link module:file.checkFile|checkFile(...paths)} - check if a file at a path exists
+ *   * {@link module:file.fileExists|fileExists(filePath)} - check if a single file at a path exists
+ * * using a cache for long running executions
+ *   * {@link module:file.useCache|file.useCache()} - perform an expensive calculation and write to a cache, or read from the cache transparently
  * 
  * ---
  * 
@@ -96,6 +99,8 @@ const FileUtil = module.exports;
  * 
  * @param {string} filePath - path of the file to load
  * @param {Object} fsOptions - options to pass for fsRead (ex: { encoding: 'utf-8' })
+ * @param {Function} fsOptions.formatter - formatter to use when writing the JSON
+ * @param {String} fsOptions.encoding - the encoding to write the JSON out with
  * @example
  * const weather = [
  *   { id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87 },
@@ -117,7 +122,11 @@ const FileUtil = module.exports;
 module.exports.readJSON = function readJSON(filePath, fsOptions = {}) {
   const resolvedPath = path.resolve(filePath);
   const optionsDefaults = { encoding: 'utf-8' };
-  const cleanedOptions = { ...optionsDefaults, ...fsOptions };
+  let cleanedOptions = { ...optionsDefaults, ...fsOptions };
+
+  //-- unfortunately we cannot pass the formatter in addition, it must replace
+  //-- https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse
+  if (cleanedOptions.formatter) cleanedOptions = cleanedOptions.formatter;
 
   /** @type {string} */
   let result;
@@ -227,12 +236,14 @@ module.exports.readFile = function readFile(filePath, fsOptions = {}) {
  */
 module.exports.writeJSON = function writeJSON(filePath, contents, fsOptions = {}) {
   //-- if it isn't desired, simply pass as a string.
-  const jsonContents = JSON.stringify(contents, null, 2);
   const optionsDefaults = { encoding: 'utf-8' };
   const cleanedOptions = { ...optionsDefaults, ...fsOptions };
   const isAppend = cleanedOptions.append === true;
   const prefix = cleanedOptions.prefix || '';
   const suffix = cleanedOptions.suffix || '';
+  const formatter = cleanedOptions.formatter || null;
+  const spacing = cleanedOptions.spacing || 2;
+  const jsonContents = JSON.stringify(contents, formatter, spacing);
 
   // const resolvedPath = path.resolve(filePath);
   try {
@@ -465,23 +476,103 @@ module.exports.checkFile = function checkFile(...files) {
   return notFoundFiles;
 };
 
-/*
- * Execute an async function if any of the files do not exist
- * @param {String[]} filePaths - list of paths of files to check that they exist
- * @param {*} fnIfFailed - async function tha will run - but only if any of the files are not found.
+/**
+ * Checks if a single file exists
+ * @param {String} filePath - path to check if the file exists.
+ * @returns {Boolean} - if the file exists (true) or not (false)
+ * @see {@link module:file.checkFile|file.checkFile} - if checking multiple files
  */
+module.exports.fileExists = function fileExists(filePath) {
+  const resolvedPath = path.resolve(filePath);
+  return fs.existsSync(resolvedPath);
+};
+
 /*
-module.exports.ifNotExists = async function ifNotExists(filePaths, fnIfFailed) {
-  const filesNotFound = FileUtil.checkFile(filePaths);
+//-- not needed - dates already serialize to iso Strings
+module.exports.cacheSerializer = (key, value) => {
+  if (key && (key === 'date' || key.endsWith('_date')) && (value instanceof Date)) {
+    return value.toISOString();
+  }
+  return value;
+};
+*/
 
-  let results;
+module.exports.cacheDeserializer = (key, value) => {
+  if (key && (key === 'date' || key.endsWith('_date'))) {
+    return new Date(value);
+  }
+  return value;
+};
 
-  if (filesNotFound) {
-    results = await fnIfFailed(filesNotFound);
-  } else {
-    results = null;
+/**
+ * For very long or time-intensive executions, sometimes it is better to cache the results
+ * than to execute them every single time.
+ * 
+ * Note that this works synchronously, and can be easier to use than if promises are involved.
+ * 
+ * As opposed to {@link module:ijs.useCache|ijs.useCache} - which works with promises.
+ * 
+ * ```
+ * shouldWrite = true; /// we will write to the cache with the results from the execution
+ * expensiveResults = utils.file.useCache(shouldWrite, './cache', 'expensive.json', () => {
+ *    const data = d3.csvParse(utils.file.readFile('./someFile.csv'))
+ *      .map(obj => ({ ...obj, date: Date.parse(obj.epoch) }));
+ *    
+ *    const earliestDate = utils.date.startOfDay( utils.agg.min(data, 'date') );
+ *    const lastDate = utils.date.endOfDay( utils.agg.max(data, 'date') );
+ * 
+ *    // binning or lots of other things.
+ * 
+ *    return finalResults;
+ * });
+ * 
+ * expensiveresults.length = 1023424;
+ * ```
+ * 
+ * but sometimes I would rather just skip to the end
+ * 
+ * ```
+ * shouldWrite = false; /// we will read from the cache instead,
+ * // everything else remains the same
+ * 
+ * expensiveResults = utils.file.useCache(shouldWrite, './cache', 'expensive.json', () => {
+ *    const data = d3.csvParse(utils.file.readFile('./someFile.csv'))
+ *      .map(obj => ({ ...obj, date: Date.parse(obj.epoch) }));
+ * 
+ *    //-- function can remain untouched,
+ *    //-- BUT nothing in here will be executed
+ *    //-- since we are reading from the cache
+ * });
+ * 
+ * //-- completely transparent to the runner
+ * expensiveresults.length = 1023424;
+ * ```
+ * 
+ * @param {Boolean} shouldWrite - whether we should write to the cache (true) or read from the cache (false)
+ * @param {String} cachePath - Path to the cache folder, ex: './cache'
+ * @param {String} cacheFile - Filename of the cache file to use for this execution, ex: 'ExecutionsPerMin.js'
+ * @param {Function} expensiveFn - function that returns the results to be stored in the cache
+ * @param {Object} fsOptions - options to use when writing or reading files
+ * @returns {any} - either the deserialized json from the cache or the results from the expensive function
+ * @see {@link module:file.readJSON|file.readJSON} - reads a local JSON file
+ * @see {@link module:file.writeJSON|file.writeJSON} - writes to a JSON file
+ * @see {@link module:ijs.useCache|ijs.useCache} - similar idea - but supports promises
+ */
+module.exports.useCache = function useCache(shouldWrite, cachePath, cacheFile, expensiveFn, fsOptions = null) {
+  const ensureEndsWithSlash = (str) => str.endsWith('/') ? str : `${str}/`;
+  const cacheFilePath = `${ensureEndsWithSlash(cachePath)}${cacheFile}`;
+  
+  if (!shouldWrite) {
+    const cleanOptions = { ...fsOptions, formatter: FileUtil.cacheDeserializer };
+    const results = FileUtil.readJSON(cacheFilePath, cleanOptions);
+    return results;
   }
 
+  const results = expensiveFn();
+
+  const cleanOptions = { ...fsOptions, formatter: null }; // FileUtil.cacheSerializer not needed
+
+  FileUtil.writeJSON(cacheFilePath, results, cleanOptions);
+
   return results;
 };
-*/

package/src/hashMap.js

@@ -83,12 +83,11 @@ module.exports.add = function add(map, key, value) {
  * @param {any} functor.value - the first argument is the current value
  * @param {any} functor.key - the second argument is the key passed
  * @param {any} functor.map - the third argument is the map being acted upon
- * @param {any} [setKey = null] - optional separate key to use to set the updated value
  * @returns {Map}
  */
-module.exports.getSet = function getSet(map, key, functor, setKey = null) {
-  const cleanSetKey = setKey || key;
-  map.set(cleanSetKey, functor(map.get(key), key, map));
+module.exports.getSet = function getSet(map, key, functor) {
+  const currentValue = map.has(key) ? map.get(key) : undefined;
+  map.set(key, functor(currentValue, key, map));
   return map;
 };
 module.exports.update = module.exports.getSet;

package/src/ijs.js

@@ -2,6 +2,8 @@
 
 const uuid = require('uuid').v4;
 
+const FileUtil = require('./file');
+
 require('./_types/global');
 
 /**
@@ -27,6 +29,8 @@ require('./_types/global');
  *   * {@link module:ijs.noOutputNeeded|ijs.noOutputNeeded} - clears the output to declutter results (like importing libraries, or functions)
  *   * {@link module:ijs.initializePageBreaks|ijs.initializePageBreaks} - call at least once to allow pageBreaks when rendering PDFs
  *   * {@link module:ijs.printPageBreak|ijs.printPageBreak} - call to print a page break when rendering PDFs
+ * * using a cache for long running executions
+ *   * {@link module:ijs.useCache|ijs.useCache()} - perform an expensive calculation and write to a cache, or read from the cache transparently
  * 
  * For example:
  * 
@@ -662,3 +666,102 @@ module.exports.printPageBreak = function printPageBreak() {
 
   context.$$.html('<div class="pagebreak"></div>');
 };
+
+/**
+ * For very long or time-intensive executions, sometimes it is better to cache the results
+ * than to execute them every single time.
+ * 
+ * Note that this supports promises, and can be a bit harder to understand.
+ * 
+ * As opposed to {@link module:file.useCache|file.useCache} - which works synchronously
+ * 
+ * ```
+ * shouldWrite = true; /// we will write to the cache with the results from the execution
+ * utils.file.useCache(shouldWrite, './cache', 'expensive.json', () => {
+ *   //-- all the items to cache 
+ *   return Promise.resolve()
+ *      .then(() => ajax.retrieve(...))
+ *      .then((results) => {
+ *          const data = results
+ *            .map(obj => ({ ...obj, date: Date.parse(obj.epoch) }));
+ *          .. other things to do
+ *          return data;
+ *       });
+ * })
+ *   //-- using the information AFTER the expensive function or retrieval from cache
+ *   //-- this can ALSO be run in a subsequence cell
+ *   .then((results) => {
+ *      expensiveresults = results;
+ *      conosole.log(`expensiveResults.length: ${results.length}`);
+ *    });
+ * ```
+ * 
+ * but sometimes I would rather just skip to the end
+ * 
+ * ```
+ * shouldWrite = false; /// we will read from the cache instead,
+ * // everything else remains the same
+ * 
+ * utils.file.useCache(shouldWrite, './cache', 'expensive.json', () => {
+ *   //-- all the items to cache 
+ *   return Promise.resolve()
+ *     ... blah blah - none of this will get executed
+ * })
+ *   //-- using the information AFTER the expensive function or retrieval from cache
+ *   //-- this can ALSO be run in a subsequence cell
+ *   .then((results) => {
+ *      expensiveresults = results;
+ *      conosole.log(`expensiveResults.length: ${results.length}`);
+ *    });
+ * 
+ * //-- completely transparent to the runner
+ * expensiveresults.length = 1023424;
+ * ```
+ * 
+ * @param {Boolean} shouldWrite - whether we should write to the cache (true) or read from the cache (false)
+ * @param {String} cachePath - Path to the cache folder, ex: './cache'
+ * @param {String} cacheFile - Filename of the cache file to use for this execution, ex: 'ExecutionsPerMin.js'
+ * @param {Function} expensiveFn - function that returns the results to be stored in the cache
+ * @param {Object} fsOptions - options to use when writing or reading files
+ * @returns {any} - either the deserialized json from the cache or the results from the expensive function
+ * @see {@link module:file.readJSON|file.readJSON} - reads a local JSON file
+ * @see {@link module:file.writeJSON|file.writeJSON} - writes to a JSON file
+ * @see {@link module:file.useCache|file.useCache} - can be much easier than using promises
+ */
+module.exports.useCache = async function useCache(shouldWrite, cachePath, cacheFile, expensiveFn, fsOptions = null) {
+  const ensureEndsWithSlash = (str) => str.endsWith('/') ? str : `${str}/`;
+  const cacheFilePath = `${ensureEndsWithSlash(cachePath)}${cacheFile}`;
+  const context = IJSUtils.detectContext();
+
+  if (!shouldWrite) {
+    const cleanOptions = { ...fsOptions, formatter: FileUtil.cacheDeserializer };
+    //-- we read the info and be done with it
+    //context.console.log(`before retrieving cache:${cacheFilePath}`);
+    const results = FileUtil.readJSON(cacheFilePath, cleanOptions);
+    //context.console.log(`after retrieving cache`);
+    return Promise.resolve(results);
+  }
+
+  if (!context) {
+    throw (Error('IJSUtils.async must be run within iJavaScript. Otherwise, use normal async methods'));
+  }
+
+  context.$$.async();
+
+  try {
+    context.console.log('before starting expensive fn');
+    const results = await expensiveFn(context.$$, context.console);
+    context.console.log('AFTER starting expensive fn');
+
+    FileUtil.writeJSON(cacheFilePath, results);
+    // context.$$.sendResult('success');
+    return results;
+  } catch (err) {
+    context.console.error('error occurred');
+    context.console.error(err);
+    context.$$.sendResult(err);
+
+    // return Promise.reject(err);
+    throw err;
+  }
+};

package/src/object.js

@@ -26,6 +26,7 @@ const FormatUtils = require('./format');
  *   * {@link module:object.extractObjectProperties|extractObjectProperties(list, propertyNameOrFnMap)} - extracts multiple propertie or fn across all objects in list.
  * * Apply deep values safely
  *   * {@link module:object.assign|objAssign(object, property, value)} - Applies properties to an object in functional programming style.
+ *   * {@link module:object.getSet|getSet(object, property, functor)} - calls a function with the current value on an object, allowing for decrementing/incrementing/etc.
  *   * {@link module:object.augment|augment(object, augmentFn)} - Applies properties to an object similar to Map
  *   * {@link module:object.assignEntities|objAssignEntities(object, [property, value])} - Applies properties to an object using Array values - [key,value]
  *   * {@link module:object.setPropertyDefaults|setPropertyDefaults()} - sets values for objects that don't currently have the property
@@ -169,6 +170,53 @@ module.exports.assignEntities = function objAssignEntities(obj, entities) {
 };
 module.exports.objAssignEntities = module.exports.assignEntities;
 
+/**
+ * Use this for times where you want to update a value
+ * 
+ * 
+ * ```
+ * key = 'somethingToIncrement';
+ * defaultValue = null;
+ * 
+ * const initialObject = {};
+ * initialObject[key] = defaultValue;
+ * 
+ * // { somethingToIncrement: null }
+ * 
+ * const functor = (value) => { //, key, map) => {
+ *   if (!value) return 1;
+ *   return value + 1;
+ * };
+ * 
+ * utils.object.getSet(initialObject, key, functor);
+ * 
+ * // equivalent to
+ * // intitialObject[key] = intitialObject[key] ? initialObject[key] + 1 : 1`
+ * // but in a way that is repeatable across many values
+ * 
+ * utils.object.getSet(initialObject, key, functor);
+ * utils.object.getSet(initialObject, key, functor);
+ * utils.object.getSet(initialObject, key, functor);
+ * utils.object.getSet(initialObject, key, functor);
+ * 
+ * initialObject.get(key); // 5
+ * ```
+ * 
+ * @param {Map} map - map to get and set values from
+ * @param {any} key - they key to GET and SET the value (unless setKey is provided)
+ * @param {Function} functor - the function called with the arguments below - returning the value to set
+ * @param {any} functor.value - the first argument is the current value
+ * @param {any} functor.key - the second argument is the key passed
+ * @param {any} functor.map - the third argument is the map being acted upon
+ * @returns {Map}
+ */
+module.exports.getSet = function getSet(obj, field, functor) {
+  const currentValue = Object.hasOwn(obj, field) ? obj[field] : undefined;
+  obj[field] = functor(currentValue, field, obj);
+  return obj;
+};
+module.exports.update = module.exports.getSet;
+
 /**
  * Runs a map over a collection, and adds properties the the objects.
  * 
@@ -413,9 +461,32 @@ module.exports.cleanPropertyName = function cleanPropertyName(property) {
   return cleanProperty;
 };
 
-const renameObjectProperties = function renameObjectProperties(object, originalKeys, targetKeys) {
+/**
+ * Renames properties on an object with a list of original keys and new keys.
+ * 
+ * For example:
+ * 
+ * ```
+ * myData = [{ _time: '...', 'series001': 1, 'series002': 2 }];
+ * 
+ * originalKeys = utils.object.keys(myData);
+ * // ['series001', 'series002'];
+ * 
+ * myMap = new Map([['series001': 'Alpha'], ['series002', 'Bravo']]);
+ * newKeys = utils.format.replaceStrings(originalKeys, myMap);
+ * // ['Alpha', 'Bravo'];
+ * 
+ * utils.object.renamePropertiesFromList(myData, originalKeys, newKeys);
+ * // [{ _time: '...', 'Alpha': 1, 'Bravo': 2 }];
+ * 
+ * @param {Object[]} objects - objects to reassign - likely from a CSV
+ * @param {String[]} originalKeys - list of keys to change FROM
+ * @param {String[]} updatedKeys - list of keys to change TO
+ * @returns {Object[]}
+ */
+module.exports.renamePropertiesFromList = function renamePropertiesFromList(object, originalKeys, targetKeys) {
   const result = { ...object };
-  originalKeys.forEach((originalKey, index) => {
+  Array.from(originalKeys).forEach((originalKey, index) => {
     const targetKey = targetKeys[index];
     if (targetKey !== originalKey) {
       result[targetKey] = result[originalKey];
@@ -440,10 +511,10 @@ module.exports.renameProperties = function renameProperties(objects, propertyTra
 
   if (Array.isArray(objects)) {
     return objects.map(
-      (object) => renameObjectProperties(object, originalKeys, targetKeys)
+      (object) => ObjectUtils.renamePropertiesFromList(object, originalKeys, targetKeys)
     );
   }
-  return renameObjectProperties(objects, originalKeys, targetKeys);
+  return ObjectUtils.renamePropertiesFromList(objects, originalKeys, targetKeys);
 };
 
 const collapseSpecificObject = function collapseSpecificObject(sourceObj, targetObj, depth) {