jupyter-ijavascript-utils 1.23.0 → 1.24.0

package/DOCS.md

@@ -75,6 +75,7 @@ Give it a try here:
 
 ## What's New
 
+* 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
 * 1.21 - include {@link module:chain|chain} - simple monoid

package/Dockerfile

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

package/README.md

@@ -55,6 +55,7 @@ This is not intended to be the only way to accomplish many of these tasks, and a
 
 # What's New
 
+* 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
 * 1.21 - include chain - simple monoid

package/package.json

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

package/src/TableGenerator.js

@@ -105,6 +105,7 @@ const { createSort } = require('./array');
  * * 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#offset|offset(number)} - starts results only after an offset number 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
@@ -197,6 +198,17 @@ class TableGenerator {
    */
   #limit = 0;
 
+  /**
+   * The number of rows to skip before showing results.
+   * 
+   * 10 : means start showing results only after the first 10 records
+   * 
+   * -10 : means only show the last 10
+   * 
+   * @type {Number}
+   */
+  #offset = 0;
+
   /**
    * PrintValue options to use when rendering the table values
    * @type {PrintOptions}
@@ -289,6 +301,7 @@ class TableGenerator {
     this.#formatterFn = null;
     this.#labels = {};
     this.#limit = 0;
+    this.#offset = 0;
     this.#printOptions = null;
     this.#sortFn = null;
     this.#styleTable = '';
@@ -677,6 +690,21 @@ class TableGenerator {
     return this;
   }
 
+  /**
+   * The number of rows to skip before showing any records.
+   * 
+   * 10 : means start showing results only after the first 10 records
+   * 
+   * -10 : means only show the last 10
+   * 
+   * @param {Number} offsetRecords - the number of rows to skip 
+   * @returns {TableGenerator} - chainable interface
+   */
+  offset(offsetRecords) {
+    this.#offset = offsetRecords;
+    return this;
+  }
+
   /**
    * Sets the alternative labels to be used for specific fields.
    * 
@@ -1130,8 +1158,12 @@ class TableGenerator {
 
     if (this.#limit < 0) {
       data = data.reverse().slice(0, -this.#limit);
+    } else if (this.#offset < 0) {
+      data = data.slice(this.#offset);
     } else if (this.#limit > 0) {
-      data = data.slice(0, this.#limit);
+      data = data.slice(this.#offset, this.#offset + this.#limit);
+    } else if (this.#offset > 0) {
+      data = data.slice(this.#offset);
     }
 
     if (this.#isTransposed) {

package/src/chain.js

@@ -13,6 +13,9 @@
  * * {@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
@@ -158,6 +161,69 @@ class ChainContainer {
     return this.chain((value) => value.map(fn));
   }
 
+  /**
+   * Assuming that value is an array, performs a
+   * [javaScript flatMap](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flatMap)
+   * against the results.
+   * 
+   * This can be very helpful in expanding the list of items in an array, or removing items from an array.
+   * 
+   * ```
+   * // expanding size of the array
+   * initializeArray = (size) => Array.from(Array(size)).map((val, index) => index);
+   * initializeArray(3); // [0, 1, 2]
+   * 
+   * utils.chain([1, 2, 3, 4])
+   *  .chainFlatMap(initializeArray)
+   *  .close();
+   * 
+   * // [1, 1, 2, 1, 2, 3, 1, 2, 3, 4];
+   * ```
+   * 
+   * or similar to {@link ChainContainer#chainFilter|chainFilter}
+   * 
+   * ```
+   * // reducing the size of the array
+   * filterOdd = (value) => value % 2 === 0 ? [value] : [];
+   * filterOdd(2); // [2]
+   * filterOdd(1); // []
+   * 
+   * chain([1, 2, 3, 4, 5])
+   *  .chainFlatMap(filterOdd)
+   *  .close();
+   * 
+   * // [2, 4];
+   * ```
+   * 
+   * @param {function(any):any} fn - function that can either return a value or array of values.
+   * @returns {ChainContainer}
+   * @see {@link ChainContainer#chainFilter} - for other options in filtering
+   */
+  chainFlatMap(fn) {
+    if (!Array.isArray(this.value)) throw Error(`chainFlatMap expects an array, but was passed:${this.value}`);
+
+    return this.chain((value) => value.flatMap(fn));
+  }
+
+  /**
+   * Assuming that value is an array, this maps fn to filter the results in the array.
+   * 
+   * ```
+   * chain([1,2,3,4])
+   *    .chainFilter((value) => value < 3)
+   *    .close();
+   * // [1, 2]
+   * ```
+   * 
+   * @param {function(any):Boolean} fn - Function accepting a value and returning whether it should be included (true) or not (false)
+   * @returns {ChainContainer}
+   */
+  chainFilter(fn) {
+    if (!Array.isArray(this.value)) throw Error(`chainFilter expects an array, but was passed:${this.value}`);
+
+    return this.chain((value) => value.filter(fn));
+  }
+
   /**
    * Assuming that the value is an array, performs a reduce using fn and initialValue
    * 
@@ -361,6 +427,9 @@ class ChainContainer {
  * * {@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

package/src/format.js

@@ -15,6 +15,7 @@
  *   * {@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')
  *   * {@link module:format.ellipsify|format.ellipsify} - Truncates a string if the length is 'too long'
+ *   * {@link module:format.stripHtmlTags|format.stripHtmlTags} - removes html / xml tags from strings.
  *   * {@link module:format.limitLines|format.limitLines(string, toLine, fromLine, lineSeparator)} - selects only a subset of lines in a string
  *   * {@link module:format.consoleLines|format.consoleLines(...)} - same as limit lines, only console.logs the string out.
  * * Formatting Time
@@ -30,7 +31,7 @@
  *   * {@link module:format.safeConvertInteger|format.safeConvertInteger} - converts a value to a Number (123), or uses a default for any error or NaN
  *   * {@link module:format.safeConvertBoolean|format.safeConvertBoolean} - converts a value to a boolean
  * * Parsing values
- *   * {@link module:format.parseNumber|format.parseBoolean(val)} - converts a value to a boolean value
+ *   * {@link module:format.parseBoolean|format.parseBoolean(val)} - converts a value to a boolean value
  *   * {@link module:format.parseNumber|format.parseNumber(val, locale)} - converts a value to a number
  * * Identifying values
  *   * {@link module:format.isEmptyValue|format.isEmptyValue} - determine if a value is not 'empty'
@@ -977,3 +978,21 @@ module.exports.limitLines = function limitLines(str, toLine, fromLine, lineSepar
 module.exports.consoleLines = function consoleLines(str, toLine, fromLine, lineSeparator) {
   console.log(FormatUtils.limitLines(str, toLine, fromLine, lineSeparator));
 };
+
+/**
+ * Strips any html or xml tags from a string.
+ * 
+ * Note, if you want to remove html entities (ex: ` ` or `‑`), please consider [other libraries](https://www.npmjs.com/search?q=html%20entities)
+ * 
+ * @param {String} str - string to strip html / xml entities from
+ * @returns {String}
+ * @example 
+ * 
+ * utils.format.stripHtmlTags('Hello <br />Nice to see <b>you</b>'); // 'Hello Nice to see you'
+ * utils.format.stripHtmlTags('example string'); // 'example string' -- untouched
+ */
+module.exports.stripHtmlTags = function stripHtmlTags(str) {
+  if (!str) return str;
+
+  return str.replace(/<[^>]+>/g, '');
+};

package/src/vega.js

@@ -293,8 +293,11 @@ const IJSUtils = require('./ijs');
  * 
  * If your data is at the series level, you can:
  * 
- * * Transform the data with the {@link group#separateByFields|group.separateByFields}
+ * * Transform the data with the {@link module:group.separateByFields|group.separateByFields}
+ *     * utils.group.separateByFields(fruitSeriesData, 'apples', 'bananas', 'pears');
+ *     * this makes a new field called 'key' that will have values of either apples, bananas or pears
  * * or using the [vega-lite fold transform](https://vega.github.io/vega-lite/docs/fold.html)
+ *     * by adding in the `.transform()` into the spec - like below
  * 
  * ```
  * fruitSeriesData = [{ year:'2020', apples:20, bananas:15, pears:18 },