jupyter-ijavascript-utils 1.9.1 → 1.10.1

package/DOCS.md

@@ -28,6 +28,7 @@ See the [#Installation section for requirements and installation](#install)
 
 ## What's New
 
+* 1.10 - provide {@link module:aggregate.percentile|percentile} (like 50th percentile) aggregates
 * 1.9 - allow {@link TableGenerator#transpose|transposing results} on TableGenerator.
 * 1.8 - add in What can I Do tutorial, and {@link module:object.join|object.join methods}
 * 1.7 - revamp of `animation` method for ijs.htmlScript

package/Dockerfile

@@ -0,0 +1,34 @@
+# per https://github.com/n-riesco/ijavascript/issues/273
+# and https://github.com/paulroth3d/jupyter-ijavascript-utils/issues/4
+
+# as of today this is python-3.7.1
+FROM jupyter/base-notebook:latest
+
+# for nbhosting
+USER root
+COPY start-in-dir-as-uid.sh /usr/local/bin
+
+# prerequisites with apt-get
+# we do install python(2) here because
+# some npm build part named gyp still requires it
+RUN apt-get update && apt-get install -y gcc g++ make python
+
+# !!! dirty trick!!!
+# original PATH is
+# /opt/conda/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+# move conda's path **at the end**
+# so that python resolves in /usr/bin/python(2)
+# but node is still found in conda
+ENV PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/opt/conda/bin"
+USER jovyan
+RUN npm install -g ijavascript
+RUN ijsinstall
+
+# for displaying html fragments
+RUN npm install -g jsdom d3
+
+# !!! clean up!!!
+USER root
+RUN apt-get autoremove -y python
+ENV PATH="/opt/conda/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+USER jovyan

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.9.1-red" />
+        <img src="https://img.shields.io/badge/npm-%5E1.10.0-red" />
     </a>
 </p>
 
@@ -21,6 +21,7 @@ See documentation at: [https://jupyter-ijavascript-utils.onrender.com/](https://
 
 # What's New
 
+* 1.10 - provide percentile (like 50th percentile) aggregates
 * 1.9 - allow transposing results on TableGenerator.
 * 1.8 - add in What can I Do tutorial, and object.join methods
 * 1.7 - revamp of `animation` method to htmlScript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jupyter-ijavascript-utils",
-  "version": "1.9.1",
+  "version": "1.10.1",
   "description": "Utilities for working with iJavaScript - a Jupyter Kernel",
   "homepage": "https://jupyter-ijavascript-utils.onrender.com/",
   "license": "MIT",
@@ -27,7 +27,6 @@
     "jupyter"
   ],
   "author": "Paul Roth",
-  "license": "MIT",
   "devDependencies": {
     "babel-eslint": "^10.1.0",
     "docdash": "^1.2.0",
@@ -44,6 +43,7 @@
     "fs-extra": "^10.0.1",
     "generate-schema": "^2.6.0",
     "node-fetch": "^2.6.5",
+    "percentile": "^1.6.0",
     "pino": "^6.12.0",
     "pino-pretty": "^5.1.2",
     "plantuml-encoder": "^1.4.0",

package/src/TableGenerator.js

@@ -13,7 +13,7 @@
 
 const { printValue } = require('./format');
 
-const generateRange = (length, defaultValue) => new Array(length).fill(defaultValue);
+// const generateRange = (length, defaultValue) => new Array(length).fill(defaultValue);
 
 const IJSUtils = require('./ijs');
 
@@ -82,6 +82,7 @@ const { createSort } = require('./array');
  *   * {@link TableGenerator#styleHeader|styleHeader(string)} - css styles for the header row
  *   * {@link TableGenerator#styleRow|styleRow(fn)} - Function to style rows
  *   * {@link TableGenerator#styleCell|styleCell(fn)} - Function to style cells
+ *   * {@link TableGenerator#border|border(string)} - Apply a border to the table data cells
  * * generate output
  *   * {@link TableGenerator#generateHTML|generateHTML()} - returns html table with the results
  *   * {@link TableGenerator#generateMarkdown|generateMarkdown()} - returns markdown with the results
@@ -105,6 +106,12 @@ class TableGenerator {
    */
   #augmentFn = null;
 
+  /**
+   * Border CSS to also apply to the cells
+   * @type {String}
+   */
+  #borderCSS = ''; // 'solid 1px #AAA';
+
   /**
    * Optional array of exclusive columns to show based on the properties of each row\n
    * ex: ['Miles_per_Gallon', 'Name', 'Cylinders', etc]
@@ -235,6 +242,7 @@ class TableGenerator {
   reset() {
     this.#data = [];
     this.#augmentFn = null;
+    this.#borderCSS = '';
     this.#columns = null;
     this.#columnsToExclude = [];
     this.#fetch = null;
@@ -338,6 +346,62 @@ class TableGenerator {
     return this;
   }
 
+  /**
+   * Convenience function to set an a border on the Data Cells.
+   * 
+   * This only applies when {@link TableGenerator#render|rendering HTML}
+   * or {@link TableGenerator#generateHTML|generating HTML}
+   * 
+   * As this adds additional CSS, the styling applied:
+   *   * {@link TableGenerator#styleTable|to the whole table}
+   *   * or {@link TableGenerator#styleRow|to the rows}
+   *   * or {@link TableGenerator#styleCell|to the data cells} will be affected
+   * 
+   * For example:
+   * 
+   * ```
+   * sourceData = [{id: 1, temp_F:98}, {id: 2, temp_F:99}, {id: 3, temp_F:100}];
+   * 
+   * new utils.TableGenerator(sourceData)
+   *    .border('1px solid #aaa')
+   *    .render();
+   * ```
+   * 
+   * <table cellspacing="0px" >
+   * <tr >
+   *   <th>id</th>
+   *   <th>temp_F</th>
+   * </tr>
+   * <tr >
+   *   <td style=" border: 1px solid #aaa">1</td>
+   *   <td style=" border: 1px solid #aaa">98</td>
+   * </tr>
+   * <tr >
+   *   <td style=" border: 1px solid #aaa">2</td>
+   *   <td style=" border: 1px solid #aaa">99</td>
+   * </tr>
+   * <tr >
+   *   <td style=" border: 1px solid #aaa">3</td>
+   *   <td style=" border: 1px solid #aaa">100</td>
+   * </tr>
+   * </table>
+   * 
+   * @param {String | Boolean} borderCSS - CSS String to additionally apply HTML TD elements
+   */
+  border(borderCSS) {
+    let cleanCSS = '';
+
+    if (borderCSS === true) {
+      cleanCSS = 'border: 1px solid #AAA';
+    } else if (borderCSS) {
+      cleanCSS = `border: ${borderCSS}`;
+    }
+
+    this.#borderCSS = cleanCSS;
+
+    return this;
+  }
+
   /**
    * Applies an optional set of columns / properties to render
    * 
@@ -452,20 +516,64 @@ class TableGenerator {
    * 
    * (This is an alternate to {@link formatterFn} or simple `.map()` call on the source data)
    * 
+   * **NOTE: Only matching properties on the formatter object are changed - all others are left alone.**
+   * 
    * For example:
    * 
    * ```
-   * data = [{temp: 98, type: 'F'}, {temp: 99, type: 'F'}, {temp: 100, type: 'F'}];
+   * data = [
+   *   {station: 'A', temp: 98, type: 'F', descr: '0123'},
+   *   {station: 'A', temp: 99, type: 'F', descr: '0123456'},
+   *   {station: 'A', temp: 100, type: 'F', descr: '0123456789'}
+   * ];
    * 
    * //-- simple example where the temp property is converted, and type property overwritten
    * new TableGenerator(data)
    *  .formatter({
+   *    //-- property 'station' not mentioned, so no change
+   *    
+   *    //-- convert temperature to celsius
    *    temp: (value) => (value - 32) * 0.5556,
-   *    type: (value) => 'C'
-   *  })...
+   *    //-- overwrite type from 'F' to 'C'
+   *    type: 'C',
+   *    //-- ellipsify to shorten the description string, if longer than 8 characters
+   *    descr: (str) => utils.format.ellipsify(str, 8)
+   *  }).renderMarkdown()
    * ```
    * 
-   * Only properties on the object are checked - all others are left alone.
+   * station|temp  |type|descr    
+   * --     |--    |--  |--       
+   * A      |36.67 |F   |0123     
+   * A      |37.225|F   |0123456  
+   * A      |37.781|F   |01234567…
+   * 
+   * Note, due to frequent requests, simple datatype conversions can be requested.
+   * 
+   * Only ('String', 'Number', and 'Boolean') are supported
+   * 
+   * ```
+   * data = [
+   *   { propA: ' 8009', propB: 8009, isBoolean: 0},
+   *   { propA: ' 92032', propB: 92032, isBoolean: 1},
+   *   { propA: ' 234234', propB: 234234, isBoolean: 1},
+   * ];
+   * 
+   * new utils.TableGenerator(data)
+   *   .formatter({
+   *     //-- convert Prop A to Number - so render with Locale Number Formatting
+   *     propA: 'number',
+   *     //-- conver PropB to String - so render without Locale Number Formatting
+   *     propB: 'string',
+   *     //-- render 'True' or 'False'
+   *     isBoolean: 'boolean'
+   *   }).renderMarkdown();
+   * ```
+   * 
+   * propA|propB|isBoolean
+   * --                  |--                |--       
+   * 8,009               |8009              |false    
+   * 92,032              |92032             |true     
+   * 234,234             |234234            |true 
    * 
    * @param {Object} obj - object with properties storing arrow functions
    * @param {Function} obj.PropertyToTranslate - (value) => result
@@ -480,10 +588,25 @@ class TableGenerator {
 
     const fnMap = new Map();
     Object.getOwnPropertyNames(obj).forEach((key) => {
-      if ((typeof obj[key]) !== 'function') {
-        throw (Error(`Formatter properties must be functions. [${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]);
       }
-      fnMap.set(key, obj[key]);
     });
     
     this.#formatterFn = ({ value, property }) => fnMap.has(property)
@@ -928,6 +1051,7 @@ class TableGenerator {
     const styleRowFn = this.#styleRow;
     const styleCellFn = this.#styleCell;
     const printOptions = this.#printOptions;
+    const borderCSS = this.#borderCSS;
     
     const cleanFn = printValue;
 
@@ -948,16 +1072,17 @@ class TableGenerator {
           + dataRow.map((value, columnIndex) => {
             //-- note - the data is from the original dataset, not the results
             const cellStyle = !styleCellFn
-              ? null
+              ? ''
               : styleCellFn({ value, columnIndex, rowIndex, row: dataRow, record });
             return '<td '
-              + (!cellStyle ? '' : `style="${cellStyle}"`)
+              + (borderCSS || cellStyle ? `style="${cellStyle} ${borderCSS}"` : '')
               + `>${cleanFn(value, printOptions)}</td>`;
           }).join('\n\t')
           + '\n</tr>';
       }).join('\n');
     
     const tableResults = '<table '
+      + 'cellspacing="0px" '
       + (!styleTable ? '' : `style="${styleTable}"`)
       + '>'
       + printHeader(results.headers, '')

package/src/aggregate.js

@@ -1,5 +1,7 @@
 /* eslint-disable implicit-arrow-linebreak */
 
+const Percentile = require('percentile');
+
 const ObjectUtils = require('./object');
 const FormatUtils = require('./format');
 
@@ -13,6 +15,8 @@ const FormatUtils = require('./format');
  * 
  * Types of methods:
  * 
+ * * Select a single property
+ *   * {@link module:aggregate.property|property()} - maps to a single property (often used with other libraries)
  * * Ranges of values
  *   * {@link module:aggregate.extent|extent()} - returns the min and max of range
  *   * {@link module:aggregate.min|min()} - returns the minimum value of the range
@@ -35,6 +39,17 @@ const FormatUtils = require('./format');
  *   * {@link module:aggregate.sum|sum()} - sum of a collection
  * * Functional
  *   * {@link module:aggregate.deferCollection|deferCollection(function, bindArg, bindArg, ...)} - bind a function with arguments
+ * * Percentile
+ *   * {@link module:aggregate.percentile|percentile()} - determines the Nth percentile of a field or value
+ *   * {@link module:aggregate.percentile_01|percentile_01()} - 1th percentile
+ *   * {@link module:aggregate.percentile_05|percentile_05()} - 5th percentile
+ *   * {@link module:aggregate.percentile_10|percentile_10()} - 10th percentile
+ *   * {@link module:aggregate.percentile_25|percentile_25()} - 25th percentile
+ *   * {@link module:aggregate.percentile_50|percentile_50()} - 50th percentile
+ *   * {@link module:aggregate.percentile_75|percentile_75()} - 75th percentile
+ *   * {@link module:aggregate.percentile_90|percentile_90()} - 90th percentile
+ *   * {@link module:aggregate.percentile_95|percentile_95()} - 95th percentile
+ *   * {@link module:aggregate.percentile_99|percentile_99()} - 99th percentile
  * 
  * Please note, there is nothing special for these functions, such as working with {@link SourceMap#reduce|SourceMap.reduce()}
  * 
@@ -225,6 +240,34 @@ module.exports = {};
 // eslint-disable-next-line no-unused-vars
 const AggregateUtils = module.exports;
 
+/**
+ * Maps an array of values to a single property.
+ * 
+ * For example:
+ * 
+ * ```
+ * const data = [{ record: 'jobA', val: 1 }, { record: 'jobA', val: 2 },
+ *  { record: 'jobA', val: 3 }, { record: 'jobA', val: 4 },
+ *  { record: 'jobA', val: 5 }, { record: 'jobA', val: 6 },
+ *  { record: 'jobA', val: 7 }, { record: 'jobA', val: 8 },
+ *  { record: 'jobA', val: 9 }, { record: 'jobA', val: 10 }
+ * ];
+ * 
+ * utils.object.propertyFromList(data, 'val')
+ * //-- [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+ * 
+ * utils.object.propertyFromList(data, (r) => r.val);
+ * //-- [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+ * ```
+ * 
+ * @param {Object[]} objectArray - Array of Objects to be mapped to a single property / value
+ * @param {Function | String} propertyOrFn - Name of the property or Function to return a value
+ * @returns {Array} - Array of values
+ */
+module.exports.property = function propertyFromList(objectArray, propertyOrFn) {
+  return ObjectUtils.propertyFromList(objectArray, propertyOrFn);
+};
+
 /**
  * Converts an aggregate function to two functions -
  * one that takes all arguments except the collection
@@ -662,3 +705,157 @@ module.exports.isUnique = function isUnique(collection, accessor) {
   });
   return duplicateValue === undefined;
 };
+
+/**
+ * Returns a given percentile from a list of objects.
+ * 
+ * **Note: this simply aggregates the values and passes to the [Percentile NPM Package](https://www.npmjs.com/package/percentile)**
+ * 
+ * @param {Object[]} collection - collection of objects
+ * @param {Function | String} accessor - function to access the value, string property or null
+ * @param {Number} pct - Percentile (either .5 or 50)
+ * @returns {Number} - the pct percentile of a property within the collection
+ * @example
+ * const data = [{ record: 'jobA', val: 1 }, { record: 'jobA', val: 2 },
+ *  { record: 'jobA', val: 3 }, { record: 'jobA', val: 4 },
+ *  { record: 'jobA', val: 5 }, { record: 'jobA', val: 6 },
+ *  { record: 'jobA', val: 7 }, { record: 'jobA', val: 8 },
+ *  { record: 'jobA', val: 9 }, { record: 'jobA', val: 10 }
+ * ];
+ * 
+ * utils.aggregate.percentile(data, 'val', 50) //-- returns 5
+ * utils.aggregate.percentile(data, (r) => r.val, 70) //-- returns 7
+ */
+module.exports.percentile = function percentile(collection, accessor, pct) {
+  const values = ObjectUtils.propertyFromList(collection, accessor);
+  const cleanPercentile = pct > 0 && pct < 1
+    ? pct * 100
+    : pct;
+  return Percentile(cleanPercentile, values);
+};
+
+/**
+ * Returns a hard coded percentage
+ * 
+ * {@link module:aggregate.percentage|See Percentage for more detail}
+ * 
+ * @param {Object[]} collection - collection of objects
+ * @param {Function | String} accessor - function to access the value, string property or null
+ * @returns {Number} - the percentile of a property within the collection
+ * @see {@link module:aggregate.percentile|percentile} - as this simply hard codes the percentage
+ */
+module.exports.percentile_01 = function percentile(collection, accessor) {
+  return AggregateUtils.percentile(collection, accessor, 1);
+};
+
+/**
+ * Returns a hard coded percentage
+ * 
+ * {@link module:aggregate.percentage|See Percentage for more detail}
+ * 
+ * @param {Object[]} collection - collection of objects
+ * @param {Function | String} accessor - function to access the value, string property or null
+ * @returns {Number} - the percentile of a property within the collection
+ * @see {@link module:aggregate.percentile|percentile} - as this simply hard codes the percentage
+ */
+module.exports.percentile_05 = function percentile(collection, accessor) {
+  return AggregateUtils.percentile(collection, accessor, 5);
+};
+
+/**
+ * Returns a hard coded percentage
+ * 
+ * {@link module:aggregate.percentage|See Percentage for more detail}
+ * 
+ * @param {Object[]} collection - collection of objects
+ * @param {Function | String} accessor - function to access the value, string property or null
+ * @returns {Number} - the percentile of a property within the collection
+ * @see {@link module:aggregate.percentile|percentile} - as this simply hard codes the percentage
+ */
+module.exports.percentile_10 = function percentile(collection, accessor) {
+  return AggregateUtils.percentile(collection, accessor, 10);
+};
+
+/**
+ * Returns a hard coded percentage
+ * 
+ * {@link module:aggregate.percentage|See Percentage for more detail}
+ * 
+ * @param {Object[]} collection - collection of objects
+ * @param {Function | String} accessor - function to access the value, string property or null
+ * @returns {Number} - the percentile of a property within the collection
+ * @see {@link module:aggregate.percentile|percentile} - as this simply hard codes the percentage
+ */
+module.exports.percentile_25 = function percentile(collection, accessor) {
+  return AggregateUtils.percentile(collection, accessor, 25);
+};
+
+/**
+ * Returns a hard coded percentage
+ * 
+ * {@link module:aggregate.percentage|See Percentage for more detail}
+ * 
+ * @param {Object[]} collection - collection of objects
+ * @param {Function | String} accessor - function to access the value, string property or null
+ * @returns {Number} - the percentile of a property within the collection
+ * @see {@link module:aggregate.percentile|percentile} - as this simply hard codes the percentage
+ */
+module.exports.percentile_50 = function percentile(collection, accessor) {
+  return AggregateUtils.percentile(collection, accessor, 50);
+};
+
+/**
+ * Returns a hard coded percentage
+ * 
+ * {@link module:aggregate.percentage|See Percentage for more detail}
+ * 
+ * @param {Object[]} collection - collection of objects
+ * @param {Function | String} accessor - function to access the value, string property or null
+ * @returns {Number} - the percentile of a property within the collection
+ * @see {@link module:aggregate.percentile|percentile} - as this simply hard codes the percentage
+ */
+module.exports.percentile_75 = function percentile(collection, accessor) {
+  return AggregateUtils.percentile(collection, accessor, 75);
+};
+
+/**
+ * Returns a hard coded percentage
+ * 
+ * {@link module:aggregate.percentage|See Percentage for more detail}
+ * 
+ * @param {Object[]} collection - collection of objects
+ * @param {Function | String} accessor - function to access the value, string property or null
+ * @returns {Number} - the percentile of a property within the collection
+ * @see {@link module:aggregate.percentile|percentile} - as this simply hard codes the percentage
+ */
+module.exports.percentile_90 = function percentile(collection, accessor) {
+  return AggregateUtils.percentile(collection, accessor, 90);
+};
+
+/**
+ * Returns a hard coded percentage
+ * 
+ * {@link module:aggregate.percentage|See Percentage for more detail}
+ * 
+ * @param {Object[]} collection - collection of objects
+ * @param {Function | String} accessor - function to access the value, string property or null
+ * @returns {Number} - the percentile of a property within the collection
+ * @see {@link module:aggregate.percentile|percentile} - as this simply hard codes the percentage
+ */
+module.exports.percentile_95 = function percentile(collection, accessor) {
+  return AggregateUtils.percentile(collection, accessor, 95);
+};
+
+/**
+ * Returns a hard coded percentage
+ * 
+ * {@link module:aggregate.percentage|See Percentage for more detail}
+ * 
+ * @param {Object[]} collection - collection of objects
+ * @param {Function | String} accessor - function to access the value, string property or null
+ * @returns {Number} - the percentile of a property within the collection
+ * @see {@link module:aggregate.percentile|percentile} - as this simply hard codes the percentage
+ */
+module.exports.percentile_99 = function percentile(collection, accessor) {
+  return AggregateUtils.percentile(collection, accessor, 99);
+};

package/src/file.js

@@ -26,6 +26,8 @@ const logger = require('./logger');
  * * listing directory
  *   * {@link module:file.pwd|pwd()} - list the current path
  *   * {@link module:file.listFiles|listFiles(path)} - list files in a diven path
+ * * checking files exist
+ *   * {@link module:file.checkFile|checkFile(...paths)} - check if a file at a path exists
  * 
  * ---
  * 
@@ -299,3 +301,87 @@ module.exports.listFiles = function listFiles(directoryPath) {
     logger.error(`unable to read directory: ${resolvedPath}`);
   }
 };
+
+/**
+ * Synchronously checks if any of the files provided do not exist.
+ * 
+ * For example:
+ * 
+ * ```
+ * //-- these exist
+ * // ./data/credentials.env
+ * // ./data/results.json
+ * 
+ * if (!utils.file.checkFile('./data/results.json')) {
+ *    //-- retrieve the results
+ *    utils.ijs.await(async($$, console) => {
+ *      results = await connection.query('SELECT XYZ from Contacts');
+ *      utils.file.write('./data/results.json', results);
+ *    });
+ * } else {
+ *    results = utils.file.readJSON('./data/results.json');
+ * }
+ * ```
+ * 
+ * Note, you can also ask for multiple files at once
+ * 
+ * ```
+ * utils.file.checkFile(
+ *    './data/credentials.env',
+ *    './data/results.json',
+ *    './data/results.csv'
+ * );
+ * // false
+ * ```
+ * 
+ * or as an array:
+ * 
+ * ```
+ * utils.file.checkFile(['./data/credentails.env']);
+ * // true
+ * ```
+ * 
+ * @param  {...String} files - List of file paths to check (can use relative paths, like './') <br />
+ *    see {@link file:listFiles|listFiles()} or {@link file:pwd|pwd()} to help you)
+ * @returns {String[]} - null if all files are found, or array of string paths of files not found
+ */
+module.exports.checkFile = function checkFile(...files) {
+  //-- allow passing an array of files
+  const cleanFiles = files.length === 1 && Array.isArray(files[0])
+    ? files[0]
+    : files;
+  
+  const resolvedFiles = cleanFiles.map((unresolvedPath) => path.resolve(unresolvedPath));
+
+  const notFoundFiles = resolvedFiles.map((resolvedPath) => fs.existsSync(resolvedPath)
+    ? null
+    : resolvedPath);
+  
+  //-- do not filter empty files, as position in array is helpful
+  if (notFoundFiles.filter((p) => p).length === 0) {
+    return null;
+  }
+
+  return notFoundFiles;
+};
+
+/*
+ * Execute an async function if any of the files do not exist
+ * @param {String[]} filePaths - list of paths of files to check that they exist
+ * @param {*} fnIfFailed - async function tha will run - but only if any of the files are not found.
+ */
+/*
+module.exports.ifNotExists = async function ifNotExists(filePaths, fnIfFailed) {
+  const filesNotFound = FileUtil.checkFile(filePaths);
+
+  let results;
+
+  if (filesNotFound) {
+    results = await fnIfFailed(filesNotFound);
+  } else {
+    results = null;
+  }
+
+  return results;
+};
+*/

package/src/format.js

@@ -9,6 +9,10 @@
  * * formatting Numbers
  *   * {@link module:format.zeroFill|format.zeroFill} - Pads a number to a specific length
  *   * {@link module:format.divideR|format.divideR}   - Divides a number to provide { integer, remainder } - ex: 5/3 as ( 1, remainder 2 )
+ * * Formatting Strings
+ *   * {@link module:format.capitalize|format.capitalize} - Capitalizes only the first character in the string (ex: 'John paul');
+ *   * {@link module:format.capitalizeAll|format.capitalizeAll} - Capitalizes all the words in a string (ex: 'John Paul')
+ *   * {@link module:format.ellipsify|format.ellipsify} - Truncates a string if the length is 'too long'
  * * Formatting Time
  *   * {@link module:format.millisecondDuration|format.millisecondDuration}
  * * Mapping Values
@@ -454,3 +458,40 @@ module.exports.clampDomain = function clampDomain(value, [minimum, maximum]) {
   }
   return value;
 };
+
+/**
+ * Capitalizes the first character of the string.
+ * 
+ * @param {String} str - String to capitalize the first letter only
+ * @returns {String} - ex: 'John paul'
+ * @see {@link module:format.capitalizeAll|capitalizeAll} - to capitalize all words in a string
+ * @example
+ * utils.format.capitalize('john'); // 'John'
+ * utils.format.capitalize('john doe'); // 'John doe'
+ */
+module.exports.capitalize = function capitalize(str) {
+  if (!str || str.length === 0) {
+    return '';
+  }
+
+  //-- charAt does not work for unicode
+  const [first, ...rest] = str;
+  return first.toLocaleUpperCase() + rest.join('');
+};
+
+/**
+ * Capitalizes all words in a string.
+ * 
+ * @param {String} str - String to capitalize
+ * @returns {String} - ex: 'John-Paul'
+ * @see {@link module:format.capitalizeAll|capitalizeAll} - to capitalize all words in a string
+ * @example
+ * utils.format.capitalize('john'); // 'John'
+ * utils.format.capitalize('john doe'); // 'John Doe'
+ * utils.format.capitalize('john-paul'); // 'John-Paul'
+ */
+module.exports.capitalizeAll = function capitalizeAll(str) {
+  return (str || '').split(/\b/)
+    .map(FormatUtils.capitalize)
+    .join('');
+};

package/src/object.js

@@ -9,6 +9,9 @@ const schemaGenerator = require('generate-schema');
  *   * {@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
+ *   * {@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
  * * Manipulating objects
  *   * {@link module:object.objAssign|objAssign()} -
  *   * {@link module:object.objAssignEntities|objAssignEntities()} -
@@ -19,6 +22,7 @@ const schemaGenerator = require('generate-schema');
  *   * {@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.
+ *   * {@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.cleanPropertyNames|cleanPropertyNames()} - create a translation of inaccessible names to accessible ones
@@ -634,3 +638,188 @@ module.exports.joinProperties = function join(objectArray, indexField, targetMap
 
   return ObjectUtils.join(objectArray, indexField, targetMap, joinFn);
 };
+
+/**
+ * Maps an array of values to a single property.
+ * 
+ * For example:
+ * 
+ * ```
+ * const data = [{ record: 'jobA', val: 1 }, { record: 'jobA', val: 2 },
+ *  { record: 'jobA', val: 3 }, { record: 'jobA', val: 4 },
+ *  { record: 'jobA', val: 5 }, { record: 'jobA', val: 6 },
+ *  { record: 'jobA', val: 7 }, { record: 'jobA', val: 8 },
+ *  { record: 'jobA', val: 9 }, { record: 'jobA', val: 10 }
+ * ];
+ * 
+ * utils.object.propertyFromList(data, 'val')
+ * //-- [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+ * 
+ * utils.object.propertyFromList(data, (r) => r.val);
+ * //-- [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+ * ```
+ * 
+ * @param {Object[]} objectArray - Array of Objects to be mapped to a single property / value
+ * @param {Function | String} propertyOrFn - Name of the property or Function to return a value
+ * @returns {Array} - Array of values
+ */
+module.exports.propertyFromList = function propertyFromList(objectArray, propertyOrFn) {
+  const cleanArray = Array.isArray(objectArray)
+    ? objectArray
+    : [];
+  
+  const fn = ObjectUtils.evaluateFunctionOrProperty(propertyOrFn);
+
+  return cleanArray.map(fn);
+};
+
+/**
+ * Finds objects that do not have ALL the properties specified.
+ *
+ * This can be very helpful in ensuring all objects actually meet a specification and are not missing values.
+ * 
+ * ```
+ * const students = [
+ *   { first: 'john', last: 'doe', age: 23 }, { first: 'jane', last: 'doe', age: 23 }, { first: 'jack', last: 'white', failure: 401 }
+ * ];
+ *
+ * utils.findWithoutProperties(students, 'first', 'last', 'age');
+ * // [{ first: 'jack', last: 'white', failure: 401 }]
+ * 
+ * utils.findWithoutProperties(students, 'failure');
+ * // [{ first: 'john', last: 'doe', age: 23 }, { first: 'jane', last: 'doe', age: 23 }] 
+ * ```
+ *
+ * Please note, that we can check a single object:
+ *
+ * ```
+ * utils.findWithoutProperties(students[0], 'failure');
+ * // []
+ * ```
+ * 
+ * @param {Object[]} objectsToCheck - the array of objects to check for the properties.
+ * @param {...String} propertiesToFind - the list of properties to find within the collection.
+ * @returns {Object[]} - Array of objects that are missing at least one of those properties
+ * @see {@link module:file.findWithProperties|findWithProperties} - if you want objects that do not have all properties
+ **/
+module.exports.findWithoutProperties = function findWithoutProperties(targetObj, ...propertiesToFind) {
+  const cleanProperties = propertiesToFind.length > 0 && Array.isArray(propertiesToFind[0])
+    ? propertiesToFind[0]
+    : propertiesToFind;
+  
+  const cleanTargets = Array.isArray(targetObj)
+    ? targetObj
+    : [targetObj];
+  
+  const results = [];
+      
+  cleanTargets.forEach((target) => {
+    if (cleanProperties.find((prop) => (typeof target[prop]) === 'undefined')) {
+      results.push(target);
+    }
+  });
+  
+  return results;
+};
+
+/**
+ * Finds objects that have any of the properties specified.
+ * 
+ * This can be very helpful when working with datasets that include mixed data (such as JSON)
+ * 
+ * ```
+ * const students = [
+ *   { first: 'john', last: 'doe' }, { first: 'jane', last: 'doe' }, { first: 'jack', last: 'white', failure: 401 }
+ * ];
+ *
+ * utils.findWithProperties(students, 'failure');
+ * // { first: 'jack', last: 'white', failure: 401 }
+ * ```
+ *
+ * Please note, that we can check a single object:
+ *
+ * ```
+ * utils.findWithProperties({ first: 'john', last: 'doe' }, 'failure');
+ * // []
+ * ```
+ * 
+ * @param {Object[]} objectsToCheck - the array of objects to check for the properties.
+ * @param {...String} propertiesToFind - the list of properties to find within the collection.
+ * @returns {Object[]} - Array of objects that have at least one of those properties
+ * @see {@link module:file.findWithoutProperties|findWithoutProperties} - if you want objects that do not have all properties
+ **/
+module.exports.findWithProperties = function findWithProperties(targetObj, ...propertiesToFind) {
+  const cleanProperties = propertiesToFind.length > 0 && Array.isArray(propertiesToFind[0])
+    ? propertiesToFind[0]
+    : propertiesToFind;
+
+  const cleanTargets = Array.isArray(targetObj)
+    ? targetObj
+    : [targetObj];
+   
+  const results = [];
+       
+  cleanTargets.forEach((target) => {
+    if (cleanProperties.find((prop) => (typeof target[prop]) !== 'undefined')) {
+      results.push(target);
+    }
+  });
+
+  return results;
+};
+
+/**
+ * Sets values for objects that don't currently have the property
+ * 
+ * This is very helpful for ensuring that all objects have a property,
+ * or setting a value to make it easier to identify that it is 'N/A'
+ * 
+ * Note, that only the {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/hasOwnProperty|ownProperties}
+ * on the default object are checked.
+ * 
+ * And values are applied to the target object, only if the property is not on the object (property is undefined)
+ * 
+ * @param {Object[] | Object} targetObject - Object to apply the properties to <br />
+ *              but ONLY if the object does not have that property (ex: undefined)
+ * @param {Object} defaultObj - Object with the properties and defaults applied
+ * @param {any} defaultObj.property - the property to check, with the default value assigned
+ * @see {@link module:file.findWithoutProperties|findWithoutProperties} - to determine if any objects do not have a set of properties
+ * @see {@link module:file.keys|keys} - to get a list of unique properties of all objects in a list.
+ * @example
+ * const students = [
+ *   { first: 'john', last: 'doe', birthday: '2002-04-01' },
+ *   { first: 'jane', last: 'doe', birthday: '2003-05-01' },
+ *   { first: 'jack', last: 'white', failure: 401 }
+ * ];
+ * 
+ * utils.object.setPropertyDefaults(students, {
+ *  first: '',
+ *  last: '',
+ *  birthday: ''
+ * });
+ * 
+ * // [
+ * //   { first: 'john', last: 'doe', birthday: '2002-04-01' },
+ * //   { first: 'jane', last: 'doe', birthday: '2003-05-01' },
+ * //   { first: 'jack', last: 'white', birthday: '', failure: 401 }
+ * // ];
+ */
+module.exports.setPropertyDefaults = function setPropertyDefaults(targetObject, defaultObj) {
+  const cleanTargets = Array.isArray(targetObject)
+    ? targetObject
+    : [targetObject];
+  
+  if (!defaultObj || typeof defaultObj !== 'object') {
+    throw Error('object.setPropertyDefaults(targetObject, defaultObject): defaultObject is expected to be an object with properties set to the defaults to apply');
+  }
+
+  const defaultKeys = Object.getOwnPropertyNames(defaultObj);
+
+  cleanTargets.forEach((target) => {
+    defaultKeys.forEach((prop) => {
+      if (typeof target[prop] === 'undefined') {
+        target[prop] = defaultObj[prop];
+      }
+    });
+  });
+};