bajo 2.23.0 → 2.25.0

package/class/bajo.js

@@ -13,11 +13,14 @@ import * as yaml from 'js-yaml'
 import aneka from 'aneka'
 import {
   buildBaseConfig,
-  buildExtConfig,
+  buildConfig,
   buildPlugins,
   collectConfigHandlers,
   bootOrder,
-  bootPlugins,
+  checkNameAliases,
+  checkDependencies,
+  collectHooks,
+  runPlugins,
   exitHandler,
   importModule,
   types as formatTypes,
@@ -27,20 +30,20 @@ import {
 const require = createRequire(import.meta.url)
 
 const {
-  isFunction, map, isObject,
+  isFunction, map, isObject, findIndex, uniq, merge, mergeWith,
   trim, filter, isEmpty, orderBy, pullAt, find, camelCase,
   cloneDeep, isPlainObject, isArray, isString, omit, keys, indexOf,
-  last, get, has, values, pick
+  last, get, has, values, pick, isBoolean
 } = lodash
 
-const { resolvePath, getGlobalModuleDir } = aneka
+const { resolvePath, getGlobalModuleDir, defaultsDeep, isSet, parseObject } = aneka
 
 /**
- * Name based `{ns}:{path}` format.
+ * Name in `{ns}:{path}` format.
  *
  * @typedef {string} TNsPathPairs
  * @memberof Bajo
- * @see TNsPathResult
+ * @see Bajo.TNsPathResult
  * @see Bajo#buildNsPath
  * @see Bajo#breakNsPath
  */
@@ -56,23 +59,30 @@ const { resolvePath, getGlobalModuleDir } = aneka
  */
 
 /**
- * Object returned by {@link Bajo#breakNsPath|bajo:breakNsPath}.
+ * Object returned by {@link Bajo#breakNsPath|bajo:breakNsPath()}.
  *
  * @typedef {Object} TNsPathResult
  * @memberof Bajo
- * @property {string} ns - Namespace
+ * @property {string} [ns] - Namespace
  * @property {string} [subNs] - Sub namespace
  * @property {string} [subSubNs] - Sub of sub namespace
+ * @property {string} [fullNs] - Full namespace, including sub namespaces
  * @property {string} path - Path without query string or hash
- * @property {string} fullPath - Full path, including query string and hash
- * @see TNsPathPairs
+ * @property {string} [fullPath] - Full path, including query string and hash
+ * @property {string} [realPath] - Path without query string or hash, but with parameters replaced with their values
+ * @property {string} [realFullPath] - Full path, including query string and hash, but with parameters replaced with their values
+ * @property {Object} [qs] - Query string object
+ * @property {Object} [params] - Parameters object
+ * @see Bajo.TNsPathPairs
  * @see Bajo#buildNsPath
  * @see Bajo#breakNsPath
  */
 
 /**
- * The Core. The main engine. The one and only plugin that control app's boot process and
- * making sure all other plugins working nicely.
+ * The core plugin. The main engine. The special plugin that controls the app's boot process and
+ * makes sure all other plugins work nicely.
+ *
+ * Don't create your own instance of this class or {@link App} class. Instead, use the {@link boot} process.
  *
  * @class
  */
@@ -86,57 +96,61 @@ class Bajo extends Plugin {
     super('bajo', app)
 
     /**
-     * Alias
+     * Alias. Read-only
      * @type {string}
+     * @default 'bajo'
      */
     this.alias = 'bajo'
 
     /**
-     * White space characters
+     * Array of white space characters. Used to trim strings
      * @type {string[]}
      */
     this.whiteSpace = [' ', '\t', '\n', '\r']
 
     /**
-     * Config object.
-     *
-     * @type {Bajo.TObject}
+     * Configuration object
+     * @type {Bajo.TConfig}
      * @see {@tutorial config}
      */
     this.config = {}
 
     /**
-     * Hooks container.
-     *
+     * Hooks container. This is where all hooks definition are stored.
      * @type {Array<Bajo.THook>}
      */
     this.hooks = []
   }
 
   /**
-   * Initialization:
-   *
-   * 1. Building {@link module:Helper/Bajo.buildBaseConfig|base config}
-   * 2. {@link module:Helper/Bajo.buildPlugins|Building plugins}
-   * 3. Collect all {@link module:Helper/Bajo.collectConfigHandlers|config handler}
-   * 4. Building {@link module:Helper/Bajo.buildExtConfig|extra config}
-   * 5. Setup {@link module:Helper/Bajo.bootOrder|boot order}
-   * 6. {@link module:Helper/Bajo.bootPlugins|Boot loaded plugins}
-   * 7. Attach {@link module:Helper/Bajo.exitHandler|exit handlers}
+   * Bajo boot process. This method is called by the {@link App} class during the app's boot process:
+   * 1. Building Bajo's {@link module:Helper.buildBaseConfig|base configuration}
+   * 2. Collect all {@link module:Helper.collectConfigHandlers|config handlers} from all loaded plugins
+   * 3. Build {@link module:Helper.buildConfig|configuration} object
+   * 4. {@link module:Helper.buildPlugins|Building plugins} listed in `package.json` or `.plugins` file
+   * 5. Determining the {@link module:Helper.bootOrder|boot order}
+   * 6. Ensure the {@link module:Helper.checkNameAliases|uniqueness} of all plugins' name and alias
+   * 7. Ensure all plugins {@link module:Helper.checkDependencies|dependencies} are met
+   * 8. Collect all {@link module:Helper.collectHooks|hooks} from all loaded plugins
+   * 9. {@link module:Helper.runPlugins|Run all plugins} according to the boot order
+   * 10. And finally attaching all {@link module:Helper.exitHandler|exit handlers} it could find
    *
    * @method
    * @async
    */
-  init = async () => {
+  bootApp = async () => {
     await buildBaseConfig.call(this)
     await collectConfigHandlers.call(this)
-    await buildExtConfig.call(this)
+    await buildConfig.call(this)
     await buildPlugins.call(this)
     await bootOrder.call(this)
-    await bootPlugins.call(this)
+    await checkNameAliases.call(this)
+    await checkDependencies.call(this)
+    await collectHooks.call(this)
+    await runPlugins.call(this)
     await exitHandler.call(this)
     if (this.app.bajoSpatial) {
-      this.anekaSpatial = await this.importPkg('bajoSpatial:aneka-spatial')
+      this.app.lib.anekaSpatial = await this.importPkg('bajoSpatial:aneka-spatial')
     }
   }
 
@@ -191,12 +205,24 @@ class Bajo extends Plugin {
   }
 
   /**
-   * Break name to its namespace & path infos
+   * Break `name` to their components.
+   *
+   * If path starts with `//`, e.g. name is `https://example.com`, it will be treated as a URL and returned as an
+   * object with only `path` property filled with the original name.
+   *
+   * If query string is present in the path, it will be parsed and returned as an object with `qs`
+   * property containing the parsed query string.
+   *
+   * If path contains parameters in the format of `:key|value` or `{key|value}`, they will be extracted and returned
+   * as an object with `params` property containing the extracted parameters.
+   *
+   * This method is one of the most used method in Bajo. It is because every files, names, resources, and even commands
+   * are all identified by their namespace and path.
    *
    * @method
-   * @param {(TNsPathPairs|string)} name - Name to break
-   * @param {boolean} [checkNs=true] - If `true` (default), namespace will be checked for its validity
-   * @returns {TNsPathResult}
+   * @param {Bajo.TNsPathPairs} name - Name in format `ns:path`
+   * @param {boolean} [checkNs=true] - If `true` (default), check if the namespace exists in the app. If not, throw an error
+   * @returns {Bajo.TNsPathResult}
    */
   breakNsPath = (name = '', checkNs = true) => {
     let [ns, ...path] = name.split(':')
@@ -225,14 +251,17 @@ class Bajo extends Plugin {
     const params = {}
     for (const idx in parts) {
       const part = parts[idx]
-      if (part[0] !== ':' || part.indexOf('|') === -1) {
+      if (part.indexOf('|') === -1 && ![':', '{'].includes(part[0])) {
         realParts.push(part)
         continue
       }
-      const [key, val] = part.split('|')
-      parts[idx] = key
-      params[key.slice(1)] = val
-      realParts.push(val)
+      let [key, val] = part.split('|')
+      if (!val) val = key[0] === '{' ? '}' : ''
+      key = key.slice(1)
+      val = val[val.length - 1] === '}' ? val.slice(0, val.length - 1) : val
+      // parts[idx] = key
+      params[key] = val
+      realParts.push(isEmpty(val) ? parts[idx] : val)
     }
     path = parts.join('/')
     const realPath = realParts.join('/')
@@ -240,33 +269,39 @@ class Bajo extends Plugin {
     if (!isEmpty(qs)) fullPath += ('?' + querystring.stringify(qs, null, null, { encodeURIComponent: (text) => (text) }))
     let realFullPath = realPath
     if (!isEmpty(qs)) realFullPath += ('?' + querystring.stringify(qs, null, null, { encodeURIComponent: (text) => (text) }))
-    return { ns, path, subNs, subSubNs, qs, fullPath, fullNs, realPath, realFullPath }
+    return { ns, path, subNs, subSubNs, qs, params, fullPath, fullNs, realPath, realFullPath }
   }
 
   /**
-   * Method to transform config's array or object into an array of collection.
+   * Method to transform config's array or object into a collection of objects with uniformed structure. This is useful to build a collection of items
+   * from config's array or object, e.g. a collection of commands, routes, etc.
+   *
+   * You typically also provide a `handler` function to transform each item in the collection. The handler function will be called with an object
+   * containing the following keys:
+   * - `item`: the current item in the collection
+   * - `index`: the index of the current item in the collection
+   * - `cfg`: the entire config object
    *
    * @method
    * @async
-   * @param {Object} options - Options.
-   * @param {string} [options.ns] - Namespace. If not provided, defaults to `bajo`
-   * @param {function} [options.handler] - Handler to call while building the collection item.
-   * @param {string[]} [options.dupChecks=[]] - Array of keys to check for duplicates.
-   * @param {string} options.container - Key used as container name.
-   * @param {boolean} [options.useDefaultName=true] - If true (default) and `name` key is not provided, returned collection will be named `default`.
-   * @fires bajo:beforeBuildCollection
-   * @fires bajo:afterBuildCollection
-   * @returns {Object[]} The collection
+   * @param {Object} [options={}] - Options
+   * @param {string} [options.ns='bajo'] - Namespace. If not provided, defaults to `bajo`
+   * @param {function} [options.handler] - Function to transform each item while building
+   * @param {string[]} [options.dupChecks=[]] - Array of keys to check for duplicates
+   * @param {string} options.container - Key used as container name
+   * @param {boolean} [options.useDefaultName=true] - If true (default) and `name` key is not provided, returned item will be named `default`
+   * @returns {Array<Object>} Returned collection of objects
+   * @see module:Hook.{ns}:beforeBuildCollection
+   * @see module:Hook.{ns}:afterBuildCollection
    */
   buildCollections = async (options = {}) => {
     const { parseObject } = this.app.lib
-    let { ns, handler, dupChecks = [], container, useDefaultName = true, noDefault = true } = options
-    if (!ns) ns = this.ns
+    const { ns = this.ns, handler, dupChecks = [], container, useDefaultName = true, noDefault = true } = options
     const cfg = this.app[ns].getConfig()
     let items = get(cfg, container, [])
     if (!isArray(items)) items = [items]
     this.app[ns].log.trace('collecting%s', this.t(container))
-    await this.runHook(`${ns}:beforeBuildCollection`, container)
+    await this.runHook(`${ns}:beforeBuildCollection`, container, items)
     const deleted = []
     for (const index in items) {
       const item = parseObject(items[index])
@@ -300,8 +335,7 @@ class Bajo extends Plugin {
   }
 
   /**
-   * Calling any plugin's method by its name:
-   *
+   * Calling a function handler in any plugins:
    * - If name is a string, the corresponding plugin's method will be called with passed args as its parameters
    * - If name is a plugin instance, this will be used as the scope instead. The first args is now the handler name and the rest are its parameters
    * - If name is a function, this function will be run under scope with the remaining args
@@ -309,9 +343,9 @@ class Bajo extends Plugin {
    *
    * @method
    * @async
-   * @param {(TNsPathPairs|Object|function)} name - Method's name, function handler, plain object or plugin instance.
-   * @param  {...any} [args] - One or more arguments passed as parameter to the handler.
-   * @returns {any} Returned value.
+   * @param {(TNsPathPairs|Plugin|function|Object)} name - Method's name, plugin instance, function handler or plain object. See above for details
+   * @param  {...*} [args] - One or more arguments passed as parameter to the handler
+   * @returns {Promise<*>} Returned value
    */
   callHandler = async (item, ...args) => {
     let result
@@ -356,8 +390,8 @@ class Bajo extends Plugin {
    * @param {boolean} [options.useBajo=false] - If true, add `bajo` to the running plugins too.
    * @param {string} [options.prefix=''] - Prepend glob pattern with prefix.
    * @param {boolean} [options.noUnderscore=true] - If true (default), matched file with name starts with underscore is ignored.
-   * @param {any} [options.returnItems] - If true, each value of returned handler call will be saved as an object with running plugin name as its keys.
-   * @returns {any}
+   * @param {*} [options.returnItems] - If true, each value of returned handler call will be saved as an object with running plugin name as its keys.
+   * @returns {*}
    */
   eachPlugins = async (handler, options = {}) => {
     if (isString(options)) options = { glob: options }
@@ -424,7 +458,7 @@ class Bajo extends Plugin {
    *
    * @method
    * @param {string} type - Format type. See {@link TBajoFormatType} for acceptable values.
-   * @param {any} value - Value to format.
+   * @param {*} value - Value to format.
    * @param {string} [dataType] - Value's data type. See {@link TBajoDataType} for acceptable values.
    * @param {Object} [options={}] - Options.
    * @param {boolean} [options.withUnit=true] - Return with its unit appended.
@@ -432,7 +466,6 @@ class Bajo extends Plugin {
    * @returns {(Array|string)} Return string if `withUnit` is true. Otherwise is an array of `[value, unit, separator]`.
    */
   formatByType = (type, value, dataType, options = {}) => {
-    const { defaultsDeep } = this.app.lib.aneka
     const { format } = this.getUnitFormat(options)
     const { withUnit = true } = options
     const lang = options.lang ?? this.config.lang
@@ -449,7 +482,7 @@ class Bajo extends Plugin {
    * Format value.
    *
    * @method
-   * @param {any} value - Value to format.
+   * @param {*} value - Value to format.
    * @param {string} [type] - Data type to use. See {@link TBajoDataType} for acceptable values. If not provided, return the untouched value.
    * @param {Object} [options={}] - Options.
    * @param {string} [options.emptyValue=''] - Empty value to use if function resulted empty. Defaults to the one from your config.
@@ -460,7 +493,6 @@ class Bajo extends Plugin {
    * @returns {string} Formatted value.
    */
   format = (value, type, options = {}) => {
-    const { defaultsDeep, isSet } = this.app.lib.aneka
     const { format } = this.config.intl
     const { emptyValue = format.emptyValue } = options
     const lang = options.lang ?? this.config.lang
@@ -585,7 +617,6 @@ class Bajo extends Plugin {
    * @returns {(Object|Array)} See above.
    */
   importPkg = async (...pkgs) => {
-    const { defaultsDeep } = this.app.lib.aneka
     const result = {}
     const notFound = []
     let opts = { returnDefault: true, throwNotFound: false }
@@ -600,7 +631,7 @@ class Bajo extends Plugin {
         notFound.push(pkg)
         continue
       }
-      const p = this.readJson(`${dir}/package.json`, opts.throwNotFound)
+      const p = await this.fromJson(`${dir}/package.json`, { readFromFile: true, throwNotFound: opts.throwNotFound })
       const mainFileOrg = dir + '/' + (p.main ?? get(p, 'exports.default', 'index.js'))
       let mainFile = resolvePath(mainFileOrg, os.platform() === 'win32')
       if (isEmpty(path.extname(mainFile))) {
@@ -675,35 +706,34 @@ class Bajo extends Plugin {
   }
 
   /**
-   * Human friendly join array of items.
+   * Return human friendly joined array of items.
    *
    * @method
-   * @param {any[]} array - Array to join
-   * @param {(string|Object)} options - If provided and is a string, it will be used as separator.
+   * @param {Array<*>} input - Array to join
+   * @param {(string|Object)} [options={}] - If provided and is a string, it will be used as separator.
    * @param {string} [options.separator=', '] - Separator to use.
-   * @param {string} [options.lastSeparator=and] - Text to use as the last separator.
+   * @param {string} [options.lastSeparator='and'] - Text to use as the last separator.
    * @returns {string}
    */
   join = (input = [], options = {}) => {
     const array = [...input]
     if (isString(options)) options = { separator: options }
-    let { separator = ', ', lastSeparator = 'and', lang } = options
+    const { separator = ', ', lastSeparator = 'and', lang } = options
     const translate = (val) => {
       return this.t(val, { lang }).toLowerCase()
     }
     if (array.length === 0) return translate('none')
     if (array.length === 1) return array[0]
-    lastSeparator = translate(lastSeparator)
     const last = (array.pop() ?? '').trim()
-    return array.map(a => (a + '').trim()).join(separator) + ` ${lastSeparator} ${last}`
+    return array.map(a => (a + '').trim()).join(separator) + ` ${translate(lastSeparator)} ${last}`
   }
 
   /**
-   * Return its numeric portion of a value.
+   * Get numeric portion and its unit from a string.
    *
    * @method
-   * @param {string} [value=''] - Value to get its numeric portion.
-   * @param {string} [defUnit=''] - Default unit if value doesn't have one.
+   * @param {string} [value=''] - Value to get its numeric portion
+   * @param {string} [defUnit=''] - Default unit if value doesn't have one
    * @returns {string}
    */
   numUnit = (value = '', defUnit = '') => {
@@ -714,27 +744,31 @@ class Bajo extends Plugin {
 
   /**
    * Read and parse file as config object. Supported types: `.js`, `.json` and `.yml/.yaml`.
-   * More supports can be added using plugin. {@link https://github.com/ardhi/bajo-config|bajo-config} gives you additional supports for `.yml`, `.yaml` and `.toml` file.
+   * More supports can be added using plugin. {@link https://ardhi.github.io/bajo-config|bajo-config} gives you additional supports for `.yml`, `.yaml` and `.toml` file.
    *
    * If file extension is `.*`, it will be auto detected and parsed accordingly
    *
    * @method
    * @async
    * @param {string} file - File to read and parse.
-   * @param {Object} [options={}] - Options.
-   * @param {boolean} [options.ignoreError] - Any exception will be silently discarded.
-   * @param {string} [options.ns] - If given, use this as the scope.
-   * @param {string} [options.pattern] - If given and auto detection is on (extension is `.*`), it will be used for instead the default one.
-   * @param {Object} [options.defValue={}] - Default value to use if value returned empty.
-   * @param {Object} [options.parserOpts={}] - Parser setting.
-   * @param {Object} [options.globOpts={}] - {@link https://github.com/mrmlnc/fast-glob|fast-glob} options.
+   * @param {Object} [options={}] - Options
+   * @param {boolean} [options.ignoreError] - Any exception will be silently discarded
+   * @param {string} [options.ns] - If provided, scoped to this namespace. Otherwise, the running plugin's namespace will be used
+   * @param {string} [options.baseNs] - If provided, it will be used as the base namespace for extending config from other plugins
+   * @param {string|string[]|boolean} [options.extend] - If provided, it will be used as the base namespace for extending config from other plugins. Set to `false` to disable extending
+   * @param {boolean} [options.checkOverride] - If `true` and `baseNs` is provided or `extend` is not `false`, check for override config in main plugin
+   * @param {boolean|string} [options.merge] - If `true`, config from other plugins will be merged into the original config. If `concat`, it performs array concatenation if object is an array. Otherwise, it will perform a deep defaults merge
+   * @param {string} [options.pattern] - If provided and auto detection is on (extension is `.*`), it will be used for instead the auto generated one
+   * @param {Object} [options.defValue={}] - Default value to use if value returned empty
+   * @param {Object} [options.parserOpts={}] - Parser options
+   * @param {Object} [options.globOpts={}] - {@link https://github.com/mrmlnc/fast-glob|fast-glob} options
    * @returns {Object}
    */
   readConfig = async (file, options = {}) => {
-    const { parseObject } = this.app.lib
-    const { defaultsDeep } = this.app.lib.aneka
-    const { uniq, isString, isArray, findIndex, isPlainObject, merge } = this.app.lib._
-    let { ns, baseNs, extend, checkOverride, merge: merged, pattern, ignoreError = true, defValue = {}, parserOpts = {}, globOpts = {}, handler, cache = {} } = options
+    let {
+      ns, baseNs, extend, checkOverride, merge: merged, pattern, ignoreError = true,
+      defValue = {}, parserOpts = {}, globOpts = {}, handler, cache = {}
+    } = options
 
     const getParseOptsArgs = (opts, orig) => {
       opts.parserOpts = opts.parserOpts ?? {}
@@ -746,6 +780,15 @@ class Bajo extends Plugin {
       else opts.parserOpts.args.push({ _orig: orig })
     }
 
+    const binder = (...args) => {
+      if (merged === 'concat') {
+        return mergeWith(...args, (objValue, srcValue) => {
+          if (isArray(objValue)) return objValue.concat(srcValue)
+        })
+      }
+      return merged ? merge(...args) : defaultsDeep(...args)
+    }
+
     const output = async (obj) => {
       let orig = parseObject(obj)
       if (!baseNs || extend === false) {
@@ -755,7 +798,7 @@ class Bajo extends Plugin {
       }
       const { suffix = '', keys = [] } = options
       let bases = this.app.getAllNs()
-      if (isString(extend)) extend = extend.split(',').map(i => i.trim)
+      if (isString(extend)) extend = extend.split(',').map(i => i.trim())
       if (isArray(extend)) bases = [...extend, 'main']
       bases = uniq(bases)
       let ext = isArray(orig) ? [] : {}
@@ -776,14 +819,13 @@ class Bajo extends Plugin {
         if (!isEmpty(result)) orig = result
       }
       getParseOptsArgs(opts, orig)
-      const binder = merged ? merge : defaultsDeep
       for (const base of bases) {
         if (!this.app[base]) continue
         options.sourceNs = base
         const fileExt = `${this.app[base].dir.pkg}/extend/${baseNs}/extend/${ns}${suffix}/${_path}`
-        await this.runHook('bajo.extend:beforeReadConfig', fileExt, options)
+        await this.runHook('bajo.extend:beforeReadConfig', fileExt, orig, options)
         const result = parseObject(await this.readConfig(fileExt, { ...opts, extend: false, merge: false }))
-        await this.runHook('bajo.extend:afterReadConfig', fileExt, result, options)
+        await this.runHook('bajo.extend:afterReadConfig', fileExt, orig, result, options)
         if (isEmpty(result)) continue
         if (isArray(result)) ext = [...result, ...ext]
         else ext = binder({}, result, ext)
@@ -800,23 +842,24 @@ class Bajo extends Plugin {
     if (cache.name) result = await this.app.cache.load(cache.name, cache.ttlDur)
     if (result) return result
     await this.runHook('bajo:beforeReadConfig', file, options)
-    parserOpts.readFromFile = true
+    const readOpts = {
+      readFromFile: true,
+      throwNotFound: !ignoreError,
+      defValue,
+      parserOpts
+    }
     if (!ns) ns = this.ns
     file = resolvePath(this.app.getPluginFile(file))
     let ext = path.extname(file)
     const fname = path.dirname(file) + '/' + path.basename(file, ext)
     ext = ext.toLowerCase()
-    if (['.js', '.json'].includes(ext)) {
-      const item = find(this.app.configHandlers, { ext })
-      return await output(await item.readHandler.call(this.app[ns], file, parserOpts))
-    }
     if (!['', '.*'].includes(ext)) {
       const item = find(this.app.configHandlers, { ext })
       if (!item) {
         if (!ignoreError) throw this.error('cantParse%s', file, { code: 'BAJO_CONFIG_NO_PARSER' })
         return await output(defValue)
       }
-      return await output(await item.readHandler.call(this.app[item.ns], file, parserOpts))
+      return await output(await item.readHandler.call(this.app[item.ns], file, readOpts))
     }
     const formats = this.app.getConfigFormats(true)
     const item = pattern ?? `${fname}.{${formats.join(',')}}`
@@ -834,147 +877,174 @@ class Bajo extends Plugin {
         continue
       }
       const _ns = ['.js', '.json'].includes(ext) ? ns : item.ns
-      config = await item.readHandler.call(this.app[_ns], f, parserOpts)
+      config = await item.readHandler.call(this.app[_ns], f, readOpts)
       if (!isEmpty(config)) break
     }
     return await output(config)
   }
 
-  /**
-   * Read and parse json file.
-   *
-   * @method
-   * @param {string} file - File to read.
-   * @param {boolean} [thrownNotFound=false] - If `true`, silently ignore if file is not found.
-   * @returns {Object}
-   */
-  readJson = (file, thrownNotFound = false) => {
-    const { parseObject } = this.app.lib
-    if (isPlainObject(thrownNotFound)) thrownNotFound = false
-    if (!fs.existsSync(file) && thrownNotFound) throw this.error('notFound%s%s', this.t('file'), file)
-    let resp
-    try {
-      resp = fs.readFileSync(file, 'utf8')
-    } catch (err) {}
-    if (isEmpty(resp)) return resp
-    return parseObject(JSON.parse(resp))
-  }
-
   /**
    * Read and parse JavaScript file.
    *
    * @async
    * @method
-   * @param {string} file - File to read and parse.
-   * @param {Object} [options={}] - Options.
-   * @returns {Object} Parsed JavaScript object.
+   * @param {string} file - File to read and parse
+   * @param {boolean} [options.readFromFile=false] - Ignored for this method. Always read from file.
+   * @param {boolean} [options.throwNotFound=false] - If `true`, throw exception if file is not found
+   * @param {object} [options.defValue={}] - Default value to use if value returned empty
+   * @param {object} [options.parserOpts={}] - Options to be passed if file exports a function
+   * @returns {Object} Parsed JavaScript object
    */
   async fromJs (file, options = {}) {
-    const args = options.args ?? []
+    if (isBoolean(options)) options = {}
+    options.defValue = options.defValue ?? {}
+    if (options.throwNotFound && !fs.existsSync(file)) throw this.error('notFound%s%s', this.t('file'), file)
     let mod = await importModule(file)
-    if (isFunction(mod)) mod = await mod.call(this, ...args)
-    return mod
+    if (isFunction(mod)) mod = await mod.call(this, options.parserOpts)
+    return isEmpty(mod) ? options.defValue : mod
   }
 
   /**
-   * Read and parse JSON string or object.
+   * Parse JSON string or read and parse JSON file.
    *
-   * @param {string} data - Filename to load from or JSON string to parse.
-   * @param {Object} [options={}] - Options.
-   * @returns {Object} Parsed JSON object.
+   * @async
+   * @method
+   * @param {string} text - Text to be parsed or file path to be read if `options.readFromFile` is `true`
+   * @param {object|boolean} [options={}] - Options object. If a boolean is provided, it will be treated as `options.readFromFile`
+   * @param {boolean} [options.readFromFile=false] - If `true`, `text` is treated as a file path
+   * @param {boolean} [options.throwNotFound=false] - If `true`, throw exception if file is not found
+   * @param {object} [options.defValue={}] - Default value to use if value returned empty
+   * @param {object} [options.parserOpts={}] - Options to be passed to `JSON.parse()`
+   * @returns {Object} Parsed object.
+   * @see Bajo#toJson
    */
-  fromJson (data, options = {}) {
-    const content = options.readFromFile ? fs.readFileSync(data, 'utf8') : data
-    return JSON.parse(content)
+  async fromJson (text, options = {}) {
+    if (isBoolean(options)) options = { readFromFile: options }
+    options.defValue = options.defValue ?? {}
+    if (options.readFromFile && !fs.existsSync(text) && options.throwNotFound) throw this.error('notFound%s%s', this.t('file'), text)
+    const content = options.readFromFile ? fs.readFileSync(text, 'utf8') : text
+    const result = JSON.parse(content)
+    return isEmpty(result) ? options.defValue : result
   }
 
   /**
-   * Parse YAML text
+   * Parse YAML text or read and parse YAML file.
    *
+   * @async
    * @method
-   * @param {string} text - Text to be parsed
-   * @param {object} options - Options object
+   * @param {string} text - Text to be parsed or file path to be read if `options.readFromFile` is `true`
+   * @param {object|boolean} [options={}] - Options object. If a boolean is provided, it will be treated as `options.readFromFile`
+   * @param {boolean} [options.readFromFile=false] - If `true`, `text` is treated as a file path
+   * @param {boolean} [options.throwNotFound=false] - If `true`, throw exception if file is not found
+   * @param {object} [options.parserOpts={}] - Options to be passed to `YAML.load()`
+   * @param {object} [options.defValue={}] - Default value to use if value returned empty
    * @returns {object} Parsed object
+   * @see Bajo#toYaml
    */
-  fromYaml = (text, options = {}) => {
-    const { fs } = this.app.lib
+  async fromYaml (text, options = {}) {
+    if (isBoolean(options)) options = { readFromFile: options }
+    options.defValue = options.defValue ?? {}
+    if (options.readFromFile && !fs.existsSync(text) && options.throwNotFound) throw this.error('notFound%s%s', this.t('file'), text)
     const content = options.readFromFile ? fs.readFileSync(text, 'utf8') : text
-    return yaml.load(content)
+    const result = yaml.load(content)
+    return isEmpty(result) ? options.defValue : result
   }
 
   /**
-   * Parse YML text. Alias for fromYaml.
+   * Parse YML text or read and parse YML file. Alias for {@link Bajo#fromYaml}.
    *
+   * @async
    * @method
-   * @param {string} text - Text to be parsed
-   * @param {object} options - Options object
+   * @param {string} text - Text to be parsed or file path to be read if `options.readFromFile` is `true`
+   * @param {object|boolean} [options={}] - Options object. If a boolean is provided, it will be treated as `options.readFromFile`
+   * @param {boolean} [options.readFromFile=false] - If `true`, `text` is treated as a file path
+   * @param {boolean} [options.throwNotFound=false] - If `true`, throw exception if file is not found
+   * @param {object} [options.defValue={}] - Default value to use if value returned empty
+   * @param {object} [options.parserOpts={}] - Options to be passed to `YAML.load()`
    * @returns {object} Parsed object
+   * @see Bajo#toYml
    */
-  fromYml = (text, options = {}) => {
+  async fromYml (text, options = {}) {
     return this.fromYaml(text, options)
   }
 
   /**
-   * Convert data to JSON string.
+   * Convert data to JSON string, optionally write to file if `options.writeToFile` is provided.
    *
+   * @async
    * @method
-   * @param {Object} data - Data to convert to JSON string.
-   * @param {Object} [options={}] - Options.
-   * @param {boolean} [options.writeToFile=false] - If true, write the JSON string to a file.
-   * @param {string} [options.saveAsFile] - The file path to save the JSON string if writeToFile is true.
-   * @returns {string} JSON string
+   * @param {Object} data - Data to convert to JSON string
+   * @param {Object|string} [options={}] - Options object. If a string is provided, it will be treated as `options.writeToFile`
+   * @param {string} [options.writeToFile] - If not empty, write result to this file path instead of returning it as string
+   * @param {Object} [options.parserOpts={}] - Options for `JSON.stringify()`
+   * @returns {Promise<string|void>} JSON string or void if written to file
+   * @see Bajo#fromJson
    */
-  toJson = (data, options = {}) => {
-    const content = JSON.stringify(data, null, omit(options, ['writeToFile']))
-    if (options.writeToFile) {
-      fs.writeFileSync(options.saveAsFile, content, 'utf8')
+  async toJson (data, options = {}) {
+    if (isString(options)) options = { writeToFile: options }
+    options.parserOpts = options.parserOpts ?? {}
+    options.parserOpts.space = options.parserOpts.space ?? 2
+    const content = JSON.stringify(data, null, options.parserOpts)
+    if (isString(options.writeToFile)) {
+      fs.writeFileSync(options.writeToFile, content, 'utf8')
       return
     }
     return content
   }
 
   /**
-   * Convert object to YAML string
+   * Convert object to YAML string, optionally write to file if `options.writeToFile` is provided.
    *
+   * @async
    * @method
    * @param {object} object - Object to be converted
-   * @param {object} options - Options object
-   * @returns {string} YAML string
+   * @param {object|string} [options] - Options object. If a string is provided, it will be treated as `options.writeToFile`
+   * @param {string} [options.writeToFile] - If not empty, write result to this file path instead of returning it as string
+   * @param {Object} [options.parserOpts={}] - Options for `YAML.dump()`
+   * @returns {Promise<string|void>} YAML string or void if written to file
+   * @see Bajo#fromYaml
    */
-  toYaml = (object, options = {}) => {
-    const { omit } = this.app.lib._
-    const { fs } = this.app.lib
-    const content = yaml.dump(object, omit(options, ['writeToFile']))
+  async toYaml (object, options = {}) {
+    if (isString(options)) options = { writeToFile: options }
+    options.parserOpts = options.parserOpts ?? {}
+    const content = yaml.dump(object, options.parserOpts)
     if (options.writeToFile) {
-      fs.writeFileSync(options.saveAsFile, content, 'utf8')
-      return
+      if (isString(options.writeToFile)) {
+        fs.writeFileSync(options.writeToFile, content, 'utf8')
+        return
+      }
     }
     return content
   }
 
   /**
-   * Convert object to YML string. Alias for toYaml.
-   *
+   * Convert object to YML string, optionally write to file if `options.writeToFile` is provided. Alias for {@link Bajo#toYaml}.
+   * @async
    * @method
    * @param {object} object - Object to be converted
-   * @param {object} options - Options object
-   * @returns {string} YML string
+   * @param {object|string} [options] - Options object. If a string is provided, it will be treated as `options.writeToFile`
+   * @param {string} [options.writeToFile] - If not empty, write result to this file path instead of returning it as string
+   * @param {Object} [options.parserOpts={}] - Options for `YAML.dump()`
+   * @returns {Promise<string|void>} YAML string or void if written to file
+   * @see Bajo#fromYml
    */
-  toYml = (object, options = {}) => {
+  async toYml (object, options = {}) {
     return this.toYaml(object, options)
   }
 
   /**
-   * Read all config files from path.
+   * Read all forms of configuration files from file path.
+   *
+   * Internally, it will call {@link Bajo#readConfig} twice, first for the default config file and
+   * second for the environment based config file. Then it will merge both results using `defaultsDeep`.
    *
    * @method
    * @async
    * @param {string} path - Base path to start looking config files.
-   * @param {Object} [options={}] - Options.
+   * @param {Object} [options={}] - Options. See {@link Bajo#readConfig} for more.
    * @returns {Object} Merged configuration object.
    */
   readAllConfigs = async (path, options) => {
-    const { defaultsDeep } = this.app.lib.aneka
     let cfg = {}
     let ext = {}
     // default config file
@@ -993,7 +1063,14 @@ class Bajo extends Plugin {
   }
 
   /**
-   * Run named hook/event.
+   * Run named {@link module:Hook}.
+   *
+   * If no hook found with the given name, it will return an empty array.
+   * If a hook has `noWait` set to `true`, it will not wait for the hook to finish and will not return its result.
+   *
+   * > **Note**: Even though this method returns a result, it is not recommended to use the result for any purpose.
+   * Use the result only for debugging or logging purposes. Hooks are designed to be fast, lightweight and mutate
+   * arguments given to them so that the next hook can benefit from the changes.
    *
    * @method
    * @async
@@ -1023,6 +1100,7 @@ class Bajo extends Plugin {
 
   /**
    * Get download directory. If doesn't exist, it will be created automatically.
+   *
    * @method
    * @returns {string} Absolute path to the download directory
    */
@@ -1047,25 +1125,27 @@ class Bajo extends Plugin {
    * @returns {string} Full file path.
    */
   saveAsDownload = async (file, item, printSaved = true) => {
-    const { print } = this.app.bajo
     const fname = increment(`${this.getDownloadDir()}/${trim(file, '/')}`, { fs: true })
     await fs.writeFile(fname, item, 'utf8')
-    if (printSaved) print.succeed('savedAs%s', path.resolve(fname), { skipSilence: true })
+    if (printSaved) this.print.succeed('savedAs%s', path.resolve(fname), { skipSilence: true })
     return fname
   }
 
   /**
-   * Read config using all registered config handlers. The first handler that returns a
+   * Parse `input` using all registered config handlers. The first handler that returns a
    * valid object or array will be used.
    *
+   * Use this method if you want to parse a text `input` that can be in any format supported by the registered config handlers.
+   *
    * @method
    * @param {string} input - The input string to be processed by the config handlers.
    * @param {string[]} [exts] - Optional array of extensions to filter the config handlers. If provided, only handlers with matching extensions will be used.
    * @param {object} [options={}] - Options to be passed to the config handlers.
    * @returns {Object|Array|null} The result from the first successful config handler, or null if none succeed.
    */
-  readAsConfig = async (input, exts, options = {}) => {
+  parseWithConfig = async (input, exts, options = {}) => {
     let result
+    options.readFromFile = false
     const handlers = exts ? this.app.configHandlers.filter(h => exts.includes(h.ext)) : this.app.configHandlers
     for (const handler of handlers) {
       if (result) break