'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');
...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,
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);
/**
* 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) {
/**
* Parse the bits out of the flags.
+ * @param {number} flags flags
+ * @returns {object} decoded flags
*/
static _decodeFlags(flags) {
return {
/**
* 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) {
/**
* 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.
* 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++) {
* 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);
/**
* 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;
/**
* Stats tracked when packing/unpacking boxes.
- * @returns {Object}
+ * @param {string} method method name generating stats
+ * @returns {object} stats and timings
*/
static _newStats(method) {
return {
/**
* 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');
break;
}
stats.compressedBytes = Buffer.byteLength(compressedContents);
- // const compressionRatio = stats.compressedBytes / stats.serializedBytes;
timingsMs.postCompress = timingsMs.preCrypt = performance.now();
let payload;
/**
* 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');
/**
* 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) => {
/**
* 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 {
"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",
"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",
projects / squeep-mystery-box / commitdiff