From 7af0e270b96989ac2310f9333ac80adf6d7d0006 Mon Sep 17 00:00:00 2001 From: Justin Wind Date: Tue, 16 Apr 2024 16:24:42 -0700 Subject: [PATCH] add jsdoc linting, address issues --- eslint.config.js | 3 ++ lib/mystery-box.js | 63 +++++++++++++++---------- package-lock.json | 114 +++++++++++++++++++++++++++++++++++++++++++++ package.json | 1 + 4 files changed, 157 insertions(+), 24 deletions(-) diff --git a/eslint.config.js b/eslint.config.js index ebefcac..fdfd9a7 100644 --- a/eslint.config.js +++ b/eslint.config.js @@ -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, diff --git a/lib/mystery-box.js b/lib/mystery-box.js index 55d1c38..a3e3192 100644 --- a/lib/mystery-box.js +++ b/lib/mystery-box.js @@ -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} 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} + * @param {object|Buffer} contents object or buffer + * @param {number=} version version + * @param {number=} flags flags + * @returns {Promise} 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} + * @param {string} box - Base64URL encoded payload + * @returns {Promise} 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 { diff --git a/package-lock.json b/package-lock.json index 4d0fddf..dc676f8 100644 --- a/package-lock.json +++ b/package-lock.json @@ -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", @@ -437,6 +438,20 @@ "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", @@ -881,6 +896,15 @@ "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", @@ -971,6 +995,18 @@ "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", @@ -1117,6 +1153,15 @@ "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", @@ -1380,6 +1425,29 @@ "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", @@ -1969,6 +2037,21 @@ "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", @@ -2213,6 +2296,15 @@ "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", @@ -3388,6 +3480,28 @@ "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", diff --git a/package.json b/package.json index f951c11..87453f9 100644 --- a/package.json +++ b/package.json @@ -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", -- 2.43.2