Merge pull request #125 from ethereumjs/base-trie-code-docs-and-base-…

…refactoring

Base trie code documentation and function clustering

src/checkpointTrie.ts

@@ -5,6 +5,9 @@ import { DB, BatchDBOp } from './db'
 import { TrieNode } from './trieNode'
 const WriteStream = require('level-ws')
 
+/**
+ * Adds checkpointing to the {@link BaseTrie}
+ */
 export class CheckpointTrie extends BaseTrie {
   _mainDB: DB
   _scratch: ScratchDB | null
@@ -80,7 +83,7 @@ export class CheckpointTrie extends BaseTrie {
 
   /**
    * Returns a copy of the underlying trie with the interface of CheckpointTrie.
-   * @param {boolean} includeCheckpoints - If true and during a checkpoint, the copy will contain the checkpointing metadata and will use the same scratch as underlying db.
+   * @param includeCheckpoints - If true and during a checkpoint, the copy will contain the checkpointing metadata and will use the same scratch as underlying db.
    */
   copy(includeCheckpoints = true): CheckpointTrie {
     const db = this._mainDB.copy()
@@ -140,10 +143,10 @@ export class CheckpointTrie extends BaseTrie {
   /**
    * Formats node to be saved by `levelup.batch`.
    * @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).
+   * @param node - the node to format.
+   * @param topLevel - if the node is at the top level.
+   * @param opStack - the opStack to push the node's data.
+   * @param remove - whether to remove the node (only used for CheckpointTrie).
    * @returns The node's hash used as the key or the rawNode.
    */
   _formatNode(node: TrieNode, topLevel: boolean, opStack: BatchDBOp[], remove: boolean = false) {

src/db.ts

@@ -24,15 +24,15 @@ export class DB {
   /**
    * Initialize a DB instance. If `leveldb` is not provided, DB
    * defaults to an [in-memory store](https://github.com/Level/memdown).
-   * @param {Object} [leveldb] - An abstract-leveldown compliant store
+   * @param leveldb - An abstract-leveldown compliant store
    */
   constructor(leveldb?: LevelUp) {
     this._leveldb = leveldb || level()
   }
 
   /**
    * Retrieves a raw value from leveldb.
-   * @param {Buffer} key
+   * @param key
    * @returns A Promise that resolves to `Buffer` if a value is found or `null` if no value is found.
    */
   async get(key: Buffer): Promise<Buffer | null> {
@@ -52,27 +52,24 @@ export class DB {
 
   /**
    * Writes a value directly to leveldb.
-   * @param {Buffer} key The key as a `Buffer`
-   * @param {Buffer} value The value to be stored
-   * @returns {Promise}
+   * @param key The key as a `Buffer`
+   * @param value The value to be stored
    */
   async put(key: Buffer, val: Buffer): Promise<void> {
     await this._leveldb.put(key, val, ENCODING_OPTS)
   }
 
   /**
    * Removes a raw value in the underlying leveldb.
-   * @param {Buffer} key
-   * @returns {Promise}
+   * @param keys
    */
   async del(key: Buffer): Promise<void> {
     await this._leveldb.del(key, ENCODING_OPTS)
   }
 
   /**
    * Performs a batch operation on db.
-   * @param {Array} opStack A stack of levelup operations
-   * @returns {Promise}
+   * @param opStack A stack of levelup operations
    */
   async batch(opStack: BatchDBOp[]): Promise<void> {
     await this._leveldb.batch(opStack, ENCODING_OPTS)

src/prioritizedTaskExecutor.ts

@@ -4,18 +4,18 @@ interface Task {
 }
 
 export class PrioritizedTaskExecutor {
+  /** The maximum size of the pool */
   private maxPoolSize: number
+  /** The current size of the pool */
   private currentPoolSize: number
+  /** The task queue */
   private queue: Task[]
 
   /**
    * Executes tasks up to maxPoolSize at a time, other items are put in a priority queue.
    * @class PrioritizedTaskExecutor
    * @private
-   * @param {Number} maxPoolSize The maximum size of the pool
-   * @prop {Number} maxPoolSize The maximum size of the pool
-   * @prop {Number} currentPoolSize The current size of the pool
-   * @prop {Array} queue The task queue
+   * @param maxPoolSize The maximum size of the pool
    */
   constructor(maxPoolSize: number) {
     this.maxPoolSize = maxPoolSize
@@ -26,8 +26,8 @@ export class PrioritizedTaskExecutor {
   /**
    * Executes the task.
    * @private
-   * @param {Number} priority The priority of the task
-   * @param {Function} fn The function that accepts the callback, which must be called upon the task completion.
+   * @param priority The priority of the task
+   * @param fn The function that accepts the callback, which must be called upon the task completion.
    */
   execute(priority: number, fn: Function) {
     if (this.currentPoolSize < this.maxPoolSize) {
@@ -48,7 +48,7 @@ export class PrioritizedTaskExecutor {
   /**
    * Checks if the taskExecutor is finished.
    * @private
-   * @returns {Boolean} - Returns `true` if the taskExecutor is finished, otherwise returns `false`.
+   * @returns Returns `true` if the taskExecutor is finished, otherwise returns `false`.
    */
   finished(): boolean {
     return this.currentPoolSize === 0

src/secure.ts

@@ -4,7 +4,7 @@ import { Proof } from './baseTrie'
 
 /**
  * You can create a secure Trie where the keys are automatically hashed
- * using **keccak256** by using `require('merkle-patricia-tree').SecureTrie`.
+ * using **keccak256** by using `import { SecureTrie as Trie } from 'merkle-patricia-tree'`.
  * It has the same methods and constructor as `Trie`.
  * @class SecureTrie
  * @extends Trie
@@ -15,20 +15,55 @@ export class SecureTrie extends CheckpointTrie {
     super(...args)
   }
 
+  /**
+   * Gets a value given a `key`
+   * @param key - the key to search for
+   * @returns A Promise that resolves to `Buffer` if a value was found or `null` if no value was found.
+   */
+  async get(key: Buffer): Promise<Buffer | null> {
+    const hash = keccak256(key)
+    const value = await super.get(hash)
+    return value
+  }
+
+  /**
+   * Stores a given `value` at the given `key`.
+   * For a falsey value, use the original key to avoid double hashing the key.
+   * @param key
+   * @param value
+   */
+  async put(key: Buffer, val: Buffer): Promise<void> {
+    if (!val || val.toString() === '') {
+      await this.del(key)
+    } else {
+      const hash = keccak256(key)
+      await super.put(hash, val)
+    }
+  }
+
+  /**
+   * Deletes a value given a `key`.
+   * @param key
+   */
+  async del(key: Buffer): Promise<void> {
+    const hash = keccak256(key)
+    await super.del(hash)
+  }
+
   /**
    * prove has been renamed to [[SecureTrie.createProof]].
    * @deprecated
-   * @param {Trie} trie
-   * @param {Buffer} key
+   * @param trie
+   * @param key
    */
   static async prove(trie: SecureTrie, key: Buffer): Promise<Proof> {
     return this.createProof(trie, key)
   }
 
   /**
    * Creates a proof that can be verified using [[SecureTrie.verifyProof]].
-   * @param {Trie} trie
-   * @param {Buffer} key
+   * @param trie
+   * @param key
    */
   static createProof(trie: SecureTrie, key: Buffer): Promise<Proof> {
     const hash = keccak256(key)
@@ -37,9 +72,9 @@ export class SecureTrie extends CheckpointTrie {
 
   /**
    * Verifies a proof.
-   * @param {Buffer} rootHash
-   * @param {Buffer} key
-   * @param {Proof} proof
+   * @param rootHash
+   * @param key
+   * @param proof
    * @throws If proof is found to be invalid.
    * @returns The value from the key.
    */
@@ -50,46 +85,11 @@ export class SecureTrie extends CheckpointTrie {
 
   /**
    * Returns a copy of the underlying trie with the interface of SecureTrie.
-   * @param {boolean} includeCheckpoints - If true and during a checkpoint, the copy will contain the checkpointing metadata and will use the same scratch as underlying db.
+   * @param includeCheckpoints - If true and during a checkpoint, the copy will contain the checkpointing metadata and will use the same scratch as underlying db.
    */
   copy(includeCheckpoints = true): SecureTrie {
     const trie = super.copy(includeCheckpoints)
     const db = trie.db.copy()
     return new SecureTrie(db._leveldb, this.root)
   }
-
-  /**
-   * Gets a value given a `key`
-   * @param {Buffer} key - the key to search for
-   * @returns A Promise that resolves to `Buffer` if a value was found or `null` if no value was found.
-   */
-  async get(key: Buffer): Promise<Buffer | null> {
-    const hash = keccak256(key)
-    const value = await super.get(hash)
-    return value
-  }
-
-  /**
-   * Stores a given `value` at the given `key`.
-   * For a falsey value, use the original key to avoid double hashing the key.
-   * @param {Buffer} key
-   * @param {Buffer} value
-   */
-  async put(key: Buffer, val: Buffer): Promise<void> {
-    if (!val || val.toString() === '') {
-      await this.del(key)
-    } else {
-      const hash = keccak256(key)
-      await super.put(hash, val)
-    }
-  }
-
-  /**
-   * Deletes a value given a `key`.
-   * @param {Buffer} key
-   */
-  async del(key: Buffer): Promise<void> {
-    const hash = keccak256(key)
-    await super.del(hash)
-  }
 }

src/util/hex.ts

@@ -2,8 +2,8 @@ import { Nibbles } from '../trieNode'
 
 /**
  * Prepends hex prefix to an array of nibbles.
- * @param {Nibbles} key - Array of nibbles
- * @returns {Nibbles} - returns buffer of encoded data
+ * @param key - Array of nibbles
+ * @returns returns buffer of encoded data
  **/
 export function addHexPrefix(key: Nibbles, terminator: boolean): Nibbles {
   // odd
@@ -24,7 +24,7 @@ export function addHexPrefix(key: Nibbles, terminator: boolean): Nibbles {
 
 /**
  * Removes hex prefix of an array of nibbles.
- * @param {Nibbles} val - Array of nibbles
+ * @param val - Array of nibbles
  * @private
  */
 export function removeHexPrefix(val: Nibbles): Nibbles {
@@ -39,7 +39,7 @@ export function removeHexPrefix(val: Nibbles): Nibbles {
 
 /**
  * Returns true if hex-prefixed path is for a terminating (leaf) node.
- * @param {Nibbles} key - a hex-prefixed array of nibbles
+ * @param key - a hex-prefixed array of nibbles
  * @private
  */
 export function isTerminator(key: Nibbles): boolean {

src/util/nibbles.ts

@@ -3,7 +3,7 @@ import { Nibbles } from '../trieNode'
 /**
  * Converts a buffer to a nibble array.
  * @private
- * @param {Buffer} key
+ * @param key
  */
 export function bufferToNibbles(key: Buffer): Nibbles {
   const bkey = Buffer.from(key)
@@ -22,7 +22,7 @@ export function bufferToNibbles(key: Buffer): Nibbles {
 /**
  * Converts a nibble array into a buffer.
  * @private
- * @param {Nibbles} arr - Nibble array
+ * @param arr - Nibble array
  */
 export function nibblesToBuffer(arr: Nibbles): Buffer {
   let buf = Buffer.alloc(arr.length / 2)
@@ -36,8 +36,8 @@ export function nibblesToBuffer(arr: Nibbles): Buffer {
 /**
  * Returns the number of in order matching nibbles of two give nibble arrays.
  * @private
- * @param {Nibbles} nib1
- * @param {Nibbles} nib2
+ * @param nib1
+ * @param nib2
  */
 export function matchingNibbleLength(nib1: Nibbles, nib2: Nibbles): number {
   let i = 0
@@ -49,8 +49,8 @@ export function matchingNibbleLength(nib1: Nibbles, nib2: Nibbles): number {
 
 /**
  * Compare two nibble array keys.
- * @param {Nibbles} keyA
- * @param {Nibbles} keyB
+ * @param keyA
+ * @param keyB
  */
 export function doKeysMatch(keyA: Nibbles, keyB: Nibbles): boolean {
   const length = matchingNibbleLength(keyA, keyB)