jupyter-ijavascript-utils 1.31.0 → 1.33.0

package/DOCS.md

@@ -75,6 +75,8 @@ Give it a try here:
 
 ## What's New
 
+* 1.33 - Object.augmentInherit and Object.union
+* 1.32 - Array.indexify to identify sections within a 1d array into a hierarchy.
 * 1.31 - harden Array.transpose for arrays with nulls, and Table.generateTSV
 * 1.30 - add Format.wordWrap and Format.lineCount
 * 1.29 - Updated TableGenerator.format method

package/Dockerfile

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

package/README.md

@@ -55,6 +55,8 @@ This is not intended to be the only way to accomplish many of these tasks, and a
 
 # What's New
 
+* 1.33 - Object.augmentInherit and Object.union
+* 1.32 - Array.indexify to identify sections within a 1d array into a hierarchy.
 * 1.31 - harden Array.transpose for arrays with nulls, and Table.generateTSV
 * 1.30 - add Format.wordWrap and Format.lineCount
 * 1.29 - Updated TableGenerator.format method

package/package.json

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

package/src/array.js

@@ -17,6 +17,7 @@ require('./_types/global');
  *   * {@link module:array.createSort|array.createSort(sortIndex, sortIndex, ...)} - generates a sorting function
  *   * {@link module:array.SORT_ASCENDING|array.SORT_ASCENDING} - common ascending sorting function for array.sort()
  *   * {@link module:array.SORT_DESCENDING|array.SORT_DESCENDING} - common descending sorting function for array.sort()
+ *   * {@link module:array.indexify|array.indexify} - identify sections within a 1d array to create a hierarchy.
  * * Rearrange Array
  *   * {@link module:array.reshape|array.reshape} - reshapes an array to a size of rows and columns
  *   * {@link module:array.transpose|array.transpose} - transposes (flips - the array along the diagonal)
@@ -504,3 +505,186 @@ module.exports.arrangeMulti = function arangeMulti(...dimensions) {
   return ArrayUtils.size(currentDimension, () => ArrayUtils.clone(childDimensionalValue));
 };
 module.exports.arangeMulti = module.exports.arrangeMulti;
+
+/** 
+ * Create a unique number index for each element in an array,
+ * alternatively using additional functions to indicate hierarchies of data.
+ * 
+ * For example, markdown can be considered a hierarchy of data:
+ * 
+ * ```
+ * markdownList = `# Overview
+ * This entire list is a hierarchy of data.
+ * 
+ * # Section A
+ * This describes section A
+ * 
+ * ## SubSection 1
+ * With a subsection belonging to Section A
+ * 
+ * ## SubSection 2
+ * And another subsection sibling to SubSection 1, but also under Section A.
+ * 
+ * # Section B
+ * With an entirely unrelated section B, that is sibling to Section A
+ * 
+ * ## SubSection 1
+ * And another subsection 1, but this time related to Section B.`;
+ * ```
+ * 
+ * And we want to convert this 1d array into a hierarchy.
+ * 
+ * ```
+ * data = markdownList.split('\n')
+ *    .filter(line => line ? true : false); // check for empty lines
+ * 
+ * utils.format.consoleLines( data, 4);
+ * // ['# Overview',
+ * // 'This entire list is a hierarchy of data.',
+ * // '# Section A',
+ * // 'This describes section A',;
+ * 
+ * //-- functions that return True if we are in a new "group"
+ * isHeader1 = (str) => str.startsWith('# ');
+ * 
+ * isHeader1('# Overview'); // true
+ * isHeader1('This entire list is a hierarchy of data'); // false
+ * isHeader1('# Section A'); // true
+ * 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
+ *   }
+ * ];
+ * ```
+ * 
+ * Note that this only indexes elements by the first header.
+ * 
+ * To index this with two levels of hierarchy, we can pass another function.
+ * 
+ * ```
+ * isHeader2 = (str) => str.startsWith('## ');
+ * 
+ * isHeader2('# Overview'); // false
+ * isHeader2('This entire list is a hierarchy of data'); // false
+ * isHeader2('# Section A'); // true
+ * isHeader2('This describes section A'); // false
+ * 
+ * indexedData = utils.array.indexify(data, isHeader1, isHeader2);
+ * // [
+ * //   { entry: 'Heading', section: [ 0, 0 ], subIndex: 1 },
+ * //   { entry: '# Overview', section: [ 1, 0 ], subIndex: 0 },
+ * //   {
+ * //     entry: 'This entire list is a hierarchy of data.',
+ * //     section: [ 1, 0 ],
+ * //     subIndex: 1
+ * //   },
+ * //   { entry: '# Section A', section: [ 2, 0 ], subIndex: 0 },
+ * //   { entry: 'This describes section A', section: [ 2, 0 ], subIndex: 1 },
+ * //   { entry: '## SubSection 1', section: [ 2, 1 ], subIndex: 0 },
+ * //   {
+ * //     entry: 'With a subsection belonging to Section A',
+ * //     section: [ 2, 1 ],
+ * //     subIndex: 1
+ * //   },
+ * //   { entry: '## SubSection 2', section: [ 2, 2 ], subIndex: 0 },
+ * //   {
+ * //     entry: 'And another subsection sibling to SubSection 1, but also under Section A.',
+ * //     section: [ 2, 2 ],
+ * //     subIndex: 1
+ * //   },
+ * //   { entry: '# Section B', section: [ 3, 0 ], subIndex: 0 },
+ * //   {
+ * //     entry: 'With an entirely unrelated section B, that is sibling to Section A',
+ * //     section: [ 3, 0 ],
+ * //     subIndex: 1
+ * //   },
+ * //   { entry: '## SubSection 1', section: [ 3, 1 ], subIndex: 0 },
+ * //   {
+ * //     entry: 'And another subsection 1, but this time related to Section B.',
+ * //     section: [ 3, 1 ],
+ * //     subIndex: 1
+ * //   }
+ * // ];
+ * ```
+ * 
+ * @param {Array} source - list of values to index
+ * @param {...Function} sectionIndicatorFunctions - each function indicates a new section
+ * @returns {Object[]} - collection of objects, each with a new section (indicating the layers) 
+ *            and subIndex: unique value in the section (always 0 for header)
+ */
+module.exports.indexify = function indexify(source, ...sectionIndicatorFunctions) {
+  const functionSignature = 'indexify(source, ...sectionIndicatorFunctions)';
+
+  const counters = new Array(sectionIndicatorFunctions.length).fill(0);
+  let subIndex = 0;
+  // counters[counters.length - 1] = -1;
+
+  //-- validate inputs
+  if (!Array.isArray(source)) {
+    throw new Error(`${functionSignature}: source must be an array`);
+  }
+  sectionIndicatorFunctions.forEach((fn) => {
+    if (typeof fn !== 'function') {
+      throw new Error(`${functionSignature}: all section indicators passed must be functions`);
+    }
+  });
+
+  const results = source.map((entry) => {
+    let isNewSectionTripped = false;
+
+    sectionIndicatorFunctions.forEach((fn, index) => {
+      if (isNewSectionTripped) {
+        counters[index] = 0;
+      } else {
+        isNewSectionTripped = fn(entry) ? true : false;
+
+        if (isNewSectionTripped) {
+          counters[index] += 1;
+        }
+      }
+    });
+
+    if (isNewSectionTripped) {
+      subIndex = 0;
+    } else {
+      subIndex += 1;
+    }
+
+    return ({ entry, section: [...counters], subIndex });
+  });
+
+  return results;
+};

package/src/object.js

@@ -16,12 +16,15 @@ const FormatUtils = require('./format');
  *   * {@link module:object.setPropertyDefaults|setPropertyDefaults()} - sets values for objects that don't currently have the property
  *   * {@link module:object.propertyValueSample|propertyValueSample(collection)} - finds non-empty values for all properties found in the collection
  * * Manipulating objects
- *   * {@link module:object.objAssign|objAssign()} -
- *   * {@link module:object.objAssignEntities|objAssignEntities()} -
+ *   * {@link module:object.assign|objAssign(object, property, value)} - Applies properties to an object in functional programming style.
+ *   * {@link module:object.assignEntities|objAssignEntities(object, [property, value])} - Applies properties to an object using Array values - [key,value]
+ *   * {@link module:object.augment|augment(object, augmentFn)} - Applies properties to an object similar to Map
+ *   * {@link module:object.augmentInherit|augmentInherit(object, augmentFn)} - Applies properties to a collection of objects, 'remembering' the last value - useful for 1d to *D lists.
  *   * {@link module:object.selectObjectProperties|selectObjectProperties()} - keep only specific properties
  *   * {@link module:object.filterObjectProperties|filterObjectProperties()} - remove specific properties
  *   * {@link module:object.mapProperties|mapProperties(collection, fn, ...properties)} - map multiple properties at once (like parseInt, or toString)
  *   * {@link module:object.formatProperties|formatProperties(collection, propertyTranslation)} - map specific properties (ex: toString, toNumber, etc)
+ *   * {@link module:object.union|union(objectList1, objectList2)} - Unites the properties of two collections of objects.
  * * Fetch child properties from related objects
  *   * {@link module:object.fetchObjectProperty|fetchObjectProperty(object, string)} - use dot notation to bring a child property onto a parent
  *   * {@link module:object.fetchObjectProperties|fetchObjectProperties(object, string[])} - use dot notation to bring multiple child properties onto a parent
@@ -1129,3 +1132,186 @@ module.exports.propertyValueSample = function propertyValueSample(objCollection)
 
   return result;
 };
+
+/**
+ * Appends values to a collection of objects,
+ * where if the value `undefined` is provided, 
+ * then it "remembers" or "inherits" the value previously used.
+ * 
+ * This is VERY useful for converting a 1 dimensional list, into a hierarchical tree structure.
+ * 
+ * For example, say we got this from a previous successful scrape:
+ * 
+ * ```
+ * source = [
+ *   { text: '# Overview' },
+ *   { text: 'This entire list is a hierarchy of data.' },
+ *   { text: '# Section A' },
+ *   { text: 'This describes section A' },
+ *   { text: '## SubSection 1' },
+ *   { text: 'With a subsection belonging to Section A' },
+ *   { text: '# Section B' },
+ *   { text: 'With an entirely unrelated section B, that is sibling to Section A' }
+ * ];
+ * ```
+ * 
+ * We would like to know which heading1 and heading2 the texts belong to:
+ * 
+ * ```
+ * 
+ * const isHeader1 = (str) => str.startsWith('# ');
+ * const isHeader2 = (str) => str.startsWith('## ');
+ * 
+ * //-- note, return undefined for any property you don't want to have inherited.
+ * inheritFn = (entry) => ({
+ *   section: isHeader1(entry.text) ? entry.text.replace(/#+\s+/, '') : undefined,
+ *   subSection: isHeader2(entry.text) ? entry.text.replace(/#+\s+/, '') : undefined
+ * });
+ * 
+ * results = utils.object.augmentInherit(source, inheritFn);
+ * ```
+ * 
+ * text                                                              |section  |subSection  
+ * --                                                                |--       |--          
+ * Overview                                                          |Overview |undefined            
+ * This entire list is a hierarchy of data.                          |Overview |undefined   
+ * Section A                                                         |Section A|undefined   
+ * This describes section A                                          |Section A|undefined   
+ * SubSection 1                                                      |Section A|SubSection 1
+ * With a subsection belonging to Section A                          |Section A|SubSection 1
+ * Section B                                                         |Section B|undefined   
+ * With an entirely unrelated section B, that is sibling to Section A|Section B|undefined   
+ * SubSection 1                                                      |Section B|SubSection 1
+ * And another subsection 1, but this time related to Section B.     |Section B|SubSection 1
+ * 
+ * So we pass the collection of results as the source, and an augment function,
+ * that returns the heading 1 value - that is then kept until the next heading 1.
+ * (Similar for subSection using heading 2)
+ * 
+ * @param {Object[]} source - the collection of objects to check and augment.
+ * @param {Function} augmentFn - function accepting each entry, and returning the properties to "inherit" <br /> or a property with a value of undefined - if it should not be preserved.
+ * @returns {Object[]} - new version of the source objects with the properties applied.
+ * 
+ *  @see {@link module:object.augment|augment()} - Applies properties to an object similar to Map
+ */
+module.exports.augmentInherit = function augmentInherit(source, augmentFn) {
+  const signature = 'augmentInherit(source, augmentFn)';
+  if (!Array.isArray(source)) {
+    throw new Error(`${signature}: source must be an array`);
+  } else if (typeof augmentFn !== 'function') {
+    throw new Error(`${signature}: augmentFn must be a function of signature: (entry, lastValue) => obj`);
+  }
+
+  let keys;
+
+  let lastValue = {};
+  return source.map((entry, index) => {
+    const fnResult = augmentFn(entry, lastValue);
+
+    //-- ignore all values that are undefined
+    const newValue = { ...lastValue };
+    let isFlipped = false;
+    keys = Object.keys(fnResult || {});
+    keys.forEach((key) => {
+      if (isFlipped) {
+        newValue[key] = undefined;
+      } else if (fnResult[key] !== undefined) {
+        newValue[key] = fnResult[key];
+        isFlipped = true;
+      }
+    });
+
+    // console.log(`index:${index}: entry:${JSON.stringify(entry)}, newValue:${JSON.stringify(newValue)}, lastValue:${JSON.stringify(lastValue)}`)
+    const result = ({ ...entry, ...newValue });
+    lastValue = newValue;
+    return result;
+  });
+};
+
+/**
+ * Unites the properties of two collections of objects.
+ * 
+ * For example:
+ * 
+ * ```
+ * source1 = [
+ *  { first: 'john' },
+ *  { first: 'jane' }
+ * ];
+ * source2 = [
+ *  { last: 'doe' },
+ *  { last: 'dough' }
+ * ];
+ * utils.object.union(source1, source2);
+ * // [{ first: 'john', last: 'doe' },
+ * //  { first: 'jane', last: 'dough' }];
+ * ```
+ * 
+ * Note that you can also pass a single object, to have it union to multiple.
+ * 
+ * ```
+ * source1 = [
+ *  { first: 'john' },
+ *  { first: 'jane' }
+ * ];
+ * //-- same object to be applied to all
+ * source2 = { last: 'doe' };
+ * 
+ * utils.object.union(source1, source2);
+ * // [{ first: 'john', last: 'doe' },
+ * //  { first: 'jane', last: 'doe' }];
+ * ```
+ * 
+ * @param {Object[]|Object} source1 - object or array of objects to union
+ * @param {Object[]|Object} source2 - object or array of objects to union
+ * @returns {Object[]} - collection of objects merging the values between the two sources
+ * 
+ * @see {@link module:object.join|join} - to instead join based on a value instead of index
+ * @see {@link module:object.filterObjectProperties|filterObjectProperties} - to remove properties from collection of objects.
+ */
+module.exports.union = function union(source1, source2) {
+  const signature = 'union(source1:object[], source2:object[])';
+  
+  let s1Iterator;
+  let s1Entry;
+  let s1Length;
+  let s2Iterator;
+  let s2Entry;
+  let s2Length;
+  
+  if (Array.isArray(source1)) {
+    s1Iterator = source1.entries();
+    s1Length = source1.length;
+  } else if (typeof source1 === 'object') {
+    s1Iterator = ({ next: () => ({ done: false, value: [0, source1] }) });
+    s1Length = 1;
+  } else {
+    throw new Error(`${signature}: source1 must be a collection of objects, or a single object`);
+  }
+
+  if (Array.isArray(source2)) {
+    s2Iterator = source2.entries();
+    s2Length = source2.length;
+  } else if (typeof source2 === 'object') {
+    s2Iterator = ({ next: () => ({ done: false, value: [0, source2] }) });
+    s2Length = 1;
+  } else {
+    throw new Error(`${signature}: source2 must be a collection of objects, or a single object`);
+  }
+
+  const len = Math.max(s1Length, s2Length);
+  const results = new Array(len);
+
+  for (let i = 0; i < len; i += 1) {
+    s1Entry = s1Iterator.next();
+    s1Entry = s1Entry.done ? {} : s1Entry.value[1];
+
+    s2Entry = s2Iterator.next();
+    s2Entry = s2Entry.done ? {} : s2Entry.value[1];
+
+    //console.log(`s1Entry: ${JSON.stringify(s1Entry)}, s2Entry: ${JSON.stringify(s2Entry)}`);
+    results[i] = { ...s1Entry, ...s2Entry };
+  }
+
+  return results;
+};