jupyter-ijavascript-utils 1.37.0 → 1.40.0

package/DOCS.md

@@ -75,6 +75,10 @@ Give it a try here:
 
 ## What's New
 
+* 1.40 - {@link module:array.extract|array.extract} and {@link module:array.applyArrayValues|array.applyArrayValues} to allow for extracting values from arrays, transforming them on a separate process and applying them deeply and safely
+* 1.39 - {@link module:format.extractWords|format.exportWords} - to identify distinct words in strings using unicode character properties
+* 1.38 - {@link module:object.extractObjectProperty|object.extractObjectProperty} / {@link module:object.applyPropertyValue|object.applyPropertyValue} to allow for extracting values from arrays, transforming them on a separate process and applying them back
+* 1.37 - {@link module:format.replaceString|format.replaceString} as convenience for replacing only a single string.
 * 1.36 - {@link module:format.replaceStrings|format.replaceStrings} to allow for replacement dictionaries and tuplets
 * 1.35 - {@link module:object.extractObjectProperties|extractObjectProperties} / {@link module:object.extractObjectProperty|extractObjectProperty} - to do horizontal transposes on objects
 * 1.34 - {@link module:format.mapArrayDomain|format.mapArrayDomain} and add notes in the header of {@link module:random|random} on using non-uniform distributions.

package/Dockerfile

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

package/README.md

@@ -55,6 +55,10 @@ This is not intended to be the only way to accomplish many of these tasks, and a
 
 # What's New
 
+* 1.40 - array.extract and array.applyArrayValue to allow for extracting values from arrays, transforming them on a separate process and applying them back
+* 1.39 - format.exportWords - to identify distinct words in strings using unicode character properties
+* 1.38 - object.extract / object.apply
+* 1.37 - {@link module:format.replaceString|format.replaceString} as convenience for replacing only a single string.
 * 1.36 - replaceStrings to allow for replacement dictionaries and tuplets
 * 1.35 - object.extractObjectProperties / object.extractObjectProperty - to do horizontal transposes on objects
 * 1.34 - format.mapArrayDomain and add notes in to random on using non-uniform distributions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jupyter-ijavascript-utils",
-  "version": "1.37.0",
+  "version": "1.40.0",
   "description": "Utilities for working with iJavaScript - a Jupyter Kernel",
   "homepage": "https://jupyter-ijavascript-utils.onrender.com/",
   "license": "MIT",
@@ -17,6 +17,7 @@
     "test:debug": "TZ=UTC node --inspect-brk node_modules/jest/bin/jest.js --runInBand",
     "test:coverage": "TZ=UTC jest src --collectCoverage",
     "test:watch:coverage": "TZ=UTC jest src --watch --collectCoverage",
+    "doc:taffy": "npm install taffydb && npm run doc",
     "docs": "npm run doc",
     "doc": "npm run prep:docdash && node_modules/.bin/jsdoc -c ./jsdoc.json -u ./tutorials ./DOCS.md",
     "prep:docdash": "cp docResources/docdash/layout.tmpl node_modules/docdash/tmpl/layout.tmpl && rm -rf docResources/notebooks/node_modules",

package/src/array.js

@@ -27,6 +27,10 @@ require('./_types/global');
  *   * {@link module:array.pickRows|array.pickRows} - picks a row from a 2d array
  *   * {@link module:array.pickColumns|array.pickColumns} - picks a column from a 2d array
  *   * {@link module:array.pick|array.pick} - picks either/or rows and columns
+ *   * {@link module:array.extract|array.extract} - synonym to array.pick to pick either a row or column from an array
+ * * 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
  * * Understanding Values
  *   * {@link module:array.isMultiDimensional|array.isMultiDimensional} - determines if an array is multi-dimensional
  * 
@@ -150,6 +154,7 @@ module.exports.peekLast = function peekLast(targetArray, defaultVal = null) {
  * @param {Array} array2d - 2d array to pick from [row][column]
  * @param {...Number} rowIndices - Indexes of the row to return, [0...length-1]
  * @returns - Array with only those rows
+ * @see {@link module:array.pick|array.pick} - pick either rows or columns
  * @example
  * data = [
  *  ['john', 23, 'purple'],
@@ -179,6 +184,7 @@ module.exports.pickRows = function pickRows(array2d, ...rowIndices) {
  * @param {Array} array2d - 2d array to pick from [row][column]
  * @param  {...any} columns - Indexes of the columns to pick the values from: [0...row.length-1]
  * @returns - Array with all rows, and only those columns
+ * @see {@link module:array.pick|array.pick} - pick either rows or columns
  * @example
  * data = [
  *  ['john', 23, 'purple'],
@@ -210,8 +216,9 @@ module.exports.pickColumns = function pickColumns(array2d, ...columns) {
  * @param {Number[]} [options.rows = null] - indices of the rows to pick
  * @param {Number[]} [options.columns = null] - indices of the columns to pick.
  * @returns {Array} - 2d array of only the rows and columns chosen.
- * @see {@link module:Array.pickRows} - picking rows
- * @see {@link module:Array.pickColumns} - picking columns
+ * @see {@link module:array.pickRows|array.pickRows} - picking rows
+ * @see {@link module:array.pickColumns|array.pickColumns} - picking columns
+ * @see {@link module:array.applyArrayValues|array.applyArrayValues} - applies a value / multiple values deeply into an array safely
  * @returns - 2dArray of the columns and rows requested
  * @example
  * data = [
@@ -250,6 +257,206 @@ module.exports.pick = function pick(array2d, options) {
   return results;
 };
 
+/**
+ * Convenience function for picking specific rows and columns from a 2d array.
+ * 
+ * Alias of {@link module:array.pick|array.pick}
+ * 
+ * Please also see [Danfo.js](https://danfo.jsdata.org/) for working with DataFrames.
+ * 
+ * @param {Array} array2d - 2d array to pick from [row][column]
+ * @param {Object} options - options on which to pick
+ * @param {Number[]} [options.rows = null] - indices of the rows to pick
+ * @param {Number[]} [options.columns = null] - indices of the columns to pick.
+ * @returns {Array} - 2d array of only the rows and columns chosen.
+ * @see {@link module:array.pickRows} - picking rows
+ * @see {@link module:array.pickColumns} - picking columns
+ * @returns - 2dArray of the columns and rows requested
+ * @example
+ * data = [
+ *  ['john', 23, 'purple'],
+ *  ['jane', 32, 'red'],
+ *  ['ringo', 27, 'green']
+ * ];
+ * 
+ * utils.array.pick(data, {rows: [0, 1]});
+ * //-- [['john', 23, 'purple'], ['jane', 32, 'red']];
+ * 
+ * utils.array.pick(data, {columns: [0, 2]});
+ * //-- [['john', 'purple'], ['jane', 'red'], ['ringo', 'green']];
+ * 
+ * utils.array.pick(data, {rows:[0, 1], columns:[0, 2]});
+ * //-- [['john', 'purple'], ['jane', 'red']];
+ */
+module.exports.extract = module.exports.pick;
+
+/**
+ * Applies deeply onto an array safely - in-place using dot-notation paths
+ * even if the child paths don't exist.
+ * 
+ * While tthis can be as simple as safely applying a value even if targetObj may be null
+ * 
+ * ```
+ * targetObj = [1, 2, null, 4, 5];
+ * 
+ * utils.object.applyPropertyValue(targetObj, '[2]', 3);
+ * // [1, 2, 3, 4, 5]
+ * // equivalent to targetObj[2] = 3;
+ * ```
+ * 
+ * This is much more safely working with deeply nested objects
+ * 
+ * ```
+ * targetObj = [{
+ *  name: 'john smith',
+ *  class: {
+ *    name: 'ECON_101',
+ *    professor: {
+ *      last_name: 'Winklemeyer'
+ *    }
+ *   }
+ * }];
+ * 
+ * utils.object.applyPropertyValue(targetObj, '[0].class.professor.first_name', 'René');
+ * // [{
+ * //  name: 'john smith',
+ * //  class: {
+ * //    name: 'ECON_101',
+ * //    professor: {
+ * //      last_name: 'Winklemeyer',
+ * //      first_name: 'René' // <- Added
+ * //    }
+ * //   }
+ * // }];
+ * ```
+ * 
+ * or creating intermediary objects along the path - if they did not exist first.
+ * 
+ * ```
+ * targetObj = [{
+ *  name: 'john smith'
+ * }];
+ * utils.object.applyPropertyValue(targetObj, '[0].class.professor.first_name', 'René');
+ * [{
+ *  name: 'john smith',
+ *  class: {
+ *    professor: {
+ *      first_name: 'René'
+ *    }
+ *   }
+ * }];
+ * ```
+ * 
+ * @param {Array} collection - array to apply the value to
+ * @param {string} path - dot notation path to set the value, ex: 'geo', or 'states[0].prop'
+ * @param {any} value - value to set
+ * @returns {Array} - the base array
+ * @see {@link module:array.pick|array.pick} - to pick a row or column into an array
+ * @see {@link module:array.applyArrayValues|array.applyArrayValues} - applies an array safely and deeply onto another array of values
+ */
+module.exports.applyArrayValue = function applyArrayValue(collection, path, value) {
+  // const signature = 'applyArrayValue(collection, path, value)';
+
+  if (!collection) return collection;
+  if (!path) return collection;
+
+  const cleanPath = String(path)
+    .replace(/\[/g, '.')
+    .replace(/\]/g, '.')
+    .replace(/[.]+/g, '.')
+    .replace(/^[.]+/, '')
+    .replace(/[.]$/, '');
+
+  const splitPath = cleanPath.split('.');
+  const terminalIndex = splitPath.length - 1;
+
+  return splitPath
+    .reduce((currentVal, prop, currentIndex) => {
+      //-- can no longer occur
+      // if (!prop) throw Error(`${signature}:Unable to set value with path:${path}`);
+
+      const isLeaf = currentIndex === terminalIndex;
+      if (isLeaf) {
+        // eslint-disable-next-line no-param-reassign
+        currentVal[prop] = value;
+        // if (value === undefined) {
+        //   delete currentVal[prop];
+        // } else {
+        //   currentVal[prop] = value;
+        // }
+        return collection;
+      }
+      //-- not a leaf
+      if (!currentVal[prop]) {
+        // eslint-disable-next-line no-param-reassign
+        currentVal[prop] = {};
+      }
+      return currentVal[prop];
+    }, collection);
+};
+
+/**
+ * Converse from the extractPropertyValue, this takes a value / set of values
+ * and applies the values for each index in the collection.
+ * 
+ * for example:
+ * 
+ * ```
+ * weather = [{ id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87 },
+ *   { id: 3, city: 'New York', month: 'Apr', precip: 3.94 },
+ *   { id: 6, city: 'Chicago',  month: 'Apr', precip: 3.62 }];
+ * 
+ * cities = utils.object.extractObjectProperty('city');
+ * // ['Seattle', 'New York', 'Chicago'];
+ * 
+ * //-- async process to geocode
+ * geocodedCities = geocodeCity(cities);
+ * // [{ city: 'Seattle', state: 'WA', country: 'USA' },
+ * // { city: 'New York', state: 'NY', country: 'USA' },
+ * // { city: 'Chicago', state: 'IL', country: 'USA' }]
+ * 
+ * utils.applyArrayValues(weather, 'geo', geocodedCities);
+ * // [{ id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87, geo: { city: 'Seattle', state: 'WA', country: 'USA' } },
+ * //  { id: 3, city: 'New York', month: 'Apr', precip: 3.94, geo: { city: 'New York', state: 'NY', country: 'USA' } },
+ * //  { id: 6, city: 'Chicago',  month: 'Apr', precip: 3.62, geo: { city: 'Chicago', state: 'IL', country: 'USA' } }];
+ * 
+ * Note that traditional [Array.map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map)
+ * works best for if you are working with objects completely in memory.
+ * 
+ * But this helps quite a bit if the action of mapping / transforming values
+ * needs to be separate from the extraction / application of values back.
+ * 
+ * @param {Array} collection - array to apply the value to on each index
+ * @param {string} path - dot notation path to set the value within each index, ex: 'geo', or 'states[0].prop'
+ * @param {any} value - the value that should be set at that path.
+ * @returns {Object}
+ * @see {@link module:array.applyArrayValue|array.applyArrayValue} - to apply a single value to a single object
+ * @see {@link module:array.pick|array.pick} - to pick a row or column into an array
+ */
+module.exports.applyArrayValues = function applyArrayValues(collection, path, valueList) {
+  // const signature = 'applyValue(objectList, path, valueList)';
+  if (!collection || !path) {
+    //-- do nothing
+    return collection;
+  }
+
+  const cleanCollection = Array.isArray(collection) ? collection : [collection];
+  const cleanValueList = Array.isArray(valueList) ? valueList : Array(cleanCollection.length).fill(valueList);
+
+  // if (cleanCollection.length !== cleanValueList) throw Error(
+  //   `${signature}: objectList.length[${cleanCollection.length}] does not match valueList.length[${cleanValueList.length}]`
+  // );
+  const minLength = Math.min(cleanCollection.length, cleanValueList.length);
+
+  for (let i = 0; i < minLength; i += 1) {
+    const obj = cleanCollection[i];
+    const val = cleanValueList[i];
+    ArrayUtils.applyArrayValue(obj, path, val);
+  }
+
+  return collection;
+};
+
 /**
  * Creates an array of a specific size and default value
  * 

package/src/format.js

@@ -20,6 +20,9 @@
  *   * {@link module:format.consoleLines|format.consoleLines(...)} - same as limit lines, only console.logs the string out.
  *   * {@link module:format.wordWrap|format.wordWrap(str, options)} - breaks apart string by line length
  *   * {@link module:format.lineCount|format.lineCount(str, options)} - counts the number of lines in a string
+ * * Replacing values in Strings
+ *   * {@link module:format.replaceString|format.replaceString(string, stringTupletsOrMap)} - applies replace from a collection of [matcher, replacement] tuplets or map based on key-> values
+ *   * {@link module:format.replaceStrings|format.replaceStrings(stringsArray, stringTupletsOrMap)} - applies replaceString on an array of values
  * * Formatting Time
  *   * {@link module:format.millisecondDuration|format.millisecondDuration}
  * * Mapping Values
@@ -38,6 +41,8 @@
  *   * {@link module:format.parseNumber|format.parseNumber(val, locale)} - converts a value to a number
  * * Identifying values
  *   * {@link module:format.isEmptyValue|format.isEmptyValue} - determine if a value is not 'empty'
+ * * Extracting values
+ *   * {@link module:format.extractWords|format.extractWords} - to extract the words from a string
  * 
  * @module format
  * @exports format
@@ -1214,6 +1219,7 @@ module.exports.lineCount = function lineCount(str, newlineCharacter = '\n') {
  * //   'and jill came tumbling after' ]
  *
  * //-- or use tuplets of [find, replace] with regular expressions
+ * //-- and strings not in tuplets are simply removed.
  * replaceValues = [['jack', 'john'], [/\s+jill/i, ' ringo'], ' down'];
  * utils.format.replaceStrings(targetStrings, replaceValues);
  * expected = [
@@ -1267,3 +1273,71 @@ module.exports.replaceStrings = function replaceStrings(targetStr, stringTuplets
       ? result
       : result.replace(replaceSearch, replaceWith), stringToClean));
 };
+
+/**
+ * Conveience function for calling {@link module:format.replaceStrings|format.replaceStrings} -
+ * giving and receiving a single value (instead of an array of values).
+ * @param {String} targetStr - A Single string to replace values on.
+ * @param {Array|Map<string|RegExp,string>} stringTupletsOrMap - [[search, replace]] or Map<String|RegExp,String>
+ * @returns {string} - the targetStr with the values replaced
+ * @see {@link module:format.replaceStrings}
+ */
+module.exports.replaceString = function replaceString(targetStr, stringTupletsOrMap) {
+  if (Array.isArray(targetStr)) {
+    throw Error('replaceString(targetStr, stringTupletsOrMap): targetStr was sent an array - please use replaceStrings instead');
+  }
+  return FormatUtils.replaceStrings([targetStr], stringTupletsOrMap)[0];
+};
+
+/**
+ * Identify an array of words each from a string.
+ * 
+ * Note that this uses the new [Unicode Properties](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Unicode_character_class_escape)
+ * using `\p{L}` to identify characters based on unicode properties.
+ * 
+ * For example:
+ * 
+ * ```
+ * strs = 'I am Modern "major-general".';
+ * FormatUtils.extractWords(strs);
+ * // ['I', 'am', 'Modern', 'major', 'general'];
+ * ```
+ * 
+ * you can also include additional characters that will no longer be considered word boundaries.
+ * 
+ * ```
+ * strs = 'I am Modern "major-general".';
+ * FormatUtils.extractWords(strs);
+ * // ['I', 'am', 'Modern', 'major-general'];
+ * ```
+ * 
+ * arrays of strings are also supported
+ * 
+ * ```
+ * strs = ['letras mayúsculas de tamaño igual a las minúsculas',
+ *  'الاختراع، ومايكل هارت'];
+ * FormatUtils.extractWords(strs);
+ * // [ 'letras', 'mayúsculas', 'de', 'tamaño', 'igual', 'a', 'las', 'minúsculas', 'الاختراع', 'ومايكل', 'هارت'];
+ * ```
+ * 
+ * @param {String|String[]} strToExtractFrom - collection of strings to extract words from
+ * @param {String} additionalNonBreakingCharacters - each char in this string will not be treated as a word boundry
+ * @returns {string[]} - collection of words
+ */
+module.exports.extractWords = function extractWords(strToExtractFrom, additionalNonBreakingCharacters) {
+  if (!strToExtractFrom) return strToExtractFrom;
+  
+  const cleanNonBreaking = additionalNonBreakingCharacters
+    ? additionalNonBreakingCharacters
+    : '';
+  
+  const regex = cleanNonBreaking
+    ? new RegExp(`[${additionalNonBreakingCharacters}\\p{L}]+`, 'gu')
+    : /\p{L}+/ug;  // -- old attempt/[A-Za-zÀ-ÖØ-öø-ÿ]+/g;
+  
+  const cleanStrings = Array.isArray(strToExtractFrom)
+    ? strToExtractFrom
+    : [strToExtractFrom];
+  
+  return cleanStrings.reduce((result, str) => [...result, ...((str || '').match(regex) || [])], []);
+};

package/src/object.js

@@ -13,29 +13,33 @@ const FormatUtils = require('./format');
  *   * {@link module:object.generateSchema|generateSchema()} - generate a schema / describe properties of a list of objects
  *   * {@link module:object.findWithoutProperties|findWithoutProperties()} - find objects without ALL the properties specified
  *   * {@link module:object.findWithoutProperties|findWithProperties()} - find objects with any of the properties specified
- *   * {@link module:object.setPropertyDefaults|setPropertyDefaults()} - sets values for objects that don't currently have the property
  *   * {@link module:object.propertyValueSample|propertyValueSample(collection)} - finds non-empty values for all properties found in the collection
- * * Manipulating objects
- *   * {@link module:object.assign|objAssign(object, property, value)} - Applies properties to an object in functional programming style.
- *   * {@link module:object.assignEntities|objAssignEntities(object, [property, value])} - Applies properties to an object using Array values - [key,value]
- *   * {@link module:object.augment|augment(object, augmentFn)} - Applies properties to an object similar to Map
- *   * {@link module:object.augmentInherit|augmentInherit(object, augmentFn)} - Applies properties to a collection of objects, 'remembering' the last value - useful for 1d to *D lists.
- *   * {@link module:object.selectObjectProperties|selectObjectProperties()} - keep only specific properties
- *   * {@link module:object.filterObjectProperties|filterObjectProperties()} - remove specific properties
- *   * {@link module:object.mapProperties|mapProperties(collection, fn, ...properties)} - map multiple properties at once (like parseInt, or toString)
- *   * {@link module:object.formatProperties|formatProperties(collection, propertyTranslation)} - map specific properties (ex: toString, toNumber, etc)
- *   * {@link module:object.union|union(objectList1, objectList2)} - Unites the properties of two collections of objects.
  * * Fetch child properties from related objects
  *   * {@link module:object.fetchObjectProperty|fetchObjectProperty(object, string)} - use dot notation to bring a child property onto a parent
  *   * {@link module:object.fetchObjectProperties|fetchObjectProperties(object, string[])} - use dot notation to bring multiple child properties onto a parent
  *   * {@link module:object.join|join(array, index, map, fn)} - join a collection against a map by a given index
  *   * {@link module:object.joinProperties|join(array, index, map, ...fields)} - join a collection, and copy properties over from the mapped object.
+ * * Fetch values safely
  *   * {@link module:object.propertyFromList|propertyFromList(array, propertyName)} - fetches a specific property from all objects in a list
  *   * {@link module:object.extractObjectProperty|extractObjectProperty(list, propertyNameOrFn)} - extracts a property or fn across all objects in list.
  *   * {@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.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
+ *   * {@link module:object.applyPropertyValue|object.applyPropertyValue} - safely apply a value deeply and safely
+ *   * {@link module:object.applyPropertyValues|object.applyPropertyValues} - apply an array of values safely and deeply against a list of objects.
+ * * Manipulating objects
+ *   * {@link module:object.augmentInherit|augmentInherit(object, augmentFn)} - Applies properties to a collection of objects, 'remembering' the last value - useful for 1d to *D lists.
+ *   * {@link module:object.selectObjectProperties|selectObjectProperties()} - keep only specific properties
+ *   * {@link module:object.filterObjectProperties|filterObjectProperties()} - remove specific properties
+ *   * {@link module:object.mapProperties|mapProperties(collection, fn, ...properties)} - map multiple properties at once (like parseInt, or toString)
+ *   * {@link module:object.formatProperties|formatProperties(collection, propertyTranslation)} - map specific properties (ex: toString, toNumber, etc)
+ *   * {@link module:object.union|union(objectList1, objectList2)} - Unites the properties of two collections of objects.
  * * Rename properties
  *   * {@link module:object.cleanProperties|cleanProperties()} - correct inaccessible property names in a list of objects - in place
- *  *   * {@link module:object.cleanProperties2|cleanProperties2()} - correct inaccessible property names in a list of objects - on a cloned list
+ *   * {@link module:object.cleanProperties2|cleanProperties2()} - correct inaccessible property names in a list of objects - on a cloned list
  *   * {@link module:object.cleanPropertyNames|cleanPropertyNames()} - create a translation of inaccessible names to accessible ones
  *   * {@link module:object.cleanPropertyName|cleanPropertyName()} - create a translation of a specific property name to be accessible.
  *   * {@link module:object.renameProperties|renameProperties()} - Use a translation from old property names to new ones
@@ -498,46 +502,6 @@ module.exports.filterObjectProperties = function filterObjectProperties(list, pr
   });
 };
 
-/**
- * Options for fetching object properties
- * @typedef {Object} FetchObjectOptions
- * @property {Boolean} safeAccess - whether to safely access, even if the path cannot be found
- * @property {Boolean} append - whether to only return the properties (default) or append
- */
-
-/**
- * Fetches multiple properties from an object or list of objects.
- * @param {Object | Object[]} list - collection of objects to reduce
- * @param {Map<String,any>} propertyNames - Object with the keys as the properties
- *    and the values using dot notation to access related records and properties
- *    (ex: {parentName: 'somePropertyObject.parent.parent.name', childName: 'child.Name'})
- * @param {FetchObjectOptions} options - {@link module:object~FetchObjectOptions|See FetchObjectOptions} 
- * @returns {Object[]} - objects with the properties resolved
- *    (ex: {parentname, childName, etc.})
- */
-module.exports.fetchObjectProperties = function fetchObjectProperties(list, propertyNames, options = {}) {
-  const {
-    //-- whether to safely access even if object path cannot be found
-    safeAccess = false,
-
-    //-- whether to fetch only those specific properties, or append to the object
-    append = false
-  } = options;
-
-  if (!list) return [];
-  const targetList = Array.isArray(list) ? list : [list];
-
-  const props = Object.getOwnPropertyNames(propertyNames);
-
-  return targetList.map((obj) => {
-    const result = append ? { ...obj } : {};
-    props.forEach((prop) => {
-      result[prop] = ObjectUtils.fetchObjectProperty(obj, propertyNames[prop], safeAccess);
-    });
-    return result;
-  });
-};
-
 /**
  * Similar to a transpose, this finds all the values of a particular property
  * within a list of objects.
@@ -558,7 +522,9 @@ module.exports.fetchObjectProperties = function fetchObjectProperties(list, prop
  * @param {Function | String} propertyOrFn - Name of the property or accessor function
  * @returns {Array} - single array the values stored in propertyOrFn across all objects in objectList.
  * @see {@link module:aggregate.unique|unique()} to see all the unique values stored
- * @see {@link module:object.extractObjectProperties|extractObjectProperties(list, propertyNameOrFnMap)} to see the values extracted into a single object / horizontal transpose.
+ * @see {@link module:object.extractObjectProperties|object.extractObjectProperties} - to extract into array vectors 
+ * @see {@link module:object.fetchObjectProperty|object.fetchObjectProperty} - to extract a deep value and optionally throw if not found
+ * @see {@link module:object.applyPropertyValue|object.applyPropertyValue} - to apply a single value to a single object using dot notation safely
  */
 module.exports.extractObjectProperty = function extractObjectProperty(list, propertyOrFn) {
   let cleanList = !list ? [] : Array.isArray(list) ? list : [list];
@@ -600,6 +566,8 @@ module.exports.extractObjectProperty = function extractObjectProperty(list, prop
  * @param {Map<Function | String>} propertyOrFnMap - Name of the property or accessor function
  * @returns {Object} - Object with the keys in the map as properties - extracting the values across all in list.
  * @see {@link module:object.extractObjectProperty|extractObjectProperty(list, propertyNameOrFn)} to see all the values stored for a single property.
+ * @see {@link module:object.applyPropertyValues|object.applyPropertyValues} - to safely and deeply apply the list of values extracted to a list of objects.
+ * @see {@link module:object.fetchObjectProperties} - to fetch multiple properties at once into objects
  */
 module.exports.extractObjectProperties = function extractObjectProperties(list, propertyOrFnMap) {
   let propertyEntries = [];
@@ -625,36 +593,266 @@ module.exports.extractObjectProperties = function extractObjectProperties(list,
   const results = {};
   propertyEntries.forEach(([propertyName, propertyOrFn]) => {
     results[propertyName] = ObjectUtils.extractObjectProperty(list, propertyOrFn || propertyName);
-    // const fn = ObjectUtils.evaluateFunctionOrProperty(propertyOrFn);
-    // results[propertyName] = cleanList.map(fn);
   });
 
   return results;
 };
 
+/**
+ * Options for fetching object properties
+ * @typedef {Object} FetchObjectOptions
+ * @property {Boolean} safeAccess - whether to safely access, even if the path cannot be found
+ */
+
+/**
+ * Fetches multiple properties from an object or list of objects.
+ * 
+ * ```
+ * testObj = {
+ *  name: 'john',
+ *  courses: [{ name: 'econ-101' }]
+ * }
+ * utils.object.fetchObjectProperty(testObj,
+ *  { 'courseName': 'courses[0].?name', personName: 'name' });
+ * // { courseName: 'econ-101', personName: 'john' }
+ * ```
+ * 
+ * @param {Object | Object[]} list - collection of objects to reduce
+ * @param {Object<String,any>} propertyNames - Object with the keys as as properties to return,
+ *    and the values using dot notation to access related records and properties
+ *    (ex: {parentName: 'somePropertyObject.parent.parent.name', childName: 'child.Name'})
+ * @param {FetchObjectOptions} options - {@link module:object~FetchObjectOptions|See FetchObjectOptions} 
+ * @returns {Object[]} - objects with the properties resolved
+ *    (ex: {parentname, childName, etc.})
+ * @see {@link module:object.fetchObjectProperty|object.fetchObjectProperty} - to safely fetch  a single value
+ * @see {@link module:object.applyPropertyValues|object.applyPropertyValues} - to safely and deeply apply the list of values extracted to a list of objects.
+ * @see {@link module:object.extractObjectProperties|object.extractObjectProperties} - to extract into array vectors instead of objects
+ */
+module.exports.fetchObjectProperties = function fetchObjectProperties(list, propertyNames, options = {}) {
+  if (!list) return [];
+  const targetList = Array.isArray(list) ? list : [list];
+  
+  const {
+    //-- whether to fetch only those specific properties, or append to the object
+    append = false
+  } = options;
+
+  const props = Object.getOwnPropertyNames(propertyNames);
+
+  return targetList.map((obj) => {
+    const result = append ? { ...obj } : {};
+    props.forEach((prop) => {
+      result[prop] = ObjectUtils.fetchObjectProperty(obj, propertyNames[prop], options);
+    });
+    return result;
+  });
+};
+
 /**
  * Accesses a property using a string
+ * 
+ * ```
+ * testObj = {
+ *  name: 'john',
+ *  courses: [{ name: 'econ-101' }]
+ * }
+ * utils.object.fetchObjectProperty(testObj, 'courses[0].?name');
+ * // 'econ-101'
+ * ```
+ * 
+ * note that the options allow for safe property access
+ * 
+ * ```
+ * testObj = {
+ *  name: 'john',
+ *  courses: [{ name: 'econ-101' }]
+ * }
+ * utils.object.fetchObjectProperty(testObj, 'courses[0].courseId');
+ * // throws an error
+ * 
+ * utils.object.fetchObjectProperty(testObj, 'courses[0].?courseId');
+ * // null - because of optional condition operator
+ * 
+ * utils.object.fetchObjectProperty(testObj, 'courses[0].courseId', { safeAccess: true });
+ * // null - because of the safe access option
+ * ```
+ * 
  * @param {Object} obj - object to access the properties on
  * @param {String} propertyAccess - dot notation for the property to access
  *    (ex: `parent.obj.Name`)
  * @param {FetchObjectOptions} options - {@link module:object~FetchObjectOptions|See FetchObjectOptions}
  * @returns {any} - the value accessed at the end ofthe property chain
+ * @see {@link module:object.fetchObjectProperties} - to fetch multiple properties at once into objects
+ * @see {@link module:object.extractObjectProperty|object.extractObjectProperty} - to safely extract a deep value without options
+ * @see {@link module:object.applyPropertyValue|object.applyPropertyValue} - to apply a single value to a single object using dot notation safely
  */
-module.exports.fetchObjectProperty = function fetchObjectProperty(obj, propertyAccess, safeAccess) {
+module.exports.fetchObjectProperty = function fetchObjectProperty(obj, propertyAccess, options = {}) {
   if (!obj || !propertyAccess) return null;
+  const {
+    //-- whether to safely access even if object path cannot be found
+    safeAccess = false
+  } = options;
 
-  //-- @TODO - should we be safe or support elvis operators?
-  return propertyAccess.split('.')
+  const cleanPropertyAccess = String(propertyAccess)
+    .replace(/\[/g, '.')
+    .replace(/\]/g, '.')
+    .replace(/[.]+/g, '.')
+    .replace(/^[.]+/, '')
+    .replace(/[.]$/, '');
+
+  return cleanPropertyAccess.split('.')
     .reduce((currentVal, prop) => {
+      let isElvis = false;
+      let cleanProp = prop;
+      if (prop && prop.length > 0 && prop[0] === '?') {
+        isElvis = true;
+        cleanProp = prop.slice(1);
+      }
       if (currentVal) {
-        return currentVal[prop];
-      } else if (safeAccess || prop[0] === '?') {
+        return currentVal[cleanProp];
+      } else if (safeAccess || isElvis) {
         return null;
       }
       throw Error(`Invalid property ${propertyAccess} [${prop}] does not exist - safeAccess:${safeAccess}`);
     }, obj);
 };
 
+/**
+ * Applies a target value onto a source object in-place safely - using dot-notation paths.
+ * 
+ * This can be as simple as safely applying a value even if targetObj may be null
+ * ```
+ * targetObj = { id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87 };
+ * utils.object.applyPropertyValue(targetObj, 'state', 'WA');
+ * // { id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87, state: 'WA };
+ * ```
+ * 
+ * working with deeply nested objects
+ * ```
+ * targetObj = { name: 'john smith', class: { name: 'ECON_101', professor: { last_name: 'Winklemeyer' }} };
+ * utils.object.applyPropertyValue(targetObj, 'class.professor.first_name', 'René');
+ * // { name: 'john smith', class: { name: 'ECON_101', professor: { last_name: 'Winklemeyer', first_name: 'René' }} };
+ * ```
+ * 
+ * or safely working with arrays of values
+ * ```
+ * targetObj = { name: 'john smith', classes: [{ name: 'ECON_101' }] };
+ * utils.object.applyPropertyValue(targetObj, 'classes[0].grade', 'A');
+ * // { name: 'john smith', classes: [{ name: 'ECON_101', grade: 'A' }] };
+ * ```
+ * 
+ * @param {Object} obj - object to apply the value to
+ * @param {string} path - dot notation path to set the value, ex: 'geo', or 'states[0].prop'
+ * @param {any} value - value to set
+ * @returns {Object} - the object the value was applied to
+ * @see {@link module:object.applyPropertyValues|object.applyPropertyValues} - to safely and deeply apply the list of values extracted to a list of objects.
+ * @see {@link module:object.extractObjectProperty|object.extractObjectProperty} - to safely extract a deep value
+ * @see {@link module:object.fetchObjectProperty|object.fetchObjectProperty} - to extract a deep value and optionally throw if not found
+ */
+module.exports.applyPropertyValue = function applyPropertyValue(obj, path, value) {
+  // const signature = 'applyPropertyValue(obj, path, value)';
+
+  if (!obj) return obj;
+  if (!path) return obj;
+
+  const cleanPath = String(path)
+    .replace(/\[/g, '.')
+    .replace(/\]/g, '.')
+    .replace(/[.]+/g, '.')
+    .replace(/^[.]+/, '')
+    .replace(/[.]$/, '');
+
+  const splitPath = cleanPath.split('.');
+  const terminalIndex = splitPath.length - 1;
+
+  return splitPath
+    .reduce((currentVal, prop, currentIndex) => {
+      //-- can no longer occur
+      // if (!prop) throw Error(`${signature}:Unable to set value with path:${path}`);
+
+      const isLeaf = currentIndex === terminalIndex;
+      if (isLeaf) {
+        // eslint-disable-next-line no-param-reassign
+        currentVal[prop] = value;
+        // if (value === undefined) {
+        //   delete currentVal[prop];
+        // } else {
+        //   currentVal[prop] = value;
+        // }
+        return obj;
+      }
+      //-- not a leaf
+      if (!currentVal[prop]) {
+        // eslint-disable-next-line no-param-reassign
+        currentVal[prop] = {};
+      }
+      return currentVal[prop];
+    }, obj);
+};
+
+/**
+ * Opposite of the extractObjectProperty, this takes a value / set of values
+ * and applies them along a given path on each of the target objects.
+ * 
+ * for example:
+ * 
+ * ```
+ * weather = [{ id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87 },
+ *   { id: 3, city: 'New York', month: 'Apr', precip: 3.94 },
+ *   { id: 6, city: 'Chicago',  month: 'Apr', precip: 3.62 }];
+ * 
+ * cities = utils.object.extractObjectProperty('city');
+ * // ['Seattle', 'New York', 'Chicago'];
+ * 
+ * //-- async process to geocode
+ * geocodedCities = geocodeCity(cities);
+ * // [{ city: 'Seattle', state: 'WA', country: 'USA' },
+ * // { city: 'New York', state: 'NY', country: 'USA' },
+ * // { city: 'Chicago', state: 'IL', country: 'USA' }]
+ * 
+ * utils.applyPropertyValues(weather, 'geo', geocodedCities);
+ *  [{ id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87, geo: { city: 'Seattle', state: 'WA', country: 'USA' } },
+ *   { id: 3, city: 'New York', month: 'Apr', precip: 3.94, geo: { city: 'New York', state: 'NY', country: 'USA' } },
+ *   { id: 6, city: 'Chicago',  month: 'Apr', precip: 3.62, geo: { city: 'Chicago', state: 'IL', country: 'USA' } }];
+ * 
+ * Note that traditional [Array.map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map)
+ * works best for if you are working with objects completely in memory.
+ * 
+ * But this helps quite a bit if the action of mapping / transforming values
+ * needs to be separate from the extraction / application of values back.
+ * 
+ * @param {Object} obj - object to apply the value to
+ * @param {string} path - dot notation path to set the value, ex: 'geo', or 'states[0].prop'
+ * @param {any} value - the value that should be set at that path.
+ * @returns {Object}
+ * @see {@link module:object.applyPropertyValue} - to apply a single value to a single object
+ * @see {@link module:object.fetchObjectProperties} - to fetch multiple properties at once into objects
+ * @see {@link module:object.extractObjectProperties|object.extractObjectProperties} - to extract properties into array vectors instead of objects
+ */
+module.exports.applyPropertyValues = function applyPropertyValues(objectList, path, valueList) {
+  // const signature = 'applyPropertyValues(objectList, path, valueList)';
+  if (!objectList || !path) {
+    //-- do nothing
+    return objectList;
+  }
+
+  const cleanObjectList = Array.isArray(objectList) ? objectList : [objectList];
+  const cleanValueList = Array.isArray(valueList) ? valueList : Array(cleanObjectList.length).fill(valueList);
+
+  // if (cleanObjectList.length !== cleanValueList) throw Error(
+  //   `${signature}: objectList.length[${cleanObjectList.length}] does not match valueList.length[${cleanValueList.length}]`
+  // );
+  const minLength = Math.min(cleanObjectList.length, cleanValueList.length);
+
+  for (let i = 0; i < minLength; i += 1) {
+    const obj = cleanObjectList[i];
+    const val = cleanValueList[i];
+    ObjectUtils.applyPropertyValue(obj, path, val);
+  }
+
+  return objectList;
+};
+
 /**
  * Translates specific properties to a new value on an object, or collection of objects.
  * 

package/src/plantuml.js

@@ -214,7 +214,7 @@ module.exports.render = function render(plantUMLText, plantUMLOptions) {
     const targetURL = this.generateURL(plantUMLText, plantUMLOptions);
     if (showURL || debug) console.log(`url:${targetURL}`);
 
-    const result = await fetch(targetURL);
+    const result = await global.fetch(targetURL);
 
     if (format === 'png') {
       const buf = await result.buffer();