jupyter-ijavascript-utils 1.60.1 → 1.62.0

package/DOCS.md

@@ -74,6 +74,8 @@ 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.62 - Update to Array.peekableIterator to include peekItr() as sugar for .peek
+* 1.61 - Docs Updated
 * 1.60 - Make post-processing of documents easier with {@link module:ijs.markDocumentPosition|ijs.markDocumentPosition}
 * 1.59 - 
     * #95 - give control with page breaks. So we can render text before the page break (like for headers) - or even get the html used and render it how we want. (ex: {@link module:ijs.generatePageBreakStylesHTML|ijs.printPageBreak})
@@ -404,6 +406,44 @@ Depends on:
 
 See the [How to Use]{@tutorial howToUse} section for more.
 
+# Common Questions
+
+## Converting Local Functions to a Local Library
+
+Often - Jupyter is not the best place to do development, and folks would like to develop in their own favourite IDE.
+
+You can write local modules (ex: `lib.js`) relative to your notebook, and then use `require('./lib')` to access them in your notebook. (see the section below on ESM Modules)
+
+NOTE: re-running the require will use a `cached version` of your module, and `may not reflect changes you just made`.
+
+(For this and other reasons, it can be helpful to have a `version` attribute to your module - to ensure the latest code is accessible)
+
+There typically are two options:
+
+* re-run the entire notebook
+
+* use a "cache bypass" only for your local library. ex: [import-fresh](https://www.npmjs.com/package/import-fresh)
+
+Using a cache bypass is fairly simple, and behaves something similar to this:
+
+```
+utils = reqire('jupyter-ijavascript-utils');
+importFresh = require('import-fresh');
+// other imports go here
+
+//-- clear the output so it doesn't pollute with nonsense we don't care about.
+utils.ijs.clearOutput();
+```
+
+and then load your module in a separate cell:
+
+```
+lib = importFresh('./lib');
+lib.version; // 1.0.0
+```
+
+and if you change your library, you can then just run that cell again
+
 ## ESM Modules + D3
 
 Note that we strongly recommend using this with other modules like D3 - that only support ESM modules now.

package/Dockerfile

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

package/README.md

@@ -54,6 +54,8 @@ 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.62 - Update to Array.peekableIterator to include peekItr() as sugar for .peek
+* 1.61 - Docs Updated
 * 1.60 - Make post-processing of documents easier with ijs.utils.markDocumentPosition
 * 1.59 - 
     * #95 - give control with page breaks. So we can render text before the page break (like for headers) - or even get the html used and render it how we want.
@@ -132,6 +134,42 @@ found under the [docResources/notebooks](https://github.com/paulroth3d/jupyter-i
 simply create a package in the folder you will run the `jupyter lab` command
 - such as the sample one under [docResources/notebooks/package.json](https://github.com/paulroth3d/jupyter-ijavascript-utils/blob/main/docResources/notebooks/package.json))
 
+## Converting Local Functions to a Local Library
+
+Often - Jupyter is not the best place to do development, and folks would like to develop in their own favourite IDE.
+
+You can write local modules (ex: `lib.js`) relative to your notebook, and then use `require('./lib')` to access them in your notebook. (see the section below on ESM Modules)
+
+NOTE: re-running the require will use a `cached version` of your module, and `may not reflect changes you just made`.
+
+(For this and other reasons, it can be helpful to have a `version` attribute to your module - to ensure the latest code is accessible)
+
+There typically are two options:
+
+* re-run the entire notebook
+
+* use a "cache bypass" only for your local library. ex: [https://www.npmjs.com/package/import-fresh](import-fresh)
+
+Using a cache bypass is fairly simple, and behaves somethng similar to this:
+
+```
+utils = reqire('jupyter-ijavascript-utils');
+importFresh = require('import-fresh');
+// other imports go here
+
+//-- clear the output so it doesn't pollute with nonsense we don't care about.
+utils.ijs.clearOutput();
+```
+
+and then load your module in a separate cell:
+
+```
+lib = importFresh('./lib');
+lib.version; // 1.0.0
+```
+
+and if you change your library, you can then just rn tat cell again
+
 ## ESM Modules + D3
 
 Note that we strongly recommend using this with other modules like D3 - that only support ESM modules now.

package/package.json

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

package/src/TableGenerator.js

@@ -1751,7 +1751,7 @@ class TableGenerator {
     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.headers.forEach((header) => ObjectUtils.assignIP(results, header, createFrameList()));
 
     prepResults.data.forEach((row, rowIndex) => {
       row.forEach((value, valIndex) => {

package/src/aggregate.js

@@ -549,7 +549,7 @@ module.exports.first = function first(collection, accessor) {
  * @param {Array} collection -
  * @returns {Number}
  * @example
- * utils.aggregate.count([0.87, 2.68, 5.31, 3.94, 4.13, 3.58, 3.62, 2.56]);
+ * utils.aggregate.length([0.87, 2.68, 5.31, 3.94, 4.13, 3.58, 3.62, 2.56]);
  * // 8
  */
 module.exports.length = function length(collection) {
@@ -684,7 +684,7 @@ module.exports.countMap = function countMap(collection, accessor, uniquifierFn)
  *   { station: 'A', timestamp: new Date(2022, 0, 2, 9, 30) },
  *   { station: 'B', timestamp: new Date(2022, 0, 2, 10, 0) },
  *   { station: 'A', timestamp: new Date(2022, 0, 3, 10, 0) },
- *   { station: 'B', timestamp: new Date(2022, 0, 3, 10, 0 }
+ *   { station: 'B', timestamp: new Date(2022, 0, 3, 10, 0) }
  * ]
  * utils.aggregate.count(series, 'timestamp', (d) => d.toISOString().slice(0, 10))
  * // { '2022-01-01': 3, '2022-01-02': 2, '2022-01-03': 2 }
@@ -744,7 +744,7 @@ module.exports.duplicates = function duplicates(collection, accessor, uniquifier
  * const superSet = new Set(['a', 'b', 'c']);
  * const data = [{ val: 'a' }, { val: 'b' }, { val: 'c' }, { val: 'd' }];
  * 
- * aggregate.notIn(data, 'val', superSet);
+ * utils.aggregate.notIn(data, 'val', superSet);
  * // Set('d')
  */
 module.exports.notIn = function notIn(collection, accessor, targetIterator) {
@@ -768,13 +768,13 @@ module.exports.notIn = function notIn(collection, accessor, targetIterator) {
  * @returns {Boolean} - whether the values in the array are truly unique
  * @example
  * let data = [{ val: 1 }, { val: 2 }, { val: 3 }, { val: 1 }];
- * aggregate.isUnique(data, 'val'); // false
+ * utils.aggregate.isUnique(data, 'val'); // false
  * 
  * let data = [{ val: 1 }, { val: 2 }, { val: 3 }];
- * aggregate.isUnique(data, 'val'); // true
+ * utils.aggregate.isUnique(data, 'val'); // true
  * 
  * data = ['a', 'b', 'c', 'd'];
- * aggregate.isUnique(data); // true
+ * utils.aggregate.isUnique(data); // true
  */
 module.exports.isUnique = function isUnique(collection, accessor) {
   const cleanedFunc = ObjectUtils.evaluateFunctionOrProperty(accessor);
@@ -981,7 +981,7 @@ module.exports.percentile_99 = function percentile(collection, accessor) {
  * // 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})`;
+ * const monthPrecip = (record) => `${record.month} (${record.precip})`;
  * utils.aggregate.topValues(collection, 3, monthPrecip, '-precip');
  * // '2021-Oct (5.31)', '2021-Dec (4.13)', '2022-Mar (3.98)'
  * ```
@@ -998,7 +998,7 @@ module.exports.percentile_99 = function percentile(collection, accessor) {
  * 
  * //-- bottom 5 values
  * utils.aggregate.topValues(collection, 5, null, '');
- * // 
+ * // [0.87, 2.56, 2.68, 3.58, 3.62]
  * ```
  * 
  * @param {Array} collection - Collection of values we want to get the top values from

package/src/array.js

@@ -63,18 +63,16 @@ const ArrayUtils = module.exports;
  * @type {Function}
  * @example
  * 
- * [3,5,1,2,4].sort(utils.sort.SIMPLE_ASCENDING))
- * //
- * [1,2,3,4,5]
+ * [3,5,1,2,4].sort(utils.array.SIMPLE_ASCENDING)
+ * // [1,2,3,4,5]
  */
 module.exports.SORT_ASCENDING = (a, b) => a === b ? 0 : a > b ? 1 : -1;
 
 /**
  * Simple descending sort function
  * @example
- * [3,5,1,2,4].sort(utils.sort.SIMPLE_ASCENDING))
- * //
- * [5,4,3,2,1]
+ * [3,5,1,2,4].sort(utils.array.SORT_DESCENDING)
+ * // [5,4,3,2,1]
  * @type {Function}
  */
 module.exports.SORT_DESCENDING = (a, b) => a === b ? 0 : a > b ? -1 : 1;
@@ -83,16 +81,17 @@ module.exports.SORT_DESCENDING = (a, b) => a === b ? 0 : a > b ? -1 : 1;
  * Creates a sort function based on fields of an object.
  * 
  * ```
- * sampleData = [{score: 200, name: 'jane'}, {score: 200, name: 'john'}]
+ * [{score: 200, name: 'jane'}, {score: 300, name: 'john'}, {score: 300, name: 'jonny'}];
  * // sort by score descending, and then by name ascending
- * sampleData.sort(utils.array.createSort('-score','name'))
+ * sampleData.sort(utils.array.createSort('-score','name'));
+ * // [{ score: 300, name: 'john' }, { score: 300, name: 'jonny' },{ score: 200, name: 'jane' }]
  * ```
  * 
  * @example
  * 
  * sampleData = [{i:4}, {v:2}, {v:1}, {v:3}];
  * sortedData = sampleData.sort(
- *    utils.createSort('-v')
+ *    utils.array.createSort('-v')
  * );
  * // [{v:4}, {v:3}, {v:2}, {v:1}]
  * 
@@ -427,16 +426,16 @@ module.exports.applyArrayValue = function applyArrayValue(collection, path, valu
  * cities = utils.object.extractObjectProperty('city');
  * // ['Seattle', 'New York', 'Chicago'];
  * 
- * //-- async process to geocode
- * geocodedCities = geocodeCity(cities);
- * // [{ city: 'Seattle', state: 'WA', country: 'USA' },
- * // { city: 'New York', state: 'NY', country: 'USA' },
- * // { city: 'Chicago', state: 'IL', country: 'USA' }]
+ * //-- get a separate dataset that needs to be joined, like geocodeCity(cities);
+ * geocodedCities = [{ city: 'Seattle', state: 'WA', country: 'USA' },
+ *   { city: 'New York', state: 'NY', country: 'USA' },
+ *   { city: 'Chicago', state: 'IL', country: 'USA' }];
  * 
- * utils.applyArrayValues(weather, 'geo', geocodedCities);
+ * utils.array.applyArrayValues(weather, 'geo', geocodedCities);
  * // [{ id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87, geo: { city: 'Seattle', state: 'WA', country: 'USA' } },
  * //  { id: 3, city: 'New York', month: 'Apr', precip: 3.94, geo: { city: 'New York', state: 'NY', country: 'USA' } },
  * //  { id: 6, city: 'Chicago',  month: 'Apr', precip: 3.62, geo: { city: 'Chicago', state: 'IL', country: 'USA' } }];
+ * ```
  * 
  * Note that traditional [Array.map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map)
  * works best for if you are working with objects completely in memory.
@@ -505,14 +504,14 @@ module.exports.size = function size(length, defaultValue) {
  * 
  * utils.array.arange(10, 1)
  *  .map((val) => `item ${val}`);
- * //
- * [
- *   'item 1', 'item 2',
- *   'item 3', 'item 4',
- *   'item 5', 'item 6',
- *   'item 7', 'item 8',
- *   'item 9', 'item 10'
- * ]
+ * 
+ * // [
+ * //   'item 1', 'item 2',
+ * //   'item 3', 'item 4',
+ * //   'item 5', 'item 6',
+ * //   'item 7', 'item 8',
+ * //   'item 9', 'item 10'
+ * // ]
  * @param {Number} length - the number of items toreturn
  * @param {Number} [start=0] - the starting number
  * @param {Number} [step=1] - the number to increment for each step
@@ -573,13 +572,13 @@ module.exports.arrayLength2d = function arrayLength2d(targetArray) {
  * @example
  * 
  * baseArray = [ 0, 1, 2, 3, 4 ];
- * utils.array.transpose(utils.array.arrange(5))
- * //
- * [ [ 0 ],
- *   [ 1 ],
- *   [ 2 ],
- *   [ 3 ],
- *   [ 4 ] ]
+ * utils.array.transpose(utils.array.arrange(5));
+ * 
+ * // [ [ 0 ],
+ * //   [ 1 ],
+ * //   [ 2 ],
+ * //   [ 3 ],
+ * //   [ 4 ] ]
  */
 module.exports.transpose = function transpose(matrix) {
   //-- fast fail
@@ -618,22 +617,22 @@ module.exports.transpose = function transpose(matrix) {
  * @example
  * 
  * baseArray = utils.array.arrange(12);
- * [
- *    0,  1, 2, 3, 4, 5,  6, 7, 8, 9, 10, 11
- * ]
+ * // [
+ * //    0,  1, 2, 3, 4, 5,  6, 7, 8, 9, 10, 11
+ * // ]
  * 
  * //-- reshape the 1d array based on 3 columns
  * newArray = utils.array.reshape(baseArray, 3)
- * [ [ 0, 1, 2 ],
- *   [ 3, 4, 5 ],
- *   [ 6, 7, 8 ],
- *   [ 9, 10, 11 ] ];
+ * // [ [ 0, 1, 2 ],
+ * //   [ 3, 4, 5 ],
+ * //   [ 6, 7, 8 ],
+ * //   [ 9, 10, 11 ] ];
  * 
  * //-- now reshape the 4x3 array to 3x4
  * utils.array.reshape(newArray, 4);
- * [ [ 0, 1, 2, 3 ],
- *   [ 4, 5, 6, 7 ],
- *   [ 8, 9, 10, 11 ] ]
+ * // [ [ 0, 1, 2, 3 ],
+ * //   [ 4, 5, 6, 7 ],
+ * //   [ 8, 9, 10, 11 ] ]
  */
 module.exports.reshape = function reshape(sourceArray, numColumns) {
   const results = [];
@@ -710,7 +709,7 @@ module.exports.clone = function clone(target) {
  * //   [ 3, 0 ], [ 3, 1 ], [ 3, 2 ], [ 3, 3 ]
  * // ]
  * 
- * myList.forEach((value, index) => {
+ * gridPositions.forEach((value, index) => {
  *   const [x, y] = gridPositions[index];
  *   console.log(`placing ${value} in row:${x}, column:${y}`);
  * });
@@ -779,41 +778,41 @@ module.exports.arangeMulti = module.exports.arrangeMulti;
  * isHeader1('This describes section A'); // false
  * 
  * indexedData = utils.array.indexify(data, isHeader1);
- * [
- *   { entry: 'Heading', section: [ 0 ], subIndex: 1 },
- *   { entry: '# Overview', section: [ 1 ], subIndex: 0 },
- *   {
- *     entry: 'This entire list is a hierarchy of data.',
- *     section: [ 1 ],
- *     subIndex: 1
- *   },
- *   { entry: '# Section A', section: [ 2 ], subIndex: 0 },
- *   { entry: 'This describes section A', section: [ 2 ], subIndex: 1 },
- *   { entry: '## SubSection 1', section: [ 2 ], subIndex: 2 },
- *   {
- *     entry: 'With a subsection belonging to Section A',
- *     section: [ 2 ],
- *     subIndex: 3
- *   },
- *   { entry: '## SubSection 2', section: [ 2 ], subIndex: 4 },
- *   {
- *     entry: 'And another subsection sibling to SubSection 1, but also under Section A.',
- *     section: [ 2 ],
- *     subIndex: 5
- *   },
- *   { entry: '# Section B', section: [ 3 ], subIndex: 0 },
- *   {
- *     entry: 'With an entirely unrelated section B, that is sibling to Section A',
- *     section: [ 3 ],
- *     subIndex: 1
- *   },
- *   { entry: '## SubSection 1', section: [ 3 ], subIndex: 2 },
- *   {
- *     entry: 'And another subsection 1, but this time related to Section B.',
- *     section: [ 3 ],
- *     subIndex: 3
- *   }
- * ];
+ * // [
+ * //   { entry: 'Heading', section: [ 0 ], subIndex: 1 },
+ * //   { entry: '# Overview', section: [ 1 ], subIndex: 0 },
+ * //   {
+ * //     entry: 'This entire list is a hierarchy of data.',
+ * //     section: [ 1 ],
+ * //     subIndex: 1
+ * //   },
+ * //   { entry: '# Section A', section: [ 2 ], subIndex: 0 },
+ * //   { entry: 'This describes section A', section: [ 2 ], subIndex: 1 },
+ * //   { entry: '## SubSection 1', section: [ 2 ], subIndex: 2 },
+ * //   {
+ * //     entry: 'With a subsection belonging to Section A',
+ * //     section: [ 2 ],
+ * //     subIndex: 3
+ * //   },
+ * //   { entry: '## SubSection 2', section: [ 2 ], subIndex: 4 },
+ * //   {
+ * //     entry: 'And another subsection sibling to SubSection 1, but also under Section A.',
+ * //     section: [ 2 ],
+ * //     subIndex: 5
+ * //   },
+ * //   { entry: '# Section B', section: [ 3 ], subIndex: 0 },
+ * //   {
+ * //     entry: 'With an entirely unrelated section B, that is sibling to Section A',
+ * //     section: [ 3 ],
+ * //     subIndex: 1
+ * //   },
+ * //   { entry: '## SubSection 1', section: [ 3 ], subIndex: 2 },
+ * //   {
+ * //     entry: 'And another subsection 1, but this time related to Section B.',
+ * //     section: [ 3 ],
+ * //     subIndex: 3
+ * //   }
+ * // ];
  * ```
  * 
  * Note that this only indexes elements by the first header.
@@ -924,8 +923,8 @@ module.exports.indexify = function indexify(source, ...sectionIndicatorFunctions
  * 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
+ * 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          
@@ -976,8 +975,8 @@ module.exports.multiLineSubstr = function multiLineSubstr(target, start, length)
  * 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
+ * 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          
@@ -1029,8 +1028,8 @@ module.exports.multiLineSubstring = function multiLineSubstring(target, startPos
  * For example:
  * 
  * ```
- * hardSpacedString = `
- * id first_name last_name  city        email                        gender ip_address      airport_code car_model_year
+ * 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          
@@ -1072,7 +1071,7 @@ module.exports.multiLineSubstring = function multiLineSubstring(target, startPos
  * cityStartingCharacter = substrPairs[3][0]; // 25
  * cityColumnLength = substrPairs[3][1]; // 12
  * 
- * cityData = ArrayUtils.multiLineSubstr(hardSpacedString, cityStartingCharacter, cityColumnLength);
+ * cityData = utils.array.multiLineSubstr(hardSpacedString, cityStartingCharacter, cityColumnLength);
  * // ['city        ', '----------- ', 'Chicago     ', 'New York    ', 'London      ', 'Lainqu      ', 'Los Angeles ']
  * ```
  * 
@@ -1080,18 +1079,18 @@ module.exports.multiLineSubstring = function multiLineSubstring(target, startPos
  * 
  * ```
  * results = substrPairs.map(
- *  ([startingPos, length]) => ArrayUtils.multiLineSubstr(hardSpacedString, startingPos, length)
+ *  ([startingPos, length]) => utils.array.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  ...', ...]]
+ * // [['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)
@@ -1154,17 +1153,17 @@ module.exports.multiStepReduce = function multiStepReduce(list, fn, initialValue
  * // [ 3, 11, 11, 12, 29, 7, 16, 13, 15 ];
  * 
  * 
- * results = utils.array.extractFromHardSpacedTable(str, columnWidths);
+ * results = utils.array.extractFromHardSpacedTable(hardSpacedString, columnWidths);
  * 
- * [['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  ...', ...]]
+ * // [['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)
@@ -1211,9 +1210,7 @@ module.exports.extractFromHardSpacedTable = function extractFromHardSpacedTable(
 /**
  * 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(...)
@@ -1222,22 +1219,26 @@ module.exports.extractFromHardSpacedTable = function extractFromHardSpacedTable(
  * 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 }
+ * console.log(itr.peek.next()); // { done: false, value: 1 }
+ * console.log(itr.peek.next()); // { done: false, value: 2 }
+ * console.log(itr.peek.next()); // { done: false, value: 3 }
+ * console.log(itr.peek.next()); // { done: false, value: 4 }
+ * console.log(itr.peek.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)) {
+ * 
+ * ```
+ * for (let i of new utils.array.PeekableArrayIterator(source)) {
  *   console.log(i);
  * }
  * // 1\n2\n3\n4\n5
+ * ```
+ * 
+ * @see https://www.npmjs.com/package/peekable-array-iterator
  */
 class PeekableArrayIterator {
   /**
@@ -1262,9 +1263,12 @@ class PeekableArrayIterator {
       }
       return undefined;
     })();
+    this.peekItr = function peekItr() {
+      return this.peek;
+    };
 
     this.i += 1;
-    return { done: this.i >= this.array.length - 1, value: this.array[this.i] };
+    return { done: this.i >= this.array.length, value: this.array[this.i] };
   }
   /* eslint-enable wrap-iife */
 }
@@ -1458,9 +1462,11 @@ module.exports.asyncWaitAndChain = (seconds, fn, rows) => {
  * ```
  * categoryValues = ['rock', 'paper', 'scissors'];
  * 
+ * //-- resizes an array to be shorter - truncating
  * utils.array.resize(categoryValues, 2); // ['rock', 'paper']
- * utils.array.resize(categoryValues, 7); // ['rock', 'paper', 'scissors',
- * undefined, undefined, undefined, undefined];
+ * 
+ * //-- resizes an array to be longer - filling with undefined
+ * utils.array.resize(categoryValues, 7); // ['rock', 'paper', 'scissors', undefined, undefined, undefined, undefined];
  * ```
  * 
  * @param {Array} sourceList - array of values