jupyter-ijavascript-utils 1.8.5 → 1.9.2

package/DOCS.md

@@ -28,7 +28,8 @@ See the [#Installation section for requirements and installation](#install)
 
 ## What's New
 
-* 1.8 - add in What can I Do tutorial, and object.join methods
+* 1.9 - allow {@link TableGenerator#transpose|transposing results} on TableGenerator.
+* 1.8 - add in What can I Do tutorial, and {@link module:object.join|object.join methods}
 * 1.7 - revamp of `animation` method for ijs.htmlScript
 * 1.6 - add SVG support for rendering SVGs and animations with {@link module:svg}.
 * 1.5 - Add LaTeX / KaTeX support with {@link module:latex} for rendering Math formulas and PlantUML support for Diagrams

package/Dockerfile

@@ -0,0 +1,34 @@
+# per https://github.com/n-riesco/ijavascript/issues/273
+# and https://github.com/paulroth3d/jupyter-ijavascript-utils/issues/4
+
+# as of today this is python-3.7.1
+FROM jupyter/base-notebook:latest
+
+# for nbhosting
+USER root
+COPY start-in-dir-as-uid.sh /usr/local/bin
+
+# prerequisites with apt-get
+# we do install python(2) here because
+# some npm build part named gyp still requires it
+RUN apt-get update && apt-get install -y gcc g++ make python
+
+# !!! dirty trick!!!
+# original PATH is
+# /opt/conda/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+# move conda's path **at the end**
+# so that python resolves in /usr/bin/python(2)
+# but node is still found in conda
+ENV PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/opt/conda/bin"
+USER jovyan
+RUN npm install -g ijavascript
+RUN ijsinstall
+
+# for displaying html fragments
+RUN npm install -g jsdom d3
+
+# !!! clean up!!!
+USER root
+RUN apt-get autoremove -y python
+ENV PATH="/opt/conda/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+USER jovyan

package/README.md

@@ -6,6 +6,9 @@
         <img src="https://img.shields.io/badge/License-MIT-green" />
     </a>
     <img src="https://img.shields.io/badge/Coverage-98-green" />
+    <a href="https://github.com/paulroth3d/jupyter-ijavascript-utils" alt="npm">
+        <img src="https://img.shields.io/badge/npm-%5E1.9.2-red" />
+    </a>
 </p>
 
 # Overview
@@ -18,6 +21,7 @@ See documentation at: [https://jupyter-ijavascript-utils.onrender.com/](https://
 
 # What's New
 
+* 1.9 - allow transposing results on TableGenerator.
 * 1.8 - add in What can I Do tutorial, and object.join methods
 * 1.7 - revamp of `animation` method to htmlScript
 * 1.6 - add SVG support for rendering SVGs and animations

package/package.json

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

package/src/TableGenerator.js

@@ -17,6 +17,8 @@ const generateRange = (length, defaultValue) => new Array(length).fill(defaultVa
 
 const IJSUtils = require('./ijs');
 
+const ArrayUtils = require('./array');
+
 const { createSort } = require('./array');
 
 /**
@@ -62,29 +64,32 @@ const { createSort } = require('./array');
  * * change the columns and headers
  *   * {@link TableGenerator#columns|columns(field, field, ...)} - specify fields and order
  *   * {@link TableGenerator#columnsToExclude|columnsToExclude(field, ...)} - specify fields not to show
- *   * {@link TableGenerator#labels|lables(obj} - labels for field headers
+ *   * {@link TableGenerator#labels|lables(obj)} - labels for field headers
  * * augment and change the values (non-destructively)
- *   * {@link TableGenerator#formatter|formatter(obj} - adjust values of specific fields
- *   * {@link TableGenerator#formatterFn|formatterFn(fn} - row, column aware adjustment
- *   * {@link TableGenerator#printOptions|printOptions(object} - options for value rendering
+ *   * {@link TableGenerator#formatter|formatter(obj)} - adjust values of specific fields
+ *   * {@link TableGenerator#formatterFn|formatterFn(fn)} - row, column aware adjustment
+ *   * {@link TableGenerator#printOptions|printOptions(object)} - options for value rendering
  *   * {@link TableGenerator#augment|augment(obj)} - add fields to table
  * * sort and limit the output
- *   * {@link TableGenerator#filter|filter(fn))} - determine which rows to include or not
- *   * {@link TableGenerator#limit|limit(number} - limit only specific # of rows
- *   * {@link TableGenerator#sortFn|sortFn(fn} - Standard Array sort function
- *   * {@link TableGenerator#sort|sort(field, field, ...} - sorts by fields, or descending with -
+ *   * {@link TableGenerator#filter|filter(fn)} - determine which rows to include or not
+ *   * {@link TableGenerator#limit|limit(number)} - limit only specific # of rows
+ *   * {@link TableGenerator#sortFn|sortFn(fn)} - Standard Array sort function
+ *   * {@link TableGenerator#sort|sort(field, field, ...)} - sorts by fields, or descending with '-'
+ * * transpose the output
+ *   * {@link TableGenerator#transpose|transpose()} - transposes the output prior to rendering
  * * style the table
- *   * {@link TableGenerator#styleTable|styleTable(string} - css style for the table
- *   * {@link TableGenerator#styleHeader|styleHeader(string} - css styles for the header row
+ *   * {@link TableGenerator#styleTable|styleTable(string)} - css style for the table
+ *   * {@link TableGenerator#styleHeader|styleHeader(string)} - css styles for the header row
  *   * {@link TableGenerator#styleRow|styleRow(fn)} - Function to style rows
- *   * {@link TableGenerator#styleCell|styleCell(fn} - Function to style cells
+ *   * {@link TableGenerator#styleCell|styleCell(fn)} - Function to style cells
  * * generate output
- *   * {@link TableGenerator#generateHTML|generateHTML(} - returns html table with the results
- *   * {@link TableGenerator#generateMarkdown|generateMarkdown(} - returns markdown with the results
- *   * {@link TableGenerator#generateCSV|generateCSV(} - generates a CSV with the results
- *   * {@link TableGenerator#generateArray|generateArray(} - generates an array for further process
+ *   * {@link TableGenerator#generateHTML|generateHTML()} - returns html table with the results
+ *   * {@link TableGenerator#generateMarkdown|generateMarkdown()} - returns markdown with the results
+ *   * {@link TableGenerator#generateCSV|generateCSV()} - generates a CSV with the results
+ *   * {@link TableGenerator#generateArray|generateArray()} - generates an array of headers and data for further process
+ *   * {@link TableGenerator#generateArray2|generateArray2()} - generates a single array for further process
  * * render in jupyter
- *   * {@link TableGenerator#render|render(} - renders the results in a table within jupyter
+ *   * {@link TableGenerator#render|render()} - renders the results in a table within jupyter
  * 
  */
 class TableGenerator {
@@ -191,6 +196,12 @@ class TableGenerator {
    */
   #styleCell = null;
 
+  /**
+   * Whether the data should be output transposed
+   * @type {Boolean}
+   */
+  #isTransposed = false;
+
   /**
    * Function to format a value for a cell
    * 
@@ -237,6 +248,7 @@ class TableGenerator {
     this.#styleHeader = '';
     this.#styleRow = null;
     this.#styleCell = null;
+    this.#isTransposed = false;
   }
 
   //--    GETTER SETTERS
@@ -781,6 +793,53 @@ class TableGenerator {
     return this;
   }
 
+  /**
+   * Transposes (flips along the diagonal) prior to output.
+   * 
+   * This can be very handy for wide, but short, tables.
+   * 
+   * For example, given the data:
+   * 
+   * ```
+   * const data = [
+   *   { name: 'John', color: 'green', age: 23, hair: 'blond', state: 'IL' },
+   *   { name: 'Jane', color: 'brown', age: 23, hair: 'blonde', state: 'IL' }
+   * ];
+   * ```
+   * 
+   * Running normally would give
+   * 
+   * ```
+   * new utils.TableGenerator(data)
+   *    .generateMarkdown();
+   * ```
+   * 
+   * name|color|age|hair  |state
+   * --  |--   |-- |--    |--
+   * John|green|23 |blond |IL
+   * Jane|brown|23 |blonde|IL
+   * 
+   * Running that transposed flips it.
+   * 
+   * ```
+   * new utils.TableGenerator(data)
+   *  .transpose()
+   *  .generateMarkdown();
+   * ```
+   * 
+   * name |John |Jane
+   * --   |--   |--
+   * color|green|brown
+   * age  |23   |23
+   * hair |blond|blonde
+   * state|IL   |IL
+   * @returns {TableGenerator}
+   */
+  transpose() {
+    this.#isTransposed = true;
+    return this;
+  }
+
   //-- Table Generation
 
   /**
@@ -833,7 +892,7 @@ class TableGenerator {
           record: row
         }));
 
-    const headers = keys.map(translateHeader);
+    let headers = keys.map(translateHeader);
     let data = cleanCollection.map(translateData);
 
     if (this.#limit < 0) {
@@ -842,6 +901,15 @@ class TableGenerator {
       data = data.slice(0, this.#limit);
     }
 
+    if (this.#isTransposed) {
+      let transposedResults = [headers, ...data];
+      transposedResults = ArrayUtils.transpose(transposedResults);
+
+      // eslint-disable-next-line prefer-destructuring
+      headers = transposedResults[0];
+      data = transposedResults.slice(1);
+    }
+
     return ({ headers, data });
   }
 
@@ -995,8 +1063,10 @@ class TableGenerator {
    */
 
   /**
-   * Generates an array of objects
+   * Generates an a result set to allow for further processing
    * 
+   * @see {@link TableGenerator#generateArray2|generateArray2()}
+   * @returns {TableArray}
    * @example
    * 
    * dataSet = [{reg:'z', source: 'A', temp: 99},
@@ -1019,14 +1089,44 @@ class TableGenerator {
    *     ['A', 100],
    *   ]
    * }
-   * 
-   * @returns {TableArray}
    */
-  generateArray() {
+  generateArray(returnUnifiedArray = false) {
     const results = this.prepare();
     return results;
   }
 
+  /**
+   * Generates an array of objects in a 2d Array
+   * 
+   * NOTE: this can be helpful for needing to transpose results
+   * 
+   * @returns {any[][]} - 2d array with both headers and data included
+   * @see {@link TableGenerator#generateArray|generateArray()}
+   * @example
+   * 
+   * dataSet = [{reg:'z', source: 'A', temp: 99},
+   *    {reg: 'z', source: 'B', temp: 98},
+   *    {reg: 'z', source:'A', temp: 100}
+   * ];
+   * 
+   * //-- only show the temp and source columns
+   * new TableGenerator(dataSet)
+   *  .columnsToExclude('reg') // or .columnsToExclude(['reg'])
+   *  .generateArray2();
+   * 
+   * //--
+   * [
+   *  ['source', 'temp'],
+   *  ['A', 99],
+   *  ['B', 98],
+   *  ['A', 100],
+   * ];
+   */
+  generateArray2() {
+    const results = this.prepare();
+    return [...results.headers, ...results.data];
+  }
+
   /**
    * Renders the html table in the cell results.
    * 

package/src/file.js

@@ -26,6 +26,8 @@ const logger = require('./logger');
  * * listing directory
  *   * {@link module:file.pwd|pwd()} - list the current path
  *   * {@link module:file.listFiles|listFiles(path)} - list files in a diven path
+ * * checking files exist
+ *   * {@link module:file.checkFile|checkFile(...paths)} - check if a file at a path exists
  * 
  * ---
  * 
@@ -299,3 +301,87 @@ module.exports.listFiles = function listFiles(directoryPath) {
     logger.error(`unable to read directory: ${resolvedPath}`);
   }
 };
+
+/**
+ * Synchronously checks if any of the files provided do not exist.
+ * 
+ * For example:
+ * 
+ * ```
+ * //-- these exist
+ * // ./data/credentials.env
+ * // ./data/results.json
+ * 
+ * if (!utils.file.checkFile('./data/results.json')) {
+ *    //-- retrieve the results
+ *    utils.ijs.await(async($$, console) => {
+ *      results = await connection.query('SELECT XYZ from Contacts');
+ *      utils.file.write('./data/results.json', results);
+ *    });
+ * } else {
+ *    results = utils.file.readJSON('./data/results.json');
+ * }
+ * ```
+ * 
+ * Note, you can also ask for multiple files at once
+ * 
+ * ```
+ * utils.file.checkFile(
+ *    './data/credentials.env',
+ *    './data/results.json',
+ *    './data/results.csv'
+ * );
+ * // false
+ * ```
+ * 
+ * or as an array:
+ * 
+ * ```
+ * utils.file.checkFile(['./data/credentails.env']);
+ * // true
+ * ```
+ * 
+ * @param  {...String} files - List of file paths to check (can use relative paths, like './') <br />
+ *    see {@link file:listFiles|listFiles()} or {@link file:pwd|pwd()} to help you)
+ * @returns {String[]} - null if all files are found, or array of string paths of files not found
+ */
+module.exports.checkFile = function checkFile(...files) {
+  //-- allow passing an array of files
+  const cleanFiles = files.length === 1 && Array.isArray(files[0])
+    ? files[0]
+    : files;
+  
+  const resolvedFiles = cleanFiles.map((unresolvedPath) => path.resolve(unresolvedPath));
+
+  const notFoundFiles = resolvedFiles.map((resolvedPath) => fs.existsSync(resolvedPath)
+    ? null
+    : resolvedPath);
+  
+  //-- do not filter empty files, as position in array is helpful
+  if (notFoundFiles.filter((p) => p).length === 0) {
+    return null;
+  }
+
+  return notFoundFiles;
+};
+
+/*
+ * Execute an async function if any of the files do not exist
+ * @param {String[]} filePaths - list of paths of files to check that they exist
+ * @param {*} fnIfFailed - async function tha will run - but only if any of the files are not found.
+ */
+/*
+module.exports.ifNotExists = async function ifNotExists(filePaths, fnIfFailed) {
+  const filesNotFound = FileUtil.checkFile(filePaths);
+
+  let results;
+
+  if (filesNotFound) {
+    results = await fnIfFailed(filesNotFound);
+  } else {
+    results = null;
+  }
+
+  return results;
+};
+*/

package/src/format.js

@@ -9,6 +9,9 @@
  * * formatting Numbers
  *   * {@link module:format.zeroFill|format.zeroFill} - Pads a number to a specific length
  *   * {@link module:format.divideR|format.divideR}   - Divides a number to provide { integer, remainder } - ex: 5/3 as ( 1, remainder 2 )
+ * * Formatting Strings
+ *   * {@link module:format.capitalize|format.capitalize} - Capitalizes only the first character in the string (ex: 'John paul');
+ *   * {@link module:format.capitalizeAll|format.capitalizeAll} - Capitalizes all the words in a string (ex: 'John Paul')
  * * Formatting Time
  *   * {@link module:format.millisecondDuration|format.millisecondDuration}
  * * Mapping Values
@@ -454,3 +457,40 @@ module.exports.clampDomain = function clampDomain(value, [minimum, maximum]) {
   }
   return value;
 };
+
+/**
+ * Capitalizes the first character of the string.
+ * 
+ * @param {String} str - String to capitalize the first letter only
+ * @returns {String} - ex: 'John paul'
+ * @see {@link module:format.capitalizeAll|capitalizeAll} - to capitalize all words in a string
+ * @example
+ * utils.format.capitalize('john'); // 'John'
+ * utils.format.capitalize('john doe'); // 'John doe'
+ */
+module.exports.capitalize = function capitalize(str) {
+  if (!str || str.length === 0) {
+    return '';
+  }
+
+  //-- charAt does not work for unicode
+  const [first, ...rest] = str;
+  return first.toLocaleUpperCase() + rest.join('');
+};
+
+/**
+ * Capitalizes all words in a string.
+ * 
+ * @param {String} str - String to capitalize
+ * @returns {String} - ex: 'John-Paul'
+ * @see {@link module:format.capitalizeAll|capitalizeAll} - to capitalize all words in a string
+ * @example
+ * utils.format.capitalize('john'); // 'John'
+ * utils.format.capitalize('john doe'); // 'John Doe'
+ * utils.format.capitalize('john-paul'); // 'John-Paul'
+ */
+module.exports.capitalizeAll = function capitalizeAll(str) {
+  return (str || '').split(/\b/)
+    .map(FormatUtils.capitalize)
+    .join('');
+};

package/src/ijs.js

@@ -135,7 +135,7 @@ module.exports.await = async function ijsAsync(fn) {
   context.$$.async();
 
   try {
-    const results = fn(context.$$, context.console);
+    const results = await fn(context.$$, context.console);
     context.$$.sendResult(results);
   } catch (err) {
     context.console.error('error occurred');

package/src/object.js

@@ -9,6 +9,9 @@ const schemaGenerator = require('generate-schema');
  *   * {@link module:object.keys|keys()} - Safely get the keys of an object or list of objects
  *   * {@link module:object.getObjectPropertyTypes|getObjectPropertyTypes()} - describe the properties of a list of objects
  *   * {@link module:object.generateSchema|generateSchema()} - generate a schema / describe properties of a list of objects
+ *   * {@link module:object.findWithoutProperties|findWithoutProperties()} - find objects without ALL the properties specified
+ *   * {@link module:object.findWithoutProperties|findWithProperties()} - find objects with any of the properties specified
+ *   * {@link module:object.setPropertyDefaults|setPropertyDefaults()} - sets values for objects that don't currently have the property
  * * Manipulating objects
  *   * {@link module:object.objAssign|objAssign()} -
  *   * {@link module:object.objAssignEntities|objAssignEntities()} -
@@ -634,3 +637,154 @@ module.exports.joinProperties = function join(objectArray, indexField, targetMap
 
   return ObjectUtils.join(objectArray, indexField, targetMap, joinFn);
 };
+
+/**
+ * Finds objects that do not have ALL the properties specified.
+ *
+ * This can be very helpful in ensuring all objects actually meet a specification and are not missing values.
+ * 
+ * ```
+ * const students = [
+ *   { first: 'john', last: 'doe', age: 23 }, { first: 'jane', last: 'doe', age: 23 }, { first: 'jack', last: 'white', failure: 401 }
+ * ];
+ *
+ * utils.findWithoutProperties(students, 'first', 'last', 'age');
+ * // [{ first: 'jack', last: 'white', failure: 401 }]
+ * 
+ * utils.findWithoutProperties(students, 'failure');
+ * // [{ first: 'john', last: 'doe', age: 23 }, { first: 'jane', last: 'doe', age: 23 }] 
+ * ```
+ *
+ * Please note, that we can check a single object:
+ *
+ * ```
+ * utils.findWithoutProperties(students[0], 'failure');
+ * // []
+ * ```
+ * 
+ * @param {Object[]} objectsToCheck - the array of objects to check for the properties.
+ * @param {...String} propertiesToFind - the list of properties to find within the collection.
+ * @returns {Object[]} - Array of objects that are missing at least one of those properties
+ * @see {@link module:file.findWithProperties|findWithProperties} - if you want objects that do not have all properties
+ **/
+module.exports.findWithoutProperties = function findWithoutProperties(targetObj, ...propertiesToFind) {
+  const cleanProperties = propertiesToFind.length > 0 && Array.isArray(propertiesToFind[0])
+    ? propertiesToFind[0]
+    : propertiesToFind;
+  
+  const cleanTargets = Array.isArray(targetObj)
+    ? targetObj
+    : [targetObj];
+  
+  const results = [];
+      
+  cleanTargets.forEach((target) => {
+    if (cleanProperties.find((prop) => (typeof target[prop]) === 'undefined')) {
+      results.push(target);
+    }
+  });
+  
+  return results;
+};
+
+/**
+ * Finds objects that have any of the properties specified.
+ * 
+ * This can be very helpful when working with datasets that include mixed data (such as JSON)
+ * 
+ * ```
+ * const students = [
+ *   { first: 'john', last: 'doe' }, { first: 'jane', last: 'doe' }, { first: 'jack', last: 'white', failure: 401 }
+ * ];
+ *
+ * utils.findWithProperties(students, 'failure');
+ * // { first: 'jack', last: 'white', failure: 401 }
+ * ```
+ *
+ * Please note, that we can check a single object:
+ *
+ * ```
+ * utils.findWithProperties({ first: 'john', last: 'doe' }, 'failure');
+ * // []
+ * ```
+ * 
+ * @param {Object[]} objectsToCheck - the array of objects to check for the properties.
+ * @param {...String} propertiesToFind - the list of properties to find within the collection.
+ * @returns {Object[]} - Array of objects that have at least one of those properties
+ * @see {@link module:file.findWithoutProperties|findWithoutProperties} - if you want objects that do not have all properties
+ **/
+module.exports.findWithProperties = function findWithProperties(targetObj, ...propertiesToFind) {
+  const cleanProperties = propertiesToFind.length > 0 && Array.isArray(propertiesToFind[0])
+    ? propertiesToFind[0]
+    : propertiesToFind;
+
+  const cleanTargets = Array.isArray(targetObj)
+    ? targetObj
+    : [targetObj];
+   
+  const results = [];
+       
+  cleanTargets.forEach((target) => {
+    if (cleanProperties.find((prop) => (typeof target[prop]) !== 'undefined')) {
+      results.push(target);
+    }
+  });
+
+  return results;
+};
+
+/**
+ * Sets values for objects that don't currently have the property
+ * 
+ * This is very helpful for ensuring that all objects have a property,
+ * or setting a value to make it easier to identify that it is 'N/A'
+ * 
+ * Note, that only the {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/hasOwnProperty|ownProperties}
+ * on the default object are checked.
+ * 
+ * And values are applied to the target object, only if the property is not on the object (property is undefined)
+ * 
+ * @param {Object[] | Object} targetObject - Object to apply the properties to <br />
+ *              but ONLY if the object does not have that property (ex: undefined)
+ * @param {Object} defaultObj - Object with the properties and defaults applied
+ * @param {any} defaultObj.property - the property to check, with the default value assigned
+ * @see {@link module:file.findWithoutProperties|findWithoutProperties} - to determine if any objects do not have a set of properties
+ * @see {@link module:file.keys|keys} - to get a list of unique properties of all objects in a list.
+ * @example
+ * const students = [
+ *   { first: 'john', last: 'doe', birthday: '2002-04-01' },
+ *   { first: 'jane', last: 'doe', birthday: '2003-05-01' },
+ *   { first: 'jack', last: 'white', failure: 401 }
+ * ];
+ * 
+ * utils.object.setPropertyDefaults(students, {
+ *  first: '',
+ *  last: '',
+ *  birthday: ''
+ * });
+ * 
+ * // [
+ * //   { first: 'john', last: 'doe', birthday: '2002-04-01' },
+ * //   { first: 'jane', last: 'doe', birthday: '2003-05-01' },
+ * //   { first: 'jack', last: 'white', birthday: '', failure: 401 }
+ * // ];
+ */
+module.exports.setPropertyDefaults = function setPropertyDefaults(targetObject, defaultObj) {
+  const cleanTargets = Array.isArray(targetObject)
+    ? targetObject
+    : [targetObject];
+  
+  if (!defaultObj || typeof defaultObj !== 'object') {
+    throw Error('object.setPropertyDefaults(targetObject, defaultObject): defaultObject is expected to be an object with properties set to the defaults to apply');
+  }
+
+  const defaultKeys = Object.getOwnPropertyNames(defaultObj);
+
+  cleanTargets.forEach((target) => {
+    defaultKeys.forEach((prop) => {
+      if (typeof target[prop] === 'undefined') {
+        target[prop] = defaultObj[prop];
+      }
+    });
+  });
+};