jupyter-ijavascript-utils 1.43.0 → 1.45.0

package/DOCS.md

@@ -75,6 +75,7 @@ Give it a try here:
 
 ## What's New
 
+* 1.45 - more ways to understand the data - {@link module:aggregate.coalesce|aggregate.coalesce()}, convert properties to arrow/dot notation / reverse it {@link module:object.flatten|object.flatten()} / {@link module:object.expand|object.expand()} and {@link module:object.isObject|object.isObject()}
 * 1.43 - esm module fix since still not supported yet in ijavascript
 * 1.41 - {@link module:object.propertyInherit|object.propertyInherit} - to simplify inheriting values from one record to the next
 * 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

package/Dockerfile

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

package/README.md

@@ -54,7 +54,7 @@ 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.45 - more ways to understand the data - aggregate.coalesce(), convert properties to arrow/dot notation / reverse it : object.flatten() / object.expand() and Object.isObject()
 * 1.43 - esm module fix since still not supported yet in ijavascript
 * 1.41 - object.propertyInherit - to simplify inheriting values from one record to the next
 * 1.40 - array.extract and array.applyArrayValue to allow for extracting values from arrays, transforming them on a separate process and applying them back

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jupyter-ijavascript-utils",
-  "version": "1.43.0",
+  "version": "1.45.0",
   "description": "Utilities for working with iJavaScript - a Jupyter Kernel",
   "homepage": "https://jupyter-ijavascript-utils.onrender.com/",
   "license": "MIT",
@@ -17,7 +17,8 @@
     "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",
+    "doc:taffy": "cp -R tmp/taffydb node_modules",
+    "doc:taffy:install": "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/aggregate.js

@@ -38,6 +38,7 @@ const FormatUtils = require('./format');
  *   * {@link module:aggregate.length|length()} - Number of records found in the collection
  *   * {@link module:aggregate.first|first()} - returns first non-null/undefined in list
  *   * {@link module:aggregate.sum|sum()} - sum of a collection
+ *   * {@link module:aggregate.coalesce|coalesce()} - given a list of objects, creates a single object with first non-null value of all properties
  * * Functional
  *   * {@link module:aggregate.deferCollection|deferCollection(function, bindArg, bindArg, ...)} - bind a function with arguments
  * * Percentile
@@ -389,6 +390,87 @@ module.exports.sum = function sum(collection, accessor) {
   return collection.reduce((current, val) => current + cleanedFunc(val), 0);
 };
 
+module.exports.coalesceDefaultEvaluationFn = function coalesceDefaultEvaluationFn(
+  entryValue,
+  currentCoalescedValue,
+  entryPropName,
+  entry
+) {
+  if (currentCoalescedValue) return false;
+  if (entryValue == null) return false;
+  if (entryValue === 0) return false;
+  if (Array.isArray(entryValue) && entryValue.length === 0) return false;
+  if (entryValue instanceof Date && entryValue.getTime() === 0) return false;
+  return true;
+};
+
+/**
+ * Coalesces a collection of objects to return a single object that has the first non-null value
+ * of all unique properties found in the collection.
+ * 
+ * example:
+ * 
+ * ```
+ * collection = [
+ *  { first: 'john' },
+ *  { last: 'doe' },
+ *  { age: 23 }
+ * ];
+ * utils.agg.coalesce(collection);
+ * // { first: 'john', last: 'doe', age: 23 };
+ * ```
+ * 
+ * this also works to show example values for a large number of objects
+ * 
+ * ```
+ * collection = [
+ *   { first: 'john', last: 'doe', age: 23, failedClass: null },
+ *   { first: 'jane', last: 'doe', favouriteColor: 'blue', failedClass: null },
+ *   null,
+ *   { first: 'bill', favouriteColor: 'red', failedClass: 'asbx-dx2' }
+ * ];
+ * utils.agg.coalesce(collection);
+ * //-- now we can understand the types of values we got for each property type
+ * // { first: 'john', last: 'doe', age: 23, favouriteColor: 'blue', failedClass: 'asbx-dx2' }
+ * ```
+ * 
+ * Note - an optional evaluationFn can be provided, that can be used to determine
+ * if a value is collected.
+ * 
+ * ```
+ * collection = [{ val: null }, { val: 23 }, { val: 2 }, { val: 100 }];
+ * maxCoalesce = (val, current) => val && (!current || val > current);
+ * utils.agg.coalesce(collection, maxCoalesce);
+ * // { val: 100 }
+ * ```
+ * 
+ * @param {Array} collection - 
+ * @param {Function} [evaluationFn] - optional function that defines the value collected
+ *  - function(entryValue:any, currentCoalescedValue:any, entryPropName:string, entry:Object):Boolean
+ * @returns {Object} - Object with all properties found, and the first 
+ * @see {@link module:describe.describeObjects|describe.describeObjects(collection, options)} - to better understand values found
+ */
+module.exports.coalesce = function coalesce(collection, evaluationFn) {
+  if (!Array.isArray(collection)) return collection;
+  const cleanEvalFn = evaluationFn || AggregateUtils.coalesceDefaultEvaluationFn;
+
+  const result = {};
+
+  collection.forEach((entry) => {
+    if (ObjectUtils.isObject(entry)) {
+      Object.keys(entry).forEach((key) => {
+        const entryValue = entry[key];
+        const currentCoalescedValue = result[key];
+        if (cleanEvalFn(entryValue, currentCoalescedValue, key, entry)) {
+          result[key] = entryValue;
+        }
+      });
+    }
+  });
+
+  return result;
+};
+
 /**
  * The difference between the lowest and the highest values in the collection
  * 

package/src/describe.js

@@ -14,6 +14,12 @@ const ObjectUtils = require('./object');
  *  * {@link module:describe.describeNumbers|describeNumbers(collection, options)} - describes a series of numbers
  *  * {@link module:describe.describeDates|describeDates(collection, options)} - describes a series of dates
  * 
+ * Most commonly, {@link module:describe.describeObjects|object.describeObjects(collection, options)} is used -
+ * as it describes with the appropriate type for each property.
+ * 
+ * Note, if there are multiple child objects within the collection, {@link module:object.flatten|object.flatten()}
+ * will bring those values down through dot notation (similar to arrow format) - so they can be better described.
+ * 
  * @module describe
  * @exports describe
  */
@@ -500,6 +506,9 @@ class DateDescription extends SeriesDescription {
  *  age     |number|3    |25                      |23                      |24                      |    |            |      
  *  enrolled|Date  |3    |2022-01-05T00:00:00.000Z|2022-01-01T00:00:00.000Z|2022-01-03T00:00:00.000Z|    |            |         
  *  
+ * Note, if there are multiple child objects within the collection, {@link module:object.flatten|object.flatten()}
+ * will bring those values down through dot notation (similar to arrow format) - so they can be better described.
+ * 
  * @param {Object[]} collection - Collection of objects to be described
  * @param {Object} options - options to be used
  * @param {String[]} options.include - string list of fields to include in the description
@@ -508,6 +517,7 @@ class DateDescription extends SeriesDescription {
  *      - that will override how that property is parsed.
  * @param {Number} maxRows - max rows to consider before halting
  * @returns {SeriesDescription[]} - collection of descriptions - one for each property
+ * @see {@link module:object.flatten|object.flatten()} - if the collection of objects have a large number of child objects.
  */
 module.exports.describeObjects = function describeObjects(collection, options) {
   const cleanCollection = Array.isArray(collection) ? collection : [collection];

package/src/object.js

@@ -8,6 +8,7 @@ const FormatUtils = require('./format');
  * Utility for working with and massaging javascript objects.
  * 
  * * Describe objects
+ *   * {@link module:object.isObject|isObject()} - Determine if a given value is an Object and not a Number, String, Array or Date
  *   * {@link module:object.keys|keys()} - Safely get the keys of an object or list of objects
  *   * {@link module:object.getObjectPropertyTypes|getObjectPropertyTypes()} - describe the properties of a list of objects
  *   * {@link module:object.generateSchema|generateSchema()} - generate a schema / describe properties of a list of objects
@@ -45,8 +46,9 @@ const FormatUtils = require('./format');
  *   * {@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
- *   * {@link module:object.collapseSpecificObject|collapseSpecificObject()} - flatten object properties
- *   * {@link module:object.collapse|collapse()} - flatten specific object
+ *   * {@link module:object.collapse|collapse()} - coalesce properties from all nested objects to the base object.
+ *   * {@link module:object.flatten|flatten()} - creates dot notation properties (similar to arrow notation) of all child objects.
+ *   * {@link module:object.expand|expand()}  - expands dot notation properties onto sub children (inverse of flatten)
  * * Create Map of objects by key
  *   * {@link module:object.mapByProperty|mapByProperty()} -
  *   * {@link module:group.by|group(collection, accessor)}
@@ -463,12 +465,138 @@ const collapseSpecificObject = function collapseSpecificObject(sourceObj, target
  * // 'Hi John, how do you like your F150?
  * @param {Object} objectTree
  * @returns {Object} - object with all the properties added
- * @see #MAX_COLLAPSE_DEPTH - 
+ * @see #MAX_COLLAPSE_DEPTH - library property that defines how far to collapse
  */
 module.exports.collapse = function collapse(targetObj) {
   return collapseSpecificObject({}, targetObj, 0);
 };
 
+/**
+ * Determines whether a value is an Object and not an Array or a Date
+ * @param {any} testValue - value to be tested
+ * @returns {Boolean} - whether the testValue is an Object and not an Array or a Date.
+ */
+module.exports.isObject = (o) => o != null
+  && typeof o === 'object'
+  && !Array.isArray(o)
+  && !(o instanceof Date);
+
+/**
+ * While originally intended as a sub-implementation for Flatten,
+ * this was exposed in case additional cases ever arose.
+ * 
+ * Example:
+ * 
+ * ```
+ * student = { first: 'john', last: 'doe' };
+ * friend = { first: 'jane', last: 'doe' };
+ * course = { id: 'econ-101', professor: { id: 10101, first: 'jim', last: 'gifford' }};
+ * flattenedObj = {};
+ * flattenedObj = utils.object.flattenObjectOntoAnother(student, flattenedObj);
+ * // { first: 'john', last: 'doe' }
+ * flattenedObj = utils.object.flattenObjectOntoAnother(friend, flattenedObj, 'friend.');
+ * // { first: 'john', last: 'doe', 'friend.first': 'jane', 'friend.last': 'doe' };
+ * flattenedObj = utils.object.flattenObjectOntoAnother(course, flattenedObj, 'course.');
+ * // { first: 'john', last: 'doe', 'friend.first': 'jane', 'friend.last': 'doe', 'course.id': 'econ-101',
+ * //   'course.professor.id': 10101, 'course.professor.first': 'jim', 'course.professor.last': 'gifford' };
+ * ```
+ * 
+ * See flatten for a an alternative to achieve the same result.
+ * 
+ * @param {Object} sourceObj - The object to review for source values / properties
+ * @param {Object} [targetObj={}] - The object to apply the dot notation properties onto
+ * @param {String} [prefix=''] - the string prefix of any properties found on source, to apply onto target
+ * @returns {Object} - the targetObj with the properties applied (in place)
+ */
+module.exports.flattenObjectOntoAnother = function flattenObjectOntoAnother(sourceObj, targetObj, prefix) {
+  const cleanTarget = targetObj || {};
+  const cleanPrefix = prefix || '';
+
+  if (!ObjectUtils.isObject(sourceObj)) {
+    return sourceObj;
+  }
+  
+  const sourceKeys = ObjectUtils.keys(sourceObj);
+  
+  sourceKeys.forEach((key) => {
+    const prefixedKey = `${cleanPrefix}${key}`;
+    const keyValue = sourceObj[key];
+    if (ObjectUtils.isObject(keyValue)) {
+      ObjectUtils.flattenObjectOntoAnother(keyValue, cleanTarget, `${prefixedKey}.`);
+    } else {
+      cleanTarget[prefixedKey] = keyValue;
+    }
+  });
+  return cleanTarget;
+};
+
+/**
+ * Flattens an object and sub-objects into dot notation - to have easier time understanding schemas and explainations.
+ * 
+ * example:
+ * 
+ * ```
+ * student = {
+ *  first: 'john', last: 'doe',
+ *  friend: { first: 'jane', last: 'doe' },
+ *  course: { id: 'econ-101', professor: { id: 10101, first: 'jim', last: 'gifford' }}
+ * };
+ * 
+ * flattenedObj = utils.object.flatten(student);
+ * // {
+ * //   first: 'john', last: 'doe',
+ * //   'friend.first': 'jane', 'friend.last': 'doe',
+ * //   'course.id': 'econ-101',
+ * //     'course.professor.id': 10101, 'course.professor.first': 'jim', 'course.professor.last': 'gifford'
+ * // };
+ * ```
+ * @param {Object} targetObj - Object with all properties and sub-objects to flatten.
+ * @returns {Object} - New object with dot notation properties
+ * @see {@link module:object.expand|expand()} - as the inverse
+ * @see {@link module:describe.describeObjects|describeObjects(collection, options)} - as a way to describe the values provided
+ */
+module.exports.flatten = function flatten(targetObj) {
+  return ObjectUtils.flattenObjectOntoAnother(targetObj);
+};
+
+/**
+ * The inverse of Flatten - this takes an object with dot notation properties,
+ * and creates the sub-objects as necessary to contain the properties defined.
+ * 
+ * Example:
+ * 
+ * ```
+ * flattenedObj = {
+ *   first: 'john', last: 'doe',
+ *   'friend.first': 'jane', 'friend.last': 'doe',
+ *   'course.id': 'econ-101',
+ *     'course.professor.id': 10101, 'course.professor.first': 'jim', 'course.professor.last': 'gifford'
+ * };
+ * 
+ * expandedObj = utils.object.expand(flattenedObj);
+ * // {
+ * //  first: 'john', last: 'doe',
+ * //  friend: { first: 'jane', last: 'doe' },
+ * //  course: { id: 'econ-101', professor: { id: 10101, first: 'jim', last: 'gifford' }}
+ * // };
+ * ```
+ * 
+ * @param {Object} targetObj - a flattened object (with dot notation properties) to be expanded
+ * @returns {Object} - a new object with sub-objects for each of the dot-notation entries
+ * @see {@link module:object.flatten|flatten()} - as the inverse
+ */
+module.exports.expand = function expand(targetObj) {
+  if (!ObjectUtils.isObject(targetObj)) return targetObj;
+
+  const result = {};
+  const keys = ObjectUtils.keys(targetObj);
+  keys.forEach((key) => {
+    ObjectUtils.applyPropertyValue(result, key, targetObj[key]);
+  });
+
+  return result;
+};
+
 /**
  * Keeps only specific properties on an object or list of objects
  * @param {Object | Object[]} list - collection of objects to filter
@@ -1429,9 +1557,11 @@ module.exports.mapProperties = function mapProperties(objCollection, formattingF
     ? [objCollection]
     : objCollection;
 
-  const cleanProperties = propertiesToFormat.length > 0 && Array.isArray(propertiesToFormat[0])
-    ? propertiesToFormat[0]
-    : propertiesToFormat;
+  const cleanProperties = propertiesToFormat.length === 0
+    ? ObjectUtils.keys(objCollection)
+    : propertiesToFormat.length > 0 && Array.isArray(propertiesToFormat[0])
+      ? propertiesToFormat[0]
+      : propertiesToFormat;
   
   if (typeof formattingFn !== 'function') {
     throw Error('object.mapProperties(collection, formattingFn, ...propertiesToFormat): formattingFn must be provided');

package/src/set.js

@@ -27,11 +27,13 @@ const SetUtils = module.exports;
 /**
  * Mutably adds a value to a set, and then returns the set. (Allowing Chaining)
  * 
- * (If you wish to immutably, use ES6: `{...setA, value1, value2, ...setB, etc...}`)
+ * (If you wish to immutably, use ES6: `{...setA, value1, value2, ...setB, etc...}`<br />
+ * or use the {@link module:set.union|union(set, list|set|iterable)} command below)
  * 
  * @param {set} setTarget - set to add values to
  * @param {any} val - value to add to the set
  * @returns {set} setTarget
+ * @see {@link module:set.union|union(set, list|set|iterable)}
  * @example
  * setA = new Set([1, 2, 3]);
  * utils.array.add(setA, 4, 5, 6); // Set([1, 2, 3, 4, 5, 6])
@@ -50,7 +52,8 @@ module.exports.add = function add(setTarget, ...rest) {
  *
  * @param {set} setTarget - set to add values to
  * @param {iteratable} iteratable - iteratable that can be unioned into the set.
- * @returns {set} setTarget
+ * @param {...iteratable} rest - additional iteratables to add to the union
+ * @returns {set} new set that contains values from all sources
  * @example
  * 
  * setA = new Set([1, 2, 3]);
@@ -61,8 +64,12 @@ module.exports.add = function add(setTarget, ...rest) {
  * listB = [4, 5, 6];
  * array.union(setA, listB) // Set([1, 2, 3, 4, 5, 6])
  * 
+ * setC = new Set([7, 8, 9]);
+ * array.union(setA, listB, setC);
+ * // Set(1, 2, 3, 4, 5, 6, 7, 8, 9);
+ * 
  */
-module.exports.union = function union(setTarget, iteratable) {
+module.exports.union = function union(setTarget, iteratable, ...rest) {
   const target = setTarget instanceof Set ? setTarget : new Set(setTarget);
   if (iteratable) {
     // eslint-disable-next-line
@@ -70,6 +77,7 @@ module.exports.union = function union(setTarget, iteratable) {
       target.add(v);
     }
   }
+  if (rest.length > 0) return SetUtils.union.apply(this, [target, ...rest]);
   return target;
 };
 
@@ -80,7 +88,8 @@ module.exports.union = function union(setTarget, iteratable) {
  * 
  * @param {Set} sourceA - the set to check for common items
  * @param {Set} sourceB - another set to check for common items
- * @returns {Set} - set of items that are in both sourceA and sourceB
+ * @param {...iteratable} rest - additional iteratables to verify
+ * @returns {Set} - set of items that are in all sources
  * @example
  * setA = new Set([1, 2, 3, 4]);
  * setB = new Set([3, 4, 5, 6]);
@@ -88,10 +97,14 @@ module.exports.union = function union(setTarget, iteratable) {
  * 
  * // Note that you can use other iteratable things too
  * utils.set.intersection([1, 2, 3, 4], [3, 4, 5, 6]); // Set([3, 4])
+ * 
+ * setC = new Set([3, 4, 9, 10]);
+ * utils.set.intersection(setA, setB, setC); // Set([3, 4]);
  */
-module.exports.intersection = function intersection(sourceA, sourceB) {
+module.exports.intersection = function intersection(sourceA, sourceB, ...rest) {
   const targetA = sourceA instanceof Set ? sourceA : new Set(sourceA);
   const results = new Set([...sourceB].filter((val) => targetA.has(val)));
+  if (rest.length > 0) return SetUtils.intersection.apply(this, [results, ...rest]);
   return results;
 };