Update lint configuration

This update includes the addition of JSDoc lint rules. Some of the
JSDoc lint rules needed to be fixed manually, the rest were automatic.

package.json

@@ -27,32 +27,33 @@
     "dist/"
   ],
   "scripts": {
-    "setup": "yarn install && yarn allow-scripts",
     "build": "tsc",
-    "test": "testem ci -P 2",
     "buildTest": "yarn build && browserify test/index.js -o test/bundle.js",
-    "lint:eslint": "eslint . --cache --ext js,ts",
-    "lint:misc": "prettier '**/*.json' '**/*.md' '!CHANGELOG.md' '**/*.yml' --ignore-path .gitignore",
     "lint": "yarn lint:eslint && yarn lint:misc --check",
-    "lint:fix": "yarn lint:eslint --fix && yarn lint:misc --write"
+    "lint:eslint": "eslint . --cache --ext js,ts",
+    "lint:fix": "yarn lint:eslint --fix && yarn lint:misc --write",
+    "lint:misc": "prettier '**/*.json' '**/*.md' '!CHANGELOG.md' '**/*.yml' '!.yarnrc.yml' --ignore-path .gitignore --no-error-on-unmatched-pattern",
+    "setup": "yarn install && yarn allow-scripts",
+    "test": "testem ci -P 2"
   },
   "devDependencies": {
     "@lavamoat/allow-scripts": "^1.0.6",
     "@metamask/auto-changelog": "^2.4.0",
-    "@metamask/eslint-config": "^7.0.1",
-    "@metamask/eslint-config-nodejs": "^7.0.1",
-    "@metamask/eslint-config-typescript": "^7.0.1",
+    "@metamask/eslint-config": "^10.0.0",
+    "@metamask/eslint-config-nodejs": "^10.0.0",
+    "@metamask/eslint-config-typescript": "^10.0.0",
     "@types/node": "^14.14.5",
-    "@typescript-eslint/eslint-plugin": "^4.28.1",
-    "@typescript-eslint/parser": "^4.28.1",
+    "@typescript-eslint/eslint-plugin": "^5.41.0",
+    "@typescript-eslint/parser": "^5.41.0",
     "browserify": "^17.0.0",
-    "eslint": "^7.29.0",
-    "eslint-config-prettier": "^8.3.0",
-    "eslint-plugin-import": "^2.23.4",
+    "eslint": "^8.26.0",
+    "eslint-config-prettier": "^8.5.0",
+    "eslint-plugin-import": "^2.26.0",
+    "eslint-plugin-jsdoc": "^39.3.25",
     "eslint-plugin-node": "^11.1.0",
-    "eslint-plugin-prettier": "^3.4.0",
-    "prettier": "^2.3.2",
-    "prettier-plugin-packagejson": "^2.2.11",
+    "eslint-plugin-prettier": "^4.2.1",
+    "prettier": "^2.7.1",
+    "prettier-plugin-packagejson": "^2.3.0",
     "testem": "^3.4.2",
     "typescript": "^4.3.4"
   },

src/index.ts

@@ -1,16 +1,16 @@
-interface EncryptionResult {
+type EncryptionResult = {
   data: string;
   iv: string;
   salt?: string;
-}
+};
 
 /**
  * Encrypts a data object that can be any serializable value using
  * a provided password.
  *
- * @param {string} password - password to use for encryption
- * @param {R} dataObj - data to encrypt
- * @returns {Promise<string>} cypher text
+ * @param password - A password to use for encryption.
+ * @param dataObj - The data to encrypt.
+ * @returns The encrypted data.
  */
 async function encrypt<R>(password: string, dataObj: R): Promise<string> {
   const salt = generateSalt();
@@ -25,9 +25,10 @@ async function encrypt<R>(password: string, dataObj: R): Promise<string> {
  * Encrypts the provided serializable javascript object using the
  * provided CryptoKey and returns an object containing the cypher text and
  * the initialization vector used.
- * @param {CryptoKey} key - CryptoKey to encrypt with
- * @param {R} dataObj - Serializable javascript object to encrypt
- * @returns {EncryptionResult}
+ *
+ * @param key - The CryptoKey to encrypt with.
+ * @param dataObj - A serializable JavaScript object to encrypt.
+ * @returns The encrypted data.
  */
 async function encryptWithKey<R>(
   key: CryptoKey,
@@ -57,9 +58,11 @@ async function encryptWithKey<R>(
 
 /**
  * Given a password and a cypher text, decrypts the text and returns
- * the resulting value
- * @param {string} password - password to decrypt with
- * @param {string} text - cypher text to decrypt
+ * the resulting value.
+ *
+ * @param password - The password to decrypt with.
+ * @param text - The cypher text to decrypt.
+ * @returns The decrypted data.
  */
 async function decrypt<R>(password: string, text: string): Promise<R> {
   const payload = JSON.parse(text);
@@ -71,8 +74,10 @@ async function decrypt<R>(password: string, text: string): Promise<R> {
 /**
  * Given a CryptoKey and an EncryptionResult object containing the initialization
  * vector (iv) and data to decrypt, return the resulting decrypted value.
- * @param {CryptoKey} key - CryptoKey to decrypt with
- * @param {EncryptionResult} payload - payload returned from an encryption method
+ *
+ * @param key - The CryptoKey to decrypt with.
+ * @param payload - The payload to decrypt, returned from an encryption method.
+ * @returns The decrypted data.
  */
 async function decryptWithKey<R>(
   key: CryptoKey,
@@ -100,9 +105,11 @@ async function decryptWithKey<R>(
 }
 
 /**
- * Generate a CryptoKey from a password and random salt
- * @param {string} password - The password to use to generate key
- * @param {string} salt - The salt string to use in key derivation
+ * Generate a CryptoKey from a password and random salt.
+ *
+ * @param password - The password to use to generate key.
+ * @param salt - The salt string to use in key derivation.
+ * @returns A CryptoKey for encryption and decryption.
  */
 async function keyFromPassword(
   password: string,
@@ -137,8 +144,9 @@ async function keyFromPassword(
 
 /**
  * Converts a hex string into a buffer.
- * @param {string} str - hex encoded string
- * @returns {Uint8Array}
+ *
+ * @param str - Hex encoded string.
+ * @returns The string ecoded as a byte array.
  */
 function serializeBufferFromStorage(str: string): Uint8Array {
   const stripStr = str.slice(0, 2) === '0x' ? str.slice(2) : str;
@@ -151,9 +159,10 @@ function serializeBufferFromStorage(str: string): Uint8Array {
 }
 
 /**
- * Converts a buffer into a hex string ready for storage
- * @param {Uint8Array} buffer - Buffer to serialize
- * @returns {string} hex encoded string
+ * Converts a buffer into a hex string ready for storage.
+ *
+ * @param buffer - Buffer to serialize.
+ * @returns A hex encoded string.
  */
 function serializeBufferForStorage(buffer: Uint8Array): string {
   let result = '0x';
@@ -167,8 +176,9 @@ function serializeBufferForStorage(buffer: Uint8Array): string {
 /**
  * Converts a number into hex value, and ensures proper leading 0
  * for single characters strings.
- * @param {number} num - number to convert to string
- * @returns {string} hex string
+ *
+ * @param num - The number to convert to string.
+ * @returns An unprefixed hex string.
  */
 function unprefixedHex(num: number): string {
   let hex = num.toString(16);
@@ -179,9 +189,10 @@ function unprefixedHex(num: number): string {
 }
 
 /**
- * Generates a random string for use as a salt in CryptoKey generation
- * @param {number} byteCount - Number of bytes to generate
- * @returns {string} randomly generated string
+ * Generates a random string for use as a salt in CryptoKey generation.
+ *
+ * @param byteCount - The number of bytes to generate.
+ * @returns A randomly generated string.
  */
 function generateSalt(byteCount = 32): string {
   const view = new Uint8Array(byteCount);