bajo 2.21.1 → 2.22.0

package/.jsdoc.conf.json

@@ -12,7 +12,7 @@
       "display-module-header": true,
       "title": "Bajo API",
       "homepageTitle": "Bajo API",
-      "sections": ["Classes", "Events", "Modules", "Global"],
+      "sections": ["Classes", "Events", "Modules", "Externals", "Global"],
       "menu": [{
         "title": "NPM",
         "link": "https://www.npmjs.com/package/bajo"

package/class/app.js

@@ -4,7 +4,7 @@ import Base from './base.js'
 import Cache from './cache.js'
 import Tools from './tools.js'
 import Plugin from './plugin.js'
-import { outmatchNs, parseObject, lib, runAsApplet } from './_helper.js'
+import { lib, runAsApplet } from '../lib/helper.js'
 import { fileURLToPath } from 'url'
 
 const { camelCase, isPlainObject, get, reverse, map, last, without, set } = lib._
@@ -31,10 +31,45 @@ function getCallerFilename () {
 }
 
 /**
- * @typedef {Object} TAppEnv
+ * @typedef {Object} TEnv
+ * @memberof App
  * @property {string} dev=development
  * @property {string} prod=production
- * @see App
+ */
+
+/**
+ * @callback readHandler
+ * @memberof App
+ * @param {string} text - Text to be parsed
+ * @param {object} options - Options object
+ * @returns {object} Parsed object
+ */
+
+/**
+ * @callback writeHandler
+ * @memberof App
+ * @param {Object} data - Data to be stringified
+ * @param {Object} [options={}] - Options
+ * @param {boolean} [options.writeToFile=false] - If true, write result to a file
+ * @param {string} [options.saveAsFile] - The file path to save result if writeToFile is true
+ * @returns {string} Stringified result
+ */
+
+/**
+ * @typedef {Object} TConfigHandler
+ * @memberof App
+ * @property {string} ns - Namespace
+ * @property {string} ext - File extension
+ * @property {App.readHandler} [readHandler] - Function to call for reading
+ * @property {App.writeHandler} [writeHandler] - Function to call for writing
+ */
+
+/**
+ * @typedef {Object} TOptions
+ * @memberof App
+ * @property {string} [cwd] - Set current working directory. Defaults to the script directory
+ * @property {string[]} [plugins] - Array of plugins to load. If provided, it override the list in `package.json` and `.plugins` file
+ * @property {Object} [config] - Plugin's config object. If provided, plugin configs will no longer be read from its config files
  */
 
 /**
@@ -44,73 +79,53 @@ function getCallerFilename () {
  */
 class App {
   /**
-   * @param {Object} [options] - App options.
-   * @param {string} [options.cwd] - Set current working directory. Defaults to the script directory.
-   * @param {string[]} [options.plugins] - Array of plugins to load. If provided, it override the list in ```package.json``` and ```.plugins``` file.
-   * @param {Object} [options.config] - Plugin's config object. If provided, plugin configs will no longer be read from its config files.
+   * Constructor.
+   * @param {App.TOptions} [options={}] - Options object.
    */
   constructor (options = {}) {
     /**
      * Copy of provided options.
-     *
-     * @type {Object}
+     * @type {App.TOptions}
      */
     this.options = options
 
     /**
-     * Your main namespace. And yes, you suppose to NOT CHANGE this.
-     *
-     * @memberof App
-     * @constant {string}
-     * @default 'main'
+     * Main namespace.
+     * @type {string}
      */
     this.mainNs = 'main'
 
     /**
      * App environments.
-     *
-     * @memberof App
-     * @constant {TAppEnv}
+     * @type {App.TEnv}
      */
     this.envs = { dev: 'development', prod: 'production' }
 
     /**
      * Date/time when your app start.
-     *
      * @type {Date}
      */
     this.runAt = new Date()
 
     /**
      * Applets container.
-     *
      * @type {Array}
      */
     this.applets = []
 
     /**
-     * Plugin's package names container. This is the list of plugins to load. It is read from ```package.json``` and ```.plugins``` file by default, but you can override it by providing ```options.plugins``` at constructor.
-     *
-     * @type {Array}
+     * Plugin's package names container. This is the list of plugins to load.
+     * @type {string[]}
      */
     this.pluginPkgs = options.plugins ?? []
 
-    /**
-     * @typedef {Object} TAppConfigHandler
-     * @property {string} ext - File extension.
-     * @property {function} [readHandler] - Function to call for reading.
-     * @property {function} [writeHandler] - Function to call for writing.
-     * @see App#configHandlers
-     */
-
     /**
      * Config handlers.
      *
-     * By default, there are two built-in handlers available: ```.js```, ```.json```
-     * and ```.yml/.yaml```. Use plugins to add more, e.g {@link https://github.com/ardhi/bajo-config|bajo-config}
-     * lets you to use ```.toml```.
-     *
-     * @type {TAppConfigHandler[]}
+     * By default, there are three built-in handlers: `.js`, `.json`
+     * and `.yml/.yaml`. Use plugins to add more, e.g {@link https://github.com/ardhi/bajo-config|bajo-config}
+     * lets you to use `.toml`.
+     * @type {Array<App.TConfigHandler>}
      */
     this.configHandlers = []
 
@@ -118,17 +133,14 @@ class App {
      * Gives you direct access to the most commonly used 3rd party library in a Bajo based app.
      * No manual import necessary, always available, anywhere, anytime!
      *
-     * Example:
-     * ```javascript
+     * @type {App.TLib}
+     * @example
      * const { camelCase, kebabCase } = this.app.lib._
      * console.log(camelCase('Elit commodo sit et aliqua'))
-     * ```
-     *
-     * @type {TAppLib}
      */
     this.lib = lib
-    this.lib.outmatchNs = outmatchNs.bind(this)
-    this.lib.parseObject = parseObject.bind(this)
+    this.lib.outmatchNs = this.lib.outmatchNs.bind(this)
+    this.lib.parseObject = this.lib.parseObject.bind(this)
 
     /**
      * Instance of system log.
@@ -139,47 +151,47 @@ class App {
 
     /**
      * All plugin's base class are saved here as key-value pairs with plugin name as its key.
-     * The special key ```Base``` && ```Tools``` is for {@link Base} & {@link Tools} class so anytime you want to
-     * create your own plugin, just use something like this:
+     * The special key `Base` && `Tools` is for {@link Base} & {@link Tools} class so that anytime you want to
+     * create your own plugin, you can just write something like this:
      *
-     * ```javascript
+     * `javascript
      * class MyPlugin extends this.app.baseClass.Base {
      *   ... your class
      * }
+     *
+     * @type {Object}
      */
     this.baseClass = { Base, Tools }
 
     /**
      * If app runs in applet mode, this will be the applet's name.
-     *
      * @type {string}
      */
     this.applet = undefined
 
     /**
-     * Program arguments.
-     *
-     * ```
+     * Parsed program arguments.
+     * @type {string[]}
+     * @see module:Helper.parseArgsArgv
+     * @example
      * $ node index.js arg1 arg2
      * ...
      * console.log(this.args) // it should print: ['arg1', 'arg2']
-     * ```
-     *
-     * @type {string[]}
-     * @see module:Lib.parseArgsArgv
      */
     this.args = []
 
     /**
-     * Program options.
+     * Parsed program options.
      *
-     * - Dash (```-```) breaks the string into object keys
-     * - While colon (```:```) is used as namespace separator. If no namespace found, it is saved under ```_``` key.
+     * - Dash (`-`) breaks the string into object keys
+     * - While colon (`:`) is used as namespace separator. If no namespace found, it is saved under `_` key.
      *
      * Values are parsed automatically. See {@link https://github.com/ladjs/dotenv-parse-variables|dotenv-parse-variables}
      * for details.
      *
-     * ```
+     * @type {Object}
+     * @see module:Helper.parseArgsArgv
+     * @example
      * $ node index.js --my-name-first=John --my-name-last=Doe --my-birthDay=secret --nameSpace:path-subPath=true
      * ...
      * // {
@@ -191,38 +203,39 @@ class App {
      * //   },
      * //   nameSpace: { path: { subPath: true } }
      * // }
-     * ```
-     *
-     * @type {Object}
-     * @see module:Lib.parseArgsArgv
      */
     this.argv = {}
 
     /**
-     * Environment variables. Support dotenv (```.env```) file too!
+     * Environment variables. Support dotenv (`.env`) file too!
      *
-     * - Underscore (```_```) translates key to camel-cased one
-     * - Double underscores (```__```) breaks the key into object keys
-     * - While dot (```.```) is used as namespace separator. If no namespace found, it is saved under ```_``` key.
+     * - Underscore (`_`) translates key to camel-cased one
+     * - Double underscores (`__`) breaks the key into object keys
+     * - While dot (`.`) is used as namespace separator. If no namespace found, it is saved under `_` key.
      *
      * Values are also parsed automatically using {@link https://github.com/ladjs/dotenv-parse-variables|dotenv-parse-variables}.
      *
-     * Example:
+     * E.g.:
      *
-     * - ```MY_KEY=secret``` → ```{ _: { myKey: 'secret' } }```
-     * - ```MY_KEY__SUB_KEY=supersecret``` → ```{ _: { myKey: { subKey: 'supersecret' } } }```
-     * - ```MY_NS.MY_NAME=John``` → ```{ myNs: { myName: 'John' } }```
+     * - `MY_KEY=secret` → `{ _: { myKey: 'secret' } }`
+     * - `MY_KEY__SUB_KEY=supersecret` → `{ _: { myKey: { subKey: 'supersecret' } } }`
+     * - `MY_NS.MY_NAME=John` → `{ myNs: { myName: 'John' } }`
      *
      * @type {Object}
-     * @see module:Lib.parseEnv
+     * @see module:Helper.parseEnv
      */
     this.envVars = {}
 
     /**
-     * Placeholder for boxen that will get imported from ```bajoCli``` later during boot process.
+     * Placeholder for boxen that will get imported from `bajoCli` later during boot process.
+     * @type {Object}
      */
     this.boxen = null
 
+    /**
+     * Cache instance. This is used to store temporary data in memory for faster access.
+     * @type {Cache}
+     */
     this.cache = new Cache(this)
 
     if (!options.cwd) options.cwd = process.cwd()
@@ -285,7 +298,7 @@ class App {
    *
    * @method
    * @param {string} name - Plugin name/namespace or alias.
-   * @param {boolean} [silent] - If ```true```, silently return undefined even on error.
+   * @param {boolean} [silent] - If `true`, silently return undefined even on error.
    * @returns {Object} Plugin object.
    */
   getPlugin = (name, silent) => {
@@ -313,7 +326,7 @@ class App {
    *
    * @method
    * @param {string} name - Plugin name (namespace) or alias.
-   * @param {boolean} [ensureDir=true] - Set ```true``` (default) to ensure directory is existed.
+   * @param {boolean} [ensureDir=true] - Set `true` (default) to ensure directory is existed.
    * @returns {string}
    */
   getPluginDataDir = (name, ensureDir = true) => {
@@ -328,8 +341,8 @@ class App {
    * Resolve file path from:
    *
    * - local/absolute file
-   * - TNsPath (```myPlugin:/path/to/file.txt```)
-   * - file under node_modules, e.g. ```myPlugin:node_modules/some-package/file.txt```
+   * - TNsPath (`myPlugin:/path/to/file.txt`)
+   * - file under node_modules, e.g. `myPlugin:node_modules/some-package/file.txt`
    *
    * @method
    * @param {string} file - File path, see above for supported types.
@@ -356,15 +369,15 @@ class App {
   }
 
   /**
-   * Dumping variable on screen. Like ```console.log``` with configurable options. Useful for quick debugging and testing. You can also use it to dump variables in production without worrying about performance because it is using Bajo's built-in cache to store the result of util's inspect, so it will only be processed once for each unique variable.
+   * Dumping variable on screen. Like `console.log` with configurable options. Useful for quick debugging and testing. You can also use it to dump variables in production without worrying about performance because it is using Bajo's built-in cache to store the result of util's inspect, so it will only be processed once for each unique variable.
    *
    * Any argument passed to this method will be displayed on screen.
-   * If the last argument is a boolean ```true```, app will quit rightaway after dumping.
+   * If the last argument is a boolean `true`, app will quit rightaway after dumping.
    *
-   * If you have ```bajoCli``` plugin installed, variables will be displayed in a nice box using ```boxen``` package.
-   * Otherwise, it will fallback to ```console.log``` with util's inspect result.
+   * If you have `bajoCli` plugin installed, variables will be displayed in a nice box using `boxen` package.
+   * Otherwise, it will fallback to `console.log` with util's inspect result.
    *
-   * To have more control on how the variable is displayed, you can set options in Bajo's config under ```dump``` key.
+   * To have more control on how the variable is displayed, you can set options in Bajo's config under `dump` key.
    * See {@link Bajo#config} for details.
    *
    * @method
@@ -391,23 +404,29 @@ class App {
   }
 
   /**
-   * Boot process:
+   * Run application:
    *
-   * - Parsing {@link module:Lib.parseArgsArgv|program arguments, options} and {@link module:Lib.parseEnv|environment values}
+   * - Parsing {@link module:Helper.parseArgsArgv|program arguments, options} and {@link module:Helper.parseEnv|environment values}
    * - Create {@link Bajo|Bajo} instance & initialize it
-   * - {@link module:Helper/Bajo.runAsApplet|Run in applet mode} if ```-a``` or ```--applet``` is given
+   * - {@link module:Helper/Bajo.runAsApplet|Run in applet mode} if `-a` or `--applet` is given
    *
-   * After boot process is completed, event ```bajo:afterBootCompleted``` is emitted.
+   * After boot process is completed, event `bajo:afterBootCompleted` is emitted.
    *
-   * If app mode is ```applet```, it runs your choosen applet instead.
+   * If app mode is `applet`, it runs your choosen applet instead.
    *
-   * @method
    * @async
-   * @returns {App}
-   * @fires bajo:afterBootCompleted
+   * @method
+   * @returns {Promise<App>} App instance.
    */
-  boot = async () => {
+  run = async () => {
     this.bajo = new Bajo(this)
+    this.configHandlers = [
+      { ns: 'bajo', ext: '.js', readHandler: this.bajo.fromJs },
+      { ns: 'bajo', ext: '.json', readHandler: this.bajo.fromJson, writeHandler: this.bajo.toJson },
+      { ns: 'bajo', ext: '.yaml', readHandler: this.bajo.fromYaml, writeHandler: this.bajo.toYaml },
+      { ns: 'bajo', ext: '.yml', readHandler: this.bajo.fromYml, writeHandler: this.bajo.toYml }
+    ]
+
     const hooks = (this.options.hooks ?? []).map(item => {
       item.src = item.src ?? 'bajo'
       return item
@@ -433,14 +452,6 @@ class App {
     // boot complete
     const elapsed = new Date() - this.runAt
     this.bajo.log.debug('bootCompleted%s', secToHms(elapsed, true))
-    /**
-     * Run after boot process is completed
-     *
-     * @global
-     * @event bajo:afterBootComplete
-     * @see {@tutorial hook}
-     * @see App#boot
-     */
     await this.bajo.runHook('bajo:afterBoot')
     if (this.applet) await runAsApplet.call(this.bajo)
     return this
@@ -450,7 +461,7 @@ class App {
    * Terminate the app and back to console.
    *
    * @method
-   * @param {string} [signal=SIGINT] - Signal to send.
+   * @param {string|boolean} [signal=SIGINT] - Signal to send. Set to `true` to terminate immediately without sending any signal.
    */
   exit = (signal = 'SIGINT') => {
     if (signal === true) process.exit('1')
@@ -461,7 +472,7 @@ class App {
    * Load internationalization & languages files for particular plugin.
    *
    * @method
-   * @param {string} ns - Plugin name.
+   * @param {string} ns - Plugin name (namespace)
    */
   loadIntl = (ns) => {
     const { fs } = this.lib
@@ -478,6 +489,16 @@ class App {
     }
   }
 
+  /**
+   * Prepare translation text and parameters for translation.
+   *
+   * @method
+   * @private
+   * @param {string} ns
+   * @param {string} text
+   * @param {Array} params
+   * @returns {Object}
+   */
   _prepTrans = (ns, text, params) => {
     const { fallback, supported } = this.bajo.config.intl
     const { isSet } = this.lib.aneka
@@ -515,22 +536,23 @@ class App {
   }
 
   /**
-   * Translate text and interpolate with given ```args```.
+   * Translate text and interpolate with given `params`.
+   *
+   * If the last parameter is an object with `lang` key, it will use that language instead of the default one.
    *
    * There is a shortcut to this method attached on all plugins. You'll normally call that shorcut
-   * instead of this method, because it is bound to plugin's name already
+   * instead of this method, because it is bound to plugin's namespace already
    *
-   * ```javascript
+   * @method
+   * @param {string} ns - Namespace
+   * @param {string} text - Text to translate
+   * @param  {...any} params - Arguments
+   * @returns {string}
+   * @example
    * ... within your main plugin
    * const translated = this.app.t('main', 'My cute cat is %s', 'purring')
-   * // or
+   * // or within your plugin
    * const translated = this.t('My cute cat is %s', 'purring')
-   * ```
-   * @method
-   * @param {string} ns - Namespace.
-   * @param {string} text - Text to translate.
-   * @param  {...any} params - Arguments.
-   * @returns {string}
    */
   t = (ns, text, ...params) => {
     const { formatText, isSet } = this.lib.aneka
@@ -547,11 +569,11 @@ class App {
   }
 
   /**
-   * Check whether translation text/key exists
+   * Check whether translation text/key exists.
    *
    * @method
-   * @param {string} ns - Namespace.
-   * @param {string} text - Text to translate.
+   * @param {string} ns - Namespace
+   * @param {string} text - Text to translate
    * @returns {boolean}
    */
   te = (ns, text, ...params) => {
@@ -563,7 +585,7 @@ class App {
    * Helper method to list all supported config formats.
    *
    * @method
-   * @param {boolean} [noDot] - If ```true```, it will return the list without dot prefix.
+   * @param {boolean} [noDot] - If `true`, it will return the list without dot prefix
    * @returns {string[]}
    */
   getConfigFormats = (noDot) => {
@@ -574,8 +596,9 @@ class App {
   /**
    * Start a plugin.
    *
+   * @method
    * @param {string} ns - Plugin namespace.
-   * @param  {...any} args - Arguments to pass to the plugin's start method.
+   * @param  {...any} args - Arguments to pass to the plugin's start method
    */
   startPlugin = (ns, ...args) => {
     this[ns].start(...args)
@@ -584,8 +607,9 @@ class App {
   /**
    * Stop a plugin.
    *
+   * @method
    * @param {string} ns - Plugin namespace.
-   * @param  {...any} args - Arguments to pass to the plugin's stop method.
+   * @param  {...any} args - Arguments to pass to the plugin's stop method
    */
   stopPlugin = (ns, ...args) => {
     // Disabled for now, reserved for future use. It is not a good idea to stop a plugin because other plugins might be dependent on it.