jupyter-ijavascript-utils 1.35.0 → 1.37.0

package/DOCS.md

@@ -75,6 +75,7 @@ Give it a try here:
 
 ## What's New
 
+* 1.36 - {@link module:format.replaceStrings|format.replaceStrings} to allow for replacement dictionaries and tuplets
 * 1.35 - {@link module:object.extractObjectProperties|extractObjectProperties} / {@link module:object.extractObjectProperty|extractObjectProperty} - to do horizontal transposes on objects
 * 1.34 - {@link module:format.mapArrayDomain|format.mapArrayDomain} and add notes in the header of {@link module:random|random} on using non-uniform distributions.
 * 1.33 - Object.augmentInherit and Object.union
@@ -369,3 +370,36 @@ Depends on:
 * [n-riesco/ijavascript jupyter kernel](https://github.com/n-riesco/ijavascript#installation)
 
 See the [How to Use]{@tutorial howToUse} section for more.
+
+## ESM Modules + D3
+
+Note that we strongly recommend using this with other modules like D3 - that only support ESM modules now.
+
+There is a [known issue #210](https://github.com/n-riesco/ijavascript/issues/210) in the iJavaScript kernel.
+
+So if you try to import libraries like d3 [and get comments like this](https://github.com/n-riesco/ijavascript/issues/279)
+
+```
+$ node -e "import defaultExport from './test.mjs'"
+[eval]:1
+import defaultExport from './test.mjs'
+^^^^^^
+
+SyntaxError: Cannot use import statement outside a module
+    at new Script (vm.js:88:7)
+    at createScript (vm.js:263:10)
+    at Object.runInThisContext (vm.js:311:10)
+    at Object.<anonymous> ([eval]-wrapper:10:26)
+    at Module._compile (internal/modules/cjs/loader.js:1151:30)
+    at evalScript (internal/process/execution.js:94:25)
+    at internal/main/eval_string.js:23:3
+```
+
+### Use [esm-hook](https://github.com/alex-kinokon/esm-hook) as a workaround for now.
+
+```
+require("esm-hook"); // must come before requiring esm modules
+d3 = require('d3');  // import esm modules
+```
+
+More is found on the documentation for [issue #210](require("esm-hook"))

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.36 - replaceStrings to allow for replacement dictionaries and tuplets
 * 1.35 - object.extractObjectProperties / object.extractObjectProperty - to do horizontal transposes on objects
 * 1.34 - format.mapArrayDomain and add notes in to random on using non-uniform distributions.
 * 1.33 - Object.augmentInherit and Object.union
@@ -98,6 +99,39 @@ 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))
 
+## ESM Modules + D3
+
+Note that we strongly recommend using this with other modules like D3 - that only support ESM modules now.
+
+There is a [known issue #210](https://github.com/n-riesco/ijavascript/issues/210) in the iJavaScript kernel.
+
+So if you try to import libraries like d3 [and get comments like this](https://github.com/n-riesco/ijavascript/issues/279)
+
+```
+$ node -e "import defaultExport from './test.mjs'"
+[eval]:1
+import defaultExport from './test.mjs'
+^^^^^^
+
+SyntaxError: Cannot use import statement outside a module
+    at new Script (vm.js:88:7)
+    at createScript (vm.js:263:10)
+    at Object.runInThisContext (vm.js:311:10)
+    at Object.<anonymous> ([eval]-wrapper:10:26)
+    at Module._compile (internal/modules/cjs/loader.js:1151:30)
+    at evalScript (internal/process/execution.js:94:25)
+    at internal/main/eval_string.js:23:3
+```
+
+### Use [esm-hook](https://github.com/alex-kinokon/esm-hook) as a workaround for now.
+
+```
+require("esm-hook"); // must come before requiring esm modules
+d3 = require('d3');  // import esm modules
+```
+
+More is found on the documentation for [issue #210](require("esm-hook"))
+
 ## Google Collab
 
 You can very easily use iJavaScript and the jupyter-ijavascript-utils within Google Collab.

package/package.json

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

package/src/format.js

@@ -397,6 +397,7 @@ module.exports.mapDomain = function mapDomain(val, [domainMin, domainMax], [rang
  * ```
  * require('esm-hook');
  * d3 = require('d3');
+ * utils = require('jupyter-ijavascript-utils');
  * 
  * //-- create a number generator using Normal / Gaussian distribution
  * randomGenerator = d3.randomNormal(
@@ -409,12 +410,14 @@ module.exports.mapDomain = function mapDomain(val, [domainMin, domainMax], [rang
  * 
  * randomDataset = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j'];
  * 
+ * numPicks = 3; // increase to a larger number (ex: 1000) to better see distributions
+ * 
  * //-- create an array of 3 items, each with the results from randomGenerator
- * results = utils.array.size(3, () => randomGenerator());
+ * results = utils.array.size(numPicks, () => randomGenerator());
  * // [ 0.6235937672428706, 0.4991359903898883, 0.4279365561645624 ]
  * 
  * //-- map those values to the randomDataset
- * results.map(val => ({ pick: utils.format.mapArrayDomain(val, randomDataset) }));
+ * resultPicks = results.map(val => ({ pick: utils.format.mapArrayDomain(val, randomDataset) }));
  * // [ { pick: 'g' }, { pick: 'e' }, { pick: 'e' } ]
  * 
  * //-- group them by the pick field
@@ -430,7 +433,7 @@ module.exports.mapDomain = function mapDomain(val, [domainMin, domainMax], [rang
  *       .title('Distribution')
  *       .data(groupedResults)
  *       .encode(
- *         vl.x().fieldN('value'),
+ *         vl.x().fieldN('pick'),
  *         vl.y().fieldQ('count').scale({type: 'log'})
  *       );
  * });
@@ -1184,3 +1187,83 @@ module.exports.lineCount = function lineCount(str, newlineCharacter = '\n') {
   const match = str.match(rex);
   return match ? match.length + 1 : 1;
 };
+
+/**
+ * Performs a set of replacement against a string or list of strings.
+ * 
+ * The string replacements can either be [[search,replace],[search,replace]]
+ * or a map of Map([[search, replace], [search, replace]])
+ * 
+ * This is meant to provide a way to apply consistent string cleanups across projects.
+ * 
+ * example:
+ * 
+ * ```
+ * targetStrings = [
+ *   'jack and jill went up the hill',
+ *   'to fetch the pail of water',
+ *   'jack fell down and broke his crown',
+ *   'and jill came tumbling after'
+ * ];
+ * 
+ * //-- include an array of strings to all remove out
+ * utils.format.replaceStrings(targetStrings, ['down ', ' of water']);
+ * // [ 'jack and jill went up the hill',
+ * //   'to fetch the pail',
+ * //   'jack fell and broke his crown',
+ * //   'and jill came tumbling after' ]
+ *
+ * //-- or use tuplets of [find, replace] with regular expressions
+ * replaceValues = [['jack', 'john'], [/\s+jill/i, ' ringo'], ' down'];
+ * utils.format.replaceStrings(targetStrings, replaceValues);
+ * expected = [
+ *   'john and ringo went up the hill',
+ *   'to fetch the pail of water',
+ *   'john fell and broke his crown',
+ *   'and ringo came tumbling after'
+ * ];
+ * 
+ * //-- a map will do the same, but will not support regular expressions for keys
+ * replaceValues = new Map();
+ * replaceValues.set('jack', 'john');
+ * replaceValues.set('jill', 'ringo');
+ * utils.format.replaceStrings(targetStrings, replaceValues);
+ * expected = [
+ *   'john and ringo went up the hill',
+ *   'to fetch the pail of water',
+ *   'john fell down and broke his crown',
+ *   'and ringo came tumbling after'
+ * ];
+ * ```
+ * 
+ * @param {string|string[]} targetStr - the string to search for with the tuplets
+ * @param {Array|Map<string|RegExp,string>} stringTupletsOrMap - [[search, replace]] or Map<String|RegExp,String>
+ * @returns {string[]} - the resulting list of strings
+ */
+module.exports.replaceStrings = function replaceStrings(targetStr, stringTupletsOrMap) {
+  const cleanStrings = !targetStr ? [] : Array.isArray(targetStr) ? targetStr : [targetStr];
+  // const signature = 'replaceStrings(targetStrings, stringTupletsOrMap)';
+  const replacementEntries = [];
+
+  if (Array.isArray(stringTupletsOrMap)) {
+    stringTupletsOrMap.forEach((possibleReplacement) => {
+      if (typeof possibleReplacement === 'string') {
+        replacementEntries.push([possibleReplacement, '']);
+      } else if (Array.isArray(possibleReplacement)) {
+        const [replaceSearch, replaceWith] = possibleReplacement;
+        replacementEntries.push([replaceSearch, replaceWith || '']);
+      }
+    });
+  } else if (stringTupletsOrMap instanceof Map) {
+    [...stringTupletsOrMap.entries()]
+      .forEach(([replaceSearch, replaceWith]) => {
+        replacementEntries.push([replaceSearch, replaceWith || '']);
+      });
+  }
+
+  return cleanStrings.map((stringToClean) => !stringToClean
+    ? stringToClean
+    : replacementEntries.reduce((result, [replaceSearch, replaceWith]) => !result
+      ? result
+      : result.replace(replaceSearch, replaceWith), stringToClean));
+};

package/src/random.js

@@ -55,6 +55,7 @@ const SimplexModule = require('./random_simplex');
  * ```
  * require('esm-hook');
  * d3 = require('d3');
+ * utils = require('jupyter-ijavascript-utils');
  * 
  * //-- create a number generator using Normal / Gaussian distribution
  * randomGenerator = d3.randomNormal(
@@ -67,12 +68,14 @@ const SimplexModule = require('./random_simplex');
  * 
  * randomDataset = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j'];
  * 
+ * numPicks = 3; // increase to a larger number (ex: 1000) to better see distributions
+ * 
  * //-- create an array of 3 items, each with the results from randomGenerator
- * results = utils.array.size(3, () => randomGenerator());
+ * results = utils.array.size(numPicks, () => randomGenerator());
  * // [ 0.6235937672428706, 0.4991359903898883, 0.4279365561645624 ]
  * 
  * //-- map those values to the randomDataset
- * results.map(val => ({ pick: utils.format.mapArrayDomain(val, randomDataset) }));
+ * resultPicks = results.map(val => ({ pick: utils.format.mapArrayDomain(val, randomDataset) }));
  * // [ { pick: 'g' }, { pick: 'e' }, { pick: 'e' } ]
  * 
  * //-- group them by the pick field
@@ -88,7 +91,7 @@ const SimplexModule = require('./random_simplex');
  *       .title('Distribution')
  *       .data(groupedResults)
  *       .encode(
- *         vl.x().fieldN('value'),
+ *         vl.x().fieldN('pick'),
  *         vl.y().fieldQ('count').scale({type: 'log'})
  *       );
  * });