bajo 2.0.1 → 2.0.2

package/class/misc/print.js

@@ -0,0 +1,264 @@
+import ora from 'ora'
+import lodash from 'lodash'
+import aneka from 'aneka'
+const { defaultsDeep } = aneka
+
+const { isPlainObject } = lodash
+
+/**
+ * @typedef TPrintOptions
+ * @property {boolean} [showDatetime=false] - Show actual date & time
+ * @property {boolean} [showCounter=false] - Show as counter
+ * @property {boolean} [silent] - Suppress any messages. Defaults to the one set in {@tutorial config}
+ * @property {Object} [ora] - {@link https://github.com/sindresorhus/ora#api|Ora's options} object
+ * @see {@link Print}
+ */
+
+/**
+ * Universal print engine, supports text translation using {@link App#t|app's built-in translation}.
+ *
+ * Features many methods to display things on screen/console using {@link https://github.com/sindresorhus/ora|ora}
+ * based spinner.
+ *
+ * @class
+ */
+class Print {
+  /**
+   * @param {Plugin} plugin - Plugin instance
+   * @param {TPrintOptions} [options={}] - Options object
+   */
+  constructor (plugin, options = {}) {
+    /**
+     * Options object
+     * @type {TPrintOptions}
+     */
+    this.options = options
+
+    /**
+     * Attached plugin
+     * @type {Plugin}
+     */
+    this.plugin = plugin
+
+    /**
+     * The app instance
+     * @type {App}
+     */
+    this.app = plugin.app
+    if (this.app.applet) {
+      if (this.app.bajo.config.counter) this.options.showCounter = true
+      if (this.app.bajo.config.datetime) this.options.showDatetime = true
+    }
+
+    /**
+     * Time when instance is created
+     * @type {Object}
+     * @see {@link https://day.js.org|dayjs}  object
+     */
+    this.startTime = this.app.lib.dayjs()
+
+    /**
+     * ora instance
+     * @see {@link https://github.com/sindresorhus/ora|ora}
+     */
+    this.ora = ora(this.options.ora)
+    this.setOpts()
+  }
+
+  /**
+   * Setting spinner options; override the one passed at constructor
+   *
+   * @method
+   * @param {any[]} [args=[]] - Array of options. If the last argument is an object, it will be used to override ora options
+   */
+  setOpts = (args = []) => {
+    const { silent } = this.app.bajo.config
+    let opts = {}
+    if (isPlainObject(args.slice(-1)[0])) opts = args.pop()
+    this.options.silent = !!(silent || this.options.silent)
+    this.options = defaultsDeep(opts, this.options)
+  }
+
+  /**
+   * Translate, prefixed with counter and/or datetime etc
+   *
+   * @param {string} text - Text to use
+   * @param {...any} [args] - Any variable to interpolate text. If the last argument is an object, it will be used to override ora's options
+   * @returns {string}
+   */
+  buildText = (text, ...args) => {
+    text = this.plugin.t(text, ...args)
+    this.setOpts(args)
+    const prefixes = []
+    if (this.options.showDatetime) prefixes.push('[' + this.app.lib.dayjs().toISOString() + ']')
+    if (this.options.showCounter) prefixes.push('[' + this.getElapsed() + ']')
+    // if (prefixes.length > 0) this.ora.prefixText = this.ora.prefixText + prefixes.join(' ')
+    if (prefixes.length > 0) text = prefixes.join(' ') + ' ' + text
+    return text
+  }
+
+  /**
+   * Set spinner's text
+   *
+   * @method
+   * @param {string} text - Text to use
+   * @param {...any} [args] - Any variable to interpolate text. If the last argument is an object, it will be used to override ora's options
+   * @returns {Print} Return the instance itself, usefull for method chaining
+   */
+  setText = (text, ...args) => {
+    text = this.buildText(text, ...args)
+    this.ora.text = text
+    return this
+  }
+
+  /**
+   * Get elapsed time since instance is created
+   *
+   * @method
+   * @param {string} [unit=hms] - Unit's time. Put 'hms' (default) to get hour, minute, second format or of any format supported by {@link https://day.js.org/docs/en/display/difference|dayjs}
+   * @returns {string} Elapsed time since start
+   * @see {@link https://day.js.org/docs/en/display/difference|dayjs duration format}
+   */
+  getElapsed = (unit = 'hms') => {
+    const u = unit === 'hms' ? 'second' : unit
+    const elapsed = this.app.lib.dayjs().diff(this.startTime, u)
+    return unit === 'hms' ? this.app.lib.aneka.secToHms(elapsed) : elapsed
+  }
+
+  /**
+   * Start the spinner
+   *
+   * @method
+   * @param {string} text - Text to use
+   * @param {...any} [args] - Any variable to interpolate text. If the last argument is an object, it will be used to override ora's options
+   * @returns {Print} Return the instance itself, usefull for method chaining
+   */
+  start = (text, ...args) => {
+    this.setOpts(args)
+    this.setText(text, ...args)
+    this.ora.start()
+    return this
+  }
+
+  /**
+   * Stop the spinner
+   *
+   * @method
+   * @returns {Print} Return the instance itself, usefull for method chaining
+   */
+  stop = () => {
+    this.ora.stop()
+    return this
+  }
+
+  /**
+   * Print success message, prefixed with a check icon
+   *
+   * @method
+   * @param {string} text - Text to use
+   * @param {...any} [args] - Any variable to interpolate text. If the last argument is an object, it will be used to override ora options
+   * @returns {Print} Return the instance itself, usefull for method chaining
+   */
+  succeed = (text, ...args) => {
+    this.setText(text, ...args)
+    this.ora.succeed()
+    return this
+  }
+
+  /**
+   * Print failed message, prefixed with a cross icon
+   *
+   * @method
+   * @param {string} text - Text to use
+   * @param {...any} [args] - Any variable to interpolate text. If the last argument is an object, it will be used to override ora options
+   * @returns {Print} Return the instance itself, usefull for method chaining
+   */
+  fail = (text, ...args) => {
+    this.setText(text, ...args)
+    this.ora.fail()
+    return this
+  }
+
+  /**
+   * Print warning message, prefixed with a warn icon
+   *
+   * @method
+   * @param {string} text - Text to use
+   * @param {...any} [args] - Any variable to interpolate text. If the last argument is an object, it will be used to override ora options
+   * @returns {Print} Return the instance itself, usefull for method chaining
+   */
+  warn = (text, ...args) => {
+    this.setText(text, ...args)
+    this.ora.warn()
+    return this
+  }
+
+  /**
+   * Print information message, prefixed with an info icon
+   *
+   * @method
+   * @param {string} text - Text to use
+   * @param {...any} [args] - Any variable to interpolate text. If the last argument is an object, it will be used to override ora options
+   * @returns {Print} Return the instance itself, usefull for method chaining
+   */
+  info = (text, ...args) => {
+    this.setText(text, ...args)
+    this.ora.info()
+    return this
+  }
+
+  /**
+   * Clear spinner text
+   *
+   * @method
+   * @returns {Print} Return the instance itself, usefull for method chaining
+   */
+  clear = () => {
+    this.ora.clear()
+    return this
+  }
+
+  /**
+   * Force render spinner
+   *
+   * @method
+   * @returns {Print} Return the instance itself, usefull for method chaining
+   */
+  render = () => {
+    this.ora.render()
+    return this
+  }
+
+  /**
+   * Print failed message, prefixed with a cross icon and exit
+   *
+   * @method
+   * @param {string} text - Text to use
+   * @param {...any} [args] - Any variable to interpolate text. If the last argument is an object, it will be used to override ora options
+   */
+  fatal = (text, ...args) => {
+    if (text instanceof Error) {
+      text = text.message
+      args = []
+    }
+    this.setText(text, ...args)
+    this.ora.fail()
+    if (text instanceof Error && this.app.bajo.config.log.level === 'trace') console.error(text)
+    this.app.exit()
+  }
+
+  /**
+   * Create a new print instance
+   *
+   * @method
+   * @param {TPrintOptions} [options] - Options object. If not provided, defaults to the current options
+   * @returns {Print} Return new print instance
+   */
+  spinner = (options) => {
+    const spin = new Print(this.plugin, options ?? this.options)
+    spin.startTime = this.startTime.clone()
+    return spin
+  }
+}
+
+export default Print

package/class/plugin.js

@@ -1,117 +1,169 @@
-import BasePlugin from './base/plugin.js'
 import lodash from 'lodash'
-import omittedPluginKeys from '../lib/omitted-plugin-keys.js'
-import readAllConfigs from '../lib/read-all-configs.js'
+import Err from './misc/err.js'
 
-const { pick, omit } = lodash
+const { get, isEmpty, cloneDeep, omit, isPlainObject, camelCase } = lodash
 
 /**
- * This is the class that your own plugin suppose to extend. Don't use {@link BasePlugin}
- * unless you know what you're doing.
+ * This is the **mother** of all plugin classes. All Bajo plugin classess inherit from this class
+ * respectfully.
+ *
+ * There are currently only two main plugins available:
+ * - {@link Bajo} - Core plugin class, responsible for system wide setup and boot process. You should not touch this obviously
+ * - {@link Base} - Base plugin class your own plugin should extend from
  *
  * @class
  */
+class Plugin {
+  /**
+   * Package name, the one from package.json
+   *
+   * @memberof Plugin
+   * @constant {string}
+   */
+  static pkgName
+
+  /**
+   * Namespace (ns) or plugin's name. Simply the camel cased version of plugin's package name
+   *
+   * @memberof Plugin
+   * @constant {string}
+   */
+  static ns
+
+  /**
+   * Plugin alias. Derived plugin must provide its own, unique alias. If it left blank,
+   * Bajo will provide this automatically (by using the kebab-cased version of plugin name)
+   *
+   * @readonly
+   * @memberof Plugin
+   * @type {string}
+   */
+  static alias = ''
 
-class Plugin extends BasePlugin {
   /**
    * @param {string} pkgName - Package name (the one you use in package.json)
    * @param {Object} app - App instance reference. Usefull to call app method inside a plugin
    */
   constructor (pkgName, app) {
-    super(pkgName, app)
+    this.constructor.pkgName = pkgName
+    this.constructor.ns = camelCase(pkgName)
+
     /**
-     * Plugin alias. Derived plugin must provide its own, unique alias. If it left blank,
-     * Bajo will provide this automatically
+     * Reference to app instance
      *
-     * @type {string}
+     * @type {Object}
      */
-    this.alias = ''
+    this.app = app
 
     /**
-     * Dependencies to other plugins. Enter all plugin's package name your plugin dependent from.
+     * Config object
      *
-     * Semver is also supported.
+     * @type {Object}
+     * @see {@tutorial config}
+     */
+    this.config = {}
+
+    /**
+     * Shortcut to {@link App#log} with prefix parameter set to this plugin name.
      *
-     * @type {Array}
+     * @type {Log}
      */
-    this.dependencies = []
-    this.state = {}
+    this.log = {
+      trace: (...params) => this.app.log.trace(this.ns, ...params),
+      debug: (...params) => this.app.log.debug(this.ns, ...params),
+      info: (...params) => this.app.log.info(this.ns, ...params),
+      warn: (...params) => this.app.log.warn(this.ns, ...params),
+      error: (...params) => this.app.log.error(this.ns, ...params),
+      fatal: (...params) => this.app.log.fatal(this.ns, ...params),
+      silent: (...params) => this.app.log.silent(this.ns, ...params)
+    }
   }
 
   /**
-   * Load config from file in data directory, program arguments and environment variables. Level of importance:
-   * ```Env Variables > Program Arguments > Config File```
+   * Get plugin's config value
    *
    * @method
-   * @async
+   * @param {string} [path] - dot separated config path (think of lodash's 'get'). If not provided, the full config will be given
+   * @param {Object} [options={}] - Options
+   * @param {any} [options.defValue={}] - Default value to use if returned object is undefined
+   * @param {string[]} [options.omit=[]] - Omit these keys from returned object
+   * @param {boolean} [options.noClone=false] - Set true to NOT clone returned object
+   * @returns {Object} Returned object. If no path provided, the whole config object is returned
    */
-  loadConfig = async () => {
-    const { defaultsDeep } = this.lib.aneka
-    const { get } = this.lib._
-    const { log, readJson, parseObject, getModuleDir } = this.app.bajo
-    log.trace('- %s', this.name)
-    const dir = this.name === this.app.bajo.mainNs ? (`${this.app.bajo.dir.base}/${this.app.bajo.mainNs}`) : getModuleDir(this.pkgName)
-    let cfg = await readAllConfigs.call(this.app, `${dir}/config`)
-    this.alias = this.alias ?? (this.pkgName.slice(0, 5) === 'bajo-' ? this.pkgName.slice(5).toLowerCase() : this.name.toLowerCase())
-    this.alias = this.alias.toLowerCase()
-
-    this.dir = {
-      pkg: dir,
-      data: `${this.app.bajo.dir.data}/plugins/${this.name}`
-    }
-    const file = `${dir + (this.name === this.app.bajo.mainNs ? '/..' : '')}/package.json`
-    const pkgJson = await readJson(file)
-    this.pkg = pick(pkgJson,
-      ['name', 'version', 'description', 'author', 'license', 'homepage'])
-    if (this.name === this.app.bajo.mainNs) {
-      this.alias = this.app.bajo.mainNs
-      this.title = this.title ?? this.alias
-    }
-    // merge with config from datadir
-    try {
-      const altCfg = await readAllConfigs.call(this.app, `${this.app.bajo.dir.data}/config/${this.name}`)
-      cfg = defaultsDeep({}, omit(altCfg, omittedPluginKeys), cfg)
-    } catch (err) {}
-    const cfgEnv = omit(get(this, `app.env._.${this.name}`, {}), omittedPluginKeys) ?? {}
-    const cfgArgv = omit(get(this, `app.argv._.${this.name}`, {}), omittedPluginKeys) ?? {}
-    const envArgv = defaultsDeep({}, cfgEnv, cfgArgv)
-    cfg = defaultsDeep({}, envArgv ?? {}, cfg ?? {}, this.config ?? {})
-    this.title = this.title ?? cfg.title ?? this.alias
-
-    this.dependencies = this.dependencies ?? []
-    this.config = parseObject(cfg, { parseValue: true })
+  getConfig = (path, options = {}) => {
+    let obj = isEmpty(path) ? this.config : get(this.config, path, options.defValue ?? {})
+    options.omit = options.omit ?? []
+    if (isPlainObject(obj) && !isEmpty(options.omit)) obj = omit(obj, options.omit)
+    if (!options.noClone) obj = cloneDeep(obj)
+    return obj
   }
 
   /**
-   * After config is read, plugin will be initialized. You can still change your config here,
-   * because after plugin is initialized, config will be deep frozen.
+   * Create an instance of {@link Err} object
    *
    * @method
-   * @async
+   * @param {msg} msg - Error message
+   * @param  {...any} [args] - Argument variables you might want to add to the error object
+   * @returns {Object} Err instance
    */
-  init = async () => {
+  error = (msg, ...args) => {
+    if (!this.print) return new Error(msg, ...args)
+    const error = new Err(this, msg, ...args)
+    return error.write()
   }
 
   /**
-   * This method will be called after plugin's init
+   * Create an instance of Err object, display it on screen and then force
+   * terminate the app process
    *
    * @method
-   * @async
+   * @param {msg} msg - Error message
+   * @param  {...any} [args] - Argument variables you might want to add to the error object
    */
-  start = async () => {
+  fatal = (msg, ...args) => {
+    if (!this.print) return new Error(msg, ...args)
+    const error = new Err(this, msg, ...args)
+    error.fatal()
   }
 
-  stop = async () => {
+  /**
+   * Getter for plugin's package name
+   *
+   * @type {string}
+   */
+  get pkgName () {
+    return this.constructor.pkgName
   }
 
   /**
-   * Upon app termination, this method will be called first. Mostly useful for system cleanup,
-   * delete temporary files, freeing resources etc.
+   * Getter for plugin's ns
    *
-   * @method
-   * @async
+   * @type {string}
+   */
+  get ns () {
+    return this.constructor.ns
+  }
+
+  /**
+   * Getter for plugin's alias
+   *
+   * @type {string}
+   */
+  get alias () {
+    return this.constructor.alias
+  }
+
+  /**
+   * Translate text and interpolate with given ```args```.
+   *
+   * Shortcut to {@link App#t} with ns parameter set to this plugin namespace.
+   *
+   * @param {string} text - Text to translate
+   * @param  {...any} params - Variables to interpolate to ```text```
+   * @returns {string}
    */
-  exit = async () => {
+  t = (text, ...params) => {
+    return this.app.t(this.ns, text, ...params)
   }
 }