X-Git-Url: http://git.squeep.com/?p=squeep-mystery-box;a=blobdiff_plain;f=lib%2Fmystery-box.js;h=a3e3192047a30d80a89a597e0158e46eb23b3f9e;hp=55d1c3827746ccbc35b2e2e64ce30e9df692888f;hb=HEAD;hpb=d65b357b4fcf5b169a785f6d698ecd81086473b7

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<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 {