jupyter-ijavascript-utils 1.18.0 → 1.19.0

package/DOCS.md

@@ -46,6 +46,7 @@ This is not intended to be the only way to accomplish many of these tasks, and a
 
 ## What's New
 
+* 1.19 - add in {@link module:describe|describe} and {@link module:hashMap|hashMap} modules, along with {@link module:format.limitLines|format.limitLines}
 * 1.18 - tie to vega-datasets avoiding esmodules until ijavascript can support them
 * 1.17 - provide object.propertyValueSample - as a way to list 'non-empty' property values
 * 1.16 - provide file.matchFiles - as a way to find files or directories
@@ -73,9 +74,11 @@ This is not intended to be the only way to accomplish many of these tasks, and a
 | {@link module:array}          | Massage, sort, reshape arrays.                                                                      |
 | {@link module:base64}         | Convert to and from base64 encoding of strings                                                      |
 | {@link module:datasets}       | Load example <a href="https://github.com/vega/vega-datasets">datasets provided by the vega team</a> |
+| {@link module:describe}       | Similar to Pandas describe, provides statistics on a set of values / objects |
 | {@link module:file}           | Read and write data/text to files.                                                                  |
 | {@link module:format}         | Formatting and massage data to be legible.                                                          |
 | {@link module:group}          | Group/Reduce Hierarchies of Object - generating Maps of records ({@link SourceMap})                 |
+| {@link module:hashMap}        | Modify JavaScript HashMaps (ex new Map())             |
 | {@link module:ijs}            | Extend iJavaScript to support await, and new types of rendering - like {@tutorial htmlScript} and markdown|
 | {@link module:latex}          | Render Math Notation with <a href="www.latex-project.org">LaTeX<a> and <a href="katex.org">KaTeX</a>|
 | {@link module:leaflet}        | Render maps with <a href="leaflet.org">Leaflet</a>                                                  |

package/README.md

@@ -46,6 +46,7 @@ This is not intended to be the only way to accomplish many of these tasks, and a
 
 # What's New
 
+* 1.19 - add in describe and hashMap modules, along with format.limitLines
 * 1.18 - tie to vega-datasets avoiding esmodules until ijavascript can support them
 * 1.17 - provide object.propertyValueSample - as a way to list 'non-empty' property values
 * 1.16 - provide file.matchFiles - as a way to find files or directories

package/package.json

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

package/src/TableGenerator.js

@@ -1008,7 +1008,7 @@ class TableGenerator {
     keys = keys.filter((key) => this.#columnsToExclude.indexOf(key) === -1);
 
     //-- identify the formatter to use
-    const cleanFormatter = this.#formatterFn ? this.#formatterFn : ({ value }) => value;
+    const cleanFormatter = this.#formatterFn ? this.#formatterFn : ({ value }) => value === undefined ? '' : value;
 
     const translateHeader = (key) => {
       if (Object.prototype.hasOwnProperty.call(this.#labels, key)) {

package/src/describe.js

@@ -0,0 +1,687 @@
+/* eslint-disable max-classes-per-file, class-methods-use-this */
+
+const FormatUtils = require('./format');
+const ObjectUtils = require('./object');
+
+/**
+ * Module to describe objects or sets of data
+ * 
+ * Describe an array of objects
+ *  * {@link module:describe.describeObjects|describeObjects(collection, options)} - given a list of objects, describes each of the fields
+ * Describe an array of values (assuming all are the same type)
+ *  * {@link module:describe.describeBoolean|describeBoolean(collection, options)} - describes a series of booleans
+ *  * {@link module:describe.describeStrings|describeStrings(collection, options)} - describes a series of strings
+ *  * {@link module:describe.describeNumbers|describeNumbers(collection, options)} - describes a series of numbers
+ *  * {@link module:describe.describeDates|describeDates(collection, options)} - describes a series of dates
+ * 
+ * @module describe
+ * @exports describe
+ */
+module.exports = {};
+const DescribeUtil = module.exports;
+
+/**
+ * @typedef {Object} DescribeOptions
+ * @property {Boolean} uniqueStrings - whether unique strings / frequency should be captured
+ */
+
+/**
+ * Base Description for a series of values
+ * @class
+ */
+class SeriesDescription {
+  /**
+   * Constructor
+   * @param {String} what - description of what is being described
+   * @param {DescribeOptions} options - options for how things are described
+   */
+  constructor(what, type, options) {
+    this.reset();
+    this.what = what;
+    this.type = type;
+    // this.options = options || {};
+  }
+
+  /**
+   * Options used for describing
+   * @type {DescribeOptions}
+   */
+  // options;
+
+  /**
+   * What is being described
+   * @type {String}
+   */
+  what;
+
+  /**
+   * The type of thing being described
+   * @type {String}
+   */
+  type;
+
+  /**
+   * The number of entries reviewed
+   * @type {Number}
+   */
+  count;
+
+  /**
+   * The minimum value found;
+   * @type {any}
+   */
+  min;
+
+  /**
+   * The maximum value found
+   * @type {any}
+   */
+  max;
+
+  /**
+   * Resets the Description to the initial state
+   */
+  reset() {
+    this.count = 0;
+    this.max = null;
+    this.min = null;
+  }
+
+  /**
+   * Validates a value is the type expected
+   * or throws an error if the type is not
+   * or throws false if the value is 'empty'
+   * @param {any} value - value to be checked
+   * @param {String} expectedTypeOf - the type of the value
+   * @returns {Boolean} - true if found and the right type, false if empty
+   * @throws {Error} if the value is the wrong type
+   */
+  check(value, expectedType) {
+    if (FormatUtils.isEmptyValue(value)) {
+      return false;
+    }
+
+    const valueType = typeof value;
+    if (expectedType && valueType !== expectedType) {
+      throw Error(`describe: Value passed(${value}) expected to be:${expectedType}, but was: ${valueType}`);
+    }
+
+    this.count += 1;
+
+    return true;
+  }
+
+  /**
+   * Checks for minimum and maximum values
+   * @param {any} value
+   */
+  checkMinMax(value) {
+    if (this.min === null || value < this.min) {
+      this.min = value;
+    }
+    if (this.max === null || value > this.max) {
+      this.max = value;
+    }
+  }
+
+  /**
+   * Finalizes the review
+   */
+  finalize() { // eslint-disable-line
+    const result = { ...this };
+    // delete result.options;
+    return result;
+  }
+}
+
+/**
+ * Describes a series of Boolean Values
+ * @augments SeriesDescription
+ * @class
+ */
+class BooleanDescription extends SeriesDescription {
+  /**
+   * Mean sum as expressed
+   * @type {number}
+   */
+  mean;
+
+  /**
+   * 
+   * @param {String} what - what is being described
+   * @param {DescribeOptions} options - options used for describing
+   */
+  constructor(what, options) {
+    super(what, 'boolean', options);
+    this.reset();
+  }
+
+  reset() {
+    super.reset();
+    this.mean = 0.0;
+  }
+
+  /**
+   * Whether the value can be described with this
+   * @param {any} value - value to check
+   * @returns {Boolean} - true if the value matches
+   */
+  static matchesType(value) {
+    return FormatUtils.parseBoolean(value);
+  }
+
+  check(value) {
+    if (FormatUtils.isEmptyValue(value)) return;
+
+    this.count += 1;
+    const cleanValue = FormatUtils.parseBoolean(value)
+      ? 1 : 0;
+    
+    const oldMean = this.mean;
+    this.mean += (cleanValue - oldMean) / this.count;
+
+    if (this.max === null && cleanValue === 1) this.max = 1;
+    if (this.min === null && cleanValue === 0) this.min = 0;
+  }
+
+  finalize() {
+    const result = super.finalize();
+    return result;
+  }
+}
+
+/**
+ * Describes a series of Numbers
+ */
+class NumberDescription extends SeriesDescription {
+  /**
+   * Mean sum as expressed
+   * @type {number}
+   */
+  mean;
+
+  /**
+   * M2 - sum of squared deviation
+   */
+  m2;
+
+  /**
+   * Standard deviation of the numbers 
+   */
+  stdDeviation;
+
+  /**
+   * Constructor
+   * @param {String} what - What is being described
+   * @param {DescribeOptions} options -
+   */
+  constructor(what, options) {
+    super(what, 'number', options);
+    this.reset();
+  }
+
+  reset() {
+    super.reset();
+    this.mean = 0.0;
+    this.m2 = 0.0;
+    this.stdDeviation = 0.0;
+  }
+
+  /**
+   * Whether the value can be described with this
+   * @param {any} value - value to check
+   * @returns {Boolean} - true if the value matches
+   */
+  static matchesType(value) {
+    return (typeof value) === 'number';
+  }
+
+  check(value) {
+    if (!super.check(value, 'number')) return;
+    super.checkMinMax(value);
+
+    /*
+    @see Welford's algorithm
+    @see https://stackoverflow.com/a/1348615
+    @see https://lingpipe-blog.com/2009/03/19/computing-sample-mean-variance-online-one-pass/
+    @see https://lingpipe-blog.com/2009/07/07/welford-s-algorithm-delete-online-mean-variance-deviation/
+    @see https://www.calculator.net/standard-deviation-calculator.html
+    */
+    const oldMean = this.mean;
+    this.mean += (value - oldMean) / this.count;
+    this.m2 += (value - oldMean) * (value - this.mean);
+    // console.log(`value:${value}, this.mean:${this.mean}, oldMean:${oldMean}, stdDeviation:${this.stdDeviation}`);
+  }
+
+  finalize() {
+    let newDeviation;
+    if (this.count > 1) {
+      newDeviation = Math.sqrt(this.m2 / this.count);
+    } else {
+      newDeviation = 0.0;
+    }
+    // console.log(`updated m2:${this.m2}, stdDeviation:${this.stdDeviation}, count:${this.count}, newDeviation:${newDeviation}`);
+    this.stdDeviation = newDeviation;
+
+    const result = super.finalize();
+    delete result.m2;
+    return result;
+  }
+}
+
+/**
+ * Describes a series of string values
+ */
+class StringDescription extends SeriesDescription {
+  /**
+   * Map of unique values
+   * @type {Map<String,Number>}
+   */
+  uniqueMap;
+
+  /**
+   * Number of unique values;
+   * @type {Number}
+   */
+  unique;
+
+  /**
+   * The most common string
+   * @type {String}
+   */
+  top;
+
+  /**
+   * The frequency of the most common string
+   * @type {Number}
+   */
+  topFrequency;
+
+  /**
+   * Constructor
+   * @param {String} what - What is being described
+   * @param {DescribeOptions} options -
+   */
+  constructor(what, options) {
+    super(what, 'string', options);
+    this.uniqueMap = null;
+    this.reset();
+  }
+
+  reset() {
+    super.reset();
+    this.uniqueMap = new Map();
+    this.unique = null;
+    this.top = null;
+    this.topFrequency = null;
+  }
+
+  /**
+   * Whether the value can be described with this
+   * @param {any} value - value to check
+   * @returns {Boolean} - true if the value matches
+   */
+  static matchesType(value) {
+    return (typeof value) === 'string';
+  }
+
+  check(value) {
+    if (!super.check(value, 'string')) return;
+
+    if (this.uniqueMap.has(value)) {
+      this.uniqueMap.set(value, this.uniqueMap.get(value) + 1);
+      return;
+    }
+
+    this.uniqueMap.set(value, 1);
+    
+    const len = value.length;
+    if (this.min === null || len < this.min.length) this.min = value;
+    if (this.max === null || len > this.max.length) this.max = value;
+    // console.log(`len:${len}, min:${this.min}, max:${this.max}`);
+  }
+
+  finalize() {
+    super.finalize();
+
+    let currentTop = null;
+    let currentTopFrequency = null;
+    for (const [key, count] of this.uniqueMap.entries()) {
+      if (currentTopFrequency == null || count > currentTopFrequency) {
+        currentTop = key;
+        currentTopFrequency = count;
+      }
+    }
+    this.top = currentTop;
+    this.topFrequency = currentTopFrequency;
+    this.unique = this.uniqueMap.size;
+
+    this.uniqueMap = null;
+
+    const result = super.finalize();
+    delete result.uniqueMap;
+    return result;
+  }
+}
+
+/**
+ * Describes a series of Dates
+ */
+class DateDescription extends SeriesDescription {
+  /**
+   * Mean sum as expressed
+   * @type {number}
+   */
+  mean;
+
+  /**
+   * Constructor
+   * @param {String} what - What is being described
+   * @param {DescribeOptions} options -
+   */
+  constructor(what, options) {
+    super(what, 'Date', options);
+    this.reset();
+  }
+
+  reset() {
+    super.reset();
+    this.mean = null;
+  }
+
+  /**
+   * Whether the value can be described with this
+   * @param {any} value - value to check
+   * @returns {Boolean} - true if the value matches
+   */
+  static matchesType(value) {
+    return (value instanceof Date); // || (typeof value) === 'number';
+  }
+
+  check(value) {
+    if (FormatUtils.isEmptyValue(value)) return;
+
+    let cleanValue;
+    if (value instanceof Date) {
+      cleanValue = value.getTime();
+    } else if (typeof value === 'number') {
+      cleanValue = value;
+    } else {
+      throw Error(`describe: Value passed(${value}) - expected to be type:Date`);
+    }
+
+    this.count += 1;
+    
+    const oldMean = this.mean;
+    this.mean += (cleanValue - oldMean) / this.count;
+
+    super.checkMinMax(cleanValue);
+  }
+
+  finalize() {
+    if (!FormatUtils.isEmptyValue(this.min)) this.min = new Date(this.min);
+    if (!FormatUtils.isEmptyValue(this.max)) this.max = new Date(this.max);
+    if (!FormatUtils.isEmptyValue(this.mean)) this.mean = new Date(this.mean);
+
+    const result = super.finalize();
+    return result;
+  }
+}
+
+/**
+ * Describes a collection of objects.
+ * 
+ * For example, given the following collection:
+ * 
+ * ```
+ *  collection = [{
+ *      first: 'john',
+ *      last: 'doe',
+ *      age: 23,
+ *      enrolled: new Date('2022-01-01')
+ *    }, {
+ *      first: 'john',
+ *      last: 'doe',
+ *      age: 24,
+ *      enrolled: new Date('2022-01-03')
+ *    }, {
+ *      first: 'jan',
+ *      last: 'doe',
+ *      age: 25,
+ *      enrolled: new Date('2022-01-05')
+ *    }];
+ *  ```
+ * 
+ * Running `utils.describe.describeObjects(collection);` gives:
+ * 
+ *  ```
+ *  [{
+ *      "count": 3,
+ *      "max": "john",
+ *      "min": "jan",
+ *      "top": "john",
+ *      "topFrequency": 2,
+ *      "type": "string",
+ *      "unique": 2,
+ *      "what": "first"
+ *    }, {
+ *      "count": 3,
+ *      "max": "doe",
+ *      "min": "doe",
+ *      "top": "doe",
+ *      "topFrequency": 3,
+ *      "type": "string",
+ *      "unique": 1,
+ *      "what": "last"
+ *    }, {
+ *      "count": 3,
+ *      "max": 25,
+ *      "min": 23,
+ *      "mean": 24,
+ *      "stdDeviation": 0.816496580927726,
+ *      "type": "number",
+ *      "what": "age"
+ *    }, {
+ *      "count": 3,
+ *      "max": "2022-01-05T00:00:00.000Z",
+ *      "min": "2022-01-01T00:00:00.000Z",
+ *      "mean": "2022-01-03T00:00:00.000Z",
+ *      "type": "Date",
+ *      "what": "enrolled"
+ *  }]
+ *  ```
+ *
+ *  Or Rendered to a table: `utils.table(results).render()`:
+ *
+ *  what    |type  |count|max                     |min                     |mean                    |top |topFrequency|unique
+ *  --      |--    |--   |--                      |--                      |--                      |--  |--          |--    
+ *  first   |string|3    |john                    |jan                     |                        |john|2           |2     
+ *  last    |string|3    |doe                     |doe                     |                        |doe |3           |1     
+ *  age     |number|3    |25                      |23                      |24                      |    |            |      
+ *  enrolled|Date  |3    |2022-01-05T00:00:00.000Z|2022-01-01T00:00:00.000Z|2022-01-03T00:00:00.000Z|    |            |         
+ *  
+ * @param {Object[]} collection - Collection of objects to be described
+ * @param {Object} options - options to be used
+ * @param {String[]} options.include - string list of fields to include in the description
+ * @param {String[]} options.exclude - string list of fields to exclude in the description
+ * @param {Object} options.overridePropertyType - object with property:type values (string|number|date|boolean)
+ *      - that will override how that property is parsed.
+ * @param {Number} maxRows - max rows to consider before halting
+ * @returns {SeriesDescription[]} - collection of descriptions - one for each property
+ */
+module.exports.describeObjects = function describeObjects(collection, options) {
+  const cleanCollection = Array.isArray(collection) ? collection : [collection];
+
+  const cleanOptions = options ? options : {};
+
+  cleanOptions.include = cleanOptions.include ? new Set(cleanOptions.include) : null;
+  cleanOptions.exclude = new Set(cleanOptions.exclude || []);
+  cleanOptions.maxRows = cleanOptions.maxRows || -1;
+
+  // cleanOptions.prepareFn = typeof cleanOptions.prepareFn === 'function'
+  //   ? cleanOptions.prepareFn
+  //   : (val) => val;
+
+  const results = new Map();
+  if (cleanOptions.overridePropertyType) {
+    ObjectUtils.keys(cleanOptions.overridePropertyType)
+      .forEach((key) => {
+        const keyValue = cleanOptions.overridePropertyType[key];
+        if (keyValue === 'string') {
+          results.set(key, new StringDescription(key, cleanOptions));
+        } else if (keyValue === 'number') {
+          results.set(key, new NumberDescription(key, cleanOptions));
+        } else if (keyValue === 'date') {
+          results.set(key, new DateDescription(key, cleanOptions));
+        } else if (keyValue === 'boolean' || keyValue === 'bool') {
+          results.set(key, new StringDescription(key, cleanOptions));
+        }
+      });
+  }
+  let val;
+  // let describer;
+
+  cleanCollection.every((obj, index) => {
+    if (cleanOptions.maxRows > 0 && index >= cleanOptions.maxRows) {
+      return false;
+    }
+    //-- handles null objects
+    // obj = cleanOptions.prepareFn(obj);
+    ObjectUtils.keys(obj)
+      .forEach((key) => {
+        val = obj[key];
+        
+        if (cleanOptions.include && !cleanOptions.include.has(key)) {
+          //-- ignore
+        } else if (cleanOptions.exclude.has(key)) {
+          //-- ignore
+        } else if (FormatUtils.isEmptyValue(val)) {
+          //-- do nothing
+        } else {
+          if (Object.prototype.hasOwnProperty.call(results, key)) {
+            //-- describer already found
+          } else if (StringDescription.matchesType(val)) {
+            results[key] = new StringDescription(key);
+          } else if (DateDescription.matchesType(val)) {
+            results[key] = new DateDescription(key);
+          } else if (NumberDescription.matchesType(val)) {
+            results[key] = new NumberDescription(key);
+          } else if (BooleanDescription.matchesType(val)) {
+            results[key] = new BooleanDescription(key);
+          } else {
+            //-- ignore?
+            results[key] = new SeriesDescription(key, typeof val);
+          }
+          results[key].check(val);
+        }
+      });
+    return true;
+  });
+
+  const resultArray = ObjectUtils.keys(results)
+    .map((key) => results[key].finalize());
+  
+  return resultArray;
+};
+
+/**
+ * Describes a series of numbers
+ * @param {String[]} collection - collection of string values to describe
+ * @param {Object} options - options for describing strings
+ * @returns {StringDescription} - Description of the list of strings
+ */
+module.exports.describeStrings = function describeStrings(collection, options) {
+  const cleanCollection = Array.isArray(collection) ? collection : [collection];
+  
+  const result = new StringDescription(null, options);
+  cleanCollection.forEach((value) => result.check(value));
+  return result.finalize();
+};
+
+/**
+ * Describes a series of numbers
+ * @param {Number[]} collection - Array of numbers
+ * @param {Object} options - options for describing numbers
+ * @returns {NumberDescription}
+ */
+module.exports.describeNumbers = function describeNumbers(collection, options) {
+  const cleanCollection = Array.isArray(collection) ? collection : [collection];
+  
+  const result = new NumberDescription(null, options);
+  cleanCollection.forEach((value) => result.check(value));
+  return result.finalize();
+};
+
+/**
+ * Describes a series of boolean values.
+ * 
+ * Note, that the following are considered TRUE:
+ * 
+ * * Boolean true
+ * * Number 1
+ * * String TRUE
+ * * String True
+ * * String true
+ * 
+ * @param {Boolean[] | String[] | Number[]} collection - Array of Boolean Values
+ * @param {Object} options - options for describing boolean values
+ * @returns {BooleanDescription}
+ * @see {@link module:format.parseBooleanValue}
+ */
+module.exports.describeBoolean = function describeBoolean(collection, options) {
+  const cleanCollection = Array.isArray(collection) ? collection : [collection];
+
+  const result = new BooleanDescription(null, options);
+  cleanCollection.forEach((value) => result.check(value));
+  return result.finalize();
+};
+
+/**
+ * Describes a series of Date / Epoch Numbers
+ * 
+ * @param {Date[] | Number[]} collection - Array of Dates / Epoch Numbers
+ * @param {Object} options - options for describing dates
+ * @returns {DateDescription}
+ */
+module.exports.describeDates = function describeDates(collection, options) {
+  const cleanCollection = Array.isArray(collection) ? collection : [collection];
+
+  const result = new DateDescription(null, options);
+  cleanCollection.forEach((value) => result.check(value));
+  return result.finalize();
+};
+
+//-- Testing Internal items
+
+/**
+ * Sanity check for standard deviation
+ * @param {Number[]} series - collection of numbers
+ * @returns {Number} - standard deviation of the numbers
+ * @private
+ */
+DescribeUtil.stdDeviation = function stdDeviation(series) {
+  let avg = 0;
+
+  if (series.length < 2) return 0.0;
+
+  const sum = series.reduce((result, val) => result + val, 0);
+  avg = sum / series.length;
+
+  const s1 = series.reduce((result, val) => result + ((val - avg) ** 2), 0);
+  // console.log(`s1:${s1}`);
+  const s2 = Math.sqrt(s1 / series.length);
+
+  return s2;
+};
+
+/**
+ * Number Description - used for testing
+ * @private
+ */
+DescribeUtil.NumberDescription = NumberDescription;
+
+/**
+ * String Description - used for testing
+ * @private
+ */
+DescribeUtil.StringDescription = StringDescription;

package/src/format.js

@@ -15,6 +15,8 @@
  *   * {@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'
+ *   * {@link module:format.limitLines|format.limitLines(string, toLine, fromLine, lineSeparator)} - selects only a subset of lines in a string
+ *   * {@link module:format.consoleLines|format.consoleLines(...)} - same as limit lines, only console.logs the string out.
  * * Formatting Time
  *   * {@link module:format.millisecondDuration|format.millisecondDuration}
  * * Mapping Values
@@ -844,3 +846,78 @@ module.exports.isEmptyValue = (val) =>
   //-- allow for 0s
   val === null || val === undefined || val === ''
   || (Array.isArray(val) && val.length === 0);
+
+/**
+ * Determines if a value is a boolean true value.
+ * 
+ * Matches for:
+ * 
+ * * boolean TRUE
+ * * number 1
+ * * string 'TRUE'
+ * * string 'True'
+ * * string 'true'
+ * 
+ * @param {any} val - the value to be tested
+ * @returns {Boolean} - TRUE if the value matches
+ */
+module.exports.parseBoolean = function parseBoolean(val) {
+  return val === true
+    || val === 1
+    || val === 'TRUE'
+    || val === 'True'
+    || val === 'true';
+};
+
+/**
+ * Narrows to only fromLine - toLine (inclusive) within a string.
+ * 
+ * @see {@link module:format.consoleLines|format.consoleLines()} - to console the values out
+ * @param {String|Object} str - string to be limited, or object to be json.stringify-ied
+ * @param {Number} toLine 
+ * @param {Number} [fromLine=0] - starting line number (starts at 0)
+ * @param {String} [lineSeparator='\n'] - separator for lines
+ * @returns {String}
+ * @example
+ * str = '1\n2\n\3';
+ * utils.format.limitLines(str, 2); // '1\n2'
+ * 
+ * str = '1\n2\n3';
+ * utils.format.limitLines(str, 3, 2); // '2\n3'
+ * 
+ * str = '1\n2\n3';
+ * utils.format.limitLines(str, undefined, 2); // '2\n3'
+ */
+module.exports.limitLines = function limitLines(str, toLine, fromLine, lineSeparator) {
+  const cleanStr = typeof str === 'string'
+    ? str
+    : JSON.stringify(str || '', FormatUtils.mapReplacer, 2);
+  const cleanLine = lineSeparator || '\n';
+
+  return cleanStr.split(cleanLine)
+    .slice(fromLine || 0, toLine)
+    .join(cleanLine);
+};
+
+/**
+ * Same as {@link module:format.limitLines|limitLines()} - only prints to the console.
+ * 
+ * @see {@link module:format.limitLines|format.limitLines}
+ * @param {String|Object} str - string to be limited, or object to be json.stringify-ied
+ * @param {Number} toLine 
+ * @param {Number} [fromLine=0] - starting line number (starts at 0)
+ * @param {String} [lineSeparator='\n'] - separator for lines
+ * @returns {String}
+ * @example
+ * str = '1\n2\n\3';
+ * utils.format.limitLines(str, 2); // '1\n2'
+ * 
+ * str = '1\n2\n3';
+ * utils.format.limitLines(str, 3, 2); // '2\n3'
+ * 
+ * str = '1\n2\n3';
+ * utils.format.limitLines(str, undefined, 2); // '2\n3'
+ */
+module.exports.consoleLines = function consoleLines(str, toLine, fromLine, lineSeparator) {
+  console.log(FormatUtils.limitLines(str, toLine, fromLine, lineSeparator));
+};

package/src/hashMap.js

@@ -0,0 +1,218 @@
+const FormatUtils = require('./format');
+
+/**
+ * Library for working with JavaScript hashmaps.
+ * 
+ * * Modifying
+ *   * {@link module:hashMap.add|hashMap.add(map, key, value):Map} - Add a value to a map and return the Map
+ *   * {@link module:hashMap.union|hashMap.union(targetMap, additionalMap, canOverwrite)} - merges two maps and ignores or overwrites with conflicts
+ * * Cloning
+ *   * {@link module:hashMap.clone|hashMap.clone(map):Map} - Clones a given Map
+ * * Conversion
+ *   * {@link module:hashMap.stringify|hashMap.stringify(map, indent)} - converts a Map to a string representation
+ *   * {@link module:hashMap.toObject|hashMap.toObject(map)} - converts a hashMap to an Object
+ *   * {@link module:hashMap.fromObject|hashMap.fromObject(object)} - converts an object's properties to hashMap keys
+ * 
+ * Note: JavaScript Maps can sometimes be faster than using Objects,
+ * and sometimes slower.
+ * 
+ * (Current understanding is that Maps do better with more updates made)
+ * 
+ * There are many searches such as `javascript map vs object performance`
+ * with many interesting links to come across.
+ * 
+ * @module hashMap
+ * @exports hashMap
+ */
+module.exports = {};
+const HashMapUtil = module.exports;
+
+/**
+ * Set a Map in a functional manner (adding a value and returning the map)
+ * @param {Map} map - the map to be updated
+ * @param {any} key -
+ * @param {any} value -
+ * @returns {Map} - the updated map value
+ * @example
+ * const objectToMap = { key1: 1, key2: 2, key3: 3 };
+ * const keys = [...Object.keys(objectToMap)];
+ * // ['key1', 'key2', 'key3'];
+ * 
+ * const result = keys.reduce(
+ *  (result, key) => utils.hashMap.add(result, key, objectToMap[key]),
+ *  new Map()
+ * );
+ * // Map([[ 'key1',1 ], ['key2', 2], ['key3', 3]]);
+ */
+module.exports.add = function add(map, key, value) {
+  map.set(key, value);
+  return map;
+};
+
+/**
+ * Clones a Map
+ * @param {Map} target - Map to clone
+ * @returns {Map} - clone of the target map
+ * @example
+ * const sourceMap = new Map();
+ * sourceMap.set('first', 1);
+ * const mapClone = utils.hashMap.clone(sourceMap);
+ * mapClone.has('first'); // true
+ */
+module.exports.clone = function clone(target) {
+  if (!(target instanceof Map)) {
+    throw Error('hashMap.clone(targetMap): targetMap must be a Map');
+  }
+  return new Map(target.entries());
+};
+
+/**
+ * Creates a new map that includes all entries of targetMap, and all entries of additionalMap.
+ * 
+ * If allowOverwrite is true, then values found in additionalMap will take priority in case of conflicts.
+ * 
+ * ```
+ * const targetMap = new Map([['first', 'John'], ['amount': 100]]);
+ * const additionalMap = new Map([['last': 'Doe'], ['amount': 200]]);
+ * 
+ * utils.hashMap.union(targetMap, additionalMap, true);
+ * // Map([['first', 'John'], ['last', 'Doe'], ['amount', 200]]);
+ * ```
+ * 
+ * If allowOverwrite is false, then values found in targetMap will take priority in case of conflicts.
+ * 
+ * ```
+ * const targetMap = new Map([['first', 'John'], ['amount': 100]]);
+ * const additionalMap = new Map([['last': 'Doe'], ['amount': 200]]);
+ * 
+ * utils.hashMap.union(targetMap, additionalMap);
+ * utils.hashMap.union(targetMap, additionalMap, false);
+ * // Map([['first', 'John'], ['last', 'Doe'], ['amount', 100]]);
+ * ```
+ * 
+ * @param {Map} targetMap 
+ * @param {Map} additionalMap - 
+ * @param {Boolean} [allowOverwrite=false] - whether targetMap is prioritized (false) or additional prioritized (true)
+ * @returns {Map}
+ */
+module.exports.union = function union(targetMap, additionalMap, allowOverwrite) {
+  if (!(targetMap instanceof Map)) {
+    return HashMapUtil.clone(additionalMap);
+  }
+
+  const result = new Map(targetMap.entries());
+
+  if (!(additionalMap instanceof Map)) {
+    return result;
+  }
+
+  for (const key of additionalMap.keys()) {
+    if (!result.has(key) || allowOverwrite) {
+      result.set(key, additionalMap.get(key));
+    }
+  }
+  return result;
+};
+
+/**
+ * Serializes a hashMap (plain javascript Map) to a string
+ * 
+ * ```
+ * const target = new Map([['first', 1], ['second', 2]]);
+ * HashMapUtil.stringify(target);
+ * // '{"dataType":"Map","value":[["first",1],["second",2]]}'
+ * ```
+ * 
+ * Note, that passing indent will make the results much more legible.
+ * 
+ * ```
+ * {
+ *   "dataType": "Map",
+ *   "value": [
+ *     [
+ *       "first",
+ *       1
+ *     ],
+ *     [
+ *       "second",
+ *       2
+ *     ]
+ *   ]
+ * }
+ * ```
+ * @param {Map} target - the Map to be serialized
+ * @param {Number} indentation - the indentation passed to JSON.serialize
+ * @returns {String} - JSON.stringify string for the map
+ */
+module.exports.stringify = function stringify(map, indentation) {
+  return JSON.stringify(map, FormatUtils.mapReplacer, indentation);
+};
+
+/**
+ * Converts a map to an object
+ * 
+ * For example, say we have a Map:
+ * 
+ * ```
+ * const targetMap = new Map([['first', 1], ['second', 2], ['third', 3]]);
+ * ```
+ * 
+ * We can convert it to an Object as follows:
+ * 
+ * ```
+ * const targetMap = utils.hashMap.toObject(targetObject)
+ * // { first: 1, second: 2, third: 3 };
+ * ```
+ * 
+ * @param {Map} target - map to be converted
+ * @returns {Object} - object with the properties as the target map's keys.
+ * @see {@link hashMap.fromObject} - to reverse the process
+ */
+module.exports.toObject = function toObject(target) {
+  const results = {};
+
+  if (!target) { // eslint-disable-line no-empty
+  } else if (!(target instanceof Map)) {
+    throw Error('hashMap.toObject(map): must be passed a Map');
+  } else {
+    [...target.keys()]
+      .forEach((key) => {
+        results[key] = target.get(key);
+      });
+  }
+
+  return results;
+};
+
+/**
+ * Creates a Map from the properties of an Object
+ * 
+ * For example, say we have an object:
+ * 
+ * ```
+ * const targetObject = { first: 1, second: 2, third: 3 };
+ * ```
+ * 
+ * We can convert it to a Map as follows:
+ * 
+ * ```
+ * const targetMap = utils.hashMap.fromObject(targetObject)
+ * // new Map([['first', 1], ['second', 2], ['third', 3]]);
+ * ```
+ * 
+ * @param {Object} target - target object with properties that should be considered keys
+ * @returns {Map<String,any>} - converted properties as keys in a new map
+ * @see {@link hashMap.toObject} - to reverse the process
+ */
+module.exports.fromObject = function fromObject(target) {
+  if (!(typeof target === 'object')) {
+    throw Error('hashMap.fromObject(object): must be passed an object');
+  }
+
+  if (target.dataType === 'Map' && Array.isArray(target.value)) {
+    return new Map(target.value);
+  }
+
+  return [...Object.keys(target)]
+    .reduce((result, key) => HashMapUtil.add(result, key, target[key]), new Map());
+};

package/src/index.js

@@ -2,7 +2,9 @@ const aggregate = require('./aggregate');
 const array = require('./array');
 const base64 = require('./base64');
 const datasets = require('./datasets');
+const describe = require('./describe');
 const group = require('./group');
+const hashMap = require('./hashMap');
 const ijsUtils = require('./ijs');
 const file = require('./file');
 const vega = require('./vega');
@@ -29,39 +31,43 @@ const table = function table(...rest) {
  * @private
  */
 module.exports = {
-  /** @see module:aggregate */
+  /** @see {@link module:aggregate} */
   aggregate,
   agg: aggregate,
-  /** @see module:array */
+  /** @see {@link module:array} */
   array,
-  /** @see module:base64 */
+  /** @see {@link module:base64} */
   base64,
-  /** @see module:datasets */
+  /** @see {@link module:datasets} */
   datasets,
   dataset: datasets,
-  /** @see module:file */
+  /** @see {@link module:describe} */
+  describe,
+  /** @see {@link module:file} */
   file,
-  /** @see module:group */
+  /** @see {@link module:group} */
   group,
-  /** @see module:format */
+  /** @see {@link module:hashMap} */
+  hashMap,
+  /** @see {@link module:format} */
   format,
-  /** @see IJSUtils */
+  /** @see {@link IJSUtils} */
   ijs: ijsUtils,
-  /** @see module:latex */
+  /** @see {@link module:latex} */
   latex,
-  /** @see module:leaflet */
+  /** @see {@link module:leaflet} */
   leaflet,
-  /** @see module:object */
+  /** @see {@link module:object} */
   object,
   /** @see {@link module:plantuml} */
   plantuml,
-  /** @see module:random */
+  /** @see {@link module:random} */
   random,
-  /** @see module:set */
+  /** @see {@link module:set} */
   set,
-  /** @see module:svg */
+  /** @see {@link module:svg} */
   svg,
-  /** @see module:vega */
+  /** @see {@link module:vega} */
   vega,
 
   /** @see SourceMap */