jupyter-ijavascript-utils 1.61.1 → 1.62.0

package/DOCS.md

@@ -74,6 +74,8 @@ Give it a try here:
 [![Binder:what can I do with this](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/paulroth3d/jupyter-ijavascript-utils/main?labpath=example.ipynb)
 
 ## What's New
+* 1.62 - Update to Array.peekableIterator to include peekItr() as sugar for .peek
+* 1.61 - Docs Updated
 * 1.60 - Make post-processing of documents easier with {@link module:ijs.markDocumentPosition|ijs.markDocumentPosition}
 * 1.59 - 
     * #95 - give control with page breaks. So we can render text before the page break (like for headers) - or even get the html used and render it how we want. (ex: {@link module:ijs.generatePageBreakStylesHTML|ijs.printPageBreak})
@@ -404,6 +406,44 @@ Depends on:
 
 See the [How to Use]{@tutorial howToUse} section for more.
 
+# Common Questions
+
+## Converting Local Functions to a Local Library
+
+Often - Jupyter is not the best place to do development, and folks would like to develop in their own favourite IDE.
+
+You can write local modules (ex: `lib.js`) relative to your notebook, and then use `require('./lib')` to access them in your notebook. (see the section below on ESM Modules)
+
+NOTE: re-running the require will use a `cached version` of your module, and `may not reflect changes you just made`.
+
+(For this and other reasons, it can be helpful to have a `version` attribute to your module - to ensure the latest code is accessible)
+
+There typically are two options:
+
+* re-run the entire notebook
+
+* use a "cache bypass" only for your local library. ex: [import-fresh](https://www.npmjs.com/package/import-fresh)
+
+Using a cache bypass is fairly simple, and behaves something similar to this:
+
+```
+utils = reqire('jupyter-ijavascript-utils');
+importFresh = require('import-fresh');
+// other imports go here
+
+//-- clear the output so it doesn't pollute with nonsense we don't care about.
+utils.ijs.clearOutput();
+```
+
+and then load your module in a separate cell:
+
+```
+lib = importFresh('./lib');
+lib.version; // 1.0.0
+```
+
+and if you change your library, you can then just run that cell again
+
 ## ESM Modules + D3
 
 Note that we strongly recommend using this with other modules like D3 - that only support ESM modules now.

package/Dockerfile

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

package/README.md

@@ -54,6 +54,8 @@ This is not intended to be the only way to accomplish many of these tasks, and a
 ![Screenshot of example notebook](docResources/img/mainExampleNotebook.png)
 
 # What's New 
+* 1.62 - Update to Array.peekableIterator to include peekItr() as sugar for .peek
+* 1.61 - Docs Updated
 * 1.60 - Make post-processing of documents easier with ijs.utils.markDocumentPosition
 * 1.59 - 
     * #95 - give control with page breaks. So we can render text before the page break (like for headers) - or even get the html used and render it how we want.
@@ -132,6 +134,42 @@ 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))
 
+## Converting Local Functions to a Local Library
+
+Often - Jupyter is not the best place to do development, and folks would like to develop in their own favourite IDE.
+
+You can write local modules (ex: `lib.js`) relative to your notebook, and then use `require('./lib')` to access them in your notebook. (see the section below on ESM Modules)
+
+NOTE: re-running the require will use a `cached version` of your module, and `may not reflect changes you just made`.
+
+(For this and other reasons, it can be helpful to have a `version` attribute to your module - to ensure the latest code is accessible)
+
+There typically are two options:
+
+* re-run the entire notebook
+
+* use a "cache bypass" only for your local library. ex: [https://www.npmjs.com/package/import-fresh](import-fresh)
+
+Using a cache bypass is fairly simple, and behaves somethng similar to this:
+
+```
+utils = reqire('jupyter-ijavascript-utils');
+importFresh = require('import-fresh');
+// other imports go here
+
+//-- clear the output so it doesn't pollute with nonsense we don't care about.
+utils.ijs.clearOutput();
+```
+
+and then load your module in a separate cell:
+
+```
+lib = importFresh('./lib');
+lib.version; // 1.0.0
+```
+
+and if you change your library, you can then just rn tat cell again
+
 ## ESM Modules + D3
 
 Note that we strongly recommend using this with other modules like D3 - that only support ESM modules now.

package/package.json

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

package/src/array.js

@@ -1210,9 +1210,7 @@ module.exports.extractFromHardSpacedTable = function extractFromHardSpacedTable(
 /**
  * Create an iterator for an array that allows for peeking next values.
  * 
- * @see https://www.npmjs.com/package/peekable-array-iterator
- * @example
- * 
+ * ```
  * source = [0, 1, 2, 3, 4, 5];
  * 
  * // also quite helpful for document.querySelector(...)
@@ -1221,22 +1219,26 @@ module.exports.extractFromHardSpacedTable = function extractFromHardSpacedTable(
  * console.log(itr.next()); // { done: false, value: 0 }
  * 
  * //-- peek without moving the iterator
- * const peekItr = itr.peek();
- * console.log(peekItr.next()); // { done: false, value: 1 }
- * console.log(peekItr.next()); // { done: false, value: 2 }
- * console.log(peekItr.next()); // { done: false, value: 3 }
- * console.log(peekItr.next()); // { done: false, value: 4 }
- * console.log(peekItr.next()); // { done: true, value: 5 }
+ * console.log(itr.peek.next()); // { done: false, value: 1 }
+ * console.log(itr.peek.next()); // { done: false, value: 2 }
+ * console.log(itr.peek.next()); // { done: false, value: 3 }
+ * console.log(itr.peek.next()); // { done: false, value: 4 }
+ * console.log(itr.peek.next()); // { done: true, value: 5 }
  * 
  * //-- move the main iterator
  * console.log(itr.next()); // { done: false, value: 1 }
+ * ```
  * 
  * Of course, for each will always work
- * or
- * for (let i of new utils.array.PeekableArrayIterator(list)) {
+ * 
+ * ```
+ * for (let i of new utils.array.PeekableArrayIterator(source)) {
  *   console.log(i);
  * }
  * // 1\n2\n3\n4\n5
+ * ```
+ * 
+ * @see https://www.npmjs.com/package/peekable-array-iterator
  */
 class PeekableArrayIterator {
   /**
@@ -1261,9 +1263,12 @@ class PeekableArrayIterator {
       }
       return undefined;
     })();
+    this.peekItr = function peekItr() {
+      return this.peek;
+    };
 
     this.i += 1;
-    return { done: this.i >= this.array.length - 1, value: this.array[this.i] };
+    return { done: this.i >= this.array.length, value: this.array[this.i] };
   }
   /* eslint-enable wrap-iife */
 }