🎨 Assorted cleanup

.eslintrc.js

@@ -39,21 +39,50 @@ module.exports = {
       plugins: ['jsdoc'],
       extends: ['plugin:jsdoc/recommended'],
       rules: {
-        'jsdoc/check-tag-names': ['warn', { definedTags: ['alpha', 'beta'] }], // Should check that tag names are valid; include 'alpha' and 'beta' as acceptable tag names
-        'jsdoc/require-param-type': 'off', // TypeDoc automatically reads types from TypeScript types, hence param types should rarely be defined explictly -- https://typedoc.org/guides/doccomments/#%40param-%3Cparam-name%3E
-        'jsdoc/require-returns-type': 'off', // Read above note for `jsdoc/require-param-type`
         // 'jsdoc/check-examples': 'warn', // Ensures examples match a certain format -- currently not supported for ESLint, waiting for this issue -- https://github.com/eslint/eslint/issues/14745
         'jsdoc/check-indentation': 'warn', // Ensures proper indentation of items inside TypeDoc comments
         'jsdoc/check-line-alignment': 'warn', // Ensures TypeDoc comments are aligned to match what it's documenting
         'jsdoc/check-syntax': 'warn', // Ensures that documentation syntax is appropriate for Google Closure Compiler
+        'jsdoc/check-tag-names': [
+          'warn',
+          { definedTags: ['alpha', 'beta', 'internal'] },
+        ], // Should check that tag names are valid; include 'alpha' and 'beta' as acceptable tag names
+        'jsdoc/no-multi-asterisks': ['warn', { allowWhitespace: true }],
         'jsdoc/require-asterisk-prefix': 'warn', // Require that all documentation is prefixed with an asterisk, makes it easier to differentiate what's documentation and what isn't
+        // 'jsdoc/require-description': ['warn'],
         'jsdoc/require-example': 'warn', // Ensures that all documentated functions have examples
         'jsdoc/require-hyphen-before-param-description': ['warn', 'never'], // Prevent hyphens before description of a parameter
+        'jsdoc/require-param-type': 'off', // TypeDoc automatically reads types from TypeScript types, hence param types should rarely be defined explictly -- https://typedoc.org/guides/doccomments/#%40param-%3Cparam-name%3E
         'jsdoc/require-returns': [
           'warn',
           { checkGetters: true, forceReturnsWithAsync: true },
         ],
-        'jsdoc/no-multi-asterisks': ['warn', { allowWhitespace: true }],
+        'jsdoc/require-returns-type': 'off', // Read above note for `jsdoc/require-param-type`
+      },
+    },
+    {
+      files: 'src/providers/BaseProvider.ts',
+      rules: {
+        'jsdoc/match-description': [
+          'warn',
+          {
+            message: `Description formatting error`,
+            // The description should match this formatting:
+            // /**
+            //  * Returns transaction receipt event logs that match a specified filter.
+            //  *
+            //  * * [Identical](/docs/api#isd) to [ethers.provider.getLogs](https://docs.ethers.io/v5/api/providers/provider/#Provider-getLogs) in ethers.js
+            //  * * [Identical](/docs/api#isd) to [web3.eth.getPastLogs](https://web3js.readthedocs.io/en/v1.7.3/web3-eth.html#getpastlogs) in web3.js
+
+            // In other words...
+            // * needs text description line explaining what function does. Starts with capital letter, ends with period
+            // * line break
+            // * needs two lines comparing to ethers and web3. Lines need to start with links that have the text Identical, Similar, or Dissimilar that link to /docs/api#isd
+            // * Comparing lines need to have links to ethers or web3, and end with either "in ethers.js" or "in web3.js"
+            matchDescription:
+              '(?:[A-Z].*\\.\\n{0,2}?)+\\n\\n(?:\\* (?:(?:\\[(?:Identical|Similar|Dissimilar)\\]\\(\\/docs\\/api#isd\\) to \\[`.*`\\]\\(.*\\))|(?:No equivalent)) in (?:ethers|web3).js,?(?:.*)\\n{0,1}){2}', //  https://regex101.com/r/1dvZxX/
+          },
+        ],
       },
     },
   ],

readme.md

@@ -1540,5 +1540,14 @@ Any function on a contract. Returns are the same as `ethers.js`, except that ins
 
 <br/>
 
+### Identical vs Similar vs Dissimliar {#isd}
+Throughout the documentation for `essential-eth`, you may notice that some functions are compared to `ethers.js` and `web3.js`. The keywords `identical`, `similar`, and `dissimilar` are used to help you migrate to `essential-eth`. Here's a guide on what these keywords mean:
+- Identical -- should behave exactly like the library you're already using, except the types might be different (`TinyBig` vs [`Bn.js`](https://github.com/indutny/bn.js)).
+- Similar -- can probably be used as a replacement to the library you're currently using, except there are some differences. Read the notes next to this keyword to see why these aren't considered `identical`.
+- Dissimilar -- *should not* be used in place of the function you're currently using. Read the notes next to this keyword to see why these functions aren't considered `similar`, and potentially learn how to alter your implementation to make `essential-eth` work for you.
+
+Note: In `web3.js`, almost every method or function can be passed a callback. `essential-eth`, like `ethers.js`, does not include this functionality and trusts that users will rely on the much more modern [promise](https://javascript.info/promise-basics) and [async/await](https://javascript.info/async-await) patterns.
+
+### Miscellaneous 
 - [📓 View full docs](https://essential-eth.vercel.app)
 - [📓 View changelog (by looking at releases diff)](https://github.com/dawsbot/essential-eth/releases)

src/classes/utils/clean-transaction.ts

@@ -30,7 +30,6 @@ export function cleanTransaction(
     switch (key) {
       case 'blockNumber':
       case 'chainId':
-      case 'nonce':
       case 'transactionIndex':
       case 'type':
       case 'v':
@@ -47,8 +46,8 @@ export function cleanTransaction(
       case 'gasPrice':
       case 'maxFeePerGas':
       case 'maxPriorityFeePerGas':
+      case 'nonce':
         cleanedTransaction[key] = tinyBig(hexToDecimal(transaction[key]));
-
         break;
     }
   });

src/classes/utils/hex-to-decimal.ts

@@ -8,7 +8,9 @@
  * ```javascript
  * hexToDecimal('0x34');
  * // 52
- *
+ * ```
+ * @example
+ * ```javascript
  * hexToDecimal('0x628608');
  * // 6456840
  * ```