Merge pull request #16 from bigman73/feature/improved-tester

Feature/improved tester

.eslintrc.json

@@ -6,7 +6,11 @@
         "mocha": true
     },
     "extends": [
-        "airbnb-base"
+        "airbnb-base",
+        "plugin:jsdoc/recommended"
+    ],
+    "plugins": [
+        "jsdoc"
     ],
     "globals": {
         "Atomics": "readonly",

.vscode/launch.json

@@ -19,6 +19,14 @@
             "name": "Run NBA graph demo",
             "args": [],
             "program": "${workspaceFolder}/demo/nba-demo.js"
+        },
+        {
+            "type": "node",
+            "request": "launch",
+            "name": "Run external module tester",
+            "cwd": "${workspaceFolder}/test-jay-gee-eff",
+            "args": [],
+            "program": "${workspaceFolder}/test-jay-gee-eff/index.js"
         }
     ]
 }

CHANGELOG.md

@@ -3,7 +3,13 @@ All notable changes to this project will be documented in this file.
 
 ## [Released]
 
-## [2.1.0] - TBD
+## [2.2.0] - 2020-07-21
+- Added eslint jsdoc enforcement
+- Fixed all eslint issues
+- Added: loadFromFileV1() function for backward compatibility with files generated with v1 schema
+- Added: Test application that uses the npm module (also a demo app)
+
+## [2.1.0] - 2020-07-19
 - Refactor code in src folder
 - Add support for legacy v1 schema, loadFromFileV1
 - Fixed: Added missing jgfSchemaV1.json, jgfSchemaV2.json to package

README.md

@@ -21,7 +21,8 @@ A library that provides the following features:
 6. Support the JGF v2 Schema
 
 ## Important note
-The JGF Schema has changed from v1 to v2. v2 is not backward compatible with v1. jay-gee-eff up to version 1.3.1 supported JGF Schema v1. Starting from jay-gee-eff v2 there is support for JGF Schema v2 which is a breaking change. Files generated with jay-gee-eff v1.* would not read properly with jay-gee-eff v2.*
+The JGF Schema has changed from v1 to v2. v2 is not backward compatible with v1. jay-gee-eff up to version 1.3.1 supported JGF Schema v1. Starting from jay-gee-eff version 2.0.0 there is support for JGF Schema v2 which is a breaking change. 
+Files previously generated with jay-gee-eff v1.* can be read with the special function *JGFContainer.loadFromFileV1()*
 
 # Installation
 ```

package.json

@@ -1,6 +1,6 @@
 {
   "name": "jay-gee-eff",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "JGF - JSON Graph Format manipulation module. Reads and writes JGF files.",
   "main": "index.js",
   "files": [
@@ -45,6 +45,7 @@
     "eslint": "^7.5.0",
     "eslint-config-airbnb-base": "^14.2.0",
     "eslint-plugin-import": "^2.22.0",
+    "eslint-plugin-jsdoc": "^30.0.3",
     "mocha": "^8.0.1"
   },
   "dependencies": {

src/common.js

@@ -5,6 +5,7 @@ const fastClone = require('fast-clone');
  * Clones an object (using fast clone)
  *
  * @param {object} obj source object o clone
+ * @returns {object} cloned object
  */
 const cloneObject = (obj) => fastClone(obj);
 

src/jgfContainer.js

@@ -33,7 +33,8 @@ const readJGFSchemaV2 = async () => {
 class JGFContainer {
     /**
      * Constructor
-     * @param {*} singleGraph true for single-graph mode, false for multi-graph mode
+     *
+     * @param {boolean} singleGraph true for single-graph mode, false for multi-graph mode
      */
     constructor(singleGraph = true) {
         this.JGFSchemaValidator = new Validator();
@@ -47,6 +48,8 @@ class JGFContainer {
 
     /**
      * Returns all graphs, in Multi-Graph mode
+     *
+     * @returns {Array} List of graphs
      */
     get graphs() {
         if (this.isSingleGraph) {
@@ -58,6 +61,8 @@ class JGFContainer {
 
     /**
      * Returns the graph, in Single-Graph mode
+     *
+     * @returns {object} The single graph
      */
     get graph() {
         if (!this.isSingleGraph) {
@@ -68,14 +73,18 @@ class JGFContainer {
     }
 
     /**
-     * Returns true if the container is in Multi-Graph mode
+     * Multi-Graph mode flag
+     *
+     * @returns {boolean} Returns true if the container is in Multi-Graph mode, otherwise false
      */
     get isMultiGraph() {
         return !this.isSingleGraph;
     }
 
     /**
      * Adds an empty graph
+     *
+     * @returns {object} Empty graph
      */
     addEmptyGraph() {
         const graph = new JGFGraph();
@@ -167,6 +176,8 @@ class JGFContainer {
      * Loads multiple partial graph files into a single merged in-memory graph
      *
      * @param {string} filenameWildcard pattern to use for partial JGF files
+     * @param {string} type Graph type
+     * @param {string} label Graph label
      */
     async loadFromPartialFiles(filenameWildcard, type, label) {
         try {
@@ -240,6 +251,7 @@ class JGFContainer {
      * Saves the in memory JSON graph into a JGF file
      *
      * @param {string} filename JGF filename
+     * @param {boolean} prettyPrint true to output a easy to read JSON, false for a compact JSON
      */
     async saveToFile(filename, prettyPrint = false) {
         try {

src/jgfGraph.js

@@ -15,6 +15,7 @@ class JGFGraph {
      * @param {string} type graph classification
      * @param {string} label a text display for the graph
      * @param {boolean} directed true for a directed graph, false for an undirected graph
+     * @param {object} metadata Graph meta data attributes
      */
     constructor(id = '', type = '', label = '', directed = true, metadata = null) {
         this.validator = new Validator();
@@ -68,6 +69,8 @@ class JGFGraph {
 
     /**
      * Returns the isPartial flag
+     *
+     * @returns {boolean} true if partial graph, otherwise false
      */
     get isPartial() {
         return this._isPartial;
@@ -82,6 +85,8 @@ class JGFGraph {
 
     /**
      * Returns the graph id
+     *
+     * @returns {string} graph id
      */
     get id() {
         return this._id;
@@ -96,6 +101,8 @@ class JGFGraph {
 
     /**
      * Returns the graph type
+     *
+     * @returns {string} Graph type
      */
     get type() {
         return this._type;
@@ -110,6 +117,8 @@ class JGFGraph {
 
     /**
      * Returns the graph label
+     *
+     * @returns {string} Graph label
      */
     get label() {
         return this._label;
@@ -124,6 +133,8 @@ class JGFGraph {
 
     /**
      * Returns the graph meta data
+     *
+     * @returns {object} Graph meta data attribute
      */
     get metadata() {
         return this._metadata;
@@ -138,20 +149,26 @@ class JGFGraph {
 
     /**
      * Returns all nodes
+     *
+     * @returns {Array} List of all nodes
      */
     get nodes() {
         return cloneObject(this._nodes);
     }
 
     /**
      * Returns all edges
+     *
+     * @returns {Array} List of all edges
      */
     get edges() {
         return cloneObject(this._edges);
     }
 
     /**
      * Returns the graph as JGF Json
+     *
+     * @returns {object} Graph as JGF JSON object
      */
     get json() {
         const json = {
@@ -192,6 +209,7 @@ class JGFGraph {
      *
      * @param {string} id Node id
      * @param {string} label Node label
+     * @param {object} metadata Node meta data attributes
      */
     addNode(id, label, metadata = null) {
         if (id in this._nodes) {
@@ -212,7 +230,7 @@ class JGFGraph {
     /**
      * Adds multiple nodes, for legacy V1 JGF Schema
      *
-     * @param {*} nodes A collection of JGF node objects
+     * @param {Array} nodes A collection of JGF node objects
      */
     addNodesV1(nodes) {
         for (const node of nodes) {
@@ -227,7 +245,7 @@ class JGFGraph {
     /**
      * Adds multiple nodes
      *
-     * @param {*} nodes A collection of JGF node objects
+     * @param {Array} nodes A collection of JGF node objects
      */
     addNodes(nodes) {
         for (const [nodeId, node] of Object.entries(nodes)) {
@@ -244,7 +262,7 @@ class JGFGraph {
      *
      * @param {string} nodeId Node id
      * @param {string} label Updated node label
-     * @param {object} metadata Updated node meta data
+     * @param {object} metadata Updated node meta data attributes
      */
     updateNode(nodeId, label, metadata = null) {
         if (!(nodeId in this._nodes)) {
@@ -279,6 +297,7 @@ class JGFGraph {
      * Lookup a node by a node id
      *
      * @param {string} nodeId Unique node id
+     * @returns {object} Graph node
      */
     getNode(nodeId) {
         if (!(nodeId in this._nodes)) {
@@ -345,6 +364,7 @@ class JGFGraph {
 
     /**
      * Adds multiple edges
+     *
      * @param {*} edges A collection of JGF edge objects
      */
     addEdges(edges) {
@@ -361,6 +381,7 @@ class JGFGraph {
 
     /**
      * Removes existing graph edges
+     *
      * @param {string} source Source node id
      * @param {string} target Target node id
      * @param {string} relation Specific edge relation type to remove.
@@ -374,9 +395,11 @@ class JGFGraph {
 
     /**
      * Get edges between source node and target node, with an optional edge relation
-     * @param {string} source
-     * @param {string} target
-     * @param {string} relation
+     *
+     * @param {string} source Node source id
+     * @param {string} target Node target id
+     * @param {string} relation Relationship name
+     * @returns {Array} List of matching edges
      */
     getEdges(source, target, relation = '') {
         if (!this.isPartial) {
@@ -398,6 +421,8 @@ class JGFGraph {
 
     /**
      * Returns the graph dimensions - Number of nodes and edges
+     *
+     * @returns {object} Graph dimensions
      */
     get graphDimensions() {
         const dimensions = {

src/misc.js

@@ -4,6 +4,7 @@ const glob = require('glob');
  * Returns all files matching the wild card pattern
  *
  * @param {string} filenameWildcard filename wildcard pattern
+ * @returns {Array} list of files
  */
 const getMatchingFiles = (filenameWildcard) => new Promise((resolve, reject) => {
     glob(filenameWildcard, (err, files) => {