jupyter-ijavascript-utils 1.14.2 → 1.15.0

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.0",
   "description": "Utilities for working with iJavaScript - a Jupyter Kernel",
   "homepage": "https://jupyter-ijavascript-utils.onrender.com/",
   "license": "MIT",

package/src/TableGenerator.js

@@ -18,6 +18,8 @@ const IJSUtils = require('./ijs');
 
 const ArrayUtils = require('./array');
 
+const FormatUtils = require('./format');
+
 const { createSort } = require('./array');
 
 /**
@@ -613,27 +615,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)

package/src/format.js

@@ -632,3 +632,72 @@ module.exports.compactNumber = function compactNumber(num, digits = 0) {
 
   return (num / siValue).toFixed(digits) + siKey;
 };
+
+module.exports.safeConvertString = function safeConvertString(val) {
+  try {
+    return String(val);
+  } catch (err) {
+    //-- I cannot find a way to reliably throw an error, but keep it in case it does
+    /* istanbul ignore next */
+    return null;
+  }
+};
+
+module.exports.safeConvertFloat = function safeConvertFloat(val) {
+  try {
+    return Number.parseFloat(val);
+  } catch (err) {
+    //-- I cannot find a way to reliably throw an error, but keep it in case it does
+    /* istanbul ignore next */
+    return null;
+  }
+};
+
+module.exports.safeConvertInteger = function safeConvertInteger(val) {
+  try {
+    return Number.parseInt(val, 10);
+  } catch (err) {
+    //-- I cannot find a way to reliably throw an error, but keep it in case it does
+    /* istanbul ignore next */
+    return null;
+  }
+};
+
+module.exports.safeConvertBoolean = function safeConvertBoolean(val) {
+  if (typeof val === 'string') {
+    return val.toUpperCase() === 'TRUE';
+  }
+  return val ? true : false;
+};
+
+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];
+    if (typeof translationVal === 'function') {
+      //-- do nothing
+    } else if (translationVal === 'string') {
+      result[key] = FormatUtils.safeConvertString;
+    } else if (translationVal === 'number' || translationVal === 'float') {
+      result[key] = FormatUtils.safeConvertFloat;
+    } else if (translationVal === 'int' || translationVal === 'integer') {
+      result[key] = FormatUtils.safeConvertInteger;
+    } else if (translationVal === 'boolean') {
+      result[key] = FormatUtils.safeConvertBoolean;
+    } 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
@@ -146,7 +149,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
@@ -439,6 +443,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