Merge pull request #109 from ethereumjs/fixFormatNodeRemove

Better document `_formatNode`

Author: ryanio

src/baseTrie.ts

@@ -340,7 +340,7 @@ export class Trie {
     } else if (lastNode instanceof BranchNode) {
       stack.push(lastNode)
       if (keyRemainder.length !== 0) {
-        // add an extention to a branch node
+        // add an extension to a branch node
         keyRemainder.shift()
         // create a new leaf
         const newLeaf = new LeafNode(keyRemainder, value)
@@ -354,7 +354,7 @@ export class Trie {
       const matchingLength = matchingNibbleLength(lastKey, keyRemainder)
       const newBranchNode = new BranchNode()
 
-      // create a new extention node
+      // create a new extension node
       if (matchingLength !== 0) {
         const newKey = lastNode.key.slice(0, matchingLength)
         const newExtNode = new ExtensionNode(newKey, value)
@@ -369,12 +369,12 @@ export class Trie {
         const branchKey = lastKey.shift() as number
 
         if (lastKey.length !== 0 || lastNode instanceof LeafNode) {
-          // shriking extention or leaf
+          // shrinking extension or leaf
           lastNode.key = lastKey
-          const formatedNode = this._formatNode(lastNode, false, toSave)
-          newBranchNode.setBranch(branchKey, formatedNode as EmbeddedNode)
+          const formattedNode = this._formatNode(lastNode, false, toSave)
+          newBranchNode.setBranch(branchKey, formattedNode as EmbeddedNode)
         } else {
-          // remove extention or attaching
+          // remove extension or attaching
           this._formatNode(lastNode, false, toSave, true)
           newBranchNode.setBranch(branchKey, lastNode.value)
         }
@@ -395,7 +395,14 @@ export class Trie {
     await this._saveStack(key, stack, toSave)
   }
 
-  // walk tree
+  /**
+   * Walks a trie until finished.
+   * @method _walkTrie
+   * @private
+   * @param {Buffer} root
+   * @param {Function} onNode - callback to call when a node is found
+   * @returns {Promise} - returns when finished walking trie
+   */
   async _walkTrie(root: Buffer, onNode: FoundNode): Promise<void> {
     return new Promise(async (resolve) => {
       const self = this
@@ -542,23 +549,23 @@ export class Trie {
         }
 
         if (branchNode instanceof BranchNode) {
-          // create an extention node
-          // branch->extention->branch
+          // create an extension node
+          // branch->extension->branch
           // @ts-ignore
-          const extentionNode = new ExtensionNode([branchKey], null)
-          stack.push(extentionNode)
+          const extensionNode = new ExtensionNode([branchKey], null)
+          stack.push(extensionNode)
           key.push(branchKey)
         } else {
           const branchNodeKey = branchNode.key
-          // branch key is an extention or a leaf
-          // branch->(leaf or extention)
+          // branch key is an extension or a leaf
+          // branch->(leaf or extension)
           branchNodeKey.unshift(branchKey)
           branchNode.key = branchNodeKey.slice(0)
           key = key.concat(branchNodeKey)
         }
         stack.push(branchNode)
       } else {
-        // parent is an extention
+        // parent is an extension
         let parentKey = parentNode.key
 
         if (branchNode instanceof BranchNode) {
@@ -569,7 +576,7 @@ export class Trie {
           stack.push(parentNode)
         } else {
           const branchNodeKey = branchNode.key
-          // branch node is an leaf or extention and parent node is an exstention
+          // branch node is an leaf or extension and parent node is an exstention
           // add two keys together
           // dont push the parent node
           branchNodeKey.unshift(branchKey)
@@ -654,8 +661,16 @@ export class Trie {
     await this._putNode(newNode)
   }
 
-  // formats node to be saved by levelup.batch.
-  // returns either the hash that will be used key or the rawNode
+  /**
+   * Formats node to be saved by levelup.batch.
+   * @method _formatNode
+   * @private
+   * @param {TrieNode} node - the node to format
+   * @param {Boolean} topLevel - if the node is at the top level
+   * @param {BatchDBOp[]} opStack - the opStack to push the node's data
+   * @param {Boolean} remove - whether to remove the node (only used for CheckpointTrie)
+   * @returns {Buffer | (EmbeddedNode | null)[]} - the node's hash used as the key or the rawNode
+   */
   _formatNode(
     node: TrieNode,
     topLevel: boolean,

src/checkpointTrie.ts

@@ -144,8 +144,16 @@ export class CheckpointTrie extends BaseTrie {
     return new ScratchReadStream(trie)
   }
 
-  // formats node to be saved by levelup.batch.
-  // returns either the hash that will be used key or the rawNode
+  /**
+   * Formats node to be saved by levelup.batch.
+   * @method _formatNode
+   * @private
+   * @param {TrieNode} node - the node to format
+   * @param {Boolean} topLevel - if the node is at the top level
+   * @param {BatchDBOp[]} opStack - the opStack to push the node's data
+   * @param {Boolean} remove - whether to remove the node (only used for CheckpointTrie)
+   * @returns {Buffer | (EmbeddedNode | null)[]} - the node's hash used as the key or the rawNode
+   */
   _formatNode(node: TrieNode, topLevel: boolean, opStack: BatchDBOp[], remove: boolean = false) {
     const rlpNode = node.serialize()
 

test/index.spec.ts

@@ -102,7 +102,7 @@ tape('simple save and retrive', function (tester) {
     })
   })
 
-  tape('testing Extentions and branches', function (tester) {
+  tape('testing extensions and branches', function (tester) {
     const it = tester.test
     const trie = new CheckpointTrie()
 
@@ -111,7 +111,7 @@ tape('simple save and retrive', function (tester) {
       t.end()
     })
 
-    it('should create extention to store this value', async function (t) {
+    it('should create extension to store this value', async function (t) {
       await trie.put(Buffer.from('do'), Buffer.from('verb'))
       t.equal(
         'f803dfcb7e8f1afd45e88eedb4699a7138d6c07b71243d9ae9bff720c99925f9',
@@ -120,7 +120,7 @@ tape('simple save and retrive', function (tester) {
       t.end()
     })
 
-    it('should store this value under the extention ', async function (t) {
+    it('should store this value under the extension', async function (t) {
       await trie.put(Buffer.from('done'), Buffer.from('finished'))
       t.equal(
         '409cff4d820b394ed3fb1cd4497bdd19ffa68d30ae34157337a7043c94a3e8cb',
@@ -130,11 +130,11 @@ tape('simple save and retrive', function (tester) {
     })
   })
 
-  tape('testing Extentions and branches - reverse', function (tester) {
+  tape('testing extensions and branches - reverse', function (tester) {
     const it = tester.test
     const trie = new CheckpointTrie()
 
-    it('should create extention to store this value', async function (t) {
+    it('should create extension to store this value', async function (t) {
       await trie.put(Buffer.from('do'), Buffer.from('verb'))
       t.end()
     })
@@ -144,7 +144,7 @@ tape('simple save and retrive', function (tester) {
       t.end()
     })
 
-    it('should store this value under the extention ', async function (t) {
+    it('should store this value under the extension', async function (t) {
       await trie.put(Buffer.from('done'), Buffer.from('finished'))
       t.equal(
         '409cff4d820b394ed3fb1cd4497bdd19ffa68d30ae34157337a7043c94a3e8cb',
@@ -155,7 +155,7 @@ tape('simple save and retrive', function (tester) {
   })
 })
 
-tape('testing deletions cases', function (tester) {
+tape('testing deletion cases', function (tester) {
   const it = tester.test
   const trie = new CheckpointTrie()
 
@@ -170,7 +170,7 @@ tape('testing deletions cases', function (tester) {
     t.end()
   })
 
-  it('should delete from a branch->branch-extention', async function (t) {
+  it('should delete from a branch->branch-extension', async function (t) {
     await trie.put(Buffer.from([11, 11, 11]), Buffer.from('first'))
     await trie.put(Buffer.from([12, 22, 22]), Buffer.from('create the first branch'))
     await trie.put(Buffer.from([12, 33, 33]), Buffer.from('create the middle branch'))
@@ -182,7 +182,7 @@ tape('testing deletions cases', function (tester) {
     t.end()
   })
 
-  it('should delete from a extention->branch-extention', async function (t) {
+  it('should delete from a extension->branch-extension', async function (t) {
     await trie.put(Buffer.from([11, 11, 11]), Buffer.from('first'))
     await trie.put(Buffer.from([12, 22, 22]), Buffer.from('create the first branch'))
     await trie.put(Buffer.from([12, 33, 33]), Buffer.from('create the middle branch'))
@@ -195,7 +195,7 @@ tape('testing deletions cases', function (tester) {
     t.end()
   })
 
-  it('should delete from a extention->branch-branch', async function (t) {
+  it('should delete from a extension->branch-branch', async function (t) {
     await trie.put(Buffer.from([11, 11, 11]), Buffer.from('first'))
     await trie.put(Buffer.from([12, 22, 22]), Buffer.from('create the first branch'))
     await trie.put(Buffer.from([12, 33, 33]), Buffer.from('create the middle branch'))