jupyter-ijavascript-utils 1.0.0

package/.eslintrc.js

@@ -0,0 +1,33 @@
+module.exports = {
+  root: true,
+  parser: 'babel-eslint',
+  env: {
+    commonjs: true,
+    es2021: true,
+    node: true,
+    jest: true
+  },
+  extends: [
+    'airbnb-base',
+  ],
+  parserOptions: {
+    ecmaVersion: 12
+  },
+  rules: {
+    'no-trailing-spaces': ['error', { skipBlankLines: true, ignoreComments: true }],
+    'comma-dangle': 'off',
+    'spaced-comment': 'off',
+    'no-confusing-arrow': 'off',
+    'no-console': 'off',
+    'no-unused-vars': ['error', { args: 'none' }],
+    'arrow-parens': ['error', 'always'],
+    'no-nested-ternary': 'off',
+    'no-restricted-syntax': 'off',
+    'consistent-return': 'off',
+    'object-curly-newline': 'off',
+    'no-multi-spaces': 'off',
+    'lines-between-class-members': 'off',
+    'no-unneeded-ternary': 'off',
+    'no-else-return': ['error', { allowElseIf: true }],
+  }
+};

package/.screenrc

@@ -0,0 +1,75 @@
+#!/bin/bash
+
+# sets a screen session for the current project
+
+# sets the current window's name
+screen -X title "notebooks"
+screen -X stuff "cd ../^M"
+screen -X number 0
+
+# uncomment below to make the tabs only run those commands
+# but note that restarting will lose that tab
+
+screen -X dynamictitle off
+screen -X defdynamictitle off
+
+screen -t "ijsUtils"
+screen -p ijsUtils -X stuff "cd ../jupyter-ijavascript-utils^M"
+screen -t "jsUtils"
+screen -p jsUtils -X stuff "cd ../jupyterJsUtils^M"
+screen -t "scratchpad"
+screen -p scratchpad -X stuff "cd ../jupyterScratchpad^M"
+screen -t "p4js"
+screen -p p4js -X stuff "cd '../python-for-js-developers'^M"
+
+screen -t lint
+screen -p lint -X stuff "npm run lint:watch"
+screen -t test
+screen -p test -X stuff "npm run test:watch"
+screen -t debug
+
+screen -t "server" 10
+screen -p server -X stuff "cd ../^Mjupyter lab"
+screen -t plantuml 11
+screen -p plantuml -X stuff "plantuml -picoweb"
+screen -t codeserver 12
+screen -p codeserver -X stuff "code-server .."
+
+screen -X select 0
+
+# create layouts
+
+screen -X layout new default
+screen -X select ijsUtils
+
+screen -X layout new dev
+#screen -X select micro
+#screen -X split -h
+#screen -X resize 70%
+#screen -X focus
+screen -X select lint
+screen -X split -v
+screen -X focus
+screen -X select test
+
+screen -X layout new test
+screen -X select test
+screen -X split -h
+screen -X resize 60%
+screen -X focus
+screen -X select lint
+
+screen -X layout new server
+screen -X select server
+screen -X split -v
+screen -X focus right
+screen -X select plantuml
+
+screen -X layout select default
+
+# key bindings
+
+# screen -X bindkey -k k1 layout select 0
+# screen -X bindkey -k k2 layout select 1
+# screen -X bindkey -k k3 layout select 2
+

package/DOCS.md

@@ -0,0 +1,79 @@
+# Overview
+
+This is a simple Library for using Jupyter with the IJavaScript kernel
+
+See the [#Installation section for requirements and installation](#install)
+
+| Export | Description                                                                      |
+|-----------|----------------------------------------------------------------------------------|
+| [ijs](./IJSUtils.html)       | Utility methods to support working within the iJavaScript kernel within Jupyter. |
+| [datasets](./module-datasets.html)  | Utilities to facilitate working with example datasets provided by vega.          |
+| [vega](./module-vega.html)      | Simple utility to streamline showing Vega-Lite charts within iJS Notebooks.      |
+
+-------
+
+## For Example
+
+```
+//-- get the data
+utils.dataset.fetch('barley.json').then((data) => barley = data);
+
+//-- get the min max of the types of barley
+barleyByVarietySite = d3.group(barley, d => d.variety, d => d.site)
+
+// InternMap(10) [Map] {
+//   'Manchuria' => InternMap(6) [Map] {
+//     'University Farm' => [ [Object], [Object] ],
+//     'Waseca' => [ [Object], [Object] ],
+//     ...
+//   }, ...
+// }
+
+//-- now group by variety and year
+barleyByVarietyYear = d3.group(barley, d => d.variety, d => d.year)
+
+// nternMap(10) [Map] {
+//  'Manchuria' => InternMap(2) [Map] {
+//    1931 => [ [Object], [Object], [Object], [Object], [Object], [Object] ],
+//    1932 => [ [Object], [Object], [Object], [Object], [Object], [Object] ]
+//  }, ...
+// 
+```
+
+[note: See here to learn more about d3 grouping](https://observablehq.com/@d3/d3-group)
+
+then later
+
+```
+utils.ijs.listGlobals();
+// ['barley','d3','barleyByVariety','barleyByVarietySite',...]
+```
+
+now show a graph
+
+```
+utils.vega.svg($$, utils.vega.markPoint()
+    .data(barley)
+    .title('Barley Yield by Site')
+    .width(600)
+    .encode(
+        utils.vega.x().fieldN('site'),
+        utils.vega.y().fieldQ('yield'),
+        utils.vega.color().fieldN('year')
+    )
+)
+```
+
+![Screenshot of Vega Cell](img/BarleyYieldBySite.png)
+
+<a name="install">&nbsp;</a>
+# Install
+
+Note that some of the utilities assumes you are running within Jupyter - within n-riesco's iJavaScript kernel (that provides JavaScript language support within Jupyter)
+
+`npm install jupyter-ijavascript-utils`
+
+Depends on:
+
+* [Jupyter Tools - such as Jupyter Lab](https://jupyter.org/)
+* [n-riesco/ijavascript jupyter kernel](https://github.com/n-riesco/ijavascript#installation)

package/LICENSE

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2022 Paul Roth
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+<p align="center">
+    <a href="https://jupyter-ijavascript-utils.onrender.com/" alt="Documentation">
+        <img src="https://img.shields.io/badge/Documentation-here-informational" />
+    </a>
+    <a href="https://jupyter-ijavascript-utils.onrender.com/LICENSE" alt="License">
+        <img src="https://img.shields.io/badge/License-MIT-green" />
+    </a>
+</p>
+
+# Overview
+
+Simple library for working with Jupyter - through IJavaScript kernel.
+
+## For Example
+
+```
+//-- get the data
+utils.dataset.fetch('barley.json').then((data) => barley = data);
+
+//-- get the min max of the types of barley
+barleyByVarietySite = d3.group(barley, d => d.variety, d => d.site)
+
+// InternMap(10) [Map] {
+//   'Manchuria' => InternMap(6) [Map] {
+//     'University Farm' => [ [Object], [Object] ],
+//     'Waseca' => [ [Object], [Object] ],
+//     ...
+//   }, ...
+// }
+
+//-- now group by variety and year
+barleyByVarietyYear = d3.group(barley, d => d.variety, d => d.year)
+
+// nternMap(10) [Map] {
+//  'Manchuria' => InternMap(2) [Map] {
+//    1931 => [ [Object], [Object], [Object], [Object], [Object], [Object] ],
+//    1932 => [ [Object], [Object], [Object], [Object], [Object], [Object] ]
+//  }, ...
+// 
+```
+
+[note: See here to learn more about d3 grouping](https://observablehq.com/@d3/d3-group)
+
+then later
+
+```
+utils.ijs.listGlobals();
+// ['barley','d3','barleyByVariety','barleyByVarietySite',...]
+```
+
+now show a graph
+
+```
+utils.vega.svg($$, utils.vega.markPoint()
+    .data(barley)
+    .title('Barley Yield by Site')
+    .width(600)
+    .encode(
+        utils.vega.x().fieldN('site'),
+        utils.vega.y().fieldQ('yield'),
+        utils.vega.color().fieldN('year')
+    )
+)
+```
+
+![Screenshot of Vega Cell](https://jupyter-ijavascript-utils.onrender.com/img/BarleyYieldBySite.png)
+
+# Documentation
+
+See documentation at: [https://jupyter-ijavascript-utils.onrender.com/](https://jupyter-ijavascript-utils.onrender.com/)
+
+# License
+
+See [License](https://jupyter-ijavascript-utils.onrender.com/LICENSE) (MIT License).
+
+# Issues
+
+If you have any questions first file it on [issues](https://github.com/paulroth3d/jupyter-ijavascript-utils/issues) before contacting authors.
+
+# Contributions
+
+Your contributions are welcome: both by reporting issues on [GitHub issues](https://github.com/paulroth3d/jupyter-ijavascript-utils/issues) or pull-requesting patches.
+
+If you want to implement any additional features, to be added to JSforce to our master branch, which may or may not be merged please first check current [opening issues](https://github.com/paulroth3d/jupyter-ijavascript-utils/issues?q=is%3Aopen) with milestones and confirm whether the feature is on road map or not.
+
+If your feature implementation is brand-new or fixing unsupposed bugs in the library's test cases, please include addtional test codes in the `src/__tests__/` directory.
+
+
+## Further Reading
+
+* [JSDoc Templates](https://cancerberosgx.github.io/jsdoc-templates-demo/demo/)
+* [DocDash Template](http://clenemt.github.io/docdash/)
+* [DocDash Example Code](http://clenemt.github.io/docdash/base_chains.js.html)
+* [Gist creating JSDoc to MD](https://gist.github.com/slorber/0bf8c8c8001505f0f99a062ac55bf442)

package/docResources/LICENSE

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2022 Paul Roth
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/jsdoc.json

@@ -0,0 +1,30 @@
+{
+    "tags": {
+        "allowUnknownTags": false
+    },
+    "source": {
+        "include": "./src",
+        "includePattern": "\\.js$",
+        "excludePattern": "(node_modules/|docs)"
+    },
+    "plugins": [
+        "plugins/markdown"
+    ],
+    "opts": {
+        "template": "node_modules/docdash",
+        "encoding": "utf8",
+        "destination": "docs/",
+        "recurse": true,
+        "verbose": true
+    },
+    "templates": {
+        "default":{
+          "outputSourceFiles":false,
+          "staticFiles": {
+            "paths": ["./docResources/"]
+        }
+        },
+        "cleverLinks": false,
+        "monospaceLinks": false
+    }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "jupyter-ijavascript-utils",
+  "version": "1.0.0",
+  "description": "Utilities for working with iJavaScript - a Jupyter Kernel",
+  "main": "src/index.js",
+  "scripts": {
+    "lint": "esw src",
+    "lint:watch": "npm run lint -- --watch",
+    "test": "jest src",
+    "test:watch": "npm run test -- --watch",
+    "test:debug": "node --inspect-brk node_modules/jest/bin/jest.js --runInBand",
+    "doc": "node_modules/.bin/jsdoc -c ./jsdoc.json ./DOCS.md"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:paulroth3d/jupyter-ijavascript-utils.git"
+  },
+  "keywords": [
+    "ijavascript",
+    "jupyter"
+  ],
+  "author": "Paul Roth",
+  "license": "MIT",
+  "devDependencies": {
+    "babel-eslint": "^10.1.0",
+    "docdash": "^1.2.0",
+    "eslint": "^7.29.0",
+    "eslint-config-airbnb-base": "^14.2.1",
+    "eslint-plugin-import": "^2.23.4",
+    "eslint-watch": "^7.0.0",
+    "jest": "^27.0.6",
+    "jsdoc": "^3.6.10",
+    "sinon": "^11.1.1"
+  },
+  "dependencies": {
+    "fs-extra": "^10.0.0",
+    "generate-schema": "^2.6.0",
+    "node-fetch": "^2.6.5",
+    "pino": "^6.12.0",
+    "pino-pretty": "^5.1.2",
+    "plantuml-encoder": "^1.4.0",
+    "promise-sequential": "^1.1.1",
+    "rxjs": "^7.1.0",
+    "vega": "^5.20.2",
+    "vega-datasets": "^2.2.0",
+    "vega-lite": "^5.1.0",
+    "vega-lite-api": "^5.0.0"
+  }
+}

package/src/__tests__/ijsUtils__spec.js

@@ -0,0 +1,8 @@
+// const codeBlockHelper = require('../codeBlockHelper');
+// const ijsUtils = require('../ijsUtils');
+
+global.describe('codeBlockHelper', () => {
+  global.it('test', () => {
+    global.expect(1 + 2).toBe(3);
+  });
+});

package/src/datasets.js

@@ -0,0 +1,117 @@
+/**
+ * @fileoverview
+ * Utilities to facilitate working with [vega/vega-datasets](https://github.com/vega/vega-datasets)
+ * 
+ * Vega datasets are a collection of datasets used in Vega and in Vega-Lite examples.
+ * 
+ * The data lives at [https://github.com/vega/vega-datasets](https://github.com/vega/vega-datasets)
+ * and [https://cdn.jsdelivr.net/npm/vega-datasets](https://cdn.jsdelivr.net/npm/vega-datasets)
+ * 
+ * @module datasets
+ * @exports datasets
+ * 
+ * @example
+ * 
+ * datasets.list(); //-- prints the list of the datasets supported
+ * myDataset = datasets.fetch('cars.json');
+ * 
+ * @see #~list
+ * @see #~fetch
+ * 
+ */
+const datasets = require('vega-datasets');
+const fetch = require('node-fetch');
+
+//-- setup datasets
+/**
+ * This will polyfill 'fetch' if your node instance does not have an implementation.
+ * @method setupFetch
+ * @private
+ */
+datasets.setupFetch = () => {
+  if ((typeof global.fetch) === 'undefined') {
+    global.fetch = fetch;
+  }
+};
+
+/**
+ * Prints the lists of datasets available
+ * @method list
+ * @returns {String[]} - list of dataset ids that can be fetched.
+ * 
+ * @example
+ * 
+ * [
+ * 'annual-precip.json',
+ * 'anscombe.json',
+ * 'barley.json',
+ * 'budget.json',
+ * 'budgets.json',
+ * 'burtin.json',
+ * 'cars.json',
+ * 'countries.json',
+ * 'crimea.json',
+ * 'driving.json',
+ * ... ];
+]
+ */
+datasets.list = () => Object.keys(datasets).filter((r) => r.endsWith('.json'));
+
+/**
+ * Shim for fetching things through the node-fetch library
+ * @method nodeFetch
+ * @private
+ */
+datasets.nodeFetch = fetch;
+
+/**
+ * Fetches a specific dataset from within the list available from [vega-datasets](https://github.com/vega/vega-datasets)
+ * 
+ * @method fetch 
+ * @param {string} library - one of the names of the libraries available from list
+ * @returns {Object[]} - results from the dataset
+ * @see #~list
+ * 
+ * @example
+ * 
+ * Example:
+ * datasets.list(); //-- see the list of datasets.
+ * // cars.json
+ * datasets.fetch('cars.json').then(results => cars = results);
+ * [
+ *   {
+ *     Name: 'chevrolet chevelle malibu',
+ *     Miles_per_Gallon: 18,
+ *     Cylinders: 8,
+ *     Displacement: 307,
+ *     Horsepower: 130,
+ *     Weight_in_lbs: 3504,
+ *     Acceleration: 12,
+ *     Year: '1970-01-01',
+ *     Origin: 'USA'
+ *   },
+ *   {
+ *     Name: 'buick skylark 320',
+ *     Miles_per_Gallon: 15,
+ *     Cylinders: 8,
+ *     Displacement: 350,
+ *     Horsepower: 165,
+ *     Weight_in_lbs: 3693,
+ *     Acceleration: 11.5,
+ *     Year: '1970-01-01',
+ *     Origin: 'USA'
+ *   },
+ *   ...
+ * ];
+ */
+datasets.fetch = (library) => {
+  const listSet = new Set(datasets.list());
+  if (!listSet.has(library)) {
+    throw new Error(`datasets do not contain[${library}] : ${listSet}`);
+  }
+
+  datasets.setupFetch();
+  return datasets[library]();
+};
+
+module.exports = datasets;

package/src/ijsUtils.js

@@ -0,0 +1,161 @@
+/* eslint-disable no-use-before-define, function-paren-newline */
+
+/**
+ * @typedef {Object} IJavaScriptContext
+ * @property {any} $$ - current display
+ * @property {any} console - current console
+ */
+
+/**
+ * @typedef {Object} StaticMember
+ * @property {Boolean} isMethod -
+ * @property {String} type - the typeof for the member
+ * @property {String} constructor - the type of constructor for the class
+ * @property {String} name - the name of the member
+ */
+
+/**
+ * Simple library to support working within the [iJavaScript kernel within Jupyter](https://github.com/n-riesco/ijavascript)
+ * 
+ * Note that this is available as `ijs` from within the
+ * [jupyter-ijavascript-utils module](./index.html)
+ * 
+ * For example:
+ * 
+ * ```
+ * //-- get the data
+ * utils.dataset.fetch('barley.json').then((data) => barley = data);
+ * //-- get the min max of the types of barley
+ * barleyByVarietySite = d3.group(barley, d => d.variety, d => d.site)
+ * //-- now group by variety and year
+ * barleyByVarietyYear = d3.group(barley, d => d.variety, d => d.year)
+ * ```
+ * 
+ * then later
+ * 
+ * ```
+ * utils.ijs.listGlobals();
+ * // ['barley','d3','barleyByVariety','barleyByVarietySite',...]
+ * ```
+ * 
+ * @module ijs
+ * @exports ijs
+ */
+class IJSUtils {
+  /**
+   * Set with names of common global variables that aren't needed to be listed.
+   * @see #.listGlobals
+   */
+  static COMMON_GLOBALS = new Set([
+    'global', 'clearInterval', 'clearTimeout', 'setInterval', 'setTimeout', 'queueMicrotask',
+    'clearImmediate', 'setImmediate', 'module', 'exports', 'require', '$$mimer$$', '$$done$$'
+  ]);
+
+  /**
+   * Set with names of static methods that often belong to a class.
+   * @see #.listStatic
+   */
+  static COMMON_STATIC = new Set(['length', 'prototype', 'name']);
+
+  /**
+   * Determines the current global display and console from iJavaScript
+   * (or null if not within iJavaScript)
+   * @returns {IJavaScriptContext} or null if not within iJavaScript
+   * @method detectContext
+   */
+  static detectContext() {
+    if (
+      ((typeof global.$$) === 'undefined')
+      && ((typeof global.console) === 'undefined')
+    ) {
+      return null;
+    }
+
+    return {
+      $$: global.$$,
+      console: global.console
+    };
+  }
+
+  /**
+   * Determines if we are currently within the iJavaScript context
+   * @returns {Boolean} - true if the code is running within an iJavaScript kernel
+   * @method detectIJS
+   */
+  static detectIJS() {
+    return IJSUtils.detectContext() ? true : false;
+  }
+
+  /**
+   * Prints markdown if in the context of iJavaScript
+   * @param {String} markdownText - The markdown to be rendered
+   * @method markdown
+   * @example
+   * 
+   * utils.ijs.markdown(`# Overview
+   * This is markdown rendered in a cell.`);
+   */
+  static markdown(markdownText, display) {
+    if (!IJSUtils.detectIJS()) return;
+    const displayToUse = display || global.$$;
+    displayToUse.mime({ 'text/markdown': markdownText });
+  }
+
+  /**
+   * List the globals currently defined.
+   * 
+   * This can be very useful when keeping track of values after a few cells.
+   * 
+   * For example:
+   * 
+   * ```
+   * cars = utils.datasets.fetch('cars.json').then(data => global.cars = data);
+   * ```
+   * 
+   * then later
+   * 
+   * ```
+   * utils.ijs.listGlobals();
+   * // cars
+   * ```
+   * 
+   * @returns {String[]} - list of the global variables
+   * @method listGlobals
+   */
+  static listGlobals() {
+    return Object.keys(global)
+      .filter((key) => !IJSUtils.COMMON_GLOBALS.has(key));
+  }
+
+  /**
+   * List the static members and functions of a class.
+   * 
+   * @method listStatic
+   * @param {class} target - the target class
+   * @returns {StaticMember[]} 
+   * 
+   * @example
+   * 
+   * utils.ijs.listStatic(utils.ijs)
+   * // [{type:'function', constructor:'Function', isMethod:true, name:'listStatic'}, ...]
+   */
+  static listStatic(target) {
+    if (!target) return [];
+
+    return Object.getOwnPropertyNames(target)
+      .filter((prop) => !IJSUtils.COMMON_STATIC.has(prop))
+      .map((prop) => {
+        const propType = typeof target[prop];
+        const constructor = target[prop].constructor.name;
+        const isMethod = propType === 'function';
+        return ({
+          type: propType,
+          constructor,
+          isMethod,
+          name: prop
+        });
+      });
+  }
+}
+
+module.exports = IJSUtils;

package/src/index.js

@@ -0,0 +1,18 @@
+const datasets = require('./datasets');
+const ijsUtils = require('./IJSUtils');
+const vega = require('./vega');
+
+/**
+ * Default module
+ * @module index
+ * @exports index
+ * @private
+ */
+module.exports = {
+  /** @see module:datasets */
+  datasets,
+  /** @see IJSUtils */
+  ijs: ijsUtils,
+  /** @see module:vega */
+  vega
+};

package/src/vega.js

@@ -0,0 +1,308 @@
+/**
+ * Helper for working with Vega-Lite within iJavaScript notebooks.
+ * 
+ * * (see [@vega/vega-lite-api-v5 on observablehq](https://observablehq.com/@vega/vega-lite-api-v5) for a great introduction)
+ * * (see [vega-lite documentation](https://observablehq.com/@vega/vega-lite-api-v5) for deeper options)
+ * 
+ * Vega-Lite is a charting library that provides a great deal of flexibility
+ * while also allowing for very simple use cases.
+ * 
+ * The Vega-Lite JavaScript API provides a convenient way to write Vega-Lite
+ * specifications in a programmatic fashion.
+ * 
+ * ## Getting Started
+ * 
+ * The simplext example is to have a small dataset we want to render:
+ * 
+ * ```
+ * simpleData = [{fruit:'Apples',yield:20,year:'2020'},{fruit:'Apples',yield:22,year:'2021'},
+ *               {fruit:'Bananas',yield:15,year:'2020'},{fruit:'Bananas',yield:12,year:'2021'},
+ *               {fruit:'Pears',yield:18,year:'2020'},{fruit:'Pears',yield:19,year:'2021'}];
+ * ```
+ * 
+ * We would like to render this into a chart, say with points first:
+ * 
+ * ```
+ * utils.vega.svg(
+ *     // pass the iJavaScript variable of the current cell
+ *     $$,
+ *     // render as points
+ *     utils.vega.markPoint()
+ *         // use simpleData as the data source
+ *         .data(simpleData)
+ *         // title
+ *         .title('Fruit by Yield')
+ *         // this is where the x, and y are encoded
+ *         .encode(
+ *             // use the 'yield' property as the y axis
+ *             // note this is fieldQ - a qualitative number
+ *             utils.vega.y().fieldQ('yield'),
+ *             // use the 'fruit' property as the x axis
+ *             // note this is fieldN - a nominative string
+ *             utils.vega.x().fieldN('fruit')
+ *         )
+ * )
+ * ```
+ * 
+ * ![Screenshot](img/FruitFruitByYield.png)
+ * 
+ * Instead, let's separate out by year instead
+ * 
+ * ```
+ * utils.vega.svg(
+ *     $$,
+ *     // change from `markPoint` to `markLine`
+ *     utils.vega.markLine()
+ *         .data(simpleData)
+ *         .title('Fruit by Yield')
+ *         // set the width of the graph
+ *         .width(150)
+ *         .encode(
+ *             utils.vega.y().fieldQ('yield'),
+ *             // change the field to 'year' from 'fruit'
+ *             utils.vega.x().fieldN('year'),
+ *             // add a new series coloration, using 'fruit'
+ *             utils.vega.color().fieldN('fruit')
+ *         )
+ * )
+ * ```
+ * 
+ * ![Screenshot](img/FruitYearByYield.png)
+ * 
+ * Other examples could use the `utils.datasets.fetch` for data
+ * 
+ * ```
+ * utils.datasets.fetch('cars.json').then(d => cars = d);
+ * ```
+ * 
+ * Then use transforms to only care about cylinders 4 and above:
+ * 
+ * ```
+ * utils.vega.svg($$, utils.vega.markPoint()
+ *     .data(cars)
+ *     .title('Displacement vs Horsepower')
+ *     .width(500)
+ *     .height(500)
+ *     .transform(
+ *       utils.vega.filter('datum.Cylinders > 4')
+ *     )
+ *     .encode(
+ *       utils.vega.x().fieldQ('Displacement'),
+ *       utils.vega.y().fieldQ('Horsepower'),
+ *       utils.vega.color().fieldN('Origin')
+ *          .title('Car Origin')
+ *          .scale({range:['green','red','blue']})
+ *     )
+ *   )
+ * ```
+ * 
+ * ![Screenshot](img/CarsDisplacementByHorsepower.png)
+ * 
+ * Types of fields:
+ * * fieldT (type: 'temporal') - time based
+ * * fieldN (type: 'nominal') - Represents a discrete category (string)
+ * * fieldQ (type: 'qualitative') - Represents a number
+ * 
+ * You can also explicitly define the field like this:
+ * 
+ * [See the Vega-Lite Axis Documentation](https://vega.github.io/vega-lite/docs/axis.html)
+ * 
+ * ```
+ * utils.vega.svg($$, utils.vega.markPoint()
+ *     .data(cars)
+ *     .title('Displacement vs Horsepower')
+ *     .width(500)
+ *     .height(500)
+ *     .transform(
+ *       utils.vega.filter('datum.Cylinders > 4')
+ *     )
+ *     .encode(
+ *       utils.vega.x({field:'Displacement', type:'quantitative'}),
+ *       utils.vega.y({field:'Horsepower', type:'quantitative'}),
+ *       utils.vega.color({
+ *        field:'Origin', title:'Car Origin', type:'nominal',
+ *        scale: {range: ['green', 'red', 'blue']
+ *       }}
+ *      )
+ *     )
+ *   )
+ * ```
+ * 
+ * ![Screenshot](img/CarsDisplacementByHorsepower.png)
+ * 
+ * other examples
+ * 
+ * ## Bins
+ * 
+ * ```
+ * utils.vega.svg($$, 
+ *   utils.vega.markCircle()
+ *     .title('Binned Rotten Tomatoes Rating by IMDB Rating')
+ *     .data(movies)
+ *     .encode(
+ *       utils.vega.x().fieldQ('Rotten Tomatoes Rating').bin({maxbins: 20}),
+ *       utils.vega.y().fieldQ('IMDB Rating').bin({maxbins: 20}),
+ *       utils.vega.size().count()
+ *     ));
+ * ```
+ * 
+ * ![Screenshot](img/MoviesRTbyIMDB.png)
+ * 
+ * or
+ * 
+ * ## Transformations
+ * 
+ * ```
+ * utils.vega.svg($$,
+ *   utils.vega.markBar()
+ *     .title('Gross by Director')
+ *     .width(400).height(400)
+ *     .data(movies)
+ *     .transform(
+ *       utils.vega.filter('datum.Director != null'),
+ *       utils.vega.aggregate(
+ *           utils.vega.sum('Worldwide Gross').as('Gross')
+ *       ).groupby('Director'),
+ *       utils.vega.window(utils.vega.rank().as('Rank'))
+ *         .sort(utils.vega.field('Gross').order('descending')),
+ *       utils.vega.filter('datum.Rank < 20')
+ *     )
+ *     .encode(
+ *       utils.vega.x().fieldQ('Gross'),
+ *       utils.vega.y().fieldN('Director')
+ *         .sort(utils.vega.field('Gross').order('descending'))
+ *     ))
+ * ```
+ * 
+ * ![Screenshot](img/MoviewGrossByDirector.png)
+ * 
+ * -----
+ * 
+ * * (see [@vega/vega-lite-api-v5 on observablehq](https://observablehq.com/@vega/vega-lite-api-v5) for a great introduction)
+ * * (see [vega-lite documentation](https://observablehq.com/@vega/vega-lite-api-v5) for deeper options)
+ * 
+ * @module vega
+ */
+const Vega = require('vega');
+const VegaLite = require('vega-lite');
+const VegaLiteApi = require('vega-lite-api');
+
+const vl = VegaLiteApi.register(Vega, VegaLite, {
+  config: {
+    // vega-lite default configuration
+    config: {
+      view: { continuousWidth: 400, continuousHeight: 300 },
+      mark: { tooltip: null }
+    }
+  },
+  view: {
+    renderer: 'svg'
+  }
+});
+
+/**
+ * Renders an svg of a vega lite diagram.
+ * 
+ * ObservableHQ has some great examples available here:
+ * [https://observablehq.com/@vega/vega-lite-api-v5](https://observablehq.com/@vega/vega-lite-api-v5)
+ * 
+ * @method svg
+ * @param {Display} display - the iJavaScript Display.
+ *    (Note: $$ refers to the current display within the iJavaScript kernel)
+ *    See [the NEL documentation for more](http://n-riesco.github.io/ijavascript/doc/custom.ipynb.html#Setting-the-output-using-the-global-object-$$)
+ * @param {Object} vlInstance - the vega-lite instance
+ *    (This is the vega-lite instance)
+ * 
+ * @example
+ * 
+ * vl.svg($$, 
+ *   vl.markCircle()
+ *     .title('Binned Rotten Tomatoes Rating by IMDB Rating')
+ *     .data(movies)
+ *     .encode(
+ *       vl.x().fieldQ('Rotten Tomatoes Rating').bin({maxbins: 20}),
+ *       vl.y().fieldQ('IMDB Rating').bin({maxbins: 20}),
+ *       vl.size().count()
+ *     ));
+ */
+const vegaLiteSvg = async (display, vlInstance) => {
+  const spec = vlInstance.toSpec();
+  const view = new Vega.View(Vega.parse(VegaLite.compile(spec).spec));
+  const svgText = await view.toSVG();
+  display.svg(svgText);
+};
+vl.svg = vegaLiteSvg.bind(vl);
+
+vl.help = () => console.log(`
+--
+  Helper for working with Vega-Lite within iJavaScript notebooks.
+  (see https://observablehq.com/@vega/vega-lite-api-v5)
+
+  Vega-Lite is a charting library that provides a great deal of flexibility
+  while also allowing for very simple use cases.
+
+  The Vega-Lite JavaScript API provides a convenient way to write Vega-Lite
+  specifications in a programmatic fashion.
+
+  utils.vega.svg($$, utils.vega.markPoint()
+    .data(cars)
+    .title('Displacement vs Horsepower')
+    .width(600)
+    .height(600)
+    .transform(
+      vl.filter('datum.Cylinders > 4')
+    )
+    .encode(
+      utils.vega.x().fieldQ('Displacement'),
+      utils.vega.y().fieldQ('Horsepower')
+    )
+  )
+
+  Types of fields:
+  * fieldT - time based
+  * fieldN - Nominal category
+  * fieldQ - qualitative number
+
+  You can also explicitly define the field like this:
+
+  utils.vega.svg( $$,
+    vl.markPoint()
+        .data(testExecution)
+        .width(500)
+        .encode(
+            vl.x().fieldQ('runtimeMinutes'),
+            vl.y({field:'classMethod', sort: '-x', axis: { labelLimit: 800}})
+        )
+  );
+
+  other examples
+
+  vl.svg($$, 
+    vl.markCircle()
+      .title('Binned Rotten Tomatoes Rating by IMDB Rating')
+      .data(movies)
+      .encode(
+        vl.x().fieldQ('Rotten Tomatoes Rating').bin({maxbins: 20}),
+        vl.y().fieldQ('IMDB Rating').bin({maxbins: 20}),
+        vl.size().count()
+      ));
+
+  vl.svg($$,
+    vl.markBar()
+      .title('Gross by Director')
+      .width(400).height(400)
+      .data(movies)
+      .transform(
+        vl.filter('datum.Director != null'),
+        vl.aggregate(vl.sum('Worldwide Gross').as('Gross')).groupby('Director'),
+        vl.window(vl.rank().as('Rank')).sort(vl.field('Gross').order('descending')),
+        vl.filter('datum.Rank < 20')
+      )
+      .encode(
+        vl.x().fieldQ('Gross'),
+        vl.y().fieldN('Director').sort(vl.field('Gross').order('descending'))
+      ))
+--
+`);
+
+module.exports = vl;