bajo 2.17.0 → 2.19.0

package/class/_helper.js

@@ -140,13 +140,13 @@ dayjs.extend(weekOfYear)
 
 /**
  * @typedef {Object} TAppLib
- * @property {Object} _ - Access to {@link https://lodash.com|lodash}
- * @property {Object} fs - Access to {@link https://github.com/jprichardson/node-fs-extra|fs-extra}
- * @property {Object} fastGlob - Access to {@link https://github.com/mrmlnc/fast-glob|fast-glob}
- * @property {Object} sprintf - Access to {@link https://github.com/alexei/sprintf.js|sprintf}
- * @property {Object} aneka - Access to {@link https://github.com/ardhi/aneka|aneka}
- * @property {Object} outmatch - Access to {@link https://github.com/axtgr/outmatch|outmatch}
- * @property {Object} dayjs - Access to {@link https://day.js.org|dayjs} with utc & customParseFormat plugin already applied
+ * @property {Object} _ Access to {@link https://lodash.com|lodash}.
+ * @property {Object} fs Access to {@link https://github.com/jprichardson/node-fs-extra|fs-extra}.
+ * @property {Object} fastGlob Access to {@link https://github.com/mrmlnc/fast-glob|fast-glob}.
+ * @property {Object} sprintf Access to {@link https://github.com/alexei/sprintf.js|sprintf}.
+ * @property {Object} aneka Access to {@link https://github.com/ardhi/aneka|aneka}.
+ * @property {Object} outmatch Access to {@link https://github.com/axtgr/outmatch|outmatch}.
+ * @property {Object} dayjs Access to {@link https://day.js.org|dayjs} with utc & customParseFormat plugin already applied.
  * @property {Object} freeze
  * @property {Object} findDeep
  * @see App
@@ -173,6 +173,8 @@ export const lib = {
  * - read the list of plugins from ```.plugins``` file
  *
  * @async
+ * @method
+ * @memberof module:Helper
  */
 export async function buildBaseConfig () {
   // dirs
@@ -214,6 +216,7 @@ export async function buildBaseConfig () {
  * - attach these plugins to the app instance
  *
  * @async
+ * @memberof module:Helper
  */
 export async function buildPlugins () {
   const { resolvePath } = this.app.lib.aneka
@@ -247,6 +250,7 @@ export async function buildPlugins () {
  * Collect all config handlers, including the one provided by plugins
  *
  * @async
+ * @memberof module:Helper
  */
 export async function collectConfigHandlers () {
   for (const pkg of this.app.pluginPkgs) {
@@ -271,6 +275,7 @@ export async function collectConfigHandlers () {
  * - Set environment (```dev``` or ```prod```)
  *
  * @async
+ * @memberof module:Helper
  */
 export async function buildExtConfig () {
   // config merging
@@ -321,6 +326,7 @@ export async function buildExtConfig () {
  * Setup plugins boot orders by reading plugin's ```.bootorder``` file if provided.
  *
  * @async
+ * @memberof module:Helper
  */
 export async function bootOrder () {
   const { freeze } = this.app.lib
@@ -349,6 +355,7 @@ export async function bootOrder () {
  * Build configurations
  *
  * @async
+ * @memberof module:Helper
  */
 export async function buildConfigs () {
   this.bajo.log.debug('readConfigs')
@@ -363,6 +370,7 @@ export async function buildConfigs () {
  * Ensure for names and aliases to be unique and no clashes with other plugins
  *
  * @async
+ * @memberof module:Helper
  */
 export async function checkNameAliases () {
   this.bajo.log.debug('checkAliasNameClash')
@@ -382,6 +390,7 @@ export async function checkNameAliases () {
  * Ensure dependencies are met
  *
  * @async
+ * @memberof module:Helper
  */
 export async function checkDependencies () {
   const { join } = this.bajo
@@ -417,6 +426,7 @@ export async function checkDependencies () {
  * Collect and build hooks and push them to the bajo's hook system
  *
  * @async
+ * @memberof module:Helper
  * @fires bajo:afterCollectHooks
  */
 export async function collectHooks () {
@@ -482,6 +492,7 @@ export async function collectHooks () {
  * @fires {ns}:before{method}
  * @fires {ns}:after{method}
  * @fires bajo:afterAll{method}
+ * @memberof module:Helper
  */
 export async function run () {
   const me = this
@@ -552,6 +563,7 @@ export async function run () {
  * 5. {@link module:Helper/Base.run|run plugins}
  *
  * @async
+ * @memberof module:Helper
  */
 export async function bootPlugins () {
   await buildConfigs.call(this.app)
@@ -565,6 +577,7 @@ export async function bootPlugins () {
  * Attach plugins exit handlers and make sure the app shutdowns gracefully
  *
  * @async
+ * @memberof module:Helper
  */
 export async function exitHandler () {
   if (!this.config.exitHandler) return
@@ -629,6 +642,7 @@ export async function exitHandler () {
  * @async
  * @fires {ns}:beforeAppletRun
  * @fires {ns}:afterAppletRun
+ * @memberof module:Helper
  */
 export async function runAsApplet () {
   const { isString, map, find } = this.app.lib._
@@ -671,6 +685,7 @@ export async function runAsApplet () {
    * @param {...any} params
    * @see {@tutorial hook}
    * @see module:Helper/Bajo.runAsApplet
+   * @memberof module:Helper
    */
   await this.runHook(`${applet.ns}:afterAppletRun`, ...this.app.args)
 }

package/class/app.js

@@ -3,6 +3,7 @@ import Bajo from './bajo.js'
 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 { fileURLToPath } from 'url'
 
@@ -43,21 +44,21 @@ 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
+   * @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 (options = {}) {
     /**
-     * Copy of provided options
+     * Copy of provided options.
      *
      * @type {Object}
      */
     this.options = options
 
     /**
-     * Your main namespace. And yes, you suppose to NOT CHANGE this
+     * Your main namespace. And yes, you suppose to NOT CHANGE this.
      *
      * @memberof App
      * @constant {string}
@@ -66,27 +67,29 @@ class App {
     this.mainNs = 'main'
 
     /**
-     * App environments
+     * App environments.
+     *
      * @memberof App
      * @constant {TAppEnv}
      */
     this.envs = { dev: 'development', prod: 'production' }
 
     /**
-     * Date/time when your app start
+     * Date/time when your app start.
+     *
      * @type {Date}
      */
     this.runAt = new Date()
 
     /**
-     * Applets
+     * Applets container.
      *
      * @type {Array}
      */
     this.applets = []
 
     /**
-     * List of all loaded plugin's package names
+     * 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}
      */
@@ -94,9 +97,9 @@ class App {
 
     /**
      * @typedef {Object} TAppConfigHandler
-     * @property {string} ext - File extension
-     * @property {function} [readHandler] - Function to call for reading
-     * @property {function} [writeHandler] - Function to call for writing
+     * @property {string} ext - File extension.
+     * @property {function} [readHandler] - Function to call for reading.
+     * @property {function} [writeHandler] - Function to call for writing.
      * @see App#configHandlers
      */
 
@@ -105,7 +108,7 @@ class App {
      *
      * By default, there are two built-in handlers available: ```.js```
      * and ```.json```. Use plugins to add more, e.g {@link https://github.com/ardhi/bajo-config|bajo-config}
-     * lets you to use ```.yaml/.yml``` and ```.toml```
+     * lets you to use ```.yaml/.yml``` and ```.toml```.
      *
      * @type {TAppConfigHandler[]}
      */
@@ -128,7 +131,7 @@ class App {
     this.lib.parseObject = parseObject.bind(this)
 
     /**
-     * Instance of system log
+     * Instance of system log.
      *
      * @type {Log}
      */
@@ -147,14 +150,14 @@ class App {
     this.baseClass = { Base, Tools }
 
     /**
-     * If app runs in applet mode, this will be the applet's name
+     * If app runs in applet mode, this will be the applet's name.
      *
      * @type {string}
      */
     this.applet = undefined
 
     /**
-     * Program arguments
+     * Program arguments.
      *
      * ```
      * $ node index.js arg1 arg2
@@ -233,11 +236,11 @@ class App {
   }
 
   /**
-   * Add and save plugin and it's base class definition (if provided)
+   * Add and save plugin and it's base class definition (if provided).
    *
    * @method
-   * @param {TPlugin} plugin - A valid bajo plugin
-   * @param {Object} [baseClass] - Base class definition
+   * @param {TPlugin} plugin - A valid bajo plugin.
+   * @param {Object} [baseClass] - Base class definition.
    */
   addPlugin = (plugin, baseClass) => {
     if (this[plugin.ns]) throw new Error(`Plugin '${plugin.ns}' added already`)
@@ -246,7 +249,7 @@ class App {
   }
 
   /**
-   * Get all loaded plugin namespaces
+   * Get all loaded plugin namespaces.
    *
    * @method
    * @returns {string[]}
@@ -255,6 +258,103 @@ class App {
     return this.pluginPkgs.map(pkg => camelCase(pkg))
   }
 
+  /**
+   * Get loaded plugins.
+   *
+   * @method
+   * @param {string[]} [nss] - Array of namespaces. If empty, it returns all loaded plugins.
+   * @returns {TPlugin[]}
+   */
+  getPlugins = (nss) => {
+    const allNs = nss ?? this.getAllNs()
+    return allNs.map(ns => this[ns])
+  }
+
+  /**
+   * Get all plugins loaded plugins.
+   *
+   * @method
+   * @returns {TPlugin[]}
+   */
+  getAllPlugins = () => {
+    return this.getPlugins()
+  }
+
+  /**
+   * Get plugin by its namespace.
+   *
+   * @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[name]) {
+      // alias?
+      let plugin
+      for (const key in this) {
+        const item = this[key]
+        if (item instanceof Plugin && (item.alias === name || item.pkgName === name)) {
+          plugin = item
+          break
+        }
+      }
+      if (!plugin) {
+        if (silent) return false
+        throw this.bajo.error('pluginWithNameAliasNotLoaded%s', name)
+      }
+      name = plugin.ns
+    }
+    return this[name]
+  }
+
+  /**
+   * 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 { fs } = this.lib
+    const plugin = this.getPlugin(name)
+    const dir = `${this.bajo.dir.data}/plugins/${plugin.ns}`
+    if (ensureDir) fs.ensureDirSync(dir)
+    return dir
+  }
+
+  /**
+   * 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```
+   *
+   * @method
+   * @param {string} file - File path, see above for supported types.
+   * @returns {string} Resolved file path.
+   */
+  getPluginFile = (file) => {
+    const { currentLoc } = this.lib.aneka
+    const { fs } = this.lib
+    const { trim } = this.lib._
+    if (!this) return file
+    if (file[0] === '.') file = `${currentLoc(import.meta).dir}/${trim(file.slice(1), '/')}`
+    if (file.includes(':')) {
+      if (file.slice(1, 2) === ':') return file // windows fs
+      const { ns, path } = this.bajo.breakNsPath(file, false)
+      if (ns !== 'file' && this && this[ns] && ns.length > 1) {
+        file = `${this[ns].dir.pkg}${path}`
+        if (path.startsWith('node_modules/')) {
+          file = `${this[ns].dir.pkg}/${path}`
+          if (!fs.existsSync(file)) file = `${this[ns].dir.pkg}/../${path.slice('node_modules/'.length)}`
+        }
+      }
+    }
+    return file
+  }
+
   /**
    * 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.
    *
@@ -268,12 +368,13 @@ class App {
    * See {@link Bajo#config} for details.
    *
    * @method
-   * @param  {...any} args - Variables to dump
+   * @param  {...any} args - Variables to dump.
    */
   dump = (...args) => {
     let caller = getCallerFilename()
     caller = caller ? fileURLToPath(caller) : 'Unavailable'
-    const terminate = last(args) === true
+    const opts = last(args)
+    const terminate = isPlainObject(opts) && opts.abort
     if (terminate) args.pop()
     const value = args.length === 1 ? args[0] : args
     const options = { ...this.bajo.config.dump }
@@ -346,10 +447,10 @@ class App {
   }
 
   /**
-   * Terminate the app and back to console
+   * Terminate the app and back to console.
    *
    * @method
-   * @param {string} [signal=SIGINT] - Signal to send
+   * @param {string} [signal=SIGINT] - Signal to send.
    */
   exit = (signal = 'SIGINT') => {
     if (signal === true) process.exit('1')
@@ -357,10 +458,10 @@ class App {
   }
 
   /**
-   * Load internationalization & languages files for particular plugin
+   * Load internationalization & languages files for particular plugin.
    *
    * @method
-   * @param {string} ns - Plugin name
+   * @param {string} ns - Plugin name.
    */
   loadIntl = (ns) => {
     const { fs } = this.lib
@@ -426,9 +527,9 @@ class App {
    * 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
+   * @param {string} ns - Namespace.
+   * @param {string} text - Text to translate.
+   * @param  {...any} params - Arguments.
    * @returns {string}
    */
   t = (ns, text, ...params) => {
@@ -449,18 +550,17 @@ class App {
    * 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) => {
     const { trans } = this._prepTrans(ns, text, params)
     return !!trans
   }
 
   /**
-   * Helper method to list all supported config formats
+   * Helper method to list all supported config formats.
    *
    * @returns {string[]}
    */
@@ -468,12 +568,25 @@ class App {
     return map(this.configHandlers, 'ext')
   }
 
+  /**
+   * Start a plugin.
+   *
+   * @param {string} ns - Plugin namespace.
+   * @param  {...any} args - Arguments to pass to the plugin's start method.
+   */
   startPlugin = (ns, ...args) => {
     this[ns].start(...args)
   }
 
+  /**
+   * Stop a plugin.
+   *
+   * @param {string} ns - Plugin namespace.
+   * @param  {...any} args - Arguments to pass to the plugin's stop method.
+   */
   stopPlugin = (ns, ...args) => {
-    this[ns].stop(...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.
+    // this[ns].stop(...args)
   }
 }