jupyter-ijavascript-utils 1.24.0 → 1.26.0

package/DOCS.md

@@ -75,6 +75,8 @@ Give it a try here:
 
 ## What's New
 
+* 1.26 - Support for file.writeFile and file.writeJSON to append
+* 1.25 - Additional chain methods and documentation
 * 1.24 - format.stripHtmlTags, TableGenerator.offset, chain.chainFlatMap, chain.chainFilter
 * 1.23 - add format.parseNumber and TableGenerator.styleColumn, align group.separateByFields to vega-lite fold transform
 * 1.22 - make chain iJavaScript aware, but still able to work outside of Jupyter

package/Dockerfile

@@ -1,3 +1,3 @@
 # syntax=docker/dockerfile:1
 
-FROM darkbluestudios/jupyter-ijavascript-utils:binder_1.24.0
+FROM darkbluestudios/jupyter-ijavascript-utils:binder_1.26.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.26 - Support for file.writeFile and file.writeJSON to append
+* 1.25 - Additional chain methods and documentation
 * 1.24 - format.stripHtmlTags, TableGenerator.offset, chain.chainFlatMap, chain.chainFilter
 * 1.23 - add format.parseNumber and TableGenerator.styleColumn, align group.separateByFields to vega-lite fold transform
 * 1.22 - make chain iJavaScript aware, but still able to work outside of Jupyter

package/package.json

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

package/src/chain.js

@@ -8,17 +8,129 @@
  * Very helpful for taking values and then progressively working on them,
  * instead of continually wrapping deeper in method calls.
  * 
- * Calling `chain(3)` - gives an object with two properties:
+ * Calling `chain(3)` - gives an object you can then chain calls against:
  * 
  * * {@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#chainMap|.chainMap(function)} - where it treats value as an array, and maps function on every item in the array
- * * {@link ChainContainer#chainFlatMap|.chainFlatMap(function)} - where it treats value as an array, and maps function on every item in the array,
- *        flattening the results
- * * {@link ChainContainer#chainFilter|.chainFilter(function)} - where it treats the value as an array, and filters values based on the result
- * * {@link ChainContainer#chainReduce|.chainReduce(function, initialValue)} - where it treats value as an array, and reduces the value array
  * * {@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.
+ * 
+ * * {@link ChainContainer#chainMap|.chainMap(function)} - where it calls the `.map` on value, and applies the function on every item in the array,
+ *      storing the result from the function. <br /> <b>(Useful for changing values without changing the original object))</b>
+ * * {@link ChainContainer#chainForEach|.chainForEach(function)} - where calls `.forEach` on value, and applies the function on every item,
+ *      without storing the result from the function. <br /> <b>(Useful for changing objects in-place)</b>
+ * * {@link ChainContainer#chainFlatMap|.chainFlatMap(function)} - where it calls `.flatMap` on value, and applies the function on every item,
+ *        flattening the results. <br /> <b>(Useful for expanding an array based on values in the array)</b>
+ * * {@link ChainContainer#chainFilter|.chainFilter(function)} - where it calls `.filter` on value, using the function on every item,
+ *        keeping the item in the list if the function returns true.
+ *        <br /> <b>(Useful for removing items from an array)</b>
+ * * {@link ChainContainer#chainReduce|.chainReduce(function, initialValue)} - where it calls `.reduce` on value, and reduces the value
+ *        to a single result.
+ *        <br /> <b>(Useful for reducing the array to a single value <br /> - like a concatenated string or sum total)</b>
+ * 
+ * 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#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.
+ * 
+ * For example:
+ * 
+ * ```
+ * addTwo = (value) => value + 2;
+ * 
+ * //-- we can always get the value
+ * utils.chain(3).close();  // 3
+ * ```
+ * 
+ * but this is much easier if we continue to chain it
+ * 
+ * ```
+ * addTwo = (value) => value + 2;
+ * addTwo(3); // 5
+ * 
+ * utils.chain(3)
+ *   .chain(addTwo) // (3 + 2)
+ *   .chain(addTwo) // (5 + 2)
+ *   .debug() // consoles 7 and passes the value along
+ *   // define a function inline
+ *   .chain((value) => value + 3) // (7 + 3)
+ *   .close()
+ * 
+ * // consoles out value `7`
+ * // returns value 10
+ * ```
+ * 
+ * Note that we can also map against values in the array
+ * 
+ * ```
+ * initializeArray = (size) => Array.from(Array(size)).map((val, index) => index);
+ * initializeArray(3); // [0, 1, 2]
+ * 
+ * addTwo = (value) => value + 2;
+ * addTwo(3); // 5
+ * 
+ * utils.chain(3)
+ *   .chain(initializeArray) // [0, 1, 2]
+ *   .chainMap(addTwo) // [2, 3, 4] or [0 + 2, 1 + 2, 2 + 2]
+ *   .chainMap(addTwo)
+ *   .close();
+ * // [4, 5, 6]
+ * ```
+ * 
+ * Chain to log results while transforming values
+ * 
+ * ```
+ * results = [{ userId: 'abc123' }, { userId: 'xyz987' }];
+ * 
+ * activeUsers = chain(results)
+ *  .chainMap((record) => users.get(record.userId))
+ *  .chainForEach(record => record.status =  'active')
+ *  .chain(records => d3.csv.format(records))
+ *  .execute(records => utils.file.writeFile('./log', d3.csv.format(records)))
+ *  .close()
+ * ```
+ * 
+ * Or even combine with other utility methods
+ * 
+ * ```
+ * badStr = 'I%20am%20the%20very%20model%20of%20a%20modern%20Major'
+ *  + '-General%0AI\'ve%20information%20vegetable%2C%20animal%2C%20'
+ *  + 'and%20mineral%0AI%20know%20the%20kings%20of%20England%2C%20'
+ *  + 'and%20I%20quote%20the%20fights%0AHistorical%0AFrom%20Marath'
+ *  + 'on%20to%20Waterloo%2C%20in%20order%20categorical';
+ * 
+ * chain(badStr)
+ *     .chain(decodeURIComponent)
+ *     .chain(v => v.split('\n'))
+ *     // .debug()                  // check the values along the way
+ *     .chainMap(line => ({ line, length: line.length }))
+ *     .chain(values => utils.table(values).render());
+ * ```
+ * 
+ * this can be more legible than the normal way to write this, <br />
+ * especially if you need to troubleshoot the value halfway through.
+ * 
+ * ```
+ * utils.table(
+ *  decodeURIComponent(badStr)
+ *    .split('\n')
+ *    .map(line => ({ line, length: line.length }))
+ * ).render()
+ * ```
+ * 
+ * and it renders out a lovely table like this:
+ * 
+ * line                                               |length
+ * --                                                 |--    
+ * I am the very model of a modern Major-General      |45    
+ * I've information vegetable, animal, and mineral    |47    
+ * I know the kings of England, and I quote the fights|51    
+ * Historical                                         |10    
+ * From Marathon to Waterloo, in order categorical    |47    
  */
 class ChainContainer {
   /**
@@ -134,7 +246,9 @@ class ChainContainer {
   }
 
   /**
-   * Assuming that value is an array, this maps fn to every value in the array.
+   * Assuming that value is an array, this does a
+   * [javascript array.map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map)
+   * and applies `fn` to every value in the array.
    * 
    * ```
    * initializeArray = (size) => Array.from(Array(size)).map((val, index) => index);
@@ -152,6 +266,8 @@ class ChainContainer {
    * // [4, 5, 6]
    * ```
    * 
+   * This is in contrast to {@link ChainContainer#chainForEach|chainForEach}
+   * 
    * @param {Function} fn - applies function under every index of this.value
    * @returns {ChainContainer} 
    */
@@ -161,6 +277,39 @@ class ChainContainer {
     return this.chain((value) => value.map(fn));
   }
 
+  /**
+   * Assuming that value is an array, performs a 
+   * [javaScript forEach](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach)
+   * against the results.
+   * 
+   * This will run the passed function against every element in the result,
+   * without replacing the element with the returned value and makes inline editing simpler.
+   * 
+   * ```
+   * list = [{ first: 'john', last: 'doe' }, { first: 'jane', last: 'doe' }];
+   * utils.chain(list)
+   *  .mapForEach((entry) => entry.name = `${entry.first} ${entry.last})
+   *  .close();
+   * // [{ first: 'john', last: 'doe', name: 'john doe' }, { first: 'jane', last: 'doe', name: 'jane doe' }]
+   * ```
+   * 
+   * This is in contrast to {@link ChainContainer#chainMap|chainMap}, that replaces the element with the value returned.
+   * @param {Function(any):any} fn - function to execute on each element
+   * @returns {ChainContainer} - chainable container
+   */
+  chainForEach(fn) {
+    if (!Array.isArray(this.value)
+      && !(this.value instanceof Set)
+      && !(this.value instanceof Map)
+    ) {
+      throw Error(`chainForEach expects an array, but was passed:${this.value}`);
+    }
+
+    this.value.forEach(fn);
+
+    return this;
+  }
+
   /**
    * Assuming that value is an array, performs a
    * [javaScript flatMap](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flatMap)
@@ -287,6 +436,28 @@ class ChainContainer {
     return this;
   }
 
+  /**
+   * Applies a function against the current value, while not passing the results along the chain.
+   * 
+   * ```
+   * results = [{ userId: 'abc123' }, { userId: 'xyz987' }];
+   * 
+   * activeUsers = chain(results)
+   *  .chainMap((record) => users.get(record.userId))
+   *  .chainForEach(record => record.status =  'active')
+   *  .chain(records => d3.csv.format(records))
+   *  .execute(records => utils.file.writeFile('./log', d3.csv.format(records)))
+   *  .close()
+   * ```
+   * 
+   * @param {Function} fn - function to execute against the current value
+   * @returns {ChainContainer}
+   */
+  execute(fn) {
+    fn(this.value);
+    return this;
+  }
+
   /**
    * Function to call if an error occurs anywhere on the chain.
    * 
@@ -325,6 +496,20 @@ class ChainContainer {
     return this;
   }
 
+  /**
+   * Normally, you will want to replace the value in the chain
+   * based on the current value.
+   * 
+   * This replaces the value regardless, and is rarely used.
+   * 
+   * @param {any} value - new value in the chain.
+   * @returns {ChainContainer}
+   */
+  replace(value) {
+    this.value = value;
+    return this;
+  }
+
   /**
    * Closes the chain and returns the current value.
    * @returns {any}
@@ -422,27 +607,42 @@ class ChainContainer {
  * Very helpful for taking values and then progressively working on them,
  * instead of continually wrapping deeper in method calls.
  * 
- * Calling `chain(3)` - gives an object you can either use the value of, or continue the chain going.
+ * Calling `chain(3)` - gives an object you can then chain calls against:
  * 
  * * {@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#chainMap|.chainMap(function)} - where it treats value as an array, and maps function on every item in the array
- * * {@link ChainContainer#chainFlatMap|.chainFlatMap(function)} - where it treats value as an array, and maps function on every item in the array,
- *        flattening the results
- * * {@link ChainContainer#chainFilter|.chainFilter(function)} - where it treats the value as an array, and filters values based on the result
- * * {@link ChainContainer#chainReduce|.chainReduce(function, initialValue)} - where it treats value as an array, and reduces the value array
  * * {@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.
+ * 
+ * * {@link ChainContainer#chainMap|.chainMap(function)} - where it calls the `.map` on value, and applies the function on every item in the array,
+ *      storing the result from the function. <br /> <b>(Useful for changing values without changing the original object))</b>
+ * * {@link ChainContainer#chainForEach|.chainForEach(function)} - where calls `.forEach` on value, and applies the function on every item,
+ *      without storing the result from the function. <br /> <b>(Useful for changing objects in-place)</b>
+ * * {@link ChainContainer#chainFlatMap|.chainFlatMap(function)} - where it calls `.flatMap` on value, and applies the function on every item,
+ *        flattening the results. <br /> <b>(Useful for expanding an array based on values in the array)</b>
+ * * {@link ChainContainer#chainFilter|.chainFilter(function)} - where it calls `.filter` on value, using the function on every item,
+ *        keeping the item in the list if the function returns true.
+ *        <br /> <b>(Useful for removing items from an array)</b>
+ * * {@link ChainContainer#chainReduce|.chainReduce(function, initialValue)} - where it calls `.reduce` on value, and reduces the value
+ *        to a single result.
+ *        <br /> <b>(Useful for reducing the array to a single value <br /> - like a concatenated string or sum total)</b>
+ * 
+ * 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#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.
+ * 
  * For example:
  * 
  * ```
  * addTwo = (value) => value + 2;
  * 
  * //-- we can always get the value
- * console.log(
- *  utils.chain(3).value
- * ); // 3
+ * utils.chain(3).close();  // 3
  * ```
  * 
  * but this is much easier if we continue to chain it
@@ -451,18 +651,16 @@ class ChainContainer {
  * addTwo = (value) => value + 2;
  * addTwo(3); // 5
  * 
- * console.log(
- *  utils.chain(3)
- *    .chain(addTwo) // (3 + 2)
- *    .chain(addTwo) // (5 + 2)
- *    .debug() // consoles 7 and passes the value along
- *    // define a function inline
- *    .chain((value) => value + 3) // (7 + 3)
- *    .value
- * );
- * 
- * // 7
- * // 10
+ * utils.chain(3)
+ *   .chain(addTwo) // (3 + 2)
+ *   .chain(addTwo) // (5 + 2)
+ *   .debug() // consoles 7 and passes the value along
+ *   // define a function inline
+ *   .chain((value) => value + 3) // (7 + 3)
+ *   .close()
+ * 
+ * // consoles out value `7`
+ * // returns value 10
  * ```
  * 
  * Note that we can also map against values in the array
@@ -478,10 +676,23 @@ class ChainContainer {
  *   .chain(initializeArray) // [0, 1, 2]
  *   .chainMap(addTwo) // [2, 3, 4] or [0 + 2, 1 + 2, 2 + 2]
  *   .chainMap(addTwo)
- *   .value;
+ *   .close();
  * // [4, 5, 6]
  * ```
  * 
+ * Chain to log results while transforming values
+ * 
+ * ```
+ * results = [{ userId: 'abc123' }, { userId: 'xyz987' }];
+ * 
+ * activeUsers = chain(results)
+ *  .chainMap((record) => users.get(record.userId))
+ *  .chainForEach(record => record.status =  'active')
+ *  .chain(records => d3.csv.format(records))
+ *  .execute(records => utils.file.writeFile('./log', d3.csv.format(records)))
+ *  .close()
+ * ```
+ * 
  * Or even combine with other utility methods
  * 
  * ```
@@ -499,6 +710,17 @@ class ChainContainer {
  *     .chain(values => utils.table(values).render());
  * ```
  * 
+ * this can be more legible than the normal way to write this, <br />
+ * especially if you need to troubleshoot the value halfway through.
+ * 
+ * ```
+ * utils.table(
+ *  decodeURIComponent(badStr)
+ *    .split('\n')
+ *    .map(line => ({ line, length: line.length }))
+ * ).render()
+ * ```
+ * 
  * and it renders out a lovely table like this:
  * 
  * line                                               |length

package/src/file.js

@@ -18,8 +18,8 @@ const logger = require('./logger');
  * (or storing and loading json data)
  * 
  * * Writing files
- *   * {@link module:file.writeFile|writeFile(path, string)} - write a file as plain text
- *   * {@link module:file.writeJSON|writeJSON(path, any)} - write data as JSON
+ *   * {@link module:file.writeFile|writeFile(path, string)} - write or append to file with plain text
+ *   * {@link module:file.writeJSON|writeJSON(path, any)} - write or append to a file with objects converted to JSON
  * * reading files
  *   * {@link module:file.readFile|readFile(path, string)} - read a file as plain text
  *   * {@link module:file.readJSON|readJSON(path, any)} - read data as JSON
@@ -179,11 +179,7 @@ module.exports.readFile = function readFile(filePath, fsOptions = {}) {
  * 
  * NOTE that this uses `utf-8` as the default encoding
  * 
- * @param {string} filePath - path of the file to write
- * @param {Object} fsOptions - options to pass for fsRead (ex: { encoding: 'utf-8' })
- * @param {string} contents - contents of the file
- * @see {@link module:file.readJSON|readJSON(filePath, fsOptions)} - for reading
- * @example
+ * ```
  * const weather = [
  *   { id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87 },
  *   { id: 0, city: 'Seattle',  month: 'Apr', precip: 2.68 },
@@ -199,16 +195,52 @@ module.exports.readFile = function readFile(filePath, fsOptions = {}) {
  * 
  * const myWeather = utils.file.readJSON('./data/weather.json');
  * myWeather.length; // 9
+ * ```
+ * 
+ * Note, passing `append:true` in the options, will let you append text before writing,
+ * useful for dealing with large and complex files.
+ * 
+ * ```
+ * weatherEntry1 = { id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87 };
+ * weatherEntry2 = { id: 0, city: 'Seattle',  month: 'Apr', precip: 2.68 };
+ * weatherEntry3 = { id: 2, city: 'Seattle',  month: 'Dec', precip: 5.31 };
+ * 
+ * utils.file.writeJSON('./data/weather2.json', weatherEntry1, { prefix: '[' });
+ * utils.file.writeJSON('./data/weather2.json', weatherEntry2, { append: true, prefix: ', ' });
+ * utils.file.writeJSON('./data/weather2.json', weatherEntry3, { append: true, prefix: ', ', suffix: ']' });
+ * 
+ * utils.file.readJSON('./data/weather.json');
+ * 
+ * //-- single line shown here on multiple lines for clarity
+ * // [{"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 {string} filePath - path of the file to write
+ * @param {string} contents - contents of the file
+ * @param {Object} fsOptions - [nodejs fs writeFileSync, appendFileSync options](https://nodejs.org/api/fs.html)
+ * @param {Boolean} fsOptions.append - if true, will append the text to the file
+ * @param {Boolean} fsOptions.prefix - string to add before writing the json, like an opening bracket '[' or comma ','
+ * @param {Boolean} fsOptions.prefix - string to add before writing the json, like a closing bracket ']'
+ * @param {String} fsOptions.encoding - encoding to use when writing the file.
+ * @see {@link module:file.readJSON|readJSON(filePath, fsOptions)} - for reading
  */
 module.exports.writeJSON = function writeJSON(filePath, contents, fsOptions = {}) {
   //-- if it isn't desired, simply pass as a string.
   const jsonContents = JSON.stringify(contents, null, 2);
   const optionsDefaults = { encoding: 'utf-8' };
   const cleanedOptions = { ...optionsDefaults, ...fsOptions };
+  const isAppend = cleanedOptions.append === true;
+  const prefix = cleanedOptions.prefix || '';
+  const suffix = cleanedOptions.suffix || '';
 
   // const resolvedPath = path.resolve(filePath);
   try {
-    fs.writeFileSync(filePath, jsonContents, cleanedOptions);
+    if (isAppend) {
+      fs.appendFileSync(filePath, prefix + jsonContents + suffix, cleanedOptions);
+    } else {
+      fs.writeFileSync(filePath, prefix + jsonContents + suffix, cleanedOptions);
+    }
   } catch (err) {
     logger.error(`unable to write to file: ${filePath}`);
   }
@@ -219,23 +251,35 @@ module.exports.writeJSON = function writeJSON(filePath, contents, fsOptions = {}
  * 
  * Note that this uses `utf-8` as the encoding by default
  * 
- * @param {string} filePath - path of the file to write
- * @param {string} contents - contents of the file
- * @see {@link module:file.readFile|readFile(filePath, fsOptions)} - for reading
- * @example
+ * ```
  * const myString = `hello`;
  * utils.file.writeFile('./tmp', myString);
  * const newString = utils.file.readFile('./tmp');
  * newString; // 'hello';
+ * ```
+ * 
+ * Note, you can append to the file by passing `{append:true}` in the options.
+ * 
+ * @param {string} filePath - path of the file to write
+ * @param {string} contents - contents of the file
+ * @param {Object} fsOptions - [nodejs fs writeFileSync, appendFileSync options](https://nodejs.org/api/fs.html)
+ * @param {Boolean} fsOptions.append - if true, will append the text to the file
+ * @param {String} fsOptions.encoding - encoding to use when writing the file.
+ * @see {@link module:file.readFile|readFile(filePath, fsOptions)} - for reading
  */
 module.exports.writeFile = function writeFile(filePath, contents, fsOptions = {}) {
   const resolvedPath = path.resolve(filePath);
   const optionsDefaults = { encoding: 'utf-8' };
   const cleanedOptions = { ...optionsDefaults, ...fsOptions };
+  const isAppend = cleanedOptions.append === true;
 
   try {
     // fsStd.writeFileSync(resolvedPath, contents, { encoding: 'utf-8' });
-    fs.writeFileSync(resolvedPath, contents, cleanedOptions);
+    if (isAppend) {
+      fs.appendFileSync(resolvedPath, contents, cleanedOptions);
+    } else {
+      fs.writeFileSync(resolvedPath, contents, cleanedOptions);
+    }
   } catch (err) {
     logger.error(`unable to write to file: ${filePath}`);
     logger.error('err.message', err.message);