jupyter-ijavascript-utils 1.14.2 → 1.15.2

package/DOCS.md

@@ -1,6 +1,8 @@
 # Overview
 
-This is a simple Library for using Jupyter with the IJavaScript kernel.
+This is a library to help people that understand JavaScript
+to leverage for using Jupyter with the iJavaScript kernel
+as a way to load and explore data, and ultimately tell compelling stories with visuals.
 
 Jupyter is a way to programmatically explore a subject and interleave text and markdown to make Data Driven Documents.
 
@@ -44,6 +46,7 @@ This is not intended to be the only way to accomplish many of these tasks, and a
 
 ## What's New
 
+* 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()}
 * 1.13 - provide {@link module:random|utils.random()} to genrate random values
 * 1.12 - provide `utils.table(...)` instead of `new utils.TableGenerator(...)`

package/README.md

@@ -7,7 +7,7 @@
     </a>
     <img src="https://img.shields.io/badge/Coverage-98-green" />
     <a href="https://github.com/paulroth3d/jupyter-ijavascript-utils" alt="npm">
-        <img src="https://img.shields.io/badge/npm-%5E1.14-red" />
+        <img src="https://img.shields.io/badge/npm-%5E1.15-red" />
     </a>
 </p>
 
@@ -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.15 - provide object.formatProperties - as a way to quickly convert to string, number, etc.
 * 1.14 - provide format.compactNumber and object.mapProperties
 * 1.13 - provide utils.random() to genrate random values
 * 1.12 - provide `utils.table(...)` instead of `new utils.TableGenerator(...)`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jupyter-ijavascript-utils",
-  "version": "1.14.2",
+  "version": "1.15.2",
   "description": "Utilities for working with iJavaScript - a Jupyter Kernel",
   "homepage": "https://jupyter-ijavascript-utils.onrender.com/",
   "license": "MIT",
@@ -13,6 +13,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",
+    "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",
     "open:coverage": "open ./coverage/lcov-report/index.html",

package/src/TableGenerator.js

@@ -18,6 +18,10 @@ const IJSUtils = require('./ijs');
 
 const ArrayUtils = require('./array');
 
+const FormatUtils = require('./format');
+
+const ObjectUtils = require('./object');
+
 const { createSort } = require('./array');
 
 /**
@@ -613,27 +617,11 @@ class TableGenerator {
       return this;
     }
 
+    const cleanedFormatter = FormatUtils.prepareFormatterObject(obj);
+
     const fnMap = new Map();
-    Object.getOwnPropertyNames(obj).forEach((key) => {
-      if ((typeof obj[key]) === 'string') {
-        let fn;
-        const str = obj[key].toLowerCase();
-        if (str === 'string') {
-          fn = (val) => String(val);
-        } else if (str === 'number') {
-          fn = (val) => Number(val);
-        } else if (str === 'boolean') {
-          fn = (val) => val ? 'true' : 'false';
-        } else {
-          throw Error(`TableGenerator.format: property ${key} formatter of ${str} is unsupported. Only (String, Number, Boolean) are supported`);
-        }
-        fnMap.set(key, fn);
-      } else {
-        if ((typeof obj[key]) !== 'function') {
-          throw (Error(`Formatter properties must be functions. [${key}]`));
-        }
-        fnMap.set(key, obj[key]);
-      }
+    Object.getOwnPropertyNames(cleanedFormatter).forEach((key) => {
+      fnMap.set(key, cleanedFormatter[key]);
     });
     
     this.#formatterFn = ({ value, property }) => fnMap.has(property)
@@ -1016,12 +1004,7 @@ class TableGenerator {
     }
 
     //-- determine the columns to use
-    //-- (based on fields of first record or columns provided)
-    const firstRow = cleanCollection.length > 0
-      ? cleanCollection[0]
-      : {};
-    
-    let keys = this.#columns || Object.keys(firstRow);
+    let keys = this.#columns || ObjectUtils.keys(cleanCollection);// Object.keys(firstRow);
     keys = keys.filter((key) => this.#columnsToExclude.indexOf(key) === -1);
 
     //-- identify the formatter to use

package/src/format.js

@@ -22,6 +22,11 @@
  * * Identifying Time Periods
  *   * {@link module:format.timePeriod|format.timePeriod} - Converts a time to a time period, very helpful for animations
  *   * {@link module:format.timePeriodPercent|format.timePeriodPercent} - Determines the percent complete of the current time period
+ * * Converting values safely
+ *   * {@link module:format.safeConvertString|format.safeConvertString} - converts a value to string, or uses a default for any error
+ *   * {@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
  * 
  * @module format
  * @exports format
@@ -307,11 +312,19 @@ module.exports.millisecondDuration = function millisecondDuration(milliseconds)
  * format.ellipsify('longName', 8) // 'longName' (as maxLen is 8)
  * format.ellipsify('longName', 4) // 'long…' (as str is longer than maxLen)
  */
-module.exports.ellipsify = function ellipsify(str, maxLen = 50) {
-  if (str && str.length > maxLen) {
-    return `${str.substring(0, maxLen)}…`;
+module.exports.ellipsify = function ellipsify(str, maxLen) {
+  const cleanStr = !str
+    ? ''
+    : typeof str === 'string'
+      ? str
+      : JSON.stringify(str);
+  
+  const cleanLen = maxLen > 0 ? maxLen : 50;
+
+  if (cleanStr.length > cleanLen) {
+    return `${cleanStr.substring(0, cleanLen)}…`;
   }
-  return str;
+  return cleanStr;
 };
 
 /**
@@ -632,3 +645,180 @@ module.exports.compactNumber = function compactNumber(num, digits = 0) {
 
   return (num / siValue).toFixed(digits) + siKey;
 };
+
+/**
+ * Converts a value to a String, <br />
+ * Or returns `otherwise` if any exceptions are found.
+ * 
+ * @param {any} val - value to convert
+ * @param {any} otherwise - value to use if any exceptions are caught
+ * @returns {String} - `String(val)`
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive|toPrimitive}
+ * @returns {String}
+ * @example
+ * utils.format.safeConvertString(23); // '23'
+ * 
+ * const customObj = {
+ *  toString: () => `String Value`
+ * };
+ * utils.format.safeConvertString(customObj); // 'String Value'
+ */
+module.exports.safeConvertString = function safeConvertString(val, otherwise = null) {
+  try {
+    return String(val);
+  } catch (err) {
+    return otherwise;
+  }
+};
+
+/**
+ * Converts a value to a Floating Number, <br />
+ * Or returns `otherwise` if any exceptions are found or value is NaN
+ * 
+ * @param {any} val - value to convert
+ * @param {any} otherwise - value to use if any exceptions are caught
+ * @returns {Number}
+ * @example
+ * utils.format.safeConvertFloat('23.1'); // 23.1
+ * utils.format.safeConvertFloat('not a number', -1); // -1
+ */
+module.exports.safeConvertFloat = function safeConvertFloat(val, otherwise = NaN) {
+  if (typeof val === 'string') {
+    //-- replace the variable in memory to minimize garbage collection.
+    // eslint-disable-next-line no-param-reassign
+    val = val.replace(/[^0-9.]/g, '');
+  }
+
+  try {
+    const result = Number.parseFloat(val);
+    if (Number.isNaN(result)) {
+      return otherwise;
+    }
+    return result;
+  } catch (err) {
+    //-- cannot reliably get the exception to be thrown so cannot test this line
+    /* istanbul ignore next */
+    return otherwise;
+  }
+};
+
+/**
+ * Converts a value to a Floating Number, <br />
+ * Or returns `otherwise` if any exceptions are found or value is Not a Number.
+ * 
+ * @param {any} val - value to convert
+ * @param {any} otherwise - value to use if any exceptions are caught
+ * @param {Number} [radix = 10] - radix to use in converting the string
+ * @returns {Number}
+ * @example
+ * utils.format.safeConvertFloat('23'); // 23
+ * utils.format.safeConvertFloat('not a number', -1); // -1
+ */
+module.exports.safeConvertInteger = function safeConvertInteger(val, otherwise = NaN, radix = 10) {
+  if (typeof val === 'string') {
+    //-- replace the variable in memory to minimize garbage collection.
+    // eslint-disable-next-line no-param-reassign
+    val = val.replace(/[^0-9.]/g, '');
+  }
+
+  try {
+    const result = Number.parseInt(val, radix);
+    if (Number.isNaN(result)) {
+      return otherwise;
+    }
+    return result;
+  } catch (err) {
+    //-- cannot reliably get the exception to be thrown so cannot test this line
+    /* istanbul ignore next */
+    return otherwise;
+  }
+};
+
+/**
+ * Converts a value to boolean.
+ * 
+ * Note this uses the standard JavaScript `truthy` conversion,
+ * but with special exceptions for strings: only 'true', 'yes', '1' are considered true.
+ * 
+ * @param {any} val - value to be converted
+ * @returns {Boolean}
+ * @example
+ * utils.format.safeConvertBoolean(1); // true
+ * utils.format.safeConvertBoolean({ pojo: true }); // true
+ * utils.format.safeConvertBoolean('TruE'); // true - case insensitive
+ * utils.format.safeConvertBoolean('YeS'); // true - case insensitive
+ * utils.format.safeConvertBoolean('1'); // true
+ * 
+ * utils.format.safeConvertBoolean(0); // false
+ * utils.format.safeConvertBoolean(null); // false
+ * utils.format.safeConvertBoolean('false'); // false
+ * utils.format.safeConvertBoolean('No'); // false
+ * utils.format.safeConvertBoolean('0'); // false
+ */
+module.exports.safeConvertBoolean = function safeConvertBoolean(val) {
+  if (typeof val === 'string') {
+    const valUpper = val.toUpperCase();
+    return valUpper === 'TRUE' || valUpper === 'YES' || valUpper === '1';
+  }
+  return val ? true : false;
+};
+
+module.exports.parseCommand = function parseCommand(commandStr) {
+  if (!commandStr || commandStr.indexOf('(') < 0) {
+    return [commandStr];
+  }
+
+  const match = commandStr.match(/^([a-zA-Z].+)[(](.*)[)]$/i);
+  let result = [];
+
+  if (match) {
+    const commandArgs = (match[2] || '').split(',').map((s) => s.trim()).filter((v) => v !== '');
+    result = [
+      match[1].trim(),
+      commandArgs
+    ];
+  } else {
+    result = [commandStr];
+  }
+  return result;
+};
+
+module.exports.prepareFormatterObject = function prepareFormatterObject(formatterObject) {
+  //-- @TODO: find way to reliably say that the propertyTranslation is an object
+  // propertyTranslations.constructor.name !== 'Object'
+  if (!formatterObject) {
+    throw Error(['ObjectUtils.formatProperties(collection, propertyTranslations): propertyTranslations must be an object, ',
+      'with the properties matching those to be formatted, and values as functions returning the new value'].join(''));
+  }
+
+  const translationKeys = Array.from(Object.keys(formatterObject));
+
+  const result = ({ ...formatterObject });
+
+  translationKeys.forEach((key) => {
+    const translationVal = formatterObject[key];
+    const translationValType = typeof translationVal;
+    if (translationValType === 'function') {
+      //-- do nothing
+    } else if (translationValType === 'string') {
+      const [command, args = []] = FormatUtils.parseCommand(translationVal);
+      if (command === 'string') {
+        result[key] = FormatUtils.safeConvertString;
+      } else if (command === 'ellipsify' || command === 'elipsify' || command === 'ellipsis' || command === 'elipsis') {
+        result[key] = (str) => FormatUtils.ellipsify(str, args[0]);
+      } else if (command === 'number' || command === 'float') {
+        result[key] = FormatUtils.safeConvertFloat;
+      } else if (command === 'int' || command === 'integer') {
+        result[key] = FormatUtils.safeConvertInteger;
+      } else if (command === 'bool' || command === 'boolean') {
+        result[key] = FormatUtils.safeConvertBoolean;
+      } else {
+        result[key] = () => translationVal;
+      }
+    } else {
+      result[key] = () => translationVal;
+    }
+  });
+
+  return result;
+};

package/src/object.js

@@ -2,6 +2,8 @@
 
 const schemaGenerator = require('generate-schema');
 
+const FormatUtils = require('./format');
+
 /**
  * Utility for working with and massaging javascript objects.
  * 
@@ -18,6 +20,7 @@ const schemaGenerator = require('generate-schema');
  *   * {@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)
  * * 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
@@ -25,7 +28,8 @@ const schemaGenerator = require('generate-schema');
  *   * {@link module:object.joinProperties|join(array, index, map, ...fields)} - join a collection, and copy properties over from the mapped object.
  *   * {@link module:object.propertyFromList|propertyFromList(array, propertyName)} - fetches a specific property from all objects in a list
  * * Rename properties
- *   * {@link module:object.cleanProperties|cleanProperties()} - correct inaccessible property names in a list of objects
+ *   * {@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.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
@@ -146,7 +150,8 @@ module.exports.objAssignEntities = function objAssignEntities(obj, entities) {
  * Runs a map over a collection, and adds properties the the objects.
  * 
  * @param {Object | Array<Object>} objCollection - object or collection of objects to augment
- * @param {Function} mappingFn - (record) => {Object} mapping function
+ * @param {Function | Object} mappingFn - (record) => {Object} mapping function <br />
+ *            or object with properties to create 
  * @param {Boolean} [inPlace=false] - whether to update the collection in place (true) or cloned (false)
  * @returns {Array<Object>} - collection of records with the fields merged
  * @example
@@ -227,7 +232,11 @@ module.exports.keys = function keys(objOrArray = {}) {
 };
 
 /**
- * Cleans all the properties of the array of objects
+ * Cleans all the properties of the array of objects in place (does not make Copies)
+ * 
+ * **NOTE: This is faster than {@link module:ObjectUtils.cleanProperties2|cleanProperties2},
+ * but the standard order of the properties (using Object.keys) will be altered.**
+ * 
  * @param {Object[]} objectsToBeCleaned -
  * @return {Object[]} - cleaned objects
  */
@@ -238,21 +247,98 @@ module.exports.cleanProperties = function cleanProperties(objectsToBeCleaned) {
   );
 };
 
+/**
+ * Labels and Values from {@link module:object.cleanProperties2|object.cleanProperties2}
+ * 
+ * ```
+ * {
+ *   labels: { date: 'date', kind: 'kind', num: 'num' },
+ *   values: [
+ *     { date: ' 2021-07-11T22:23:07+0100', kind: ' s', num: '192' },
+ *     { date: ' 2021-07-09T19:54:48+0100', kind: ' c', num: '190' },
+ *     { date: ' 2021-07-08T17:00:32+0100', kind: ' s', num: '190' }
+ *   ]
+ * };
+ * ```
+ * 
+ * @typedef {Object} CleanedProperties
+ * @property {Object} labels - an object with translations of the fields and labels
+ * @property {String} labels.property - for each translated property, stores the original property name
+ * @property {Object[]} values - cleaned values
+ 
+ */
+
+/**
+ * Cleans properties on clones of objects.
+ * 
+ * Additionally, this returns a mapping of what the properties used to be named,
+ * as this can be helpful for rendering out tables.
+ * 
+ * @param {Object[]} objectsToBeCleaned - collection of objects to be cleaned
+ * @returns {CleanedProperties} - { labels: Object - propertyName:originalProperty, values: cleaned collection }
+ * @see {@link module:object~CleanedProperties}
+ * @example
+const badData = [
+  { '"name"': 'john', num: '192', ' kind': ' s', '1st date': ' 2021-07-11T22:23:07+0100' },
+  { '"name"': 'jane', num: '190', ' kind': ' c', '1st date': ' 2021-07-09T19:54:48+0100' },
+  { '"name"': 'ringo', num: '190', ' kind': ' s', '1st date': ' 2021-07-08T17:00:32+0100' }
+];
+const cleaned = objectUtils.cleanProperties2(badData);
+// {
+//   labels: { 1st_date: '1st date', kind: 'kind', num: 'num' },
+//   values: [
+//     { name: 'john', num: '192', kind: ' s', '1st_date': ' 2021-07-11T22:23:07+0100' },
+//     { name: 'jane', num: '190', kind: ' c', '1st_date': ' 2021-07-09T19:54:48+0100' },
+//     { name: 'ringo', num: '190', kind: ' s', '1st_date': ' 2021-07-08T17:00:32+0100' }
+//   ]
+// }
+ */
+module.exports.cleanProperties2 = function cleanProperties2(objectsToBeCleaned) {
+  const cleanedPropertyNames = ObjectUtils.cleanPropertyNames(objectsToBeCleaned);
+  const keys = ObjectUtils.keys(cleanedPropertyNames);
+
+  const translation = keys.reduce((result, key) => ObjectUtils
+    .objAssign(result, cleanedPropertyNames[key], ObjectUtils.lightlyCleanProperty(key)), {});
+  
+  const values = (objectsToBeCleaned || [])
+    .map((obj) => keys.reduce(
+      (result, key) => ObjectUtils.objAssign(result, cleanedPropertyNames[key], obj[key]),
+      {}
+    ));
+  
+  return ({ labels: translation, values });
+};
+
+/**
+ * cleans properties so they are still legible
+ * @private
+ * @param {String} propertyName - property name to be cleaned
+ * @returns {String}
+ */
+module.exports.lightlyCleanProperty = function lightlyCleanProperty(propertyName) {
+  //-- assume property name is a string
+  return propertyName.trim()
+    .replace(/^["']/, '')
+    .replace(/['"]$/, '');
+};
+
 /**
  * Cleans the list of object keys - likely from a CSV
  * @param {(Object| String[])} objectKeys -
  * @return {Object} - object with key:value as original:new
  */
-module.exports.cleanPropertyNames = function cleanPropertyNames(objectKeys) {
+module.exports.cleanPropertyNames = function cleanPropertyNames(target) {
   let originalKeys;
-  if (Array.isArray(objectKeys)) {
-    if ((typeof objectKeys[0]) === 'string') {
-      originalKeys = objectKeys;
+  if (!target) {
+    return {};
+  } else if (Array.isArray(target)) {
+    if ((typeof target[0]) === 'string') {
+      originalKeys = target;
     } else {
-      originalKeys = ObjectUtils.keys(objectKeys);
+      originalKeys = ObjectUtils.keys(target);
     }
   } else {
-    originalKeys = Object.keys(objectKeys);
+    originalKeys = Object.keys(target);
   }
 
   const result = {};
@@ -439,6 +525,82 @@ module.exports.fetchObjectProperty = function fetchObjectProperty(obj, propertyA
     }, obj);
 };
 
+/**
+ * Translates specific properties to a new value on an object, or collection of objects.
+ * 
+ * The properties defined in the `propertyTranslations` argument is then the property to be updated. (All other properties remain the same)
+ * 
+ * You can either provide a function accepting the current value and returning the new value (any) => any
+ * 
+ * Or you can provide one of the common shorthands:
+ * 
+ * * 'string'
+ * * 'float' or 'number'
+ * * 'int' or 'integer'
+ * * 'boolean'
+ * 
+ * ```
+ * data = [
+ *   {station: 'A', isFahreinheit: 'true', offset: '0', temp: 98, type: 'F', descr: '0123'},
+ *   {station: 'A', isFahreinheit: 'TRUE', offset: '2', temp: 99, type: 'F', descr: '0123456'},
+ *   {station: 'A', isFahreinheit: 'false', offset: '3', temp: 100, type: 'F', descr: '0123456789'}
+ * ];
+ * 
+ * utils.object.format(data, ({
+ *   //-- to a literal value
+ *   type: 'C',
+ *   //-- convert it to 'string', 'number' || 'float', 'int' || 'integer', 'boolean'
+ *   offset: 'number',
+ *   isFahreinheit: 'boolean',
+ *   //-- or convert the value with a function accepting the current value
+ *   //-- and returning the new value
+ *   temp: (val) => (val - 32) * 0.5556
+ * }));
+ * 
+ * // [
+ * //   { station: 'A', isFahreinheit: true, offset: 0, temp: 36.669599999999996, type: 'C', descr: '0123' },
+ * //   { station: 'A', isFahreinheit: true, offset: 2, temp: 37.2252, type: 'C', descr: '0123456' },
+ * //   { station: 'A', isFahreinheit: false, offset: 3, temp: 37.7808, type: 'C', descr: '0123456789' }
+ * // ];
+ * ```
+ * 
+ * **Please note, you can pass a single object to be cleaned**,<br /> but it will be returned as an array of one object.
+ * 
+ * ```
+ * data = [{station: 'A', isFahreinheit: 'TRUE', offset: '2', temp: 99, type: 'F', descr: '0123456'}];
+ * 
+ * utils.object.format(data, ({
+ *   //-- convert it to 'string', 'number' || 'float', 'int' || 'integer', 'boolean'
+ *   offset: 'number',
+ *   isFahreinheit: 'boolean'
+ * }));
+ * 
+ * // [{station: 'A', isFahreinheit: true, offset: 2, temp: 99, type: 'F', descr: '0123456'}];
+ * ```
+ * 
+ * @param {Object} collection - the list of objects to update specific properties
+ * @param {Object} propertyTranslations - An object with property names as the properties to update <br />
+ *      and the values as a function ((any) => any) accepting the current value, returning the new value.
+ * @returns {Object[]} - collection of objects transformed
+ * @see {@link module:object.augment|augment(collection, fn)} - to add in new properties
+ * @see {@link TableGenerator#formatter} - for other examples
+ */
+module.exports.formatProperties = function formatProperties(collection, propertyTranslations) {
+  const cleanCollection = !collection ? []
+    : Array.isArray(collection) ? collection : [collection];
+  
+  propertyTranslations = FormatUtils.prepareFormatterObject(propertyTranslations);
+  const translationKeys = Array.from(Object.keys(propertyTranslations));
+  
+  return cleanCollection.map((obj) => {
+    const clone = { ...obj };
+    translationKeys.forEach((key) => {
+      clone[key] = propertyTranslations[key](clone[key]);
+    });
+    return clone;
+  });
+};
+
 /**
  * returns a map of the types of fields stored
  * @see generateSchema