add jsdoc linting, address issues
authorJustin Wind <justin.wind+git@gmail.com>
Tue, 16 Apr 2024 23:24:42 +0000 (16:24 -0700)
committerJustin Wind <justin.wind+git@gmail.com>
Tue, 16 Apr 2024 23:24:42 +0000 (16:24 -0700)
eslint.config.js
lib/mystery-box.js
package-lock.json
package.json

index ebefcac363dd2f0d6db0153dc7dfe9521e648080..fdfd9a7f8fdc32488d8696f754a2fa5d84f76c80 100644 (file)
@@ -1,6 +1,7 @@
 'use strict';
 const globals = require('globals');
 const js = require('@eslint/js');
+const jsdoc = require('eslint-plugin-jsdoc');
 const node = require('eslint-plugin-n');
 const security = require('eslint-plugin-security');
 const sonarjs = require('eslint-plugin-sonarjs');
@@ -13,12 +14,14 @@ module.exports = [
   ...compat.config(node.configs.recommended),
   security.configs.recommended,
   ...compat.config(sonarjs.configs.recommended),
+  jsdoc.configs['flat/recommended'],
   {
     files: [ '**/*.js' ],
     plugins: {
       node,
       security,
       sonarjs,
+      jsdoc,
     },
     languageOptions: {
       ecmaVersion: 2023,
index 55d1c3827746ccbc35b2e2e64ce30e9df692888f..a3e3192047a30d80a89a597e0158e46eb23b3f9e 100644 (file)
@@ -65,9 +65,10 @@ const payloadFlagsShift = 7;
 
 class MysteryBox extends EventEmitter {
   /**
-   * @param {Object} options
-   * @param {String|String[]} options.encryptionSecret - if an array, will always encrypt with first secret, will attempt to decrypt with all; useful for rolling secrets
-   * @param {Number=} options.defaultFlags
+   * @param {object} options options
+   * @param {string|string[]} options.encryptionSecret if an array, will always encrypt with first secret, will attempt to decrypt with all; useful for rolling secrets
+   * @param {number=} options.defaultFlags default flags to use when packing boxes
+   * @param {any[]} args passed on to EventEmitter constructor
    */
   constructor(options = {}, ...args) {
     super(...args);
@@ -106,7 +107,8 @@ class MysteryBox extends EventEmitter {
 
   /**
    * Return an array containing x if x is something and not an array
-   * @param {*} x
+   * @param {*} x thing to ensure is an array
+   * @returns {any[]} thing array or thing in an array
    */
   static _ensureArray(x) {
     if (x === undefined) {
@@ -121,6 +123,8 @@ class MysteryBox extends EventEmitter {
 
   /**
    * Parse the bits out of the flags.
+   * @param {number} flags flags
+   * @returns {object} decoded flags
    */
   static _decodeFlags(flags) {
     return {
@@ -132,6 +136,11 @@ class MysteryBox extends EventEmitter {
 
   /**
    * Generate key data.
+   * @param {string} deriver key deriver enum
+   * @param {Buffer} secret secret
+   * @param {Buffer} salt salt
+   * @param {number} keyBytes bytes in key
+   * @returns {Promise<Buffer>} key
    */
   static async _keyFromSecret(deriver, secret, salt, keyBytes) {
     switch (deriver) {
@@ -164,8 +173,8 @@ class MysteryBox extends EventEmitter {
 
   /**
    * Return bits and bit mask for given number of encoded bytes.
-   * @param {Number} numBytes
-   * @returns {Object}
+   * @param {number} numBytes number of bytes
+   * @returns {object} bits value and mask
    */
   static _versionHeaderBits(numBytes) {
     // Round up to 8 bits in result, just to be proper.
@@ -184,8 +193,8 @@ class MysteryBox extends EventEmitter {
    * Number of packed bytes is indicated by location of first leading 0 bit.
    * Support for numbers larger than 127 is of dubious practicality, but here
    * it is anyhow.
-   * @param {Number} firstByte
-   * @returns {Object}
+   * @param {number} firstByte first byte contains encoded byte length
+   * @returns {object} number of bytes and masked first byte
    */
   static _versionHeaderDecode(firstByte) {
     for (let numBytes = 1; numBytes <= 8; numBytes++) {
@@ -212,8 +221,8 @@ class MysteryBox extends EventEmitter {
    * many total bytes comprise the version, in big-endian encoding.
    * Returns decoded version and number of bytes used to decode.
    * Only supports up to 6-byte numbers, and of those, only up to 4398046511103.
-   * @param {Buffer} buf N.B. will be mogrified
-   * @returns {Object}
+   * @param {Buffer} buf N.B. will be mogrified
+   * @returns {object} decoded version and version byte length
    */
   static _versionDecode(buf) {
     const headerByte = buf.readUInt8(0);
@@ -240,8 +249,8 @@ class MysteryBox extends EventEmitter {
 
   /**
    * Encode a version identifier into a buffer of a variable number of bytes.
-   * @param {Number} version
-   * @returns {Object}
+   * @param {number} version version number to encode
+   * @returns {object} encoded version buffer and number of bytes
    */
   static _versionEncode(version) {
     let versionBytes = 0;
@@ -276,7 +285,8 @@ class MysteryBox extends EventEmitter {
 
   /**
    * Stats tracked when packing/unpacking boxes.
-   * @returns {Object}
+   * @param {string} method method name generating stats
+   * @returns {object} stats and timings
    */
   static _newStats(method) {
     return {
@@ -302,10 +312,10 @@ class MysteryBox extends EventEmitter {
 
   /**
    * Put contents into a mysterious box.
-   * @param {Object|Buffer} contents
-   * @param {Number=} version
-   * @param {Number=} flags
-   * @returns {Promise<String>}
+   * @param {object|Buffer} contents object or buffer
+   * @param {number=} version version
+   * @param {number=} flags flags
+   * @returns {Promise<string>} encoded contents
    */
   async pack(contents, version = this.bestVersion, flags = this.defaultFlags) {
     const { stats, timingsMs } = MysteryBox._newStats('pack');
@@ -357,7 +367,6 @@ class MysteryBox extends EventEmitter {
         break;
     }
     stats.compressedBytes = Buffer.byteLength(compressedContents);
-    // const compressionRatio = stats.compressedBytes / stats.serializedBytes;
     timingsMs.postCompress = timingsMs.preCrypt = performance.now();
 
     let payload;
@@ -398,8 +407,8 @@ class MysteryBox extends EventEmitter {
 
   /**
    * Take contents out of a mysterious box.
-   * @param {String} box - Base64URL encoded payload
-   * @returns {Promise<Object>}
+   * @param {string} box - Base64URL encoded payload
+   * @returns {Promise<object|Buffer>} decoded contents
    */
   async unpack(box) {
     const { stats, timingsMs } = MysteryBox._newStats('unpack');
@@ -504,8 +513,8 @@ class MysteryBox extends EventEmitter {
 
   /**
    * Pretty-print flag values
-   * @param {Number} flags
-   * @returns {String}
+   * @param {number} flags flags
+   * @returns {string} pretty flags
    */
   _prettyFlags(flags) {
     const flagNames = Object.entries(this.Flags).reduce((acc, cur) => {
@@ -521,8 +530,14 @@ class MysteryBox extends EventEmitter {
 
   /**
    * Everyone loves numbers.
-   * @param {Object} timingsMs
-   * @returns {Object}
+   * @param {object} timingsMs raw timings
+   * @param {number} timingsMs.start start
+   * @param {number} timingsMs.preCompress checkpoint
+   * @param {number} timingsMs.postCompress checkpoint
+   * @param {number} timingsMs.preCrypt checkpoint
+   * @param {number} timingsMs.postCrypt checkpoint
+   * @param {number} timingsMs.end checkpoint
+   * @returns {object} computed timings
    */
   static _timingsLog({ start, preCompress, postCompress, preCrypt, postCrypt, end }) {
     return {
index 4d0fddf2639d5570c8cf6d7eba8f4acd5dc4488b..dc676f8f9d647589cdddae292730a13d6fea7909 100644 (file)
@@ -10,6 +10,7 @@
       "license": "ISC",
       "devDependencies": {
         "eslint": "^8.57.0",
+        "eslint-plugin-jsdoc": "^48.2.3",
         "eslint-plugin-n": "^17.2.1",
         "eslint-plugin-security": "^3.0.0",
         "eslint-plugin-sonarjs": "^0.25.1",
         "node": ">=6.9.0"
       }
     },
+    "node_modules/@es-joy/jsdoccomment": {
+      "version": "0.42.0",
+      "resolved": "https://registry.npmjs.org/@es-joy/jsdoccomment/-/jsdoccomment-0.42.0.tgz",
+      "integrity": "sha512-R1w57YlVA6+YE01wch3GPYn6bCsrOV3YW/5oGGE2tmX6JcL9Nr+b5IikrjMPF+v9CV3ay+obImEdsDhovhJrzw==",
+      "dev": true,
+      "dependencies": {
+        "comment-parser": "1.4.1",
+        "esquery": "^1.5.0",
+        "jsdoc-type-pratt-parser": "~4.0.0"
+      },
+      "engines": {
+        "node": ">=16"
+      }
+    },
     "node_modules/@eslint-community/eslint-utils": {
       "version": "4.4.0",
       "resolved": "https://registry.npmjs.org/@eslint-community/eslint-utils/-/eslint-utils-4.4.0.tgz",
       "integrity": "sha512-Xg+9RwCg/0p32teKdGMPTPnVXKD0w3DfHnFTficozsAgsvq2XenPJq/MYpzzQ/v8zrOyJn6Ds39VA4JIDwFfqw==",
       "dev": true
     },
+    "node_modules/are-docs-informative": {
+      "version": "0.0.2",
+      "resolved": "https://registry.npmjs.org/are-docs-informative/-/are-docs-informative-0.0.2.tgz",
+      "integrity": "sha512-ixiS0nLNNG5jNQzgZJNoUpBKdo9yTYZMGJ+QgT2jmjR7G7+QHRCc4v6LQ3NgE7EBJq+o0ams3waJwkrlBom8Ig==",
+      "dev": true,
+      "engines": {
+        "node": ">=14"
+      }
+    },
     "node_modules/argparse": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
       "integrity": "sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ==",
       "dev": true
     },
+    "node_modules/builtin-modules": {
+      "version": "3.3.0",
+      "resolved": "https://registry.npmjs.org/builtin-modules/-/builtin-modules-3.3.0.tgz",
+      "integrity": "sha512-zhaCDicdLuWN5UbN5IMnFqNMhNfo919sH85y2/ea+5Yg9TsTkeZxpL+JLbp6cgYFS4sRLp3YV4S6yDuqVWHYOw==",
+      "dev": true,
+      "engines": {
+        "node": ">=6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/caching-transform": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/caching-transform/-/caching-transform-4.0.0.tgz",
       "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==",
       "dev": true
     },
+    "node_modules/comment-parser": {
+      "version": "1.4.1",
+      "resolved": "https://registry.npmjs.org/comment-parser/-/comment-parser-1.4.1.tgz",
+      "integrity": "sha512-buhp5kePrmda3vhc5B9t7pUQXAb2Tnd0qgpkIhPhkHXxJpiPJ11H0ZEU0oBpJ2QztSbzG/ZxMj/CHsYJqRHmyg==",
+      "dev": true,
+      "engines": {
+        "node": ">= 12.0.0"
+      }
+    },
     "node_modules/commondir": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/commondir/-/commondir-1.0.1.tgz",
         "eslint": ">=8"
       }
     },
+    "node_modules/eslint-plugin-jsdoc": {
+      "version": "48.2.3",
+      "resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-48.2.3.tgz",
+      "integrity": "sha512-r9DMAmFs66VNvNqRLLjHejdnJtILrt3xGi+Qx0op0oRfFGVpOR1Hb3BC++MacseHx93d8SKYPhyrC9BS7Os2QA==",
+      "dev": true,
+      "dependencies": {
+        "@es-joy/jsdoccomment": "~0.42.0",
+        "are-docs-informative": "^0.0.2",
+        "comment-parser": "1.4.1",
+        "debug": "^4.3.4",
+        "escape-string-regexp": "^4.0.0",
+        "esquery": "^1.5.0",
+        "is-builtin-module": "^3.2.1",
+        "semver": "^7.6.0",
+        "spdx-expression-parse": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "eslint": "^7.0.0 || ^8.0.0 || ^9.0.0"
+      }
+    },
     "node_modules/eslint-plugin-n": {
       "version": "17.2.1",
       "resolved": "https://registry.npmjs.org/eslint-plugin-n/-/eslint-plugin-n-17.2.1.tgz",
         "node": ">=8"
       }
     },
+    "node_modules/is-builtin-module": {
+      "version": "3.2.1",
+      "resolved": "https://registry.npmjs.org/is-builtin-module/-/is-builtin-module-3.2.1.tgz",
+      "integrity": "sha512-BSLE3HnV2syZ0FK0iMA/yUGplUeMmNz4AW5fnTunbCIqZi4vG3WjJT9FHMy5D69xmAYBHXQhJdALdpwVxV501A==",
+      "dev": true,
+      "dependencies": {
+        "builtin-modules": "^3.3.0"
+      },
+      "engines": {
+        "node": ">=6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/is-extglob": {
       "version": "2.1.1",
       "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz",
         "js-yaml": "bin/js-yaml.js"
       }
     },
+    "node_modules/jsdoc-type-pratt-parser": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/jsdoc-type-pratt-parser/-/jsdoc-type-pratt-parser-4.0.0.tgz",
+      "integrity": "sha512-YtOli5Cmzy3q4dP26GraSOeAhqecewG04hoO8DY56CH4KJ9Fvv5qKWUCCo3HZob7esJQHCv6/+bnTy72xZZaVQ==",
+      "dev": true,
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
     "node_modules/jsesc": {
       "version": "2.5.2",
       "resolved": "https://registry.npmjs.org/jsesc/-/jsesc-2.5.2.tgz",
         "node": ">=8"
       }
     },
+    "node_modules/spdx-exceptions": {
+      "version": "2.5.0",
+      "resolved": "https://registry.npmjs.org/spdx-exceptions/-/spdx-exceptions-2.5.0.tgz",
+      "integrity": "sha512-PiU42r+xO4UbUS1buo3LPJkjlO7430Xn5SVAhdpzzsPHsjbYVflnnFdATgabnLude+Cqu25p6N+g2lw/PFsa4w==",
+      "dev": true
+    },
+    "node_modules/spdx-expression-parse": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/spdx-expression-parse/-/spdx-expression-parse-4.0.0.tgz",
+      "integrity": "sha512-Clya5JIij/7C6bRR22+tnGXbc4VKlibKSVj2iHvVeX5iMW7s1SIQlqu699JkODJJIhh/pUu8L0/VLh8xflD+LQ==",
+      "dev": true,
+      "dependencies": {
+        "spdx-exceptions": "^2.1.0",
+        "spdx-license-ids": "^3.0.0"
+      }
+    },
+    "node_modules/spdx-license-ids": {
+      "version": "3.0.17",
+      "resolved": "https://registry.npmjs.org/spdx-license-ids/-/spdx-license-ids-3.0.17.tgz",
+      "integrity": "sha512-sh8PWc/ftMqAAdFiBu6Fy6JUOYjqDJBJvIhpfDMyHrr0Rbp5liZqd4TjtQ/RgfLjKFZb+LMx5hpml5qOWy0qvg==",
+      "dev": true
+    },
     "node_modules/sprintf-js": {
       "version": "1.0.3",
       "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz",
index f951c11359bbabdd9e8e5028683be6da1a911ab3..87453f991a47c49899c71ad2ddcf62673fc8b275 100644 (file)
@@ -27,6 +27,7 @@
   "license": "ISC",
   "devDependencies": {
     "eslint": "^8.57.0",
+    "eslint-plugin-jsdoc": "^48.2.3",
     "eslint-plugin-n": "^17.2.1",
     "eslint-plugin-security": "^3.0.0",
     "eslint-plugin-sonarjs": "^0.25.1",