From a3f943b3871195fc3b812c6ba933adcbaecd162c Mon Sep 17 00:00:00 2001
From: Justin Wind <justin.wind+git@gmail.com>
Date: Sat, 23 Nov 2024 14:20:44 -0800
Subject: [PATCH] minor jsdoc updates for more explicit types

---
 lib/mystery-box.js | 45 +++++++++++++++++++++++++++++++++++----------
 1 file changed, 35 insertions(+), 10 deletions(-)

diff --git a/lib/mystery-box.js b/lib/mystery-box.js
index a3e3192..c7ddf18 100644
--- a/lib/mystery-box.js
+++ b/lib/mystery-box.js
@@ -63,6 +63,12 @@ const compressionFlagsShift = 0;
 const payloadFlagsMask = (availableFlags.BufferPayload);
 const payloadFlagsShift = 7;
 
+/**
+ * @typedef {string|Buffer} Secret
+ * @typedef {object} MysteryBoxOptions
+ * @property {Secret|Secret[]} encryptionSecret if an array, will always encrypt with first secret, will attempt to decrypt with all in ordere
+ */
+
 class MysteryBox extends EventEmitter {
   /**
    * @param {object} options options
@@ -98,7 +104,7 @@ class MysteryBox extends EventEmitter {
     }
 
     this.Flags = availableFlags;
-    this.defaultFlags = 'defaultFlags' in options ? options.defaultFlags : availableFlags.Flate;
+    this.defaultFlags = options.defaultFlags ?? availableFlags.Flate;
     if (this.defaultFlags < 0 || this.defaultFlags > 255) {
       throw new MysteryBoxError('Invalid default flag value');
     }
@@ -283,10 +289,29 @@ class MysteryBox extends EventEmitter {
   }
 
 
+  /**
+   * @typedef {object} Stats tracking details of operation
+   * @property {string} method name of operation
+   * @property {number} version box version
+   * @property {string} flags decoded flags
+   * @property {number} flagsRaw numeric flags
+   * @property {number} serializedBytes size of payload
+   * @property {number} compressedBytes size of compressed payload
+   * @typedef {object} Timings tracking for pack and unpack operations
+   * @property {number} start timestamp in ms, start of all operations
+   * @property {number} preCompress timestamp in ms, start of compression checkpoint
+   * @property {number} postCompress timestamp in ms, end of compression checkpoint
+   * @property {number} preCrypt timestamp in ms, start of encryption checkpoint
+   * @property {number} postCrypt timestamp in ms, end of encryption checkpoint
+   * @property {number} end timestamp in ms, end of all operations
+   * @typedef {object} NewStats
+   * @property {Stats} stats stats
+   * @property {Timings} timingsMs timings
+   */
   /**
    * Stats tracked when packing/unpacking boxes.
    * @param {string} method method name generating stats
-   * @returns {object} stats and timings
+   * @returns {NewStats} stats and timings
    */
   static _newStats(method) {
     return {
@@ -528,16 +553,16 @@ class MysteryBox extends EventEmitter {
   }
 
 
+  /**
+   * @typedef {object} TimingsPhases
+   * @property {number} totalMs total time taken
+   * @property {number} compressMs time taken by compression phase
+   * @property {number} cryptMs time taken by encryption phase
+   */
   /**
    * Everyone loves numbers.
-   * @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
+   * @param {Timings} timingsMs raw timings
+   * @returns {TimingsPhases} computed timings
    */
   static _timingsLog({ start, preCompress, postCompress, preCrypt, postCrypt, end }) {
     return {
-- 
2.49.0