bajo 2.21.1 → 2.23.0

package/class/err.js

@@ -8,7 +8,7 @@ Error.stackTraceLimit = 15
 /**
  * Bajo error class, a thin wrapper of node's Error object.
  *
- * Every Bajo {@link Plugin|plugin} has a built-in method called ```error``` which basically the shortcut to create a new Err instance.
+ * Every Bajo {@link Plugin|plugin} has a built-in method called `error` which basically the shortcut to create a new Err instance.
  * It helps you create this instance anywhere in your code quickly without the hassle of importing & instantiating:
  *
  * ```javascript
@@ -18,30 +18,29 @@ Error.stackTraceLimit = 15
  */
 class Err extends Tools {
   /**
-   * @param {Plugin} plugin Plugin instance.
-   * @param {string} msg Error message.
-   * @param  {...any} [args] Variables to interpolate with error message. Payload object can be pushed at the very last argument
+   * Constructor.
+   *
+   * @param {Plugin} plugin - Plugin instance
+   * @param {string} msg - Error message
+   * @param  {...any} [args] - Variables to interpolate with error message. Payload object can be pushed at the very last argument
    */
   constructor (plugin, msg, ...args) {
     super(plugin)
 
     /**
      * Error payload extracted from the last arguments.
-     *
      * @type {Object}
      */
     this.payload = args.length > 0 && isPlainObject(args[args.length - 1]) ? args[args.length - 1] : {}
 
     /**
      * Original message before translation.
-     *
      * @type {string}
      */
     this.orgMessage = msg
 
     /**
      * Translated message.
-     *
      * @type {string}
      */
     this.message = this.payload.noTrans ? msg : this.plugin.t(msg, ...args)
@@ -51,7 +50,7 @@ class Err extends Tools {
    * Write message to the console.
    *
    * @method
-   * @returns {Err} Error object, useful for chaining.
+   * @returns {Err} - Error object, useful for chaining
    */
   write = () => {
     let err
@@ -94,8 +93,11 @@ class Err extends Tools {
   /**
    * Pretty format error details.
    *
+   * Formatted error will be applied directly to the value parameter, and a detailsMessage
+   * will be returned for display purpose.
+   *
    * @method
-   * @param {Object} value Value to format.
+   * @param {Object} value - Value to format
    * @returns {Object}
    */
   formatErrorDetails = (value) => {

package/class/log.js

@@ -1,12 +1,49 @@
 import os from 'os'
-import logLevels from '../lib/log-levels.js'
 import chalk from 'chalk'
 import { stripVTControlCharacters } from 'node:util'
 
 /**
- * Log output in stringified JSON format. Returned when app run in ```prod``` environment.
+ * @typedef {Object} TLevels
+ * @memberof Log
+ * @type {Object}
+ * @property {Object} trace
+ * @property {number} [trace.number=10]
+ * @property {string} [trace.color=gray]
+ * @property {Object} debug
+ * @property {number} [debug.number=20]
+ * @property {string} [debug.color=greenBright]
+ * @property {Object} info
+ * @property {number} [info.number=30]
+ * @property {string} [info.color=blueBright]
+ * @property {Object} warn
+ * @property {number} [warn.number=40]
+ * @property {string} [warn.color=yellowBright]
+ * @property {Object} error
+ * @property {number} [error.number=50]
+ * @property {string} [error.color=redBright]
+ * @property {Object} fatal
+ * @property {number} [fatal.number=60]
+ * @property {string} [fatal.color=magentaBright]
+ * @property {Object} silent
+ * @property {number} [silent.number=99]
+ * @property {string} [silent.color=white]
+*/
+
+export const logLevels = {
+  trace: { number: 10, color: 'gray' },
+  debug: { number: 20, color: 'greenBright' },
+  info: { number: 30, color: 'blueBright' },
+  warn: { number: 40, color: 'yellowBright' },
+  error: { number: 50, color: 'redBright' },
+  fatal: { number: 60, color: 'magentaBright' },
+  silent: { number: 99, color: 'white' }
+}
+
+/**
+ * Log output in stringified JSON format. Returned when app run in `prod` environment.
  *
- * @typedef TLogJson
+ * @typedef TJsonOutput
+ * @memberof Log
  * @property {string} prefix Message prefix.
  * @property {string} message The message itself.
  * @property {string} level Log level.
@@ -20,32 +57,34 @@ import { stripVTControlCharacters } from 'node:util'
 /**
  * A thin & fast logger system.
  *
- * An instance is created by the {@link App|app} and available to use anywhere like this:
- *
- * ```javascript
- * ... anywhere inside your code
- * this.app.log.debug(...)
- * ```
+ * An instance is created by the {@link App|app} and available to use from anywhere inside your code.
  *
  * Shortcuts to log's methods are also available on every Bajo {@link Plugin|plugin}. Call on
- * these shortcuts will be prefixed with it's plugin name automatically:
+ * these shortcuts will be prefixed with it's plugin name automatically.
  *
- * ```javascript
- * ... anywhere inside your code
- * if (!isValid) this.log.error('Invalid value!')
+ * Example:
+ * ```js
+ * // ... anywhere inside your code
+ * this.app.log.debug(...)
+ * // or inside a plugin
+ * if (!isValid) this.log.error('Invalid value!') // will be prefixed with plugin namespace automatically
  * ```
  *
  * @class
  */
 class Log {
   /**
+   * Constructor.
    * @param {App} app - App instance
    */
   constructor (app) {
-    this.lastDelta = 0
+    /**
+     * Last delta time in millisecond since app started. Used for log's time taken feature.
+     * @type {number}
+     */
+    this._lastDelta = 0
     /**
      * The app instance.
-     *
      * @type {App}
      */
     this.app = app
@@ -57,18 +96,18 @@ class Log {
 
   /**
    * Display & format message according to one of these rules:
-   * 1. ```level``` ```prefix``` ```text``` ```var 1``` ```var 2``` ```...var n``` - Translate ```text``` and interpolate with ```vars``` for level ```level```
-   * 2. ```level``` ```prefix``` ```data``` ```text``` ```var 1``` ```var 2``` ```...var n``` - As above, and append stringified ```data```
-   * 3. ```level``` ```prefix``` ```error``` - Format as {@link Err} object. If current log level is _trace_, dump it on screen
+   * 1. `level` `prefix` `text` `var 1` `var 2` `...var n` - Translate `text` and interpolate with `vars` for level `level`
+   * 2. `level` `prefix` `data` `text` `var 1` `var 2` `...var n` - As above, and append stringified `data`
+   * 3. `level` `prefix` `error` - Format as {@link Err} object. If current log level is _trace_, dump it on screen
    *
-   * In ```prod``` environment, log will be delivered as JSON stringified object. See {@link TLogJson} for more info
+   * In `prod` environment, log will be delivered as JSON stringified object. See {@link Log.TJsonOutput} for more info
    *
    * @method
-   * @param {string} level Log level to use.
-   * @param {string} prefix Prefix to the message.
-   * @param {...any} params See format above.
+   * @param {string} level - Log level to use
+   * @param {string} prefix - Prefix to the message
+   * @param {...any} params - See format above
    * @see Err
-   * @see TLogJson
+   * @see Log.TJsonOutput
    */
   formatMsg = (level, prefix, ...params) => {
     const { dayjs } = this.app.lib
@@ -95,8 +134,8 @@ class Log {
     let diff = null
     if (timeTaken) {
       const delta = dt.diff(this.app.runAt, 'ms')
-      diff = delta - this.lastDelta
-      this.lastDelta = delta
+      diff = delta - this._lastDelta
+      this._lastDelta = delta
     }
     if (this.app.bajo.config.env === 'prod') {
       const json = { prefix, msg, level: logLevels[level].number, time: dt.valueOf(), pid: process.pid, hostname: os.hostname() }
@@ -121,17 +160,24 @@ class Log {
     if (this.app.bajo.config.log.save) this.save(text, prefix)
   }
 
+  /**
+   * Get error message from an Error object. If the message is empty, return the code or statusCode instead.
+   *
+   * @method
+   * @param {Error} error - Error object
+   * @returns {string} Error message
+   */
   getErrorMessage = error => {
     const { isEmpty } = this.app.lib._
     return isEmpty(error.message) ? (error.code ?? error.statusCode) : error.message
   }
 
   /**
-   * Calculate pattern used for log rotation.
+   * Calculate pattern used for log rotation. Used by {@link Log#save|save} method to determine the log file name.
    *
    * @method
-   * @param {boolean} isPrev If true, calculate previous rotation pattern.
-   * @returns {string} Calculated pattern.
+   * @param {boolean} isPrev - If `true`, calculate previous rotation pattern.
+   * @returns {string} Calculated pattern
    */
   getRotationPattern = (isPrev) => {
     const { dayjs } = this.app.lib
@@ -160,11 +206,11 @@ class Log {
   }
 
   /**
-   * Save log to file in {dataDir}/log.
+   * Save log to file in `{dataDir}/log`.
    *
    * @method
-   * @param {string} text Log message to save.
-   * @param {string} prefix Use prefix as basename. Defaults to 'bajo'.
+   * @param {string} text - Log message to save
+   * @param {string} [prefix='bajo'] - Use prefix as basename. Defaults to `bajo`
    */
   save = (text, prefix = 'bajo') => {
     const { fs } = this.app.lib
@@ -180,77 +226,77 @@ class Log {
   }
 
   /**
-   * Display & format message in ```trace``` level. See {@link Log#formatMsg|formatMsg} for details.
+   * Display & format message in `trace` level. See {@link Log#formatMsg|formatMsg} for details.
    *
    * @method
-   * @param {string} prefix Message prefix.
-   * @param {...any} params Parameters.
+   * @param {string} prefix - Message prefix
+   * @param {...any} params - Parameters
    */
   trace = (prefix, ...params) => {
     this.formatMsg('trace', prefix, ...params)
   }
 
   /**
-   * Display & format message in ```debug``` level. See {@link Log#formatMsg|formatMsg} for details.
+   * Display & format message in `debug` level. See {@link Log#formatMsg|formatMsg} for details.
    *
    * @method
-   * @param {string} prefix Message prefix.
-   * @param {...any} params Parameters.
+   * @param {string} prefix - Message prefix
+   * @param {...any} params - Parameters
    */
   debug = (prefix, ...params) => {
     this.formatMsg('debug', prefix, ...params)
   }
 
   /**
-   * Display & format message in ```info``` level. See {@link Log#formatMsg|formatMsg} for details.
+   * Display & format message in `info` level. See {@link Log#formatMsg|formatMsg} for details.
    *
    * @method
-   * @param {string} prefix Message prefix.
-   * @param {...any} params Parameters.
+   * @param {string} prefix - Message prefix
+   * @param {...any} params - Parameters
    */
   info = (prefix, ...params) => {
     this.formatMsg('info', prefix, ...params)
   }
 
   /**
-   * Display & format message in ```warn``` level. See {@link Log#formatMsg|formatMsg} for details.
+   * Display & format message in `warn` level. See {@link Log#formatMsg|formatMsg} for details.
    *
    * @method
-   * @param {string} prefix Message prefix.
-   * @param {...any} params Parameters.
+   * @param {string} prefix - Message prefix
+   * @param {...any} params - Parameters
    */
   warn = (prefix, ...params) => {
     this.formatMsg('warn', prefix, ...params)
   }
 
   /**
-   * Display & format message in ```error``` level. See {@link Log#formatMsg|formatMsg} for details.
+   * Display & format message in `error` level. See {@link Log#formatMsg|formatMsg} for details.
    *
    * @method
-   * @param {string} prefix Message prefix.
-   * @param {...any} params Parameters.
+   * @param {string} prefix - Message prefix
+   * @param {...any} params - Parameters
    */
   error = (prefix, ...params) => {
     this.formatMsg('error', prefix, ...params)
   }
 
   /**
-   * Display & format message in ```fatal``` level. See {@link Log#formatMsg|formatMsg} for details.
+   * Display & format message in `fatal` level. See {@link Log#formatMsg|formatMsg} for details.
    *
    * @method
-   * @param {string} prefix Message prefix.
-   * @param {...any} params Parameters.
+   * @param {string} prefix - Message prefix
+   * @param {...any} params - Parameters
    */
   fatal = (prefix, ...params) => {
     this.formatMsg('fatal', prefix, ...params)
   }
 
   /**
-   * Display & format message in ```silent``` level. See {@link Log#formatMsg|formatMsg} for details.
+   * Display & format message in `silent` level. See {@link Log#formatMsg|formatMsg} for details.
    *
    * @method
-   * @param {string} prefix Message prefix.
-   * @param {...any} params Parameters.
+   * @param {string} prefix - Message prefix
+   * @param {...any} params - Parameters
    */
   silent = (prefix, ...params) => {
     this.formatMsg('silent', prefix, ...params)
@@ -258,6 +304,10 @@ class Log {
 
   /**
    * Dispose internal references.
+   *
+   * @async
+   * @method
+   * @returns {Promise<void>}
    */
   dispose = async () => {
     this.app = null

package/class/plugin.js

@@ -15,23 +15,23 @@ const { get, isEmpty, cloneDeep, omit, isPlainObject, camelCase } = lodash
  */
 class Plugin {
   /**
-   * @param {string} pkgName Package name (the one you use in package.json).
-   * @param {Object} app App instance reference. Usefull to call app method inside a plugin.
+   * Constructor.
+   *
+   * @param {string} pkgName - Package name (the one in package.json)
+   * @param {Object} app - App instance reference. Usefull to call app method inside a plugin
    */
   constructor (pkgName, app) {
     /**
      * Package name, the one from package.json.
      *
-     * @memberof Plugin
-     * @constant {string}
+     * @type {string}
      */
     this.pkgName = pkgName
 
     /**
-     * Namespace (ns) or plugin's name. Simply the camel cased version of plugin's package name.
+     * Namespace (ns) or plugin's name. It is the camel cased version of plugin's package name.
      *
-     * @memberof Plugin
-     * @constant {string}
+     * @type {string}
      */
     this.ns = camelCase(pkgName)
 
@@ -40,20 +40,18 @@ class Plugin {
      * Bajo will provide this automatically (by using the kebab-cased version of plugin name).
      *
      * @readonly
-     * @memberof Plugin
      * @type {string}
      */
     this.alias = null
 
     /**
-     * Reference to the app instance.
-     *
-     * @type {Object}
+     * Reference to the app instance
+     * @type {App}
      */
     this.app = app
 
     /**
-     * Config object.
+     * Configuration object.
      *
      * @type {Object}
      * @see {@tutorial config}
@@ -80,8 +78,9 @@ class Plugin {
    * Get package info.
    *
    * @method
-   * @param {string} [dir] Package directory. Defaults to the current plugin's package dir.
-   * @param {Array} [keys=['name', 'version', 'description', 'author', 'license', 'homepage', 'bajo']] Field keys to be use. Set empty to use all keys.
+   * @param {string} [dir] - Package directory. Defaults to the current plugin's package dir
+   * @param {Array} [keys=['name', 'version', 'description', 'author', 'license', 'homepage', 'bajo']] - Field keys to be use. Set empty to use all keys
+   * @returns {Object} Package info object
    */
   getPkgInfo = (dir, keys = ['name', 'version', 'description', 'author', 'license', 'homepage', 'bajo']) => {
     const { pick, isEmpty } = this.app.lib._
@@ -95,12 +94,12 @@ class Plugin {
    * Get plugin's config value.
    *
    * @method
-   * @param {string} [path] dot separated config path (think of lodash's 'get'). If not provided, the full config will be given.
-   * @param {Object} [options={}] Options.
-   * @param {any} [options.defValue={}] Default value to use if returned object is undefined.
-   * @param {string[]} [options.omit=[]] Omit these keys from returned object.
-   * @param {boolean} [options.noClone=false] Set true to NOT clone returned object.
-   * @returns {Object} Returned object. If no path provided, the whole config object is returned.
+   * @param {string} [path] - dot separated config path (think of lodash's 'get'). If not provided, the full config will be given
+   * @param {Object} [options={}] - Options object
+   * @param {any} [options.defValue={}] - Default value to use if returned object is undefined
+   * @param {string[]} [options.omit=[]] - Omit these keys from returned object
+   * @param {boolean} [options.noClone=false] - Set true to NOT clone returned object
+   * @returns {Object} Returned object. If no path provided, the whole config object is returned
    */
   getConfig = (path, options = {}) => {
     let obj = isEmpty(path) ? this.config : get(this.config, path, options.defValue ?? {})
@@ -114,9 +113,9 @@ class Plugin {
    * Create an instance of {@link Err} object.
    *
    * @method
-   * @param {string} msg Error message.
-   * @param  {...any} [args] Argument variables you might want to add to the error object.
-   * @returns {Object} Err instance.
+   * @param {string} msg - Error message
+   * @param  {...any} [args] - Argument variables you might want to add to the error object
+   * @returns {Err} Err instance
    */
   error = (msg, ...args) => {
     if (!this.print) return new Error(msg, ...args)
@@ -126,11 +125,12 @@ class Plugin {
 
   /**
    * Create an instance of Err object, display it on screen and then force
-   * terminate the app process.
+   * terminate the app.
    *
    * @method
-   * @param {string} msg Error message.
-   * @param  {...any} [args] Argument variables you might want to add to the error object.
+   * @param {string} msg - Error message
+   * @param  {...any} [args] - Argument variables you might want to add to the error object
+   * @returns {void}
    */
   fatal = (msg, ...args) => {
     if (!this.print) return new Error(msg, ...args)
@@ -139,12 +139,13 @@ class Plugin {
   }
 
   /**
-   * Translate text and interpolate with given ```args```.
+   * Translate text and interpolate with given `args`.
    *
    * Shortcut to {@link App#t} with ns parameter set to this plugin namespace.
    *
-   * @param {string} text Text to translate.
-   * @param  {...any} params Variables to interpolate to ```text```.
+   * @method
+   * @param {string} text - Text to translate
+   * @param  {...any} params - Variables to interpolate to `text`
    * @returns {string}
    */
   t = (text, ...params) => {
@@ -156,8 +157,9 @@ class Plugin {
    *
    * Shortcut to {@link App#te} with ns parameter set to this plugin namespace.
    *
-   * @param {string} text Text to translate.
-   * @param  {...any} params Variables to interpolate to ```text```.
+   * @method
+   * @param {string} text - Text to translate
+   * @param  {...any} params - Variables to interpolate to `text`
    * @returns {string}
    */
   te = (text, ...params) => {
@@ -165,9 +167,11 @@ class Plugin {
   }
 
   /**
-   * Force bind methods to self (```this```).
+   * Force bind methods to self (`this`).
    *
-   * @param {string[]} names Method's names.
+   * @method
+   * @param {string[]} names - Method's names
+   * @returns {void}
    */
   selfBind (names) {
     if (!Array.isArray(names)) names = [names]
@@ -177,9 +181,11 @@ class Plugin {
   }
 
   /**
-   * Alias to ```this.app.dump()```.
+   * Alias to `this.app.dump()`.
    *
-   * @param {...any} args
+   * @method
+   * @param {...any} args - Arguments
+   * @returns {void}
    */
   dump = (...args) => {
     this.app.dump(...args)
@@ -187,6 +193,10 @@ class Plugin {
 
   /**
    * Dispose internal references.
+   *
+   * @async
+   * @method
+   * @returns {Promise<void>}
    */
   dispose = async () => {
     this.app = null