JSDoc added, include/exclude array functionality for depth and comple…

…xity methods

functions/basic.js

@@ -1,17 +1,17 @@
-const determineDepth = (jt, obj) => {
+const determineDepth = (jt, obj, includeArrays) => {
     let depth = 0;
-    jt.traverse(obj, { enterLevel: (level, path) => { if (level > depth) depth = level; } });
+    jt.traverse(obj, { enterLevel: (level, path) => { if (level > depth) depth = level; } }, !includeArrays);
     return depth;
 }
 
-module.exports.getDepth = (jt, obj) => {
-    return determineDepth(jt, obj);
+module.exports.getDepth = (jt, obj, includeArrays) => {
+    return determineDepth(jt, obj, includeArrays);
 }
 
-module.exports.isSimple = (jt, obj) => {
-    return determineDepth(jt, obj) === 0;
+module.exports.isSimple = (jt, obj, includeArrays) => {
+    return determineDepth(jt, obj, includeArrays) === 0;
 }
 
-module.exports.isComplex = (jt, obj) => {
-    return determineDepth(jt, obj) > 0;
+module.exports.isComplex = (jt, obj, includeArrays) => {
+    return determineDepth(jt, obj, includeArrays) > 0;
 }

json-traverse-tools.js

@@ -1,6 +1,7 @@
 const basic = require('./functions/basic');
 const obfuscate = require('./functions/obfuscate');
 
+/** @module @tsmx/json-traverse-tools */
 module.exports = (jt) => {
     return {
         obfuscate: {
@@ -17,14 +18,32 @@ module.exports = (jt) => {
                 obfuscate.obfuscateValueRegex(jt, obj, pattern, replacement);
             }
         },
-        getDepth: (obj) => {
-            return basic.getDepth(jt, obj);
+        /**
+         * Retrieves the depth (nesting level) of a JSON object.
+         * @param {Object} obj the object to inspect
+         * @param {boolean} includeArrays sets if objects in arrays should be considered (default: true) 
+         * @returns the 0-based depth of the JSON
+         */
+        getDepth: (obj, includeArrays = true) => {
+            return basic.getDepth(jt, obj, includeArrays);
         },
-        isSimple: (obj) => {
-            return basic.isSimple(jt, obj);
+        /**
+         * Checks if a JSON object is simple, meaning it has no nested objects (depth == 0).
+         * @param {Object} obj the object to inspect
+         * @param {boolean} includeArrays sets if objects in arrays should be considered (default: true)
+         * @returns True, if the JSON is simple.
+         */
+        isSimple: (obj, includeArrays = true) => {
+            return basic.isSimple(jt, obj, includeArrays);
         },
-        isComplex: (obj) => {
-            return basic.isComplex(jt, obj);
+        /**
+         * Checks if a JSON object is complex, meaning it has nested objects (depth > 0).
+         * @param {Object} obj the object to inspect
+         * @param {boolean} includeArrays sets if objects in arrays should be considered (default: true)
+         * @returns True, if the JSON is complex.
+         */
+        isComplex: (obj, includeArrays = true) => {
+            return basic.isComplex(jt, obj, includeArrays);
         }
     }
 }

test/jtt-basic.test.js

@@ -3,6 +3,10 @@ describe('json-traverse-tools basic functions test suite', () => {
     const jt = require('@tsmx/json-traverse');
     const jtt = require('../json-traverse-tools')(jt);
 
+    beforeEach(() => {
+        jest.resetModules();
+    });
+
     it('tests getting the depth of a simple JSON object', async () => {
         let obj = require('./objects/simple.json');
         expect(jtt.getDepth(obj)).toBe(0);
@@ -13,24 +17,54 @@ describe('json-traverse-tools basic functions test suite', () => {
         expect(jtt.getDepth(obj)).toBe(1);
     });
 
-    it('tests successful isSimple check for a JSON object', async () => {
+    it('tests getting the depth of a JSON with a complex array', async () => {
+        let obj = require('./objects/array.json');
+        expect(jtt.getDepth(obj)).toBe(2);
+    });
+
+    it('tests getting the depth of a JSON with a complex array and includeArrays=false', async () => {
+        let obj = require('./objects/array.json');
+        expect(jtt.getDepth(obj, false)).toBe(0);
+    });
+
+    it('tests positive isSimple check for a JSON object', async () => {
         let obj = require('./objects/simple.json');
         expect(jtt.isSimple(obj)).toBeTruthy();
     });
 
-    it('tests failed isSimple check for a JSON object', async () => {
+    it('tests negative isSimple check for a JSON object', async () => {
         let obj = require('./objects/nested-1.json');
         expect(jtt.isSimple(obj)).toBeFalsy();
     });
 
-    it('tests successful isComplex check for a JSON object', async () => {
+    it('tests positive isSimple check for a JSON object with a complex array (includeArrays=false)', async () => {
+        let obj = require('./objects/array.json');
+        expect(jtt.isSimple(obj, false)).toBeTruthy();
+    });
+
+    it('tests negative isSimple check for a JSON object with a complex array (includeArrays=true)', async () => {
+        let obj = require('./objects/array.json');
+        expect(jtt.isSimple(obj)).toBeFalsy();
+    });
+
+    it('tests positive isComplex check for a JSON object', async () => {
         let obj = require('./objects/simple.json');
         expect(jtt.isComplex(obj)).toBeFalsy();
     });
 
-    it('tests failed isComplex check for a JSON object', async () => {
+    it('tests negative isComplex check for a JSON object', async () => {
         let obj = require('./objects/nested-1.json');
         expect(jtt.isComplex(obj)).toBeTruthy();
     });
 
+    it('tests positive isComplex check for a JSON object with a complex array (includeArrays=false)', async () => {
+        let obj = require('./objects/array.json');
+        expect(jtt.isComplex(obj, false)).toBeFalsy();
+    });
+
+    it('tests negative isComplex check for a JSON object with a complex array (includeArrays=true)', async () => {
+        let obj = require('./objects/array.json');
+        expect(jtt.isComplex(obj)).toBeTruthy();
+    });
+
 });

test/objects/array.json

@@ -0,0 +1,15 @@
+{
+    "testArray": [
+        1,
+        2,
+        {
+            "firstName": "Dow",
+            "lastName": "Jones",
+            "country": {
+                "name": "United States",
+                "code": "US"
+            }
+        },
+        "four"
+    ]
+}