jupyter-ijavascript-utils 1.45.0 → 1.47.0

package/DOCS.md

@@ -74,7 +74,11 @@ Give it a try here:
 [![Binder:what can I do with this](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/paulroth3d/jupyter-ijavascript-utils/main?labpath=example.ipynb)
 
 ## What's New
-
+* 1.47 - Correct table rendering html if filter was used ({@link https://github.com/paulroth3d/jupyter-ijavascript-utils/issues/64|#64})
+  * allow conversion from a Collection of Objects to Arrays and back with object. ({@link module:object.objectCollectionFromArray|object.objectCollectionFromArray}, {@link module:object.objectCollectionToArray|object.objectCollectionToArray})
+  * Easier iterating over values and peeking with array with {@link module:array~PeekableArrayIterator|PeekableArrayIterator}
+  * Support for delayed and asynchronous chaining of functions ({@link module:array.delayedFn|delayedFn}, {@link module:array.chainFunctions|chainFunctions}, etc)
+* 1.46 - Make it easier to extract data from "hard-spaced arrays" - {@link module:array.multiLineSubstr}, {@link module:array.multiStepReduce}
 * 1.45 - more ways to understand the data - {@link module:aggregate.coalesce|aggregate.coalesce()}, convert properties to arrow/dot notation / reverse it {@link module:object.flatten|object.flatten()} / {@link module:object.expand|object.expand()} and {@link module:object.isObject|object.isObject()}
 * 1.43 - esm module fix since still not supported yet in ijavascript
 * 1.41 - {@link module:object.propertyInherit|object.propertyInherit} - to simplify inheriting values from one record to the next

package/Dockerfile

@@ -1,3 +1,3 @@
 # syntax=docker/dockerfile:1
 
-FROM darkbluestudios/jupyter-ijavascript-utils:binder_1.45.0
+FROM darkbluestudios/jupyter-ijavascript-utils:binder_1.47.0

package/README.md

@@ -54,6 +54,11 @@ This is not intended to be the only way to accomplish many of these tasks, and a
 ![Screenshot of example notebook](docResources/img/mainExampleNotebook.png)
 
 # What's New
+* 1.47 - Correct table rendering html if filter was used (#46)
+  * allow conversion from a Collection of Objects to Arrays and back with object. (objectCollectionFromArray, objectCollectionToArray)
+  * Easier iterating over values and peeking with array with PeekableArrayIterator
+  * Support for delayed and asynchronous chaining of functions (array.delayedFn, chainFunction, etc)
+* 1.46 - Make it easier to extract data from "hard-spaced arrays" - (array.multiLineSubstr, array.multiStepReduce)
 * 1.45 - more ways to understand the data - aggregate.coalesce(), convert properties to arrow/dot notation / reverse it : object.flatten() / object.expand() and Object.isObject()
 * 1.43 - esm module fix since still not supported yet in ijavascript
 * 1.41 - object.propertyInherit - to simplify inheriting values from one record to the next

package/package.json

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

package/src/TableGenerator.js

@@ -337,8 +337,6 @@ class TableGenerator {
     this.#isTransposed = false;
   }
 
-  //--    GETTER SETTERS
-
   /**
    * Assigns the data to be used in generating the table.
    * @param {Array} collection -
@@ -365,6 +363,182 @@ class TableGenerator {
     return this;
   }
 
+  /**
+   * Assigns the data by importing in a collections of objects.
+   * 
+   * Note: this is the default functionality / syntatic sugar - as data is expected as a collection of objects.
+   * @param {Object[]} collection -
+   * @returns {TableGenerator} 
+   * @example
+   * 
+   * dataSet = [{temp: 37, type: 'C'}, {temp: 310, type: 'K'}, {temp: 98, type: 'F'}];
+   * 
+   * //-- simple example where the temp property is converted, and type property overwritten
+   * new TableGenerator()
+   *  .data(dataSet)
+   *  .generateMarkdown()
+   * 
+   * //-- gives
+   * temp | type
+   * ---- | ----
+   * 37   | C   
+   * 310  | K   
+   * 98   | F   
+   */
+  fromObjectCollection(data) {
+    this.data(data);
+    return this;
+  }
+
+  /**
+   * Assigns the data by importing a 2 dimensional array.
+   * 
+   * If headers are not provided, then the first row of the collection is assumed.
+   * 
+   * If there is no header provided (by default) - then the first row is assumed.
+   * 
+   * ```
+   * dataSet = [ [ 'temp', 'type' ], [ 37, 'C' ], [ 310, 'K' ], [ 98, 'F' ] ];
+   * 
+   * new TableGenerator()
+   *  .fromArray(dataSet)
+   *  .generateMarkdown();
+   * ```
+   * 
+   * temp | type
+   * ---- | ----
+   * 37   | C   
+   * 310  | K   
+   * 98   | F   
+   * 
+   * However, if there is a header provided, it assumes there is none in teh first row.
+   * 
+   * ```
+   * headers = [ 'temp', 'type' ];
+   * dataSet = [[ 37, 'C' ], [ 310, 'K' ], [ 98, 'F' ] ];
+   * 
+   * new TableGenerator()
+   *  .fromArray(dataSet)
+   *  .generateMarkdown();
+   * ```
+   * 
+   * temp | type
+   * ---- | ----
+   * 37   | C   
+   * 310  | K   
+   * 98   | F   
+   * 
+   * @param {Array<Array>} collection -
+   * @returns {TableGenerator}
+   * @see {TableGenerator.data}
+   * @see {TableGenerator.fromList}
+   */
+  fromArray(arrayCollection, headers = null) {
+    if (!arrayCollection) {
+      this.data(null);
+      return this;
+    }
+    this.data(ObjectUtils.objectCollectionFromArray(arrayCollection, headers));
+
+    return this;
+  }
+
+  /**
+   * Assigns the data from a single 1 dimensional array.
+   * 
+   * Is syntatic sugar to simply wrap the 1 dimensional array into a 2 dimensional array.
+   * 
+   * ```
+   * let precip = [
+   *   1, 0, 2, 3, 4
+   * ];
+   * 
+   * utils.table().fromList(precip).render()
+   * ```
+   * 
+   * _   
+   * --  
+   * 1
+   * 0
+   * 2
+   * 3
+   * 4
+   * 
+   * @param {Array} array1d 
+   * @returns {TableGenerator}
+   * @see {TableGenerator.fromArray}
+  */
+  fromList(array1d) {
+    if (!array1d) {
+      this.data(null);
+      return this;
+    }
+    this.data(array1d.map((v) => ({ _: v })));
+    return this;
+  }
+
+  /**
+   * Initializes the data in the tableGenerator with an object holding
+   * 1d tensor properties.
+   * 
+   * ```
+   * dfObject = {
+   *   id: [
+   *     1, 0, 2, 3, 4,
+   *     5, 6, 8, 7
+   *   ],
+   *   city: [
+   *     'Seattle',  'Seattle',
+   *     'Seattle',  'New York',
+   *     'New York', 'New York',
+   *     'Chicago',  'Chicago',
+   *     'Chicago'
+   *   ],
+   *   month: [
+   *     'Aug', 'Apr',
+   *     'Dec', 'Apr',
+   *     'Aug', 'Dec',
+   *     'Apr', 'Dec',
+   *     'Aug'
+   *   ],
+   *   precip: [
+   *     0.87, 2.68, 5.31,
+   *     3.94, 4.13, 3.58,
+   *     3.62, 2.56, 3.98
+   *   ]
+   * }
+   * 
+   * utils.table().fromDataFrameObject(dfObject).render()
+   * ```
+   * 
+   * id|city    |month|precip
+   * --|--      |--   |--    
+   * 1 |Seattle |Aug  |0.87  
+   * 0 |Seattle |Apr  |2.68  
+   * 2 |Seattle |Dec  |5.31  
+   * 3 |New York|Apr  |3.94  
+   * 4 |New York|Aug  |4.13  
+   * 5 |New York|Dec  |3.58  
+   * 6 |Chicago |Apr  |3.62  
+   * 8 |Chicago |Dec  |2.56  
+   * 7 |Chicago |Aug  |3.98 
+   * 
+   * @param {Object} dataFrameObject - DataFrame with 1d tensor properties
+   * @returns {TableGenerator}
+   * @see https://danfo.jsdata.org/api-reference/dataframe/creating-a-dataframe#creating-a-dataframe-from-an-object
+   * @see {TableGenerator.fromList}
+   * @see {TableGenerator.fromObjectCollection}
+   * @see {TableGenerator.data}
+   */
+  fromDataFrameObject(dataFrameObject) {
+    if (!dataFrameObject) {
+      this.data(null);
+      return this;
+    }
+    this.data(ObjectUtils.objectCollectionFromDataFrameObject(dataFrameObject));
+    return this;
+  }
+
   /**
    * Augments data with additional fields
    * 
@@ -1276,7 +1450,12 @@ class TableGenerator {
 
     const printBody = (collection) => collection
       .map((dataRow, rowIndex) => {
-        const record = this.#data[rowIndex];
+        let record;
+        if (this.#filterFn) {
+          record = results.headers.reduce((result, header, headerIndex) => ObjectUtils.assign(result, header, dataRow[headerIndex]), {});
+        } else {
+          record = this.#data[rowIndex];
+        }
         const rowStyle = !styleRowFn ? null : styleRowFn({ rowIndex, row: dataRow, record }) || '';
 
         return `<tr ${printInlineCSS(rowStyle)}>\n\t`
@@ -1507,7 +1686,26 @@ class TableGenerator {
    */
   generateArray2() {
     const results = this.prepare();
-    return [[...results.headers], ...results.data];
+    return [results.headers, ...results.data];
+  }
+
+  generateObjectCollection() {
+    return ObjectUtils.objectCollectionFromArray(this.generateArray2());
+  }
+
+  generateDataFrameObject() {
+    const prepResults = this.prepare();
+    const results = {};
+    const createFrameList = () => new Array(prepResults.data.length).fill(undefined);
+    prepResults.headers.forEach((header) => ObjectUtils.assign(results, header, createFrameList()));
+
+    prepResults.data.forEach((row, rowIndex) => {
+      row.forEach((value, valIndex) => {
+        results[prepResults.headers[valIndex]][rowIndex] = value;
+      });
+    });
+
+    return results;
   }
 
   static hasRenderedCSS = false;

package/src/array.js

@@ -27,12 +27,26 @@ require('./_types/global');
  *   * {@link module:array.pickRows|array.pickRows} - picks a row from a 2d array
  *   * {@link module:array.pickColumns|array.pickColumns} - picks a column from a 2d array
  *   * {@link module:array.pick|array.pick} - picks either/or rows and columns
+ * * Extracting Array Values
  *   * {@link module:array.extract|array.extract} - synonym to array.pick to pick either a row or column from an array
+ *   * {@link module:array.multiLineSubstr|array.multiLineSubstr} - Extract
+ *        {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substr|Substr}
+ *        from a multi-line string or array of strings
+ *   * {@link module:array.multiLineSubstring|array.multiLineSubstring} - Extract 
+ *        {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substring|Substring}
+ *        from a multi-line string or array of strings
+ *   * {@link module:array.multiStepReduce|array.multiStepReduce} - Performs reduce, and returns the value of reduce at each step
  * * Applying a value
  *   * {@link module:array.applyArrayValue|array.applyArrayValue} - applies a value deeply into an array safely
  *   * {@link module:array.applyArrayValues|array.applyArrayValues} - applies a value / multiple values deeply into an array safely
  * * Understanding Values
  *   * {@link module:array.isMultiDimensional|array.isMultiDimensional} - determines if an array is multi-dimensional
+ * * Custom Iterators
+ *   * {@link module:array~PeekableArrayIterator|PeekableArrayIterator} - Iterator that lets you peek ahead while not moving the iterator.
+ * * Iterating over values
+ *   * {@link module:array.delayedFn|delayedFn} - Similar to Function.bind() - you specify a function and arguments only to be called when you ask
+ *   * {@link module:array.chainFunctions|chainFunctions} - Chain a set of functions to be called one after another.
+ *   * {@link module:array.asyncWaitAndChain|asyncWaitAndChain} - Chains a set of functions to run one after another, but with a delay between.
  * 
  * @module array
  * @exports array
@@ -470,6 +484,7 @@ module.exports.applyArrayValues = function applyArrayValues(collection, path, va
  * @param {Number} length - the length of the new array
  * @param {any} defaultValue - the new value to put in each cell
  * @see {@link module:array.arrange} for values based on the index
+ * @see https://stackoverflow.com/questions/35578478/array-prototype-fill-with-object-passes-reference-and-not-new-instance
  * @returns {Array} - an array of length size with default values
  */
 module.exports.size = function size(length, defaultValue) {
@@ -895,3 +910,441 @@ module.exports.indexify = function indexify(source, ...sectionIndicatorFunctions
 
   return results;
 };
+
+/**
+ * Parse a fixed length table of strings (often in markdown format)
+ * 
+ * For example, say you got a string formatted like this:
+ * 
+ * ```
+ * hardSpacedString = `
+ * id first_name last_name  city        email                        gender ip_address      airport_code car_model_year
+ * -- ---------- ---------- ----------- ---------------------------- ------ --------------- ------------ --------------
+ * 1  Thekla     Brokenshaw Chicago     tbrokenshaw0@kickstarter.com Female 81.118.170.238  CXI          2003          
+ * 2  Lexi       Dugall     New York    ldugall1@fc2.com             Female 255.140.25.31   LBH          2005          
+ * 3  Shawna     Burghill   London      sburghill2@scribd.com        Female 149.240.166.189 GBA          2004          
+ * 4  Ginger     Tween      Lainqu      gtween3@wordpress.com        Female 132.67.225.203  EMS          1993          
+ * 5  Elbertina  Setford    Los Angeles esetford4@ted.com            Female 247.123.242.49  MEK          1989          `;
+ * ```
+ * 
+ * This can be a bit hard to parse, because the space delimiter is a valid character in the `city` column, ex: `New York`.
+ * 
+ * Instead, we can use the starting index and number of characters, to extract the data out
+ * 
+ * ```
+ * const carModelYears = ArrayUtils.multiLineSubstr(hardSpacedString, 102);
+ * // ['car_model_year', '--------------', '2003          ', '2005          ', '2004          ', '1993          ', '1989'];
+ * const ipAddresses = ArrayUtils.multiLineSubstr(hardSpacedString, 73, 14);
+ * // ['ip_address    ', '--------------', '81.118.170.238', '255.140.25.31 ', '149.240.166.18', '132.67.225.203', '247.123.242.49'];
+ * ```
+ * @see {@link module:array.multiLineSubstring|multiLineSubstring} - to use start and end character positions
+ * @see {@link module:array.multiStepReduce|multiStepReduce} - for example on how to extract data from hard spaced arrays
+ * 
+ * {@link module:array.size|array.size(size, default)} - generate array of a specific size and CONSISTENT default value
+ * 
+ * @param {String|String[]} str - multi-line string or array of strings
+ * @param {Number} start - the starting index to substr
+ * @param {Number} [len=0] - optional length of string to substr
+ * @returns {String[]} - substr values from each line
+ */
+module.exports.multiLineSubstr = function multiLineSubstr(target, start, length) {
+  const lines = (() => {
+    if (Array.isArray(target)) {
+      return target;
+    } else if (typeof target === 'string') {
+      return target.split(/\n/); //.trim()
+    }
+    throw Error('multiLineSubstr(target, start, length): target is assumed a multi-line string or array of strings');
+  })();
+  
+  return lines.map((line) => line.substr(start, length));
+};
+
+/**
+ * Parse a fixed length table of strings (often in markdown format)
+ * 
+ * For example, say you got a string formatted like this:
+ * 
+ * ```
+ * hardSpacedString = `
+ * id first_name last_name  city        email                        gender ip_address      airport_code car_model_year
+ * -- ---------- ---------- ----------- ---------------------------- ------ --------------- ------------ --------------
+ * 1  Thekla     Brokenshaw Chicago     tbrokenshaw0@kickstarter.com Female 81.118.170.238  CXI          2003          
+ * 2  Lexi       Dugall     New York    ldugall1@fc2.com             Female 255.140.25.31   LBH          2005          
+ * 3  Shawna     Burghill   London      sburghill2@scribd.com        Female 149.240.166.189 GBA          2004          
+ * 4  Ginger     Tween      Lainqu      gtween3@wordpress.com        Female 132.67.225.203  EMS          1993          
+ * 5  Elbertina  Setford    Los Angeles esetford4@ted.com            Female 247.123.242.49  MEK          1989          `;
+ * ```
+ * 
+ * This can be a bit hard to parse, because the space delimiter is a valid character in the `city` column, ex: `New York`.
+ * 
+ * Instead, we can use the starting index and number of characters, to extract the data out.
+ * 
+ * Note, this function uses the starting and ending character positions, to extract,
+ * where {@link module:array.multiLineSubstr|multiLineSubstr} - uses the start and character length instead.
+ * 
+ * ```
+ * const carModelYears = ArrayUtils.multiLineSubstring(hardSpacedString, 102);
+ * // ['car_model_year', '--------------', '2003          ', '2005          ', '2004          ', '1993          ', '1989'];
+ * const ipAddresses = ArrayUtils.multiLineSubstring(hardSpacedString, 73, 87);
+ * // ['ip_address    ', '--------------', '81.118.170.238', '255.140.25.31 ', '149.240.166.18', '132.67.225.203', '247.123.242.49'];
+ * ```
+ * @see {@link module:array.multiLineSubstr|multiLineSubstr} - to use character start and length
+ * @see {@link module:array.multiStepReduce|multiStepReduce} - for example on how to extract data from hard spaced arrays
+ * 
+ * @param {String|String[]} str - multi-line string or array of strings
+ * @param {Number} startPosition - the starting index to extract out - using the standard `substring` method
+ * @param {Number} [endPosition] - the ending endex to extract out
+ * @returns {String[]} - substr values from each line
+ */
+module.exports.multiLineSubstring = function multiLineSubstring(target, startPosition, endPosition) {
+  const lines = (() => {
+    if (Array.isArray(target)) {
+      return target;
+    } else if (typeof target === 'string') {
+      return target.trim().split(/\n/);
+    }
+    throw Error('multiLineSubstring(target, startPosition, endPosition): target is assumed a multi-line string or array of strings');
+  })();
+  
+  return lines.map((line) => line.substring(startPosition, endPosition));
+};
+
+/**
+ * Returns the reduce at each step along the way.
+ * 
+ * For example, if you have a set of column widths
+ * and would like to know how wide the table is after each column.
+ * 
+ * For example:
+ * 
+ * ```
+ * hardSpacedString = `
+ * id first_name last_name  city        email                        gender ip_address      airport_code car_model_year
+ * -- ---------- ---------- ----------- ---------------------------- ------ --------------- ------------ --------------
+ * 1  Thekla     Brokenshaw Chicago     tbrokenshaw0@kickstarter.com Female 81.118.170.238  CXI          2003          
+ * 2  Lexi       Dugall     New York    ldugall1@fc2.com             Female 255.140.25.31   LBH          2005          
+ * 3  Shawna     Burghill   London      sburghill2@scribd.com        Female 149.240.166.189 GBA          2004          
+ * 4  Ginger     Tween      Lainqu      gtween3@wordpress.com        Female 132.67.225.203  EMS          1993          
+ * 5  Elbertina  Setford    Los Angeles esetford4@ted.com            Female 247.123.242.49  MEK          1989          `;
+ * 
+ * columnWidths = [3, 11, 11, 12, 29, 7, 16, 13, 15];
+ * sumFn = (a, b) => a + b;
+ * 
+ * //-- get the starting position for each column,
+ * //-- ex: column 3 is sum of columnWidths[0..3] or 0 + 3 + 11 + 11 or 25
+ * columnStops = utils.format.multiStepReduce( columnWidths, (a,b) => a + b, 0);
+ * // [0, 3, 14, 25, 37, 66, 73, 89, 102, 117];
+ * ```
+ * 
+ * We can then pair with the column widths - to get exactly the starting position and width of each column.
+ * 
+ * ```
+ * substrPairs = columnWidths.map((value, index) => [columnStops[index], value]);
+ * // [[0, 3], [3, 11], [14, 11], [25, 12], [37, 29], [66, 7], [73, 16], [89, 13], [102, 15]];
+ * ```
+ * 
+ * Now that we know how the starting positions for each of the columns, we can try picking one column out:
+ * 
+ * ```
+ * //-- we can get a single column like this:
+ * cityStartingCharacter = substrPairs[3][0]; // 25
+ * cityColumnLength = substrPairs[3][0]; // 12
+ * 
+ * cityData = ArrayUtils.multiLineSubstr(hardSpacedString, cityStartingCharacter, cityColumnLength);
+ * // ['city        ', '----------- ', 'Chicago     ', 'New York    ', 'London      ', 'Lainqu      ', 'Los Angeles ']
+ * ```
+ * 
+ * Or we can get all columns with something like this:
+ * 
+ * ```
+ * results = substrPairs.map(
+ *  ([startingPos, length]) => ArrayUtils.multiLineSubstr(hardSpacedString, startingPos, length)
+ * );
+ * 
+ * [['id ', '-- ', '1  ', '2  ', '3  ', '4  ', '5  '],
+ * ['first_name ', '---------- ', 'Thekla     ', 'Lexi       ', 'Shawna     ', 'Gin...', ...],
+ * ['last_name  ', '---------- ', 'Brokenshaw ', 'Dugall     ', 'Burghill   ', 'Twe...', ...],
+ * ['city        ', '----------- ', 'Chicago     ', 'New York    ', 'London      ', ...],
+ * ['email                        ', '---------------------------- ', 'tbrokenshaw0...', ...],
+ * ['gender ', '------ ', 'Female ', 'Female ', 'Female ', 'Female ', 'Female '],
+ * ['ip_address      ', '--------------- ', '81.118.170.238  ', '255.140.25.31   ', ...],
+ * ['airport_code ', '------------ ', 'CXI          ', 'LBH          ', 'GBA       ...', ...],
+ * ['car_model_year', '--------------', '2003          ', '2005          ', '2004  ...', ...]]
+ * ```
+ * 
+ * We can then transpose the array to give us the format we might expect (non DataFrame centric)
+ * 
+ * ```
+ * resultsData = utils.array.transpose(results);
+ * 
+ * utils.table(resultsData).render();
+ * ```
+ * 
+ * 0  |1          |2          |3           |4                            |5      |6               |7            |8             
+-- |--         |--         |--          |--                           |--     |--              |--           |--            
+id |first_name |last_name  |city        |email                        |gender |ip_address      |airport_code |car_model_year
+-- |---------- |---------- |----------- |---------------------------- |------ |--------------- |------------ |--------------
+1  |Thekla     |Brokenshaw |Chicago     |tbrokenshaw0@kickstarter.com |Female |81.118.170.238  |CXI          |2003          
+2  |Lexi       |Dugall     |New York    |ldugall1@fc2.com             |Female |255.140.25.31   |LBH          |2005          
+3  |Shawna     |Burghill   |London      |sburghill2@scribd.com        |Female |149.240.166.189 |GBA          |2004          
+4  |Ginger     |Tween      |Lainqu      |gtween3@wordpress.com        |Female |132.67.225.203  |EMS          |1993          
+5  |Elbertina  |Setford    |Los Angeles |esetford4@ted.com            |Female |247.123.242.49  |MEK          |1989          
+ * 
+ * This can also be helpful with coming up with complex
+ *  {@link module:array.arrange|array.arrange(size, start, step)}
+ * collections.
+ */
+module.exports.multiStepReduce = function multiStepReduce(list, fn, initialValue = undefined) {
+  const results = [initialValue];
+  let currentResult = initialValue;
+  list.forEach((val, index) => {
+    currentResult = fn(currentResult, val, index, list);
+    results.push(currentResult);
+  });
+  return results;
+};
+
+/**
+ * Create an iterator for an array that allows for peeking next values.
+ * 
+ * @see https://www.npmjs.com/package/peekable-array-iterator
+ * @example
+ * 
+ * source = [0, 1, 2, 3, 4, 5];
+ * 
+ * // also quite helpful for document.querySelector(...)
+ * itr = new utils.array.PeekableArrayIterator(source);
+ * 
+ * console.log(itr.next()); // { done: false, value: 0 }
+ * 
+ * //-- peek without moving the iterator
+ * const peekItr = itr.peek();
+ * console.log(peekItr.next()); // { done: false, value: 1 }
+ * console.log(peekItr.next()); // { done: false, value: 2 }
+ * console.log(peekItr.next()); // { done: false, value: 3 }
+ * console.log(peekItr.next()); // { done: false, value: 4 }
+ * console.log(peekItr.next()); // { done: true, value: 5 }
+ * 
+ * //-- move the main iterator
+ * console.log(itr.next()); // { done: false, value: 1 }
+ * 
+ * Of course, for each will always work
+ * or
+ * for (let i of new utils.array.PeekableArrayIterator(list)) {
+ *   console.log(i);
+ * }
+ * // 1\n2\n3\n4\n5
+ */
+class PeekableArrayIterator {
+  /**
+   * Constructor
+   * 
+   * @param {Iterable} array - something we can iterate over
+   * @param {Number} start - the starting index
+   */
+  constructor(source, start = -1) {
+    this.array = Array.isArray(source) ? source : [...source];
+    this.i = start;
+  }
+
+  [Symbol.iterator]() { return this; }
+
+  /* eslint-disable wrap-iife */
+  next() {
+    const self = this;
+    this.peek = (function* peek() {
+      for (let peekI = self.i + 1; peekI < self.array.length; peekI += 1) {
+        yield self.array[peekI];
+      }
+      return undefined;
+    })();
+
+    this.i += 1;
+    return { done: this.i >= this.array.length - 1, value: this.array[this.i] };
+  }
+  /* eslint-enable wrap-iife */
+}
+module.exports.PeekableArrayIterator = PeekableArrayIterator;
+
+/**
+ * Defines a function and arguments that will only be called,
+ * only when the delayedFunction is called.
+ * 
+ * (Similar to Function.bind - but supports Function.call(1,2,3) or Function.apply([1,2,3]) syntax)
+ * 
+ * Example, these are equivalent, but the delayedFn does not mess with `this`
+ * 
+ * sayFn = (...rest) => console.log(...rest);
+ * arguments = [0, 1, 2, 3, 4, 5];
+ * 
+ * Spy(sayFn);
+ * 
+ * delayedFnA = sayFn.bind(globalThis, arguments);
+ * ...
+ * sayFn.calledCount; // 0
+ * delayedFnA(); // consoles: [0, 1, 2, 3, 4, 5];
+ * sayFn.calledCount; // 1
+ * 
+ * delayedFnB = utils.array.delayedFn(sayFn, 0, 1, 2, 3, 4, 5);
+ * ...
+ * delayedFnB(); // consoles: [0, 1, 2, 3, 4, 5];
+ * 
+ * @param {Function} fn - Function to be executed at a later time
+ * @param  {...any} rest - arguments to be passed to fn
+ * @returns {Function} - function that can be called to execute fn with the arguments
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/bind
+ */
+module.exports.delayedFn = (fn, ...rest) => () => {
+  const cleanRest = rest.length === 1 && Array.isArray(rest[0]) ? rest[0] : rest;
+  return fn.apply(this, cleanRest);
+};
+
+/**
+ * Chain a set of functions to be called one after another
+ * (supports functions returning promises)
+ * 
+ * This is especially helpful if calls need to be rate limited to only having 1 occur at a time.
+ * 
+ * The resulting promise will return a list, with each entry corresponding with the row of arguments sent.
+ * 
+ * ```
+ * const sumValues = (...rest) => rest.reduce((result, val) => result + val, 0);
+ * 
+ * const arguments = [
+ *  [1],
+ *  [1, 1],
+ *  [1, 1, 2],
+ *  [1, 1, 2, 3]
+ * ];
+ * 
+ * utils.array.chainFunctions(sumValues, arguments)
+ *  .then((results) => console.log(`fibonnacci numbers: ${results}`));
+ * // fibonacci numbers: [1, 2, 4, 7]
+ * ```
+ * 
+ * @param {Function} fn - the function to be called
+ * @param {Array<any[]>} rows - Array where each row are arguments to be applied to fn
+ * @returns {Promise<any>} - promise that will resolve when the last delayed function finishes
+ * @see {@link https://rxjs.dev/guide/overview|rxjs} if you would like to have more than one active at a time.
+ * @see {@link module:array.asyncWaitAndChain|asyncWaitAndChain} - if you would like a delay between executions
+ */
+module.exports.chainFunctions = (fn, rows) => {
+  const delayedFunctions = rows.map((val) => ArrayUtils.delayedFn(fn, val));
+  const delayedIterator = delayedFunctions.values();
+  const answers = [];
+  let isFirstCall = true;
+
+  return new Promise((resolve, reject) => {
+    const callNext = (result) => {
+      if (isFirstCall) {
+        isFirstCall = false;
+      } else {
+        answers.push(result);
+      }
+      try {
+        const nextVal = delayedIterator.next();
+        const { value: delayedFunction, done } = nextVal;
+        if (!done) {
+          const fnResult = delayedFunction();
+          if (fnResult instanceof Promise) {
+            fnResult.then(callNext);
+          } else {
+            callNext(fnResult);
+          }
+        } else {
+          resolve(answers);
+        }
+      } catch (err) {
+        reject(err);
+      }
+    };
+    return callNext();
+  });
+};
+
+/**
+ * Executes a function with arguments after a few second delay.
+ * 
+ * @param {Number} seconds - number of seconds to wait before calling
+ * @param {Function} fn - Function to call
+ * @param {...any} rest - arguments to send to the function when it is executed. 
+ * @returns {@Promise<any>} - that then executes when the timer is up
+ * @private
+ */
+const asyncWaitThenRun = (seconds, fn, ...rest) => new Promise(
+  (resolve, reject) => {
+    setTimeout(() => {
+      try {
+        const results = fn(...rest);
+        if (results instanceof Promise) {
+          results.then((promiseResults) => {
+            resolve(promiseResults);
+          });
+        } else {
+          resolve(results);
+        }
+      } catch (err) {
+        reject(err);
+      }
+    }, seconds * 1000);
+  }
+);
+
+/**
+ * Similar to chainFunctions - in that only one delayed function will occur at a time,
+ * but adds a delay between calls.
+ * 
+ * This also supports functions returning promises.
+ * 
+ * 
+ * ```
+ * const sumValues = (...rest) => rest.reduce((result, val) => result + val, 0);
+ * 
+ * const arguments = [
+ *  [1],
+ *  [1, 1],
+ *  [1, 1, 2],
+ *  [1, 1, 2, 3]
+ * ];
+ * 
+ * utils.array.asyncWaitAndChain(3, sumValues, arguments)
+ *  .then((results) => console.log(`fibonnacci numbers: ${results}`));
+ * // fibonacci numbers: [1, 2, 4, 7], but took 9 seconds to accomplish
+ * ```
+ * 
+ * @param {Number} seconds - number of seconds to delay between each execution
+ * @param {Function} fn - function to be called for each row of rows
+ * @param {Array<any[]>} rows - Array where each row are arguments to be applied to fn
+ * @returns {Promise<any>} - promise that will resolve when the last delayed function finishes
+ * @see {@link module:array.chainFunctions|chainFunctions} - to execute methods right after each other.
+* @see {@link https://rxjs.dev/guide/overview|rxjs} if you would like to execute more than one at a time.
+ */
+// eslint-disable-next-line no-unused-vars
+module.exports.asyncWaitAndChain = (seconds, fn, rows) => {
+  const delayedFunctions = rows.map((val) => ArrayUtils.delayedFn(fn, val));
+  const delayedIterator = delayedFunctions.values();
+  const answers = [];
+  let isFirstCall = true;
+  
+  return new Promise((resolve, reject) => {
+    const callNext = (result) => {
+      if (isFirstCall) {
+        isFirstCall = false;
+      } else {
+        answers.push(result);
+      }
+      const nextVal = delayedIterator.next();
+      const { value: delayedFunction, done } = nextVal;
+      if (!done) {
+        return asyncWaitThenRun(seconds, delayedFunction)
+          .then(callNext)
+          .catch((err) => {
+            reject(err);
+          });
+      }
+      resolve(answers);
+    };
+    return callNext();
+  });
+};

package/src/chain.js

@@ -13,7 +13,6 @@
  * * {@link ChainContainer#close|.close()} - gets the value of the current chain
  * * {@link ChainContainer#chain|.chain(function)} - where it is passed the value, and returns a new Chain with that value.
  * * {@link ChainContainer#errorHandler|.errorHandler(fn)} - custom function called if an error is ever thrown
- * * {@link ChainContainer#debug|.debug()} - console.logs the current value, and continues the chain with that value
  * 
  * Along with methods that can iterate on each element, assuming the value in the chain is an Array.
  * 
@@ -32,10 +31,12 @@
  * 
  * There may be times you want to run side effects, or replace the value entirely. (This isn't common, but may be useful on occasion)
  * 
+ * * {@link ChainContainer#debug|.debug()} - continues with the current value, but executes a console.log first
  * * {@link ChainContainer#execute|.execute(function)} - where it calls a function, but doesn't pass on the result.
  *        <br /> (This is useful for side-effects, like writing to files)
  * * {@link ChainContainer#replace|.replace(value)} - replaces the value in the chain with a literal value,
  *        regardless of the previous value.
+ * * {@link ChainContainer#toArray|.toArray()} - assuming the current value is an interatable, converts it to an array.
  * 
  * For example:
  * 
@@ -526,6 +527,25 @@ class ChainContainer {
     return this.value;
   }
 
+  /**
+   * Converts the current value to an array to be further chained.
+   * (Assumes it is iteratable);
+   * 
+   * Example: 
+   * 
+   * ```
+   * new Chain(document.querySelectorAll('div'))
+   *  .toArray()
+   *  .execute((passedValue) => Array.isArray(passedValue))
+   *  .close(); // [... list of div elements on the page]
+   * ```
+   * 
+   * @returns {ChainContainer}
+   */
+  toArray() {
+    return new ChainContainer(Array.from(this.value));
+  }
+
   //-- private methods
 
   /**

package/src/format.js

@@ -1068,6 +1068,12 @@ module.exports.limitLines = function limitLines(str, toLine, fromLine, lineSepar
     : JSON.stringify(str || '', FormatUtils.mapReplacer, 2);
   const cleanLine = lineSeparator || '\n';
 
+  if (!toLine) {
+    return cleanStr.split(cleanLine)
+      .slice(fromLine || 0)
+      .join(cleanLine);
+  }
+
   return cleanStr.split(cleanLine)
     .slice(fromLine || 0, toLine)
     .join(cleanLine);

package/src/object.js

@@ -52,6 +52,11 @@ const FormatUtils = require('./format');
  * * Create Map of objects by key
  *   * {@link module:object.mapByProperty|mapByProperty()} -
  *   * {@link module:group.by|group(collection, accessor)}
+ * * Convert collections of objects
+ *   * {@link module:object.objectCollectionFromArray|objectCollectionFromArray} - convert rows/columns 2d array to objects
+ *   * {@link module:object.objectCollectionToArray} - convert objects to a rows/columns 2d array
+ *   * {@link module:object.objectCollectionFromDataFrameObject} - convert tensor object with each field as 1d array of values
+ *   * {@link module:object.objectCollectionToDataFrameObject} - convert objects from a tensor object
  * 
  * @module object
  * @exports object
@@ -1550,7 +1555,7 @@ module.exports.setPropertyDefaults = function setPropertyDefaults(targetObject,
  * @param {Object[]} objCollection - object or multiple objects that should have properties formatted
  * @param {Function} formattingFn - function to apply to all the properties specified
  * @param  {...any} propertiesToFormat - list of properties to apply the formatting function
- * @returns {Object[] - clone of objCollection with properties mapped
+ * @returns {Object[]} - clone of objCollection with properties mapped
  */
 module.exports.mapProperties = function mapProperties(objCollection, formattingFn, ...propertiesToFormat) {
   const cleanCollection = !Array.isArray(objCollection)
@@ -1860,3 +1865,235 @@ module.exports.union = function union(source1, source2) {
 
   return results;
 };
+
+/**
+ * Converts a 2d array to a collection of objects.
+ * 
+ * For Example:
+ * ```
+ * weather = [
+ *   [ 'id', 'city', 'month', 'precip' ],
+ *   [ 1, 'Seattle', 'Aug', 0.87 ],
+ *   [ 0, 'Seattle', 'Apr', 2.68 ],
+ *   [ 2, 'Seattle', 'Dec', 5.31 ]
+ * ]
+ * 
+ * utils.object.objectCollectionFromArray(weather);
+ * // [
+ * //   { id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87 },
+ * //   { id: 0, city: 'Seattle',  month: 'Apr', precip: 2.68 },
+ * //   { id: 2, city: 'Seattle',  month: 'Dec', precip: 5.31 }
+ * // ];
+ * ```
+ * 
+ * Note that the headers can be optionally provided separately.
+ * 
+ * ```
+ * weather = [
+ *   [ 1, 'Seattle', 'Aug', 0.87 ],
+ *   [ 0, 'Seattle', 'Apr', 2.68 ],
+ *   [ 2, 'Seattle', 'Dec', 5.31 ]
+ * ];
+ * headers = [ 'id', 'city', 'month', 'precip' ];
+ * 
+ * utils.object.objectCollectionFromArray(weather, headers);
+ * // [
+ * //   { id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87 },
+ * //   { id: 0, city: 'Seattle',  month: 'Apr', precip: 2.68 },
+ * //   { id: 2, city: 'Seattle',  month: 'Dec', precip: 5.31 }
+ * // ];
+ * ```
+ * 
+ * @param {Array<Array>} arrayCollection - 2d collection of values
+ * @param {String[]} [headers] - Optional set of headers to use if not present in first row 0
+ * @returns {Object[]} - list of objects
+ * @see {@link module:object.objectCollectionFromArray|objectCollectionFromArray}
+ * @see {@link module:object.objectCollectionToArray|objectCollectionToArray}
+ * @see {@link module:object.objectCollectionFromDataFrameObject|objectCollectionFromDataFrameObject}
+ * @see {@link module:object.objectCollectionToDataFrameObject|objectCollectionToDataFrameObject}
+ */
+module.exports.objectCollectionFromArray = function objectCollectionFromArray(arrayCollection, headers = null) {
+  let cleanHeaders;
+  let cleanValues;
+  
+  if (!Array.isArray(arrayCollection)) throw Error('objectCollectionFromArray: expected collection to be a 2 dimensional array');
+  
+  if (!headers) {
+    const [arrayCollectionHeaders, ...arrayCollectionValues] = arrayCollection;
+    cleanHeaders = arrayCollectionHeaders;
+    cleanValues = arrayCollectionValues;
+  } else {
+    cleanHeaders = headers;
+    cleanValues = arrayCollection;
+  }
+
+  /* eslint-disable arrow-body-style */
+  const newData = cleanValues.map((row) => {
+    return cleanHeaders.reduce((result, header, index) => {
+      return ObjectUtils.assign(result, header, row[index]);
+    }, {});
+  });
+  /* eslint-enable arrow-body-style */
+
+  return newData;
+};
+
+/**
+ * Converts a 2d array to a collection of objects.
+ * 
+ * For Example:
+ * ```
+ * weather = [
+ *   { id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87 },
+ *   { id: 0, city: 'Seattle',  month: 'Apr', precip: 2.68 },
+ *   { id: 2, city: 'Seattle',  month: 'Dec', precip: 5.31 }
+ * ];
+ * 
+ * utils.object.objectCollectionToArray(weather);
+ * // [
+ * //   [ 'id', 'city', 'month', 'precip' ],
+ * //   [ 1, 'Seattle', 'Aug', 0.87 ],
+ * //   [ 0, 'Seattle', 'Apr', 2.68 ],
+ * //   [ 2, 'Seattle', 'Dec', 5.31 ]
+ * // ]
+ * ```
+ * 
+ * @param {Array<Array>} arrayCollection - 2d collection of values
+ * @param {String[]?} headers - Optional set of headers to use if not present in first row 0
+ * @returns {Object[]} - list of objects
+ * @see {@link module:object.objectCollectionFromArray|objectCollectionFromArray}
+ * @see {@link module:object.objectCollectionToArray|objectCollectionToArray}
+ * @see {@link module:object.objectCollectionFromDataFrameObject|objectCollectionFromDataFrameObject}
+ * @see {@link module:object.objectCollectionToDataFrameObject|objectCollectionToDataFrameObject}
+ */
+module.exports.objectCollectionToArray = function objectCollectionToArray(objectCollection) {
+  if (!Array.isArray(objectCollection)) throw Error('objectCollectionToArray: expected collection to be a collection of objects');
+
+  //-- create the result array in advance for performance 
+  // https://stackoverflow.com/questions/35578478/array-prototype-fill-with-object-passes-reference-and-not-new-instance
+
+  const keys = ObjectUtils.keys(objectCollection);
+
+  const finalResult = new Array(objectCollection.length + 1);
+  finalResult[0] = keys;
+
+  for (let i = 1; i <= objectCollection.length; i += 1) {
+    finalResult[i] = new Array(keys.length);
+  }
+
+  objectCollection.forEach((obj, objIndex) => {
+    const rowResult = finalResult[objIndex + 1];
+    keys.forEach((key, keyIndex) => {
+      rowResult[keyIndex] = obj[key];
+    });
+  });
+  return finalResult;
+};
+
+/**
+ * Convert a DataFrame Object into a collection of objects.
+ * 
+ * This uses properties with 1d tensor lists
+ * and converts them to a list of objects.
+ * 
+ * ```
+ * const weather = {
+ *   id: [1, 0, 2],
+ *   city: ['Seattle',  'Seattle', 'Seattle'],
+ *   month: ['Aug', 'Apr', 'Dec'],
+ *   precip: [0.87, 2.68, 5.31]
+ * };
+ * 
+ * ObjectUtils.objectCollectionFromDataFrameObject(weather);
+ * // [
+ * //   { id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87 },
+ * //   { id: 0, city: 'Seattle',  month: 'Apr', precip: 2.68 },
+ * //   { id: 2, city: 'Seattle',  month: 'Dec', precip: 5.31 }
+ * // ];
+ * ```
+ * 
+ * @param {Object} dataFrameObject - Object with properties holding 1d tensor arrays
+ * @returns {Object[]} - collection of objects
+ * @see {@link module:object.objectCollectionFromArray|objectCollectionFromArray}
+ * @see {@link module:object.objectCollectionToArray|objectCollectionToArray}
+ * @see {@link module:object.objectCollectionFromDataFrameObject|objectCollectionFromDataFrameObject}
+ * @see {@link module:object.objectCollectionToDataFrameObject|objectCollectionToDataFrameObject}
+ * @see {@link https://danfo.jsdata.org/api-reference/dataframe/creating-a-dataframe#creating-a-dataframe-from-an-object|Danfo DataFrame Objects}
+ */
+module.exports.objectCollectionFromDataFrameObject = function objectCollectionFromDataFrameObject(dataFrameObject) {
+  if (!dataFrameObject) return [];
+  if ((typeof dataFrameObject) !== 'object') throw Error('objectCollectionFromDataFrameObject must be passed an object with properties holding 1d tensors');
+
+  const fields = ObjectUtils.keys(dataFrameObject);
+
+  if (fields.length < 1) return [];
+
+  const len = fields.reduce((maxLen, field) => {
+    const list = dataFrameObject[field];
+    if (!Array.isArray(list)) return maxLen;
+
+    const listLength = list?.length || 0;
+    return listLength > maxLen ? listLength : maxLen;
+  }, -1);
+
+  // console.log(`fieldLength:${len}`);
+  const results = new Array(len).fill(0).map((_) => ({}));
+
+  fields.forEach((field) => {
+    const fieldArray = dataFrameObject[field];
+    if (Array.isArray(fieldArray)) {
+      fieldArray.forEach((fieldValue, rowIndex) => {
+        results[rowIndex][field] = fieldValue;
+      });
+    }
+  });
+
+  return results;
+};
+
+/**
+ * Convert a DataFrame Object into a collection of objects.
+ * 
+ * This uses properties with 1d tensor lists
+ * and converts them to a list of objects.
+ * 
+ * ```
+ * const weather = [
+ *   { id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87 },
+ *   { id: 0, city: 'Seattle',  month: 'Apr', precip: 2.68 },
+ *   { id: 2, city: 'Seattle',  month: 'Dec', precip: 5.31 }
+ * ];
+ * 
+ * ObjectUtils.objectCollectionToDataFrameObject(weather);
+ * // {
+ * //   id: [1, 0, 2],
+ * //   city: ['Seattle',  'Seattle', 'Seattle'],
+ * //   month: ['Aug', 'Apr', 'Dec'],
+ * //   precip: [0.87, 2.68, 5.31]
+ * // };
+ * ```
+ * 
+ * @param {Object} dataFrameObject - Object with properties holding 1d tensor arrays
+ * @returns {Object[]} - collection of objects
+ * @see {@link module:object.objectCollectionFromArray|objectCollectionFromArray}
+ * @see {@link module:object.objectCollectionToArray|objectCollectionToArray}
+ * @see {@link module:object.objectCollectionFromDataFrameObject|objectCollectionFromDataFrameObject}
+ * @see {@link module:object.objectCollectionToDataFrameObject|objectCollectionToDataFrameObject}
+ * @see {@link https://danfo.jsdata.org/api-reference/dataframe/creating-a-dataframe#creating-a-dataframe-from-an-object|Danfo DataFrame Objects}
+ */
+module.exports.objectCollectionToDataFrameObject = function objectCollectionToDataFrameObject(objectCollection, fields = null) {
+  const dataFrameObject = {};
+
+  const cleanFields = fields || ObjectUtils.keys(objectCollection);
+  const length = objectCollection?.length || 0;
+
+  cleanFields.forEach((field) => {
+    const fieldData = new Array(length).fill(undefined);
+    dataFrameObject[field] = fieldData;
+
+    objectCollection.forEach((obj, index) => {
+      fieldData[index] = obj[field];
+    });
+  });
+  return dataFrameObject;
+};