jupyter-ijavascript-utils 1.6.8 → 1.8.0

package/DOCS.md

@@ -28,6 +28,8 @@ See the [#Installation section for requirements and installation](#install)
 
 ## What's New
 
+* 1.8 - add in What can I Do tutorial, and object.join methods
+* 1.7 - revamp of `animation` method for ijs.htmlScript
 * 1.6 - add SVG support for rendering SVGs and animations with {@link module:svg}.
 * 1.5 - Add LaTeX / KaTeX support with {@link module:latex} for rendering Math formulas and PlantUML support for Diagrams
 * 1.4 - Add in vega embed, vega mimetypes with {@link module:vega} and example choropleth tutorial
@@ -35,6 +37,22 @@ See the [#Installation section for requirements and installation](#install)
 
 -------
 
+# What is this?
+
+The [jupyter-ijavascript-utils](https://www.npmjs.com/package/jupyter-ijavascript-utils) library is simply a collection of utility methods for Node and JavaScript Developers interested in Data Science.
+
+* Load
+* Aggregate
+* Manipulate
+* Format / Visualize
+* Refine and Explore
+
+Currently, we assume you'll be using [nriesco's iJavaScript Jupyter Kernel](https://github.com/n-riesco/ijavascript) and the [Jupyter Lab - the latest interface for Jupyter](https://jupyter.org/) - and the installation is fairly simple in the [@link howToUse] guide. (Although suggestions welcome)
+
+This is not intended to be the only way to accomplish many of these tasks, and alternatives are mentioned in the documentation as available.
+
+![Screenshot of example notebook](img/mainExampleNotebook.png)
+
 # For Example
 
 ## Get Sample Data
@@ -162,13 +180,18 @@ new utils.TableGenerator(barley)
 (See the {@tutorial vegaLite1} tutorial or the {@link module:vega|Vega module} for more)
 
 ```
+//-- make a point chart
 utils.vega.svg((vl) => vl.markPoint()
+    //-- data as an array of items
     .data(barley)
     .title('Barley Yield by Site')
     .width(600)
     .encode(
+        //-- x position is Nominal - not a number
         vl.x().fieldN('site'),
+        //-- y position is Quantitative - a number
         vl.y().fieldQ('yield'),
+        //-- Color is based on the year field
         vl.color().fieldN('year')
     )
 )
@@ -176,7 +199,33 @@ utils.vega.svg((vl) => vl.markPoint()
 
 ![Screenshot of Vega Cell](img/BarleyYieldBySite.png)
 
-and more from {@link module:vega}
+Where making it into a bar chart, to understand the proportions of varieties grown is simply changing the mark type
+
+```
+// change from markPoint to markBar
+utils.vega.svg((vl) => vl.markBar()
+    //-- data as an array of items
+    .data(barley)
+    .title('Barley Yield by Site Variety')
+    .width(600)
+    .encode(
+        //-- x position is Nominal - not a number
+        vl.x().fieldN('site').title('Site'),
+        //-- y position is Quantitative - a number
+        vl.y().fieldQ('yield').title('Yield'),
+        //-- Color is based on the variety field
+        vl.color().fieldN('variety').title('Variety')
+    )
+)
+```
+
+![Screenshot of variety type](img/BarleyYieldBySiteVariety.png)
+
+With further options to zoom, pan, or setup interactive sliders:
+
+![Screenshot of vega lite with sliders](img/vegaLiteSliders.png)
+
+Or try your hand at the [Vega Lite Examples](https://vega.github.io/vega-lite/examples/) and more from {@link module:vega}
 
 ![Screenshot of Vega-Lite Examples](img/vegaLiteExamples.png)
 

package/README.md

@@ -18,11 +18,29 @@ See documentation at: [https://jupyter-ijavascript-utils.onrender.com/](https://
 
 # What's New
 
+* 1.8 - add in What can I Do tutorial, and object.join methods
+* 1.7 - revamp of `animation` method to htmlScript
 * 1.6 - add SVG support for rendering SVGs and animations
 * 1.5 - Add Latex support for rendering Math formulas and PlantUML support for Diagrams
 * 1.4 - Add in vega embed, vega mimetypes and example choropleth tutorial
 * 1.3 - Add Leaflet for Maps, allow Vega to use explicit specs (so [Examples can be copied and pasted](https://vega.github.io/vega-lite/examples/), and add in htmlScripts
 
+# What is this?
+
+The [jupyter-ijavascript-utils](https://www.npmjs.com/package/jupyter-ijavascript-utils) library is simply a collection of utility methods for Node and JavaScript Developers interested in Data Science.
+
+* Load
+* Aggregate
+* Manipulate
+* Format / Visualize
+* Refine and Explore
+
+Currently, we assume you'll be using [nriesco's iJavaScript Jupyter Kernel](https://github.com/n-riesco/ijavascript) and the [Jupyter Lab - the latest interface for Jupyter](https://jupyter.org/) - and the installation is fairly simple in the [How to Use guide](https://jupyter-ijavascript-utils.onrender.com/tutorial-howToUse.html). (Although suggestions welcome)
+
+This is not intended to be the only way to accomplish many of these tasks, and alternatives are mentioned in the documentation as available.
+
+![Screenshot of example notebook](https://jupyter-ijavascript-utils.onrender.com/img/mainExampleNotebook.png)
+
 # For Example
 
 ## Get Sample Data
@@ -147,16 +165,21 @@ new utils.TableGenerator(barley)
 
 ## Show a Graph
 
-([See the vega module for more](https://jupyter-ijavascript-utils.onrender.com/module-vega.html))
+(See the {@tutorial vegaLite1} tutorial or the {@link module:vega|Vega module} for more)
 
 ```
+//-- make a point chart
 utils.vega.svg((vl) => vl.markPoint()
+    //-- data as an array of items
     .data(barley)
     .title('Barley Yield by Site')
     .width(600)
     .encode(
+        //-- x position is Nominal - not a number
         vl.x().fieldN('site'),
+        //-- y position is Quantitative - a number
         vl.y().fieldQ('yield'),
+        //-- Color is based on the year field
         vl.color().fieldN('year')
     )
 )
@@ -164,6 +187,32 @@ utils.vega.svg((vl) => vl.markPoint()
 
 ![Screenshot of Vega Cell](https://jupyter-ijavascript-utils.onrender.com/img/BarleyYieldBySite.png)
 
+Where making it into a bar chart, to understand the proportions of varieties grown is simply changing the mark type
+
+```
+// change from markPoint to markBar
+utils.vega.svg((vl) => vl.markBar()
+    //-- data as an array of items
+    .data(barley)
+    .title('Barley Yield by Site Variety')
+    .width(600)
+    .encode(
+        //-- x position is Nominal - not a number
+        vl.x().fieldN('site').title('Site'),
+        //-- y position is Quantitative - a number
+        vl.y().fieldQ('yield').title('Yield'),
+        //-- Color is based on the variety field
+        vl.color().fieldN('variety').title('Variety')
+    )
+)
+```
+
+![Screenshot of variety type](https://jupyter-ijavascript-utils.onrender.com/img/BarleyYieldBySiteVariety.png)
+
+With further options to zoom, pan, or setup interactive sliders:
+
+![Screenshot of vega lite with sliders](https://jupyter-ijavascript-utils.onrender.com/img/vegaLiteSliders.png)
+
 Or try your hand at the [Vega Lite Examples](https://vega.github.io/vega-lite/examples/)
 
 ![Screenshot of Vega-Lite Examples](https://jupyter-ijavascript-utils.onrender.com/img/vegaLiteExamplesSm.png)

package/package.json

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

package/src/aggregate.js

@@ -1,5 +1,6 @@
 /* eslint-disable implicit-arrow-linebreak */
 
+const ObjectUtils = require('./object');
 const FormatUtils = require('./format');
 
 /**
@@ -272,24 +273,6 @@ module.exports.deferCollection = (aggregateFn, ...rest) => {
 
 module.exports.defer = module.exports.deferCollection;
 
-/**
- * Generates a function if a property or null or a function is sent
- * @param {Function | String} fnOrProp - 
- * @return {Function}
- * @private
- */
-module.exports.evaluateFunctionOrProperty = function evaluateFunctionOrProperty(fnOrProp) {
-  if (!fnOrProp) {
-    return (r) => r;
-  } else if (typeof fnOrProp === 'string') {
-    return (r) => r[fnOrProp];
-  } else if (typeof fnOrProp === 'function') {
-    return fnOrProp;
-  }
-
-  throw (Error('Send either a Function or Property Name or null for a simple array'));
-};
-
 /**
  * Identifies the min and max of values of a collection
  * @param {Array} collection - 
@@ -318,7 +301,7 @@ module.exports.extent = function extent(collection, accessor) {
  * // 0.87
  */
 module.exports.min = function min(collection, accessor) {
-  const cleanedFunc = AggregateUtils.evaluateFunctionOrProperty(accessor);
+  const cleanedFunc = ObjectUtils.evaluateFunctionOrProperty(accessor);
   return collection.reduce((current, val) => {
     const valEval = cleanedFunc(val);
     return valEval < current ? valEval : current;
@@ -338,7 +321,7 @@ module.exports.min = function min(collection, accessor) {
  * // 5.31
  */
 module.exports.max = function max(collection, accessor) {
-  const cleanedFunc = AggregateUtils.evaluateFunctionOrProperty(accessor);
+  const cleanedFunc = ObjectUtils.evaluateFunctionOrProperty(accessor);
   return collection.reduce((current, val) => {
     const valEval = cleanedFunc(val);
     return valEval > current ? valEval : current;
@@ -356,7 +339,7 @@ module.exports.max = function max(collection, accessor) {
  * // 26.69
  */
 module.exports.sum = function sum(collection, accessor) {
-  const cleanedFunc = AggregateUtils.evaluateFunctionOrProperty(accessor);
+  const cleanedFunc = ObjectUtils.evaluateFunctionOrProperty(accessor);
   return collection.reduce((current, val) => current + cleanedFunc(val), 0);
 };
 
@@ -385,7 +368,7 @@ module.exports.difference = function difference(collection, accessor) {
  * // 3.41
  */
 module.exports.avgMean = function avgMean(collection, accessor) {
-  const cleanedFunc = AggregateUtils.evaluateFunctionOrProperty(accessor);
+  const cleanedFunc = ObjectUtils.evaluateFunctionOrProperty(accessor);
   return collection.reduce((current, val) => current + cleanedFunc(val), 0)
     / collection.length;
 };
@@ -401,7 +384,7 @@ module.exports.avgMean = function avgMean(collection, accessor) {
  * //                      3.62
  */
 module.exports.avgMedian = function avgMedian(collection, accessor) {
-  const cleanedFunc = AggregateUtils.evaluateFunctionOrProperty(accessor);
+  const cleanedFunc = ObjectUtils.evaluateFunctionOrProperty(accessor);
   const results = collection.map(cleanedFunc).sort((a, b) => a - b);
   const middle = Math.floor(collection.length / 2);
   return collection.length % 2 === 0
@@ -422,7 +405,7 @@ module.exports.avgMedian = function avgMedian(collection, accessor) {
  * // 0.87
  */
 module.exports.first = function first(collection, accessor) {
-  const cleanedFunc = AggregateUtils.evaluateFunctionOrProperty(accessor);
+  const cleanedFunc = ObjectUtils.evaluateFunctionOrProperty(accessor);
   let result = null;
   for (let i = 0; i < collection.length; i += 1) {
     result = cleanedFunc(collection[i]);
@@ -464,7 +447,7 @@ module.exports.length = function length(collection) {
  * // [ 'apple', 'orange', 'banana' ]
  */
 module.exports.unique = function unique(collection, accessor, uniquifierFn) {
-  const cleanedFunc = AggregateUtils.evaluateFunctionOrProperty(accessor);
+  const cleanedFunc = ObjectUtils.evaluateFunctionOrProperty(accessor);
   if (uniquifierFn) {
     return Array.from(new Set(
       collection.map((v) => uniquifierFn(cleanedFunc(v)))
@@ -525,7 +508,7 @@ module.exports.distinct = function distinct(collection, accessor, uniquifierFn)
  * // 2
  */
 module.exports.countMap = function countMap(collection, accessor, uniquifierFn) {
-  const cleanedFunc = AggregateUtils.evaluateFunctionOrProperty(accessor);
+  const cleanedFunc = ObjectUtils.evaluateFunctionOrProperty(accessor);
   const resultMap = new Map();
   collection.forEach((val) => {
     let result = cleanedFunc(val);
@@ -636,7 +619,7 @@ module.exports.duplicates = function duplicates(collection, accessor, uniquifier
  * // Set('d')
  */
 module.exports.notIn = function notIn(collection, accessor, targetIterator) {
-  const cleanedFunc = AggregateUtils.evaluateFunctionOrProperty(accessor);
+  const cleanedFunc = ObjectUtils.evaluateFunctionOrProperty(accessor);
   const targetSet = new Set(targetIterator);
   const results = new Set();
   collection.forEach((record) => {
@@ -665,7 +648,7 @@ module.exports.notIn = function notIn(collection, accessor, targetIterator) {
  * aggregate.isUnique(data); // true
  */
 module.exports.isUnique = function isUnique(collection, accessor) {
-  const cleanedFunc = AggregateUtils.evaluateFunctionOrProperty(accessor);
+  const cleanedFunc = ObjectUtils.evaluateFunctionOrProperty(accessor);
   const uniqueValues = new Set();
   const duplicateValue = collection.find((record) => {
     const result = cleanedFunc(record);

package/src/group.js

@@ -1,6 +1,6 @@
 const SourceMap = require('./SourceMap');
 
-const AggregateUtils = require('./aggregate');
+const ObjectUtils = require('./object');
 
 /**
  * Utilities for collating and grouping records
@@ -308,7 +308,7 @@ module.exports.index = function index(collection, indexFn) {
     throw (Error('group.index: Collection is not an array'));
   }
   
-  const cleanedIndexFn = AggregateUtils.evaluateFunctionOrProperty(indexFn);
+  const cleanedIndexFn = ObjectUtils.evaluateFunctionOrProperty(indexFn);
 
   collection.forEach((item, offset) => {
     let val = cleanedIndexFn(item, offset);

package/src/ijs.js

@@ -363,6 +363,9 @@ module.exports.listStatic = function listStatic(target) {
  * @param {String | Function} options.onReady - JavaScript to run once all files have loaded
  * @param {Element} options.onReady.rootEl - results div container
  * @param {any} [options.onReady.data] - the options.data parameter
+ * @param {Object} options.onReady.utilityFunctions - the options.utilityFunctions object
+ * @param {Object} options.onReady.options - the options object passed
+ * @param {Object} options.onReady.animate - alias to requestAnimationFrame with additional checks to avoid leaks
  * @param {String[]} [options.scripts = []] - Array of JavaScript file addresses to load
  * @param {String[]} [options.css = []] - Array of CSS file addresses to load
  * @param {any} [options.data = undefined] - any nodejs data you would like available in javaScript
@@ -450,7 +453,7 @@ module.exports.htmlScript = function htmlScripts(
   if (!onReadyCode) {
     throw Error('ijsUtils.htmlScript: onReadyCode is required');
   } else if (typeof onReadyCode === 'function') {
-    onReadyCode = `(${onReadyCode.toString()})({rootEl, data, utilityFunctions, options})`;
+    onReadyCode = `(${onReadyCode.toString()})({rootEl, data, utilityFunctions, options, animate})`;
   } else if (typeof onReadyCode === 'string') {
     onReadyCode = onReadyCode.trim();
     if (!onReadyCode.endsWith(';')) {
@@ -509,6 +512,16 @@ module.exports.htmlScript = function htmlScripts(
           css: ${JSON.stringify(scriptAddresses)},
         };
 
+        const animate = function (requestAnimationFrameTarget) {
+          requestAnimationFrame((...passThroughArgs) => {
+            if (!document.contains(rootEl)) {
+              console.log('old animation stopping. rootEl has been removed from DOM');
+              return;
+            }
+            requestAnimationFrameTarget.apply(globalThis, passThroughArgs);
+          })
+        }
+
         //-- ijsUtils.htmlScipt options.data
         const data = ${JSON.stringify(data)};
 

package/src/object.js

@@ -1,4 +1,4 @@
-/* eslint-disable no-param-reassign */
+/* eslint-disable no-param-reassign, max-len */
 
 const schemaGenerator = require('generate-schema');
 
@@ -14,15 +14,17 @@ const schemaGenerator = require('generate-schema');
  *   * {@link module:object.objAssignEntities|objAssignEntities()} -
  *   * {@link module:object.selectObjectProperties|selectObjectProperties()} - keep only specific properties
  *   * {@link module:object.filterObjectProperties|filterObjectProperties()} - remove specific properties
- * * fetch child properties onto parents
- *   * {@link module:object.fetchObjectProperties|fetchObjectProperties()} - use dot notation to bring multiple child properties onto a parent
- *   * {@link module:object.fetchObjectProperty|fetchObjectProperty()} - use dot notation to bring a child property onto a parent
+ * * 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.
  * * Rename properties
  *   * {@link module:object.cleanProperties|cleanProperties()} - correct inaccessible property names in a list of objects
  *   * {@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
- * * flatten object properties
+ * * Flatten object properties
  *   * {@link module:object.collapseSpecificObject|collapseSpecificObject()} - flatten object properties
  *   * {@link module:object.collapse|collapse()} - flatten specific object
  * * Create Map of objects by key
@@ -38,6 +40,30 @@ const ObjectUtils = module.exports;
 
 //-- private methods
 
+/**
+ * Generates a function if a property or null or a function is sent
+ * @param {Function | String} fnOrProp - 
+ * @return {Function}
+ * @private
+ */
+module.exports.evaluateFunctionOrProperty = function evaluateFunctionOrProperty(fnOrProp) {
+  if (!fnOrProp) {
+    return (r) => r;
+  } else if (typeof fnOrProp === 'string') {
+    return (r) => r[fnOrProp];
+  } else if (typeof fnOrProp === 'function') {
+    return fnOrProp;
+  }
+
+  throw (Error('Send either a Function or Property Name or null for a simple array'));
+};
+
+/**
+ * Identifies keys from an object, but handles null safely.
+ * @param {Object} - object to get the keys from
+ * @return {Array<String>} - collections of keys or [] if no keys are found.
+ * @private
+ */
 const keysFromObject = (obj) => {
   if (!obj) {
     return [];
@@ -353,7 +379,7 @@ module.exports.filterObjectProperties = function filterObjectProperties(list, pr
  * @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 -
+ * @param {FetchObjectOptions} options - {@link module:object~FetchObjectOptions|See FetchObjectOptions} 
  * @returns {Object[]} - objects with the properties resolved
  *    (ex: {parentname, childName, etc.})
  */
@@ -385,7 +411,7 @@ module.exports.fetchObjectProperties = function fetchObjectProperties(list, prop
  * @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 -
+ * @param {FetchObjectOptions} options - {@link module:object~FetchObjectOptions|See FetchObjectOptions}
  * @returns {any} - the value accessed at the end ofthe property chain
  */
 module.exports.fetchObjectProperty = function fetchObjectProperty(obj, propertyAccess, safeAccess) {
@@ -441,3 +467,170 @@ module.exports.getObjectPropertyTypes = function getObjectPropertyTypes(list) {
 module.exports.generateSchema = function generateSchema(targetObj) {
   return schemaGenerator.json(targetObj);
 };
+
+/**
+ * Join values from an objectArray to a JavaScript Map.
+ * 
+ * For example:
+ * 
+ * ```
+ * weather = [
+ *   { id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87 },
+ *   null,
+ *   { id: 3, city: 'New York', month: 'Apr', precip: 3.94 },
+ *   { id: 6, city: 'Chicago',  month: 'Apr', precip: 3.62 }
+ * ];
+ * 
+ * cityLocations = new Map([
+ *   ['Chicago', { locationId: 1, city: 'Chicago', lat: 41.8781, lon: 87.6298 }],
+ *   ['New York', { locationId: 2, city: 'New York', lat: 40.7128, lon: 74.0060 }],
+ *   ['Seattle', { locationId: 3, city: 'Seattle', lat: 47.6062, lon: 122.3321 }]
+ * ]);
+ * 
+ * utils.object.join(weather, 'city', cityLocations, (weather, city) => ({...weather, ...city}));
+ * // [
+ * //    {id:1, city:'Seattle',  month:'Aug', precip:0.87, locationId:3, lat:47.6062, lon:122.3321 },
+ * //    null,
+ * //    {id:3, city:'New York', month:'Apr', precip:3.94, locationId:2, lat:40.7128, lon:74.006 },
+ * //    {id:6, city:'Chicago',  month:'Apr', precip:3.62, locationId:1, lat:41.8781, lon:87.6298 }
+ * // ]
+ * ```
+ * 
+ * or join by lookup:
+ * 
+ * ```
+ * utils.object.join(weather, 'city', cityLocations, (weather, city) => ({...weather, city}));
+ * [
+ *   { id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87, city:
+ *     { city: 'Seattle', locationId: 3, lat: 47.6062, lon: 122.3321 }
+ *   },
+ *   null,
+ *   { id: 3, city: 'New York', month: 'Apr', precip: 3.94, city:
+ *     { city: 'New York', locationId: 2, lat: 40.7128, lon: 74.006 }
+ *   },
+ *   { id: 6, city: 'Chicago',  month: 'Apr', precip: 3.62, city:
+ *     { city: 'Chicago', locationId: 1, lat: 41.8781, lon: 87.6298 }
+ *   }
+ * ];
+ * ```
+ * 
+ * or performing a translation / calculate the index instead of a property:
+ * 
+ * ```
+ * const indexingFn = (weather) => `${weather.country}_${weather.city}`;
+ * utils.object.join(weather, indexingFn, cityLocations, (weather, city) => ({...weather, ...city}));
+ * // ...
+ * ```
+ * 
+ * The signature for the indexingFunction is `(sourceObj:Object): {any}` - providing the index to use against the map.
+ * 
+ * The signature for the mapping function is `(sourceObj:Object, mappedObject:Object) => {Object}`.
+ * 
+ * If the mappedObject could not be found by that index (left join), then mappedObject will be `null`.
+ * 
+ * As the results of the functions are mapped, you can either modify in-line (directly on the object),
+ * or on a clone of the object (ex: {...sourceObj})
+ * 
+ * Note, performing a JavaScript .map() call may be more performant in some cases,
+ * so consider it for more complex options.
+ * 
+ * **Note: indexField can be either a string name of the field to join,
+ * or a function to be passed the object and generate the index**
+ * 
+ * @param {Array<Object>} objectArray - collection of objects to join based on the target map
+ * @param {Function | String} indexField - property on each object in array to lookup against target map <br />
+ *      Signature if a function: `(sourceObj:Object): {any}`
+ * @param {Map} targetMap - Map with keys mapping to values to pass
+ * @param {Function} joinFn - function to call each time an objectArray object, has an indexField found in targetMap <br />
+ *      Signature: `(sourceObj:Object, mappedObject:Object) => {Object}`
+ * @returns {Array<Object>} - Array of results returned from `joinFn`
+ */
+module.exports.join = function join(objectArray, indexField, targetMap, joinFn) {
+  const cleanArray = !objectArray
+    ? []
+    : Array.isArray(objectArray)
+      ? objectArray
+      : [objectArray];
+
+  const indexFn = ObjectUtils.evaluateFunctionOrProperty(indexField);
+
+  if (!targetMap) {
+    throw Error('object.join(objectArray, indexField, targetMap, joinFn): targetMap cannot be null');
+  }
+
+  if (!joinFn || typeof joinFn !== 'function') {
+    throw Error('object.join(objectArray, indexField, targetMap, joinFn): joinFn is required');
+  }
+  
+  const results = cleanArray.map((entry) => {
+    if (!entry) return entry;
+
+    const index = indexFn(entry);
+    
+    const target = targetMap.has(index)
+      ? targetMap.get(index)
+      : null;
+
+    const result = joinFn(entry, target);
+
+    return result;
+  });
+
+  return results;
+};
+
+/**
+ * For cases where we simply want to pull values from one object to another.
+ * 
+ * For example:
+ * 
+ * ```
+ * weather = [
+ *   { id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87 },
+ *   null,
+ *   { id: 3, city: 'New York', month: 'Apr', precip: 3.94 },
+ *   { id: 6, city: 'Chicago',  month: 'Apr', precip: 3.62 }
+ * ];
+ * 
+ * cityLocations = new Map([
+ *   ['Chicago', { locationId: 1, city: 'Chicago', lat: 41.8781, lon: 87.6298 }],
+ *   ['New York', { locationId: 2, city: 'New York', lat: 40.7128, lon: 74.0060 }],
+ *   ['Seattle', { locationId: 3, city: 'Seattle', lat: 47.6062, lon: 122.3321 }]
+ * ]);
+ * 
+ * utils.object.joinProperties(weather, 'city', cityLocations, 'lat', 'lon'));
+ * // [
+ * //    {id:1, city:'Seattle',  month:'Aug', precip:0.87, lat:47.6062, lon:122.3321 },
+ * //    null,
+ * //    {id:3, city:'New York', month:'Apr', precip:3.94, lat:40.7128, lon:74.006 },
+ * //    {id:6, city:'Chicago',  month:'Apr', precip:3.62, lat:41.8781, lon:87.6298 }
+ * // ]
+ * ```
+ * 
+ * @param {Array<Object>} objectArray - collection of objects to join based on the target map
+ * @param {Function | String} indexField - property on each object in array to lookup against target map <br />
+ *      Signature if a function: `(sourceObj:Object): {any}`
+ * @param {Map<any,Object>} targetMap - Map with keys mapping to values to pass
+ * @param {...String} fields - List of fields to add to the objectArray in-place against values from targetMap
+ * @returns {Array<Object>} - The modified objectArray with the fields applied.
+ */
+module.exports.joinProperties = function join(objectArray, indexField, targetMap, ...fields) {
+  const cleanFields = fields.filter((f) => f);
+  if (cleanFields.length < 1) {
+    throw Error('object.joinProperties(objectArray, indexField, targetMap, ...fields): at least one property passed to join');
+  }
+
+  const joinFn = (sourceObj, targetObj) => {
+    const cleanTarget = targetObj || {};
+    //-- allow for direct manipulation for speed
+    const result = sourceObj; // { ...sourceObj };
+
+    cleanFields.forEach((field) => {
+      result[field] = cleanTarget[field];
+    });
+
+    return result;
+  };
+
+  return ObjectUtils.join(objectArray, indexField, targetMap, joinFn);
+};

package/src/svg.js

@@ -318,11 +318,13 @@ Renders an SVG through a browser side instance of [SVG.js](https://svgjs.dev/)
  * @param {Object} options - options to use for drawing - or an onReady function
  * @param {Function} options.onReady - the function to call to generate the SVG
  * @param {Element} options.onReady.el - the SVG.js primed element to use for drawing
+ * @param {Object} options.onReady.data - the data object passed - now in javascript
  * @param {any} options.onReady.SVG - the SVG.js library instance
  * @param {Number} options.onReady.width - the options.width value passed, for positioning
  * @param {Number} options.onReady.height - the options.height value passed, for positioning
  * @param {Object} options.onReady.utilityFunctions - the options.utilityFunctions object
  * @param {Object} options.onReady.options - the options object passed
+ * @param {Object} options.onReady.animate - alias to requestAnimationFrame with additional checks to avoid leaks
  * @param {boolean} options.debug - default: false - whether to print the svg result text
  * @param {Number} options.width - default: 400 - the width of the svg to generate
  * @param {Number} options.height - default 200 - ... height
@@ -366,7 +368,7 @@ const width = ${width};
 const height = ${height};
 el.size(width, height);
 
-(${onReady.toString()})({ rootEl, el, SVG, data, width, height, utilityFunctions, options });
+(${onReady.toString()})({ rootEl, el, SVG, data, width, height, utilityFunctions, options, animate });
 `
   });
 };

package/src/svg_utilityFunctions.js

@@ -99,8 +99,7 @@ const SvgUtils = module.exports; // eslint-disable-line no-unused-vars
 module.exports.animationFrameCalls = function animationFrameCalls() {
   const requestAnimationFrame = window.requestAnimationFrame
       || window.mozRequestAnimationFrame
-      || window.webkitRequestAnimationFrame
-      || window.msRequestAnimationFrame;
+      || window.webkitRequestAnimationFrame;
   
   const cancelAnimationFrame = window.cancelAnimationFrame
       || window.mozCancelAnimationFrame;
@@ -123,8 +122,15 @@ module.exports.animationFrameCalls = function animationFrameCalls() {
     window.stopAnimation = isAllowed;
   };
   
-  const nextAnimationFrame = (fn) => {
-    const animationId = requestAnimationFrame(fn);
+  const nextAnimationFrame = (fn, el) => {
+    const requestFn = (...rest) => {
+      if (el && !window.document.contains(el)) {
+        console.log('old nextAnimationFrame aborting, el has been removed from DOM');
+      } else {
+        fn.apply(globalThis, rest);
+      }
+    };
+    const animationId = requestAnimationFrame(requestFn);
     window.animation = animationId;
   };
   
@@ -146,3 +152,5 @@ module.exports.animationFrameCalls = function animationFrameCalls() {
     allowAnimations
   };
 };
+
+module.exports.animation = module.exports.animationFrameCalls;