bajo 1.2.8 → 2.0.0

package/{boot/class/bajo-core.js → class/bajo.js}

@@ -1,5 +1,5 @@
 import Plugin from './plugin.js'
-import BajoPlugin from './bajo-plugin.js'
+import BasePlugin from './base/plugin.js'
 import increment from 'add-filename-increment'
 import fs from 'fs-extra'
 import path from 'path'
@@ -29,22 +29,69 @@ const {
   last, get, has, values, dropRight, pick
 } = lodash
 
-class BajoCore extends Plugin {
+/**
+ * The Core. The main engine. The one and only plugin that control app's boot process and
+ * making sure all other plugins working smoothly.
+ *
+ * @class
+ */
+class Bajo extends BasePlugin {
+  /**
+   * @param {Object} app
+   * @param {Object} app - App instance reference. Usefull to call app method inside a plugin
+   */
   constructor (app) {
     super('bajo', app)
+    /**
+     * Date/time when your app start
+     * @type {Date}
+     */
     this.runAt = new Date()
+
+    /**
+     * Your main namespace. And yes, you suppose NOT to change this
+     *
+     * @type {string}
+     */
     this.mainNs = 'main'
-    this.lib.BajoPlugin = BajoPlugin
+
+    /**
+     * Storage for applets
+     *
+     * @type {Array}
+     */
     this.applets = []
+
+    /**
+     * List of all loaded plugin's package names
+     *
+     * @type {Array}
+     */
     this.pluginPkgs = []
+
+    /**
+     * List of all loaded plugin's names
+     *
+     * @type {Array}
+     */
     this.pluginNames = []
+
+    /**
+     * Storage for config handlers. By default there are only two handlers available: ```.js```
+     * and ```.json```.
+     *
+     * Use plugin to add more type - e.g: {@link https://github.com/ardhi/bajo-config|bajo-config}
+     * lets you to use ```.yaml``` and ```.toml```
+     *
+     * @type {Array}
+     */
     this.configHandlers = [
       { ext: '.js', readHandler: this._defConfigHandler },
       { ext: '.json', readHandler: this.readJson }
     ]
     this.whiteSpace = [' ', '\t', '\n', '\r']
-    this.logLevels = logLevels
     this.envs = { dev: 'development', staging: 'staging', prod: 'production' }
+    this.lib.Plugin = Plugin
   }
 
   async _defConfigHandler (file, opts = {}) {
@@ -53,13 +100,29 @@ class BajoCore extends Plugin {
     return mod
   }
 
-  resolvePath = (item, asFileUrl) => {
-    return resolvePath(item, asFileUrl)
+  /**
+   * Resolve file name to filesystem's path. Windows path separator ```\```
+   * is normalized to Unix's ```/```
+   *
+   * @method
+   * @param {string} file - File to resolve
+   * @param {boolean} [asFileUrl=false] - Return as file URL format ```file:///<name>```
+   * @returns {string}
+   */
+  resolvePath = (file, asFileUrl) => {
+    return resolvePath(file, asFileUrl)
   }
 
-  freeze = (o, shallow) => {
-    if (shallow) Object.freeze(o)
-    else deepFreeze(o)
+  /**
+   * Freeze object
+   *
+   * @method
+   * @param {Object} obj - Object
+   * @param {boolean} [shallow=false] - If true (default), deep freeze object
+   */
+  freeze = (obj, shallow) => {
+    if (shallow) Object.freeze(obj)
+    else deepFreeze(obj)
   }
 
   setImmediate = async () => {
@@ -94,14 +157,33 @@ class BajoCore extends Plugin {
     return `${ns}:${path}`
   }
 
-  breakNsPath = (item = '', defaultNs = 'bajo', checkNs = true) => {
-    let [ns, ...path] = item.split(':')
+  /**
+   * Object returned by {@link BajoCore#breakNsPath|breakNsPath}
+   *
+   * @typedef {Object} NsPathType
+   * @property {string} ns - Namespace
+   * @property {string} [subNs] - Sub namespace
+   * @property {string} [subSubNs] - Sub of sub namespace
+   * @property {string} path - Path without query string or hash
+   * @property {string} fullPath - Full path, including query string and hash
+   */
+
+  /**
+   * Break name to its namespace & path infos
+   *
+   * @method
+   * @param {string} name - Name to break
+   * @param {boolean} [checkNs=true] - If true (default), namespace will be checked for its validity
+   * @returns {NsPathType}
+   */
+  breakNsPath = (name = '', checkNs = true) => {
+    let [ns, ...path] = name.split(':')
     const fullNs = ns
     let subNs
     let subSubNs
     path = path.join(':')
     if (path.startsWith('//')) {
-      return { path: item } // for: http:// etc
+      return { path: name } // for: http:// etc
     }
 
     [ns, subNs, subSubNs] = ns.split('.')
@@ -139,6 +221,23 @@ class BajoCore extends Plugin {
     return { ns, path, subNs, subSubNs, qs, fullPath, fullNs, realPath, realFullPath }
   }
 
+  /**
+   * Method to transform an array or object from config into an array of collection safely.
+   *
+   * Emitted hooks:
+   * 1. ```{ns}:beforeBuildCollection (container)``` - called before collection is built
+   * 2. ```{ns}:afterBuildCollection (container, items)``` - called after collection is built
+   *
+   * @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 {Array} [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```
+   * @returns {Array} The collection
+   */
   buildCollections = async (options = {}) => {
     let { ns, handler, dupChecks = [], container, useDefaultName } = options
     useDefaultName = useDefaultName ?? true
@@ -173,15 +272,28 @@ class BajoCore extends Plugin {
         if (checkers.includes(checker)) this.app[ns].fatal('oneOrMoreSharedTheSame%s%s', container, this.join(dupChecks.filter(i => !isFunction(i))))
       }
     }
-    await this.runHook(`${ns}:${camelCase('afterBuildCollection')}`, container)
+    await this.runHook(`${ns}:${camelCase('afterBuildCollection')}`, container, items)
     this.app[ns].log.debug('collected%s%d', this.app[ns].print.write(container), items.length)
     return items
   }
 
+  /**
+   * Calling any plugin's method by its name. Name format: ```ns:methodName```.
+   * - 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
+   * - If name is an object and has ```handler``` key in it, this function handler will be instead
+   *
+   * @method
+   * @async
+   * @param {(string|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
+   */
   callHandler = async (item, ...args) => {
     let result
     let scope = this
-    if (item instanceof BajoPlugin) {
+    if (item instanceof Plugin) {
       scope = item
       item = args.shift()
     }
@@ -201,12 +313,30 @@ class BajoCore extends Plugin {
       }
     } else if (isFunction(item)) {
       result = await item.call(scope, ...args)
-    } else if (isPlainObject(item) && item.handler) {
+    } else if (isPlainObject(item) && isFunction(item.handler)) {
       result = await item.handler.call(scope, ...args)
     }
     return result
   }
 
+  /**
+   * This function iterates through all loaded plugins and call the provided handler scoped as the running plugin.
+   * And an object with the following key serves as its parameter:
+   *
+   * - ```file```: file matched the glob pattern
+   * - ```dir```: plugin's base directory
+   *
+   * @method
+   * @async
+   * @param {function} handler - Function handler. Can be an async function. Scoped to the running plugin
+   * @param {(string|Object)} [options={}] - Options. If a string is provided, it serves as the glob pattern, otherwise:
+   * @param {(string|Array)} [options.glob] - Glob pattern. If provided,
+   * @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}
+   */
   eachPlugins = async (handler, options = {}) => {
     if (typeof options === 'string') options = { glob: options }
     const result = {}
@@ -215,11 +345,9 @@ class BajoCore extends Plugin {
     if (useBajo) pluginPkgs.unshift('bajo')
     for (const pkgName of pluginPkgs) {
       const ns = camelCase(pkgName)
-      const config = this.app[ns].config
-      const alias = this.app[ns].alias
       let r
       if (glob) {
-        const base = prefix === '' ? this.app[ns].dir.pkg : `${this.app[ns].dir.pkg}/${prefix}`
+        const base = prefix === '' ? `${this.app[ns].dir.pkg}/extend` : `${this.app[ns].dir.pkg}/extend/${prefix}`
         let opts = isString(glob) ? { pattern: [glob] } : glob
         let pattern = opts.pattern ?? []
         if (isString(pattern)) pattern = [pattern]
@@ -230,7 +358,7 @@ class BajoCore extends Plugin {
         const files = await fastGlob(pattern, opts)
         for (const f of files) {
           if (path.basename(f)[0] === '_' && noUnderscore) continue
-          const resp = await handler.call(this.app[ns], { ns, pkgName, config, alias, file: f, dir: base })
+          const resp = await handler.call(this.app[ns], { file: f, dir: base })
           if (resp === false) break
           else if (resp === undefined) continue
           else {
@@ -239,7 +367,7 @@ class BajoCore extends Plugin {
           }
         }
       } else {
-        r = await handler.call(this.app[ns], { ns, pkgName, config, dir: this.app[ns].dir.pkg, alias })
+        r = await handler.call(this.app[ns], { dir: this.app[ns].dir.pkg })
         if (r === false) break
         else if (r === undefined) continue
         else result[ns] = r
@@ -257,6 +385,23 @@ class BajoCore extends Plugin {
     return result
   }
 
+  /**
+   * Object returned by {@link BajoCore#getUnitFormat|getUnitFormat}
+   *
+   * @typedef {Object} ObjectFormatType
+   * @property {string} unitSys - Unit system
+   * @property {Object} format - Format object
+   */
+
+  /**
+   * Get unit format
+   *
+   * @method
+   * @param {Object} [options={}] - Options
+   * @param {string} [options.lang] - Language to use. Defaults to the one you set in config
+   * @param {string} [options.unitSys] - Unit system to use. Defaults to language's unit system or ```metric``` if unspecified
+   * @returns {ObjectFormatType} - Returned value
+   */
   getUnitFormat = (options = {}) => {
     const lang = options.lang ?? this.config.lang
     let unitSys = options.unitSys ?? this.config.intl.unitSys[lang] ?? 'metric'
@@ -264,6 +409,18 @@ class BajoCore extends Plugin {
     return { unitSys, format: formats[unitSys] }
   }
 
+  /**
+   * Format value by type
+   *
+   * @method
+   * @param {string} type - Format type. See {@link FormatType} for acceptable values
+   * @param {any} value - Value to format
+   * @param {string} [dataType] - Value's data type. See {@link DataType} for acceptable values
+   * @param {Object} [options={}] - Options
+   * @param {boolean} [options.withUnit=true] - Return with its unit appended
+   * @param {string} [options.lang] - Format value according to this language. Defaults to the one you set in config
+   * @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.lib.aneka
     const { format } = this.getUnitFormat(options)
@@ -278,6 +435,20 @@ class BajoCore extends Plugin {
     return `${value}${sep}${unit}`
   }
 
+  /**
+   * Format value
+   *
+   * @method
+   * @param {any} value - Value to format
+   * @param {string} [type] - Data type to use. See {@link DataType} 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
+   * @param {boolean} [options.withUnit=true] - Return with its unit appended
+   * @param {string} [options.lang] - Format value according to this language. Defaults to the one you set in config
+   * @param {string} [options.latitude] - If Bajo Spatial is loaded and data type is a double or float, then format it as latitude in degree, minute, second
+   * @param {string} [options.longitude] - If Bajo Spatial is loaded and data type is a double or float, then format it as longitude in degree, minute, second
+   * @returns {string} Formatted value
+   */
   format = (value, type, options = {}) => {
     const { defaultsDeep } = this.lib.aneka
     const { format } = this.config.intl
@@ -324,6 +495,17 @@ class BajoCore extends Plugin {
     return value
   }
 
+  /**
+   * Generate unique random characters that can be used as ID. Use {@link https://github.com/ai/nanoid|nanoid} under the hood
+   *
+   * @method
+   * @param {(boolean|string|Object)} [options={}] - Options. If set to ```true``` or ```alpha```, it will generate alphaphet only characters. If set to ```int```, it will generate integer only characters. Otherwise:
+   * @param {string} [options.pattern] - Character pattern to use. Defaults to all available alphanumeric characters
+   * @param {number} [options.length=13] - Length of resulted characters
+   * @param {string} [options.case] - If set to ```lower``` to use lower cased pattern only. For upper cased pattern, set it to ```upper```
+   * @param {boolean} [options.returnInstance] - Set to ```true``` to return {@link https://github.com/ai/nanoid|nanoid} instance instead of string
+   * @returns {(string|Object)} Return string or instance of {@link https://github.com/ai/nanoid|nanoid}
+   */
   generateId = (options = {}) => {
     let type
     if (options === true) options = 'alpha'
@@ -344,6 +526,14 @@ class BajoCore extends Plugin {
     return type === 'int' ? parseInt(value) : value
   }
 
+  /**
+   * Get NPM global module directory
+   *
+   * @method
+   * @param {string} [pkgName] - If provided, return this package global directory. Otherwise the npm global module directory
+   * @param {boolean} [silent=true] - Set to ```false``` to throw exception in case of error. Otherwise silently returns undefined
+   * @returns {string}
+   */
   getGlobalModuleDir = (pkgName, silent = true) => {
     let nodeModulesDir = process.env.BAJO_GLOBAL_MODULE_DIR
     if (!nodeModulesDir) {
@@ -364,6 +554,14 @@ class BajoCore extends Plugin {
     return dir
   }
 
+  /**
+   * Get class method by name
+   *
+   * @method
+   * @param {string} name - Name in format ```ns:methodName```
+   * @param {boolean} [thrown=true] - If ```true``` (default), throw exceptiom in case of error
+   * @returns {function} Class method
+   */
   getMethod = (name = '', thrown = true) => {
     const { ns, path } = this.breakNsPath(name)
     const method = get(this.app, `${ns}.${path}`)
@@ -371,6 +569,14 @@ class BajoCore extends Plugin {
     if (thrown) throw this.error('cantFindMethod%s', name)
   }
 
+  /**
+   * Find item deep in paths
+   *
+   * @method
+   * @param {string} item - Item to find
+   * @param {Array} paths - Array of path to look for
+   * @returns {string}
+   */
   findDeep = (item, paths) => {
     let dir
     for (const p of paths) {
@@ -383,6 +589,14 @@ class BajoCore extends Plugin {
     return dir
   }
 
+  /**
+   * Get module directory, locally and globally
+   *
+   * @method
+   * @param {string} pkgName - Package name to find
+   * @param {*} base - Provide base name if ```pkgName``` is a module under ```base```'s package name
+   * @returns {string} Return absolute package directory
+   */
   getModuleDir = (pkgName, base) => {
     if (pkgName === 'main') return resolvePath(this.app.dir)
     if (base === 'main') base = this.app.dir
@@ -398,6 +612,14 @@ class BajoCore extends Plugin {
     return resolvePath(path.dirname(dir))
   }
 
+  /**
+   * Get plugin data directory
+   *
+   * @method
+   * @param {string} name - Plugin name (namespace) or alias
+   * @param {boolean} [ensureDir=true] - Set ```true``` (default) to ensure directory is existed
+   * @returns {string}
+   */
   getPluginDataDir = (name, ensureDir = true) => {
     const plugin = this.getPlugin(name)
     const dir = `${this.app.bajo.dir.data}/plugins/${plugin.name}`
@@ -405,6 +627,16 @@ class BajoCore extends Plugin {
     return dir
   }
 
+  /**
+   * Resolve file path from:
+   *
+   * - local/absolute file
+   * - ns based path (```myPlugin:/path/to/file.txt```)
+   *
+   * @method
+   * @param {string} file - File path, see above for supported types
+   * @returns {string} Resolved file path
+   */
   getPluginFile = (file) => {
     if (!this) return file
     if (file[0] === '.') file = `${currentLoc(import.meta).dir}/${trim(file.slice(1), '/')}`
@@ -418,13 +650,21 @@ class BajoCore extends Plugin {
     return file
   }
 
+  /**
+   * Get plugin by name
+   *
+   * @method
+   * @param {string} name - Plugin name/namespace or alias
+   * @param {boolean} [silent] - If ```true```, silently return undefined even on error
+   * @returns {Object} Plugin object
+   */
   getPlugin = (name, silent) => {
     if (!this.app[name]) {
       // alias?
       let plugin
       for (const key in this.app) {
         const item = this.app[key]
-        if (item instanceof BajoPlugin && (item.alias === name || item.pkgName === name)) {
+        if (item instanceof Plugin && (item.alias === name || item.pkgName === name)) {
           plugin = item
           break
         }
@@ -438,10 +678,54 @@ class BajoCore extends Plugin {
     return this.app[name]
   }
 
+  /**
+   * Import file/module from any loaded plugins
+   *
+   * Your plugin structure:
+   * ```
+   * |- src
+   * |  |- lib
+   * |  |  |- my-module.js
+   * |- index.js
+   * |- package.json
+   * ```
+   *
+   * Inside your app/plugin:
+   * ```javascript
+   * const { importModule } = this.app.bajo
+   * const myModule = await importModule('myPlugin:/src/lib/my-module.js')
+   * ```
+   * @method
+   * @async
+   * @param {string} file - File in format ```ns:<ns based file path>```
+   * @param {Object} [options={}] - Options
+   * @param {boolean} [options.asDefaultImport=true] - If ```true``` (default), return default imported module
+   * @param {boolean} [options.asHandler] - If ```true```, return as a {@link HandlerType|handler}
+   * @param {boolean} [options.noCache] - If ```true```, always import as a fresh copy
+   * @returns {(function|Object)}
+   */
   importModule = async (file, { asDefaultImport, asHandler, noCache } = {}) => {
     return await importModule.call(this, file, { asDefaultImport, asHandler, noCache })
   }
 
+  /**
+   * Import one or more package belongs to a plugin
+   *
+   * Example: you want to import packages ```delay``` and ```chalk``` from ```bajo``` namespace and use it inside your app/plugin
+   *
+   * ```javascript
+   * const { importPkg } from this.app.bajo
+   * const [delay, chalk] = await importPkg('bajo:delay', 'bajo:chalk')
+   *
+   * await delay(1000)
+   * ...
+   * ```
+   *
+   * @method
+   * @async
+   * @param {...any} pkgs - One or more packages in format ```ns:packageName```
+   * @returns {(Object|Array)} Depends on how many parameters are provided, it should return the named package or an array of packages
+   */
   importPkg = async (...pkgs) => {
     const { defaultsDeep } = this.lib.aneka
     const result = {}
@@ -450,7 +734,8 @@ class BajoCore extends Plugin {
     if (isPlainObject(last(pkgs))) {
       opts = defaultsDeep(pkgs.pop(), opts)
     }
-    for (const pkg of pkgs) {
+    for (let pkg of pkgs) {
+      if (pkg.indexOf(':') === -1) pkg = `bajo:${pkg}`
       const { ns, path: name } = this.breakNsPath(pkg)
       const dir = this.getModuleDir(name, ns)
       if (!dir) {
@@ -478,13 +763,30 @@ class BajoCore extends Plugin {
     return values(result)
   }
 
-  isEmptyDir = async (dir) => {
+  /**
+   * Check whether directory is empty or not. More info please {@link https://github.com/gulpjs/empty-dir|check here}.
+   *
+   * @method
+   * @async
+   * @param {string} dir - Directory to check. Can be a ns based directory too!
+   * @param {function} filterFn - Filter function to filter out files that cause false positives.
+   * @returns {boolean}
+   */
+  isEmptyDir = async (dir, filterFn) => {
+    dir = resolvePath(this.getPluginFile(dir))
     await fs.exists(dir)
-    return await emptyDir(dir)
+    return await emptyDir(dir, filterFn)
   }
 
+  /**
+   * Check whether log level is within log's app current level
+   *
+   * @method
+   * @param {string} level - Level to check. See {@link LogLevelsType} for more
+   * @returns {boolean}
+   */
   isLogInRange = (level) => {
-    const levels = keys(this.logLevels)
+    const levels = keys(logLevels)
     const logLevel = indexOf(levels, this.app.bajo.config.log.level)
     return indexOf(levels, level) >= logLevel
   }
@@ -503,11 +805,27 @@ class BajoCore extends Plugin {
     }
   }
 
+  /**
+   * Check whether directory is a valid Bajo app
+   *
+   * @method
+   * @param {string} dir - Directory to check
+   * @param {boolean} [returnPkg] - Set ```true``` to return its package.json content
+   * @returns {(boolean|Object)}
+   */
   isValidApp = (dir, returnPkg) => {
     if (!dir) dir = this.app.dir
     return this.isValidAppPlugin(dir, 'app', returnPkg)
   }
 
+  /**
+   * Check whether directory is a valid Bajo plugin
+   *
+   * @method
+   * @param {string} dir - Directory to check
+   * @param {boolean} [returnPkg] - Set ```true``` to return its package.json content
+   * @returns {(boolean|Object)}
+   */
   isValidPlugin = (dir, returnPkg) => {
     if (!dir) dir = this.app.dir
     return this.isValidAppPlugin(dir, 'plugin', returnPkg)
@@ -528,22 +846,59 @@ class BajoCore extends Plugin {
     return array.map(a => (a + '').trim()).join(separator) + ` ${joiner} ${last}`
   }
 
+  /**
+   * Return its numeric portion of a value
+   *
+   * @method
+   * @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 = '') => {
     const num = value.match(/\d+/g)
     const unit = value.match(/[a-zA-Z]+/g)
     return `${num[0]}${isEmpty(unit) ? defUnit : unit[0]}`
   }
 
-  parseDur = (val) => {
-    return isNumber(val) ? val : ms(val)
+  /**
+   * Parse duration to its millisecond value. Use {@link https://github.com/vercel/ms|ms} under the hood
+   *
+   * @method
+   * @param {(number|string)} dur - If string is given, parse this to its millisecond value. Otherwise return as is
+   * @returns {number}
+   */
+  parseDur = (dur) => {
+    return isNumber(dur) ? dur : ms(dur)
   }
 
-  parseDt = (val) => {
-    const dt = this.lib.dayjs(val)
-    if (!dt.isValid()) throw this.error('dtUnparsable%s', val)
-    return dt.toDate()
+  /**
+   * Parse datetime string as Javascript object. Please visit {@link https://day.js.org|dayjs} for valid formats and more infos
+   *
+   * @method
+   * @param {string} dt - Datetime string
+   * @returns {Object} Javascript object
+   */
+  parseDt = (dt) => {
+    const value = this.lib.dayjs(dt)
+    if (!value.isValid()) throw this.error('dtUnparsable%s', dt)
+    return value.toDate()
   }
 
+  /**
+   * Parse an object and optionally normalize its values recursively. Use {@link https://github.com/ladjs/dotenv-parse-variables}
+   * to parse values, so please have a visit to know how it works
+   *
+   * If ```options.parseValue``` is ```true```, any key ends with ```Dur``` and ```Dt``` will
+   * also be parsed as millisecond and Javascript datetime accordingly
+   *
+   * @method
+   * @param {(Object|string)} input - If string is given, parse it first using JSON.parse
+   * @param {Object} [options={}] - Options
+   * @param {boolean} [options.silent=true] - If ```true``` (default), exception are not thrown and silently ignored
+   * @param {boolean} [options.parseValue=false] - If ```true```, values will be parsed & normalized
+   * @param {string} [options.lang] - If provided, use this language instead of the one in config
+   * @returns {Object}
+   */
   parseObject = (input, options = {}) => {
     const { silent = true, parseValue = false, lang, ns } = options
     const { isSet } = this.lib.aneka
@@ -553,6 +908,14 @@ class BajoCore extends Plugin {
       return scope.print.write(text, ...args, { lang })
     }
     const statics = ['*']
+    if (isString(input)) {
+      try {
+        input = JSON.parse(input)
+      } catch (err) {
+        if (silent) input = {}
+        else throw err
+      }
+    }
     let obj = cloneDeep(input)
     const keys = Object.keys(obj)
     const mutated = []
@@ -602,13 +965,31 @@ class BajoCore extends Plugin {
     return result
   }
 
+  /**
+   * Read and parse file as config object. Supported types: ```.js``` and ```.json```.
+   * 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
+   *
+   * 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.globOptions={}] - {@link https://github.com/mrmlnc/fast-glob|fast-glob} options
+   * @param {Object} [options.defValue={}] - Default value to use if value returned empty
+   * @param {Object} [options.opts={}] - Parser setting
+   * @returns {Object}
+   */
   readConfig = async (file, { ns, pattern, globOptions = {}, ignoreError, defValue = {}, opts = {} } = {}) => {
     if (!ns) ns = this.name
     file = resolvePath(this.getPluginFile(file))
     let ext = path.extname(file)
     const fname = path.dirname(file) + '/' + path.basename(file, ext)
     ext = ext.toLowerCase()
-    if (['.mjs', '.js'].includes(ext)) {
+    if (ext === '.js') {
       const { readHandler } = find(this.app.bajo.configHandlers, { ext })
       return this.parseObject(await readHandler.call(this.app[ns], file, opts))
     }
@@ -641,6 +1022,14 @@ class BajoCore extends Plugin {
     return this.parseObject(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) => {
     if (isPlainObject(thrownNotFound)) thrownNotFound = false
     if (!fs.existsSync(file) && thrownNotFound) throw this.error('notFound%s%s', this.print.write('file'), file)
@@ -652,10 +1041,19 @@ class BajoCore extends Plugin {
     return this.parseObject(JSON.parse(resp))
   }
 
+  /**
+   * Run named hook
+   *
+   * @method
+   * @async
+   * @param {string} hookName - ns based hook name
+   * @param  {...any} [args] - Argument passed to the hook function
+   * @returns {Array} Array of hook execution results
+   */
   runHook = async (hookName, ...args) => {
     const [ns, path] = (hookName ?? '').split(':')
     let fns = filter(this.app.bajo.hooks, { ns, path })
-    if (isEmpty(fns)) return
+    if (isEmpty(fns)) return []
     fns = orderBy(fns, ['level'])
     const results = []
     for (const i in fns) {
@@ -671,15 +1069,29 @@ class BajoCore extends Plugin {
     return results
   }
 
-  saveAsDownload = async (file, obj, printSaved = true) => {
+  /**
+   * Save item as file in Bajo's download directory. That is a directory inside your
+   * Bajo plugin's data directory.
+   *
+   * If file exists already, file will automatically be
+   * renamed incrementally.
+   *
+   * @method
+   * @async
+   * @param {string} file - File name
+   * @param {Object} item - Item to save
+   * @param {boolean} [printSaved=true] - Print info on screen
+   * @returns {string} Full file path
+   */
+  saveAsDownload = async (file, item, printSaved = true) => {
     const { print, getPluginDataDir } = this.app.bajo
-    const fname = increment(`${getPluginDataDir(this.name)}/${trim(file, '/')}`, { fs: true })
+    const fname = increment(`${getPluginDataDir(this.name)}/download/${trim(file, '/')}`, { fs: true })
     const dir = path.dirname(fname)
     if (!fs.existsSync(dir)) fs.ensureDirSync(dir)
-    await fs.writeFile(fname, obj, 'utf8')
+    await fs.writeFile(fname, item, 'utf8')
     if (printSaved) print.succeed('savedAs%s', path.resolve(fname), { skipSilence: true })
     return fname
   }
 }
 
-export default BajoCore
+export default Bajo