bajo 2.23.0 → 2.24.0

package/class/base.js

@@ -1,8 +1,72 @@
 import Plugin from './plugin.js'
 
 /**
- * This is the class your own plugin suppose to extend. Don't use {@link Plugin} directly
- * unless you know what you're doing.
+ * To be recognized as a valid Bajo plugin, your package must be an `ES6 module` and have a `package.json` file
+ * with the additional `bajo` property and at least the `type` property set to `plugin`.
+ *
+ * Other than `type`, you might need to specify these additional properties:
+ * - `type`: `string`, must be set to `plugin`
+ * - `alias`: `string`, the alias name of your plugin. Must be unique among all plugins. If it is missing, it will be generated by Bajo as camel-cased version of your plugin namespace.
+ * - `dependencies`: `array`, if your plugin requires one or more other plugins to work, you need to put their **package names** in this array
+ *
+ * Example:
+ * ```json
+ * {
+ *   "name": "my-plugin",
+ *   "version": "1.0.0",
+ *   "description": "My Bajo plugin",
+ *   "type": "module",
+ *   "main": "index.js",
+ *   "bajo": {
+ *     "type": "plugin",
+ *     "alias": "myplugin",
+ *     "dependencies": ["bajo-config", "bajo-cli"]
+ *   }
+ * }
+ * ...
+ * ```
+ *
+ * > **Note**: The dot symbol in `package.json` has been replaced with `·` symbol because of JSDoc theme limitation
+ *
+ * > **Warning**: Do not confuse with your app's {@link package·json|package.json} specification, since this one is for plugin while the other is for app.
+ * @memberof Base
+ * @typedef package·json
+ */
+
+/**
+ * Base class for all plugins.
+ *
+ * This is the class you must extend when creating a new plugin. It provides basic methods and properties to manage your plugin.
+ *
+ * You need to wrap your plugin in a factory function with a single parameter `pkgName`, which will be called by the Bajo framework
+ * during boot process. The factory function must return your plugin class.
+ *
+ * Don't forget to write `package.json` for your plugin that follows {@link Base.package·json|this specification}. Please do not
+ * confuse this with your app's {@link package·json|package.json} specification, since this one is for your plugin only.
+ *
+ * Example:
+ * ```js
+ * // index.js
+ * async function factory (pkgName) {
+ *   const { Base } = this.app.baseClass // get Base from app's baseClass repository
+ *   const me = this // 'this' is Bajo instance. See Bajo boot process for more details
+ *   class BajoCache extends Base {
+ *     constructor () {
+ *       super(pkgName, me.app)
+ *       this.config = {} // your plugin's configuration object. If omitted, it will be set to an empty object
+ *     }
+ *
+ *     init = async () => {
+ *       // your plugin's initialization code here
+ *     }
+ *
+ *     start = async () => {
+ *       // your plugin's start code here
+ *     }
+ *   }
+ *   return BajoCache
+ * }
+ * ```
  *
  * @class
  */
@@ -18,29 +82,30 @@ class Base extends Plugin {
     super(pkgName, app)
 
     /**
-     * Dependencies to other plugins. Enter all plugin's package name your plugin dependent from.
-     *
-     * Semver is also supported.
-     *
+     * Array of plugin dependencies. If your plugin depends on other plugins, you can specify their package names here e.g. `['bajo-config', 'bajo-cli']`, NOT the plugin name/namespace
      * @type {string[]}
      */
     this.dependencies = []
 
     this.state = {}
+
+    /**
+     * Package information from `package.json`. It will be automatically loaded by the framework during plugin initialization
+     * @type {object}
+     */
     this.pkg = {}
   }
 
   /**
-   * Load config from file in data directory, program arguments and environment variables. Level of importance:
-   * `Env Variables > Program Arguments > Config File`
+   * Load plugin configuration. This method will be called by the framework during boot process.
    *
    * @method
    * @async
-   * @returns {void}
+   * @returns {Promise<void>}
    */
   loadConfig = async () => {
     const { defaultsDeep } = this.app.lib.aneka
-    const { get, keys, pick, isEmpty, upperFirst } = this.app.lib._
+    const { get, keys, pick, isEmpty, upperFirst, camelCase } = this.app.lib._
     const { log, getModuleDir, readAllConfigs } = this.app.bajo
     const { parseObject } = this.app.lib
 
@@ -57,42 +122,40 @@ class Base extends Plugin {
     // merge with config from datadir
     try {
       let altCfg = get(this, `app.options.config.${this.ns}`, {})
-      if (isEmpty(altCfg)) altCfg = await readAllConfigs(`${this.app.bajo.dir.data}/config/${this.ns}`)
+      if (isEmpty(altCfg)) altCfg = await readAllConfigs(`${this.app.bajo.dir.data}/config/${camelCase(this.ns)}`)
       cfg = defaultsDeep({}, altCfg, cfg)
     } catch (err) {}
     const cfgEnv = get(this, `app.env.${this.ns}`, {})
     const cfgArgv = get(this, `app.argv.${this.ns}`, {})
-    cfg = pick(defaultsDeep({}, cfgEnv ?? {}, cfgArgv ?? {}, cfg ?? {}, this[`config${upperFirst(this.app.bajo.config.env)}`] ?? {}, this.config ?? {}), defKeys)
+    const envValue = this[`config${upperFirst(this.app.bajo.config.env)}`]
+    cfg = pick(defaultsDeep({}, envValue ?? {}, cfgEnv ?? {}, cfgArgv ?? {}, cfg ?? {}, envValue ?? {}, this.config ?? {}), defKeys)
     this.config = parseObject(cfg, { parseValue: true })
   }
 
   /**
-   * After config is read, plugin will be initialized.
-   *
+   * Plugin initialization. This method will be called by the framework during boot process, after configuration is loaded.
    * @method
    * @async
-   * @returns {void}
+   * @returns {Promise<void>}
    */
   init = async () => {
   }
 
   /**
-   * This method will be called after plugin's init. You can still change your config here,
-   * because after plugin is started, config will be deep frozen
-   *
+   * Plugin start. This method will be called by the framework during boot process, after initialization. You still can
+   * modifiy your plugin's configuration here before it is deep frozen.
    * @method
    * @async
-   * @returns {void}
+   * @returns {Promise<void>}
    */
   start = async () => {
   }
 
   /**
    * Reserved for future use. This method will be called before plugin is stopped.
-   *
    * @method
    * @async
-   * @returns {void}
+   * @returns {Promise<void>}
    */
   stop = async () => {
   }
@@ -100,10 +163,9 @@ class Base extends Plugin {
   /**
    * Upon app termination, this method will be called first. Mostly useful for system cleanup,
    * delete temporary files, freeing resources etc.
-   *
    * @method
    * @async
-   * @returns {void}
+   * @returns {Promise<void>}
    */
   exit = async () => {
     await this.dispose()
@@ -111,7 +173,6 @@ class Base extends Plugin {
 
   /**
    * Dispose internal references.
-   *
    * @async
    * @method
    * @returns {Promise<void>}

package/class/cache.js

@@ -1,21 +1,19 @@
 /**
- * File-system backed cache helper with TTL-based invalidation.
+ * Simple, file-system based cache with TTL-based invalidation for every day use.
  *
  * @class
  */
 class Cache {
   /**
    * Constructor.
-   *
-   * @param {object} app - Application container
+   * @param {App} app - App instance
    */
   constructor (app) {
     this.app = app
   }
 
   /**
-   * Get root directory for this class. It will be used to store all cache files, organized by namespace and TTL.
-   *
+   * Get root directory. It will be used to store all cache files, organized by namespace and TTL.
    * @method
    * @returns {string} Absolute cache root directory
    */
@@ -25,7 +23,6 @@ class Cache {
 
   /**
    * Prepare cache paths for a namespaced key and TTL.
-   *
    * @method
    * @param {string} name - Cache key in namespaced path format
    * @param {number|string} [ttlDur=0] - TTL duration (milliseconds or parseable duration)
@@ -46,11 +43,10 @@ class Cache {
 
   /**
    * Load cached content when available and not expired.
-   *
    * @method
    * @param {string} name - Cache key in namespaced path format
    * @param {number|string} [ttlDur=0] - TTL duration (milliseconds or parseable duration)
-   * @returns {Promise<any>} Cached value, or undefined if missing/expired
+   * @returns {Promise<*>} Cached value, or undefined if missing/expired
    */
   load = async (name, ttlDur = 0) => {
     const { fs } = this.app.lib
@@ -71,10 +67,9 @@ class Cache {
 
   /**
    * Save a value into cache for the given key and TTL directory.
-   *
    * @method
    * @param {string} name - Cache key in namespaced path format
-   * @param {any} item - Value to persist
+   * @param {*} item - Value to persist
    * @param {number|string} [ttlDur=0] - TTL duration (milliseconds or parseable duration)
    * @returns {Promise<void>} Resolves when the value is written
    */
@@ -92,13 +87,12 @@ class Cache {
   }
 
   /**
-   * Return cached content, and store the fallback value if cache is empty.
-   *
+   * Return cached content, and store the fallback value if cache is empty
    * @method
    * @param {string} name - Cache key in namespaced path format
-   * @param {any} item - Fallback value to save when cache miss happens
+   * @param {*} item - Fallback value to save when cache miss happens
    * @param {number|string} [ttlDur=0] - TTL duration (milliseconds or parseable duration)
-   * @returns {Promise<any>} Cached content
+   * @returns {Promise<*>} Cached content
    */
   sync = async (name, item, ttlDur = 0) => {
     const content = await this.loadCache(name, ttlDur)
@@ -108,7 +102,6 @@ class Cache {
 
   /**
    * Remove a specific cache namespace or all first-level namespaces.
-   *
    * @method
    * @param {string} name - Namespace name or `*` for all
    * @returns {void}
@@ -149,7 +142,6 @@ class Cache {
 
   /**
    * Dispose internal reference.
-   *
    * @async
    * @method
    * @returns {Promise<void>}

package/class/err.js

@@ -6,13 +6,27 @@ const { isPlainObject, each, isArray, get, isEmpty, merge } = lodash
 Error.stackTraceLimit = 15
 
 /**
- * Bajo error class, a thin wrapper of node's Error object.
+ * Error details object type definition. This type is used to represent detailed information about an error,
+ * including the field that caused the error, the error message, the value that caused the error, and any additional context.
+ *
+ * This type is particularly useful for validation errors, where you want to provide detailed feedback about what went wrong.
+ * @typedef TErrDetails
+ * @memberof Err
+ * @type {Object}
+ * @property {string} field - Field name
+ * @property {string} error - Error message
+ * @property {*} [value] - The value that caused the error
+ * @property {Object} [ext] - Additional context about the error
+ */
+
+/**
+ * Bajo error class, a thin wrapper around the 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.
  * It helps you create this instance anywhere in your code quickly without the hassle of importing & instantiating:
  *
  * ```javascript
- * ... anywhere inside your code
+ * // anywhere inside your code
  * if (notfound) throw this.error('Sorry, item is nowhere to be found!')
  * ```
  */
@@ -22,32 +36,39 @@ 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
+   * @param  {...*} [args] - Variables to interpolate with error message. Error's payload can be pushed to the very last argument if needed
    */
   constructor (plugin, msg, ...args) {
     super(plugin)
 
     /**
-     * Error payload extracted from the last arguments.
+     * Error payload extracted from the last arguments, if any
      * @type {Object}
      */
     this.payload = args.length > 0 && isPlainObject(args[args.length - 1]) ? args[args.length - 1] : {}
 
     /**
-     * Original message before translation.
+     * Original message before translation
      * @type {string}
      */
     this.orgMessage = msg
 
     /**
-     * Translated message.
+     * Translated message
      * @type {string}
      */
     this.message = this.payload.noTrans ? msg : this.plugin.t(msg, ...args)
   }
 
   /**
-   * Write message to the console.
+   * Write message to the console. Chainable method, returns the Err instance itself.
+   *
+   * If a payload is provided, it will be merged with the existing payload. If `details` is provided in the payload,
+   * it will be formatted and merged to the existing payload and a `detailsMessage` will be generated for display purpose.
+   *
+   * Original message and translated message will be stored in `orgMessage` and `message` properties respectively.
+   *
+   * `ns` property will be set to the plugin's namespace.
    *
    * @method
    * @returns {Err} - Error object, useful for chaining
@@ -91,14 +112,14 @@ class Err extends Tools {
   }
 
   /**
-   * Pretty format error details.
+   * Pretty format error details. Used to format error payloads that contain `details` property, which is an array of error details.
    *
-   * Formatted error will be applied directly to the value parameter, and a detailsMessage
+   * 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
-   * @returns {Object}
+   * @returns {{result: TErrDetails[], detailsMessage: string}} - Formatted result and details message
    */
   formatErrorDetails = (value) => {
     const { isString, last } = this.app.lib._

package/class/log.js

@@ -1,4 +1,5 @@
 import os from 'os'
+import fs from 'fs-extra'
 import chalk from 'chalk'
 import { stripVTControlCharacters } from 'node:util'
 
@@ -57,7 +58,8 @@ export const logLevels = {
 /**
  * A thin & fast logger system.
  *
- * An instance is created by the {@link App|app} and available to use from anywhere inside your code.
+ * You typically don't need to create an instance of this class, since an instance is already 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.
@@ -84,51 +86,55 @@ class Log {
      */
     this._lastDelta = 0
     /**
-     * The app instance.
+     * Reference to the app instance
      * @type {App}
      */
     this.app = app
 
-    const { fs } = this.app.lib
+    /**
+     * Directory to save log files. Defaults to `{dataDir}/log`. If log saving is on (see {@link App#config|app.config.log.save})
+     * and directory does not exist, this directory will be created automatically.
+     * @type {string}
+     */
     this.logDir = `${this.app.bajo.dir.data}/log`
     if (this.app.bajo.config.log.save) fs.ensureDirSync(this.logDir)
   }
 
   /**
-   * 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
+   * Format & display log message according to the current log level with the following syntax:
+   * 1. `level` `prefix` `text` `param 1` `param 2` `...param n` - Translate `text` and interpolate with `params` for level `level`
+   * 2. `level` `prefix` `{data}` `text` `param 1` `param 2` `...param n` - Same as above, but with additional stringified `data` object to be logged
+   * 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 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 {...*} params - See format above
    * @see Err
    * @see Log.TJsonOutput
    */
-  formatMsg = (level, prefix, ...params) => {
+  formatMsg = (level, prefix, ...args) => {
     const { dayjs } = this.app.lib
     const { isEmpty, merge, without } = this.app.lib._
 
     if (this.app.bajo.config.log.level === 'silent') return
     if (!this.app.bajo.isLogInRange(level)) return
     const { useUtc, timeTaken, dateFormat, pretty } = this.app.bajo.config.log
-    let [data, msg, ...args] = params
+    let [data, msg, ...params] = args
     if (data instanceof Error) {
       msg = 'error%s'
-      args = [this.getErrorMessage(data)]
+      params = [this.getErrorMessage(data)]
       console.error(data)
     }
     if (typeof data === 'string') {
-      args.unshift(msg)
+      params.unshift(msg)
       msg = data
       data = null
     }
-    args = without(args, undefined)
-    msg = this.app.t(prefix, msg, ...args)
+    params = without(params, undefined)
+    msg = this.app.t(prefix, msg, ...params)
     let text
     const dt = dayjs()
     let diff = null
@@ -161,8 +167,7 @@ class Log {
   }
 
   /**
-   * Get error message from an Error object. If the message is empty, return the code or statusCode instead.
-   *
+   * Get error message from an Error object. If the error message is empty, return the error code or status code instead.
    * @method
    * @param {Error} error - Error object
    * @returns {string} Error message
@@ -174,6 +179,7 @@ class Log {
 
   /**
    * Calculate pattern used for log rotation. Used by {@link Log#save|save} method to determine the log file name.
+   * Rotation pattern is based on the `rotation.cycle` configuration. See {@link App#config|app.config.log.rotation.cycle} for more info.
    *
    * @method
    * @param {boolean} isPrev - If `true`, calculate previous rotation pattern.
@@ -206,7 +212,7 @@ class Log {
   }
 
   /**
-   * Save log to file in `{dataDir}/log`.
+   * Save log to file in {@link Log#logDir|logDir}.
    *
    * @method
    * @param {string} text - Log message to save
@@ -230,10 +236,12 @@ class Log {
    *
    * @method
    * @param {string} prefix - Message prefix
-   * @param {...any} params - Parameters
+   * @param {...*} args - Argumets to be passed to the message. See {@link Log#formatMsg|formatMsg} for details.
+   * @see Err
+   * @see Log.TJsonOutput
    */
-  trace = (prefix, ...params) => {
-    this.formatMsg('trace', prefix, ...params)
+  trace = (prefix, ...args) => {
+    this.formatMsg('trace', prefix, ...args)
   }
 
   /**
@@ -241,10 +249,10 @@ class Log {
    *
    * @method
    * @param {string} prefix - Message prefix
-   * @param {...any} params - Parameters
+   * @param {...*} args - Arguments to be passed to the message. See {@link Log#formatMsg|formatMsg} for details.
    */
-  debug = (prefix, ...params) => {
-    this.formatMsg('debug', prefix, ...params)
+  debug = (prefix, ...args) => {
+    this.formatMsg('debug', prefix, ...args)
   }
 
   /**
@@ -252,10 +260,10 @@ class Log {
    *
    * @method
    * @param {string} prefix - Message prefix
-   * @param {...any} params - Parameters
+   * @param {...*} args - Arguments to be passed to the message. See {@link Log#formatMsg|formatMsg} for details.
    */
-  info = (prefix, ...params) => {
-    this.formatMsg('info', prefix, ...params)
+  info = (prefix, ...args) => {
+    this.formatMsg('info', prefix, ...args)
   }
 
   /**
@@ -263,10 +271,10 @@ class Log {
    *
    * @method
    * @param {string} prefix - Message prefix
-   * @param {...any} params - Parameters
+   * @param {...*} args - Arguments to be passed to the message. See {@link Log#formatMsg|formatMsg} for details.
    */
-  warn = (prefix, ...params) => {
-    this.formatMsg('warn', prefix, ...params)
+  warn = (prefix, ...args) => {
+    this.formatMsg('warn', prefix, ...args)
   }
 
   /**
@@ -274,10 +282,10 @@ class Log {
    *
    * @method
    * @param {string} prefix - Message prefix
-   * @param {...any} params - Parameters
+   * @param {...*} args - Arguments to be passed to the message. See {@link Log#formatMsg|formatMsg} for details.
    */
-  error = (prefix, ...params) => {
-    this.formatMsg('error', prefix, ...params)
+  error = (prefix, ...args) => {
+    this.formatMsg('error', prefix, ...args)
   }
 
   /**
@@ -285,10 +293,10 @@ class Log {
    *
    * @method
    * @param {string} prefix - Message prefix
-   * @param {...any} params - Parameters
+   * @param {...*} args - Arguments to be passed to the message. See {@link Log#formatMsg|formatMsg} for details.
    */
-  fatal = (prefix, ...params) => {
-    this.formatMsg('fatal', prefix, ...params)
+  fatal = (prefix, ...args) => {
+    this.formatMsg('fatal', prefix, ...args)
   }
 
   /**
@@ -296,10 +304,10 @@ class Log {
    *
    * @method
    * @param {string} prefix - Message prefix
-   * @param {...any} params - Parameters
+   * @param {...*} args - Arguments to be passed to the message. See {@link Log#formatMsg|formatMsg} for details.
    */
-  silent = (prefix, ...params) => {
-    this.formatMsg('silent', prefix, ...params)
+  silent = (prefix, ...args) => {
+    this.formatMsg('silent', prefix, ...args)
   }
 
   /**