jupyter-ijavascript-utils 1.9.2 → 1.11.0

package/DOCS.md

@@ -28,6 +28,8 @@ See the [#Installation section for requirements and installation](#install)
 
 ## What's New
 
+* 1.11 - provide {@link module:aggregate.topValues|topValues} (like top 5, bottom 3)
+* 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/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.2-red" />
+        <img src="https://img.shields.io/badge/npm-%5E1.11.0-red" />
     </a>
 </p>
 
@@ -21,6 +21,8 @@ See documentation at: [https://jupyter-ijavascript-utils.onrender.com/](https://
 
 # What's New
 
+* 1.11 - provide topValues (like top 5, bottom 3)
+* 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.2",
+  "version": "1.11.0",
   "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,8 @@
 /* eslint-disable implicit-arrow-linebreak */
 
+const Percentile = require('percentile');
+
+const ArrayUtils = require('./array');
 const ObjectUtils = require('./object');
 const FormatUtils = require('./format');
 
@@ -13,6 +16,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 +40,19 @@ 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
+ * * Top Values
+ *   * {@link module:aggregate.topValues|topValues} - top (or bottom) values from a list of objects or literals
  * 
  * Please note, there is nothing special for these functions, such as working with {@link SourceMap#reduce|SourceMap.reduce()}
  * 
@@ -225,6 +243,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 +708,240 @@ 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);
+};
+
+/**
+ * Returns the Top N values from within a collection.
+ * 
+ * For example, if we have a list of weather records,
+ * we can get the month with the greatest rain.
+ * 
+ * **Note: this can also return the Bottom N values, if sorting in ascending order.
+ * ({@link module:array.createSort|see array.createSort() for more.})**
+ * 
+ * ```
+ * collection = [
+ *   { id: 0, month: '2021-Sep', precip: 2.68 },
+ *   { id: 1, month: '2021-Aug', precip: 0.87 },
+ *   { id: 2, month: '2021-Oct', precip: 5.31 },
+ *   { id: 3, month: '2021-Nov', precip: 3.94 },
+ *   { id: 4, month: '2021-Dec', precip: 4.13 },
+ *   { id: 5, month: '2022-Jan', precip: 3.58 },
+ *   { id: 6, month: '2022-Feb', precip: 3.62 },
+ *   { id: 7, month: '2022-Mar', precip: 3.98 },
+ *   { id: 8, month: '2022-Apr', precip: 2.56 }
+ * ];
+ * 
+ * //-- We can get the top 3 months with the highest rainfall
+ * utils.aggregate.topValues(collection, 3, 'month', '-precip');
+ * // '2021-Oct', '2021-Dec', '2022-Mar'
+ * 
+ * //-- Or the 3 most recent precipitation values:
+ * utils.aggregate.topValues(collection, 3, 'precip', '-id');
+ * // 2.56, 3.98, 3.62
+ * 
+ * //-- Lowest Rainfall is simply sorting in ascending order
+ * utils.aggregate.topValues(collection, 5, 'month', 'precip');
+ * // 0.87, 2.56, 2.68, 3.58, 3.62
+ * 
+ * //-- you can also combine values to make the values clearer, by passing a function
+ * const monthPrecip = function (record) => `${record.month} (${record.precip})`;
+ * utils.aggregate.topValues(collection, 3, monthPrecip, '-precip');
+ * // '2021-Oct (5.31)', '2021-Dec (4.13)', '2022-Mar (3.98)'
+ * ```
+ * 
+ * Literal values are also supported
+ * 
+ * ```
+ * collection = [ 2.68, 0.87, 5.31, 3.94, 4.13, 3.58, 3.62, 3.98, 2.56 ];
+ * 
+ * //-- top 5 values
+ * utils.aggregate.topValues(collection, 5);
+ * utils.aggregate.topValues(collection, 5, null, '-')
+ * // [5.31, 4.13, 3.98, 3.94, 3.62]
+ * 
+ * //-- bottom 5 values
+ * utils.aggregate.topValues(collection, 5, null, '');
+ * // 
+ * ```
+ * 
+ * @param {Array} collection - Collection of values we want to get the top values from
+ * @param {Number} [numValues=5] - the number of values to return
+ * @param {string | Function} [fieldOrFn = null] - field of the object to use as the value, <br />
+ *    Or the Function to generate the value, <br />
+ *    Or null if the value is an array of Comparables (like Number)
+ * @param  {...String} sortFields - field in the object to sort by,<br />
+ *    Prefixed by '-' if it should be sorted in Descending order
+ *    (ex: '-Year', 'Manufacturer')
+ * @returns {Array} - array of values
+ */
+module.exports.topValues = function topValues(collection, numValues = 5, fieldOrFn, ...sortFields) {
+  let cleanCollection = collection || [];
+
+  //-- if no sort fields are provided, sort in descending order
+  const cleanSortFields = sortFields.length === 0
+    ? ['-']
+    : sortFields;
+
+  cleanCollection = cleanCollection.sort(
+    ArrayUtils.createSort(...cleanSortFields)
+  );
+
+  return AggregateUtils.property(
+    cleanCollection.slice(0, numValues),
+    fieldOrFn
+  );
+};

package/src/format.js

@@ -12,6 +12,7 @@
  * * 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

package/src/object.js

@@ -22,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
@@ -638,6 +639,40 @@ 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.
  *