jupyter-ijavascript-utils 1.16.3 → 1.17.0

package/DOCS.md

@@ -46,6 +46,7 @@ This is not intended to be the only way to accomplish many of these tasks, and a
 
 ## What's New
 
+* 1.17 - provide object.propertyValueSample - as a way to list 'non-empty' property values
 * 1.16 - provide file.matchFiles - as a way to find files or directories
 * 1.15 - provide {@link module:object.formatProperties|object.formatProperties} - as a way to quickly convert to string, number, etc.
 * 1.14 - provide {@link module:object.mapProperties|object.mapProperties()} and {@link module:format.compactNumber|format.compactNumber()}

package/README.md

@@ -46,6 +46,7 @@ This is not intended to be the only way to accomplish many of these tasks, and a
 
 # What's New
 
+* 1.17 - provide object.propertyValueSample - as a way to list 'non-empty' property values
 * 1.16 - provide file.matchFiles - as a way to find files or directories
 * 1.15 - provide object.formatProperties - as a way to quickly convert to string, number, etc.
 * 1.14 - provide format.compactNumber and object.mapProperties

package/package.json

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

package/src/format.js

@@ -27,6 +27,8 @@
  *   * {@link module:format.safeConvertFloat|format.safeConvertFloat} - converts a value to a Number (123.4), or uses a default for any error or NaN
  *   * {@link module:format.safeConvertInteger|format.safeConvertInteger} - converts a value to a Number (123), or uses a default for any error or NaN
  *   * {@link module:format.safeConvertBoolean|format.safeConvertBoolean} - converts a value to a boolean
+ * * Identifying values
+ *   * {@link module:format.isEmptyValue|format.isEmptyValue} - determine if a value is not 'empty'
  * 
  * @module format
  * @exports format
@@ -825,3 +827,20 @@ module.exports.prepareFormatterObject = function prepareFormatterObject(formatte
 
   return result;
 };
+
+/**
+ * Tests for empty values:
+ * 
+ * * (zeros are allowed)
+ * * not null
+ * * not undefined
+ * * not an empty string
+ * * not an empty array `[]`
+ * 
+ * @param {any} val - a value to be tested 
+ * @returns {Boolean} - TRUE if the value is not 'empty'
+ */
+module.exports.isEmptyValue = (val) =>
+  //-- allow for 0s
+  val === null || val === undefined || val === ''
+  || (Array.isArray(val) && val.length === 0);

package/src/object.js

@@ -14,6 +14,7 @@ const FormatUtils = require('./format');
  *   * {@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.objAssign|objAssign()} -
  *   * {@link module:object.objAssignEntities|objAssignEntities()} -
@@ -1048,3 +1049,55 @@ module.exports.mapProperties = function mapProperties(objCollection, formattingF
     return clone;
   });
 };
+
+/**
+ * Finds all the properties for objects in a collection,
+ * and provides the first 'non-empty' value found of each property.
+ * 
+ * Non-Empty means:
+ * 
+ * * not null
+ * * not undefined
+ * * not an empty string
+ * * not an empty array
+ * 
+ * This can be especially helpful for heterogeneous collections
+ * and can be much faster than something like {@link https://danfo.jsdata.org/api-reference/dataframe/danfo.dataframe.describe|danfojs.describe}
+ * 
+ * @param {Object[]} objCollection - Array of objects that we want to understand
+ * @returns {Map<String,any>} - Collection of all properties and the first 'non-empty' value found
+ * @example
+ * let collection = [
+ *  { first: 'jane', age: 23 },
+ *  { first: 'john', last: 'doe', age: 21 }
+ * ];
+ * 
+ * utils.object.propertyValueSample(collection);
+ * // { first: 'jane', last: 'doe', age: 23 }
+ */
+module.exports.propertyValueSample = function propertyValueSample(objCollection) {
+  if (!objCollection) {
+    throw new Error('propertyValueSample(objectCollection): objectCollection is required');
+  }
+
+  const collection = Array.isArray(objCollection) ? objCollection : [objCollection];
+
+  const result = new Map();
+  let entryValue;
+
+  collection.forEach((entry) => {
+    if (entry && (typeof entry) === 'object') {
+      for (const entryProperty of Object.keys(entry)) {
+        entryValue = entry[entryProperty];
+        if (
+          !FormatUtils.isEmptyValue(entryValue)
+          && !result.has(entryProperty)
+        ) {
+          result.set(entryProperty, entryValue);
+        }
+      }
+    }
+  });
+
+  return result;
+};