more documentation

Author: LucasArmstrong

README.md

@@ -4,36 +4,37 @@
 [MerkleHash](https://github.com/LucasArmstrong/merkle-ts/blob/main/src/merkle/MerkleHash.ts), 
 and [MerkleChain](https://github.com/LucasArmstrong/merkle-ts/blob/main/src/merkle/MerkleChain.ts) 
 in TypeScript
-- Created by: Lucas Armstrong - Lucas@throneit.com - github.com/LucasArmstrong
+- Created by: Lucas Armstrong - Lucas@throneit.com - [github.com/LucasArmstrong](https://github.com/LucasArmstrong)
 - License: `MIT`
 
 ## Install in your project with NPM and use it
 - In your project run:
-- >`npm i https://github.com/LucasArmstrong/merkle-ts`
+- >npm i https://github.com/LucasArmstrong/merkle-ts
 - For TypeScript projects you can import the module MerkleTree
-- For JavaScript projects you can build with `npm run build`
+- For JavaScript projects you can build with:
+- >npm run build
 - - Then require in your code like:
-- - >`const {MerkleTree} = require('./node_modules/merkle-ts/dist/src/merkle/MerkleTree.js');`
+- - >const {MerkleTree} = require('./node_modules/merkle-ts/dist/src/merkle/MerkleTree.js');
 - - Example of using a merkle root in a jest test:
-- - >`let tree = new MerkleTree([1]); expect(tree.root).toBe('6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b');`
+- - >let tree = new MerkleTree([1]); expect(tree.root).toBe('6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b');
 
 ## Calculate a Merkle Root from a directory of files recursively
 - First set or export environment variable `ASSET_DIRECTORY_PATH` to the directory you want to process.
 - Then run:
-- >`npm run process`
+- >npm run process
 - Digests and calculates a Merkle Root for the entire specified directory and contents
 
-### Test
+## Test
 - Execute tests with:
-- >`npm run test`
+- >npm run test
 - Runs a variety of tests proving that the MerkleTree class correctly calculates the merkle root for a set of data
 
 ## Merkle Tree Info.
 In cryptography and computer science, a hash tree or Merkle tree is a tree in which every "leaf" (node) is labelled with the cryptographic hash of a data block, and every node that is not a leaf (called a branch, inner node, or inode) is labelled with the cryptographic hash of the labels of its child nodes. A hash tree allows efficient and secure verification of the contents of a large data structure. A hash tree is a generalization of a hash list and a hash chain.
 - Read more at https://en.wikipedia.org/wiki/Merkle_tree
 
 ## Available Hash Algorithms
->'RSA-MD4',
+`'RSA-MD4',
 'RSA-MD5',
 'RSA-MDC2',
 'RSA-RIPEMD160',
@@ -91,4 +92,4 @@ In cryptography and computer science, a hash tree or Merkle tree is a tree in wh
 'sm3WithRSAEncryption',
 'ssl3-md5',
 'ssl3-sha1',
-'whirlpool'
+'whirlpool'`

src/merkle/MerkleChain.ts

@@ -1,7 +1,8 @@
 /** 
- * @module MerkleChain - list based data structure seeded with a gensis timestamp and 
+ * @module MerkleChain - list based data structure seeded with a genesis timestamp and 
  *          maintains a merkle root, optimized to quickly traverse and search nodes 
  * @module MerkleChainNode - type for the nodes in MerkleChain
+ * 
  * @author Lucas Armstrong - Lucas@throneit.com - github.com/LucasArmstrong
  */
 
@@ -18,8 +19,15 @@ export type MerkleChainNodeNullable = MerkleChainNode | null;
 
 /**
  * @class MerkleChainNode
+ * 
+ * @param genesisAt {number}
+ * @param dataArray {MerkleDataType[]}
  */
 export class MerkleChainNode {
+
+    /**
+     * @var next
+     */
     private _next: MerkleChainNodeNullable = null;
     set next(nextNode: MerkleChainNodeNullable) {
         this._next = nextNode;
@@ -33,11 +41,17 @@ export class MerkleChainNode {
         return this._next;
     }
 
+    /**
+     * @var nextRoot
+     */
     private _nextRoot: string = '';
     get nextRoot(): string {
         return this._nextRoot;
     }
 
+    /**
+     * @var prev
+     */
     private _prev: MerkleChainNodeNullable = null;
     set prev(prevNode: MerkleChainNodeNullable) {
         this._prev = prevNode;
@@ -51,12 +65,22 @@ export class MerkleChainNode {
         return this._prev;
     }
 
+    /**
+     * @var prevRoot
+     */
     private _prevRoot: string = '';
     get prevRoot(): string {
         return this._prevRoot;
     }
 
+    /**
+     * @var merkleRoot
+     */
     merkleRoot: string = '';
+
+    /**
+     * @var dataArray
+     */
     dataArray: MerkleDataType[];
 
     constructor (genesisAt: number, dataArray: MerkleDataType[] = []) {
@@ -71,13 +95,28 @@ export class MerkleChainNode {
 
 /**
  * @class MerkleChain
+ * @param dataArray {MerkleDataType[]}
  */
 export class MerkleChain {
+    
+    /**
+     * @var head - pointer for the node at the start of the list
+     */
     head: MerkleChainNodeNullable = null;
+
+    /**
+     * @var tail - pointer for the node at the end of the list
+     */
     tail: MerkleChainNodeNullable = null;
 
+    /**
+     * @var genesisAt - timestamp used to seed the list
+     */
     genesisAt: number = 0;
 
+    /**
+     * @var merkleRoot
+     */
     private _merkleRoot: string = '';
     get merkleRoot(): string {
         return this._merkleRoot;
@@ -88,11 +127,22 @@ export class MerkleChain {
         this.genesisAt = new Date().getTime();
     }
 
-    addNode(dataArray: MerkleDataType[] = []) {
+    /**
+     * @method addNode - creates a new node from a MerkleDataType array
+     * 
+     * @param dataArray {MerkleDataType[]} - array of MerkleDataType data that gets inserted into the list as a new node
+     * @returns {void}
+     */
+    addNode(dataArray: MerkleDataType[] = []): void {
         this.newNode(new MerkleChainNode(this.genesisAt, dataArray));
         this._merkleRoot = new MerkleTree(this.toRootArray()).root;
     }
 
+    /**
+     * @method toRootArray - returns an array of the merkle roots from all nodes in the list
+     * 
+     * @returns {string[]}
+     */
     toRootArray(): string[] {
         const values: string[] = [];
         let current: MerkleChainNodeNullable = this.head;
@@ -103,6 +153,12 @@ export class MerkleChain {
         return values;
     }
 
+    /**
+     * @method newNode - manages inserting a new node to the list
+     * 
+     * @param node {MerkleChainNode} - node to be added to the list
+     * @returns {MerkleChainNode}
+     */
     private newNode(node: MerkleChainNode) : MerkleChainNode {
         if (!this.head) {
             this.head = node;
@@ -119,4 +175,5 @@ export class MerkleChain {
 
         return node;
     }
+
 }

src/merkle/MerkleFileProcessor.ts

@@ -1,5 +1,6 @@
 /** 
  * @module MerkleFileProcessor - utilities to find the Merkle Root of a file or directory
+ * 
  * @author Lucas Armstrong - Lucas@throneit.com - github.com/LucasArmstrong
  */
 
@@ -70,4 +71,5 @@ export class MerkleFileProcessor {
             throw new Error(`processDirectory Error: ${error}`);
         }
     }
+
 }

src/merkle/MerkleHash.ts

@@ -1,5 +1,6 @@
 /** 
  * @module MerkleHash - hash utlities for MerkleTree
+ * 
  * @author Lucas Armstrong - Lucas@throneit.com - github.com/LucasArmstrong 
  */
 
@@ -95,6 +96,7 @@ export class MerkleHash {
 
     /**
      * @method createHashFromFile - Static method to be used as utility in order to create a hash from a file of any size
+     * 
      * @param filePath 
      * @returns {Promise<string>}
      */
@@ -133,4 +135,5 @@ export class MerkleHash {
                 return dataType;
         }
     }
+
 }

src/merkle/MerkleTree.ts

@@ -1,5 +1,6 @@
 /** 
  * @module MerkleTree - generates a MerkleTree from a list of data
+ * 
  * @author Lucas Armstrong - Lucas@throneit.com - github.com/LucasArmstrong 
  */
 
@@ -157,4 +158,5 @@ export class MerkleTree implements IMerkleTree {
         // one hash means the root has been found
         return hashed[0];
     }
+
 }