bajo 1.2.9 → 2.0.1

package/{boot/class/error.js → class/base/err.js}

@@ -3,7 +3,16 @@ const { isPlainObject, each, isArray, get, isEmpty, merge } = lodash
 
 Error.stackTraceLimit = 15
 
-class BajoError {
+/**
+ * Bajo error class, a thin wrapper of node's Error object. Use this name instead of Error
+ * because, of course, Error is a reserved keyword in node.
+ */
+class Err {
+  /**
+   * @param {Object} plugin - Plugin instance
+   * @param {string} msg - Error message
+   * @param  {...any} [args] - Variables to interpolate with error message. Payload object can be pushed as the very last argument
+   */
   constructor (plugin, msg, ...args) {
     this.plugin = plugin
     this.payload = args.length > 0 && isPlainObject(args[args.length - 1]) ? args[args.length - 1] : {}
@@ -12,6 +21,12 @@ class BajoError {
     this.write()
   }
 
+  /**
+   * Create the error object
+   *
+   * @method
+   * @returns {Object} Error object
+   */
   write = () => {
     let err
     if (this.payload.class) err = this.payload.class(this.message)
@@ -36,17 +51,28 @@ class BajoError {
     return err
   }
 
+  /**
+   * Print error object on screen and terminate app process
+   *
+   * @method
+   */
   fatal = () => {
     const err = this.write()
     console.error(err)
     process.kill(process.pid, 'SIGINT')
   }
 
+  /**
+   * Pretty format error details
+   *
+   * @method
+   * @param {Object} value - Value to format
+   * @returns {Object}
+   */
   formatErrorDetails = (value) => {
     const { isString } = this.plugin.app.bajo.lib._
     const result = {}
     const me = this
-    this.plugin.app.dump(value)
     each(value, (v, i) => {
       const print = me.plugin.print
       if (isString(v)) v = { error: v }
@@ -67,4 +93,4 @@ class BajoError {
   }
 }
 
-export default BajoError
+export default Err

package/class/base/log.js

@@ -0,0 +1,205 @@
+import os from 'os'
+import lodash from 'lodash'
+import dayjs from 'dayjs'
+import logLevels from '../../lib/log-levels.js'
+import chalk from 'chalk'
+
+const { isEmpty, without, merge } = lodash
+
+export function isIgnored (level) {
+  const { filter, isArray } = this.lib._
+  let ignore = this.app.bajo.config.log.ignore ?? []
+  if (!isArray(ignore)) ignore = [ignore]
+  const items = filter(ignore, i => {
+    const [ns, lvl] = i.split(':')
+    if (lvl) return ns === this.name && lvl === level
+    return ns === this.name
+  })
+  return items.length > 0
+}
+
+/**
+ * A thin logger system.
+ *
+ * @class
+ */
+class Log {
+  /**
+   * @param {Object} plugin - Plugin instance
+   */
+  constructor (plugin) {
+    this.plugin = plugin
+    this.format = 'YYYY-MM-DDTHH:mm:ss.SSS[Z]'
+  }
+
+  /**
+   * Initialize logger. Auto detect to use different logger via Bajo's config file
+   *
+   * @method
+   */
+  init = () => {
+    this.bajoLog = this.plugin.app.bajo.config.log.logger ?? 'bajoLogger'
+  }
+
+  /**
+   * Interpolate and translate text via plugin's print engine. Check Print class
+   * for more information
+   *
+   * @method
+   * @param {string} text - Text pattern to use
+   * @param {...any} [args] - Variables to interpolate with text pattern above
+   * @returns {string} Interpolated & translated text
+   */
+  write = (text, ...args) => {
+    return this.plugin.print.write(text, ...args)
+  }
+
+  /**
+   * Do we use external logger or Bajo's built-in one?
+   *
+   * @method
+   * @returns {boolean}
+   */
+  isExtLogger = () => {
+    return !!(this.plugin.app[this.bajoLog] && this.plugin.app[this.bajoLog].logger)
+  }
+
+  /**
+   * Is provided level being ignored by config?
+   *
+   * @method
+   * @param {string} level - Log level
+   * @returns {boolean}
+   */
+  isIgnored = level => {
+    return isIgnored.call(this.plugin, level)
+  }
+
+  /**
+   * Create child logger
+   *
+   * @method
+   * @returns {Object} Child logger instance
+   */
+  child = () => {
+    if (this.isExtLogger()) return this.plugin.app[this.bajoLog].logger.child()
+    return this.plugin.app
+  }
+
+  /**
+   * Display & format message according to one of these rules:
+   * 1. ```level``` ```text``` ```var 1``` ```var 2``` ```...var n``` - Translate ```text``` and interpolate with ```vars``` for level ```level```
+   * 2. ```level``` ```data``` ```text``` ```var 1``` ```var 2``` ```...var n``` - As above, and append stringified ```data```
+   * 3. ```level``` ```error``` - Format as **error**. If current log level is _trace_, dump the error object on screen
+   *
+   * @method
+   * @param {string} level - Log level to use
+   * @param {...any} params - See format above
+   */
+  formatMsg = (level, ...params) => {
+    if (this.plugin.app.bajo.config.log.level === 'silent') return
+    if (!this.plugin.app.bajo.isLogInRange(level)) return
+    const plain = this.plugin.app.bajo.config.log.plain
+    let [data, msg, ...args] = params
+    if (typeof data === 'string') {
+      args.unshift(msg)
+      msg = data
+      data = null
+    }
+    args = without(args, undefined)
+    if (data instanceof Error) {
+      msg = 'error%s'
+      args = [data.message]
+    }
+    msg = this.write(msg, ...args)
+    if (this.plugin.app[this.bajoLog] && this.plugin.app[this.bajoLog].logger) {
+      this.plugin.app[this.bajoLog].logger[level](data, `[${this.plugin.name}] ${msg}`, ...args)
+    } else {
+      let text
+      const dt = new Date()
+      if (this.plugin.app.bajo.config.env === 'prod') {
+        const json = { level: logLevels[level].number, time: dt.valueOf(), pid: process.pid, hostname: os.hostname() }
+        if (!isEmpty(data)) merge(json, data)
+        merge(json, { msg: `[${this.plugin.name}] ${msg}` })
+        text = JSON.stringify(json)
+      } else {
+        const date = dayjs(dt).utc(true).format(this.format)
+        const tdate = plain ? `[${date}]` : chalk.cyan(date)
+        const tlevel = plain ? level.toUpperCase() : chalk[logLevels[level].color](level.toUpperCase())
+        const tplugin = plain ? `[${this.plugin.name}]` : chalk.bgBlue(`${this.plugin.name}`)
+        text = `${tdate} ${tlevel}: ${tplugin} ${msg}`
+        if (!isEmpty(data)) text += '\n' + JSON.stringify(data)
+      }
+      if (!this.isIgnored(level)) {
+        console.log(text)
+        if (data instanceof Error && level === 'trace') console.error(data)
+      }
+    }
+  }
+
+  /**
+   * Display & format message as ```trace``` level. See {@link Log#formatMsg|formatMsg} for details
+   *
+   * @method
+   * @param  {...any} params
+   */
+  trace = (...params) => {
+    this.formatMsg('trace', ...params)
+  }
+
+  /**
+   * Display & format message as ```debug``` level. See {@link Log#formatMsg|formatMsg} for details
+   *
+   * @method
+   * @param  {...any} params
+   */
+  debug = (...params) => {
+    this.formatMsg('debug', ...params)
+  }
+
+  /**
+   * Display & format message as ```info``` level. See {@link Log#formatMsg|formatMsg} for details
+   *
+   * @method
+   * @param  {...any} params
+   */
+  info = (...params) => {
+    this.formatMsg('info', ...params)
+  }
+
+  /**
+   * Display & format message as ```warn``` level. See {@link Log#formatMsg|formatMsg} for details
+   *
+   * @method
+   * @param  {...any} params
+   */
+  warn = (...params) => {
+    this.formatMsg('warn', ...params)
+  }
+
+  /**
+   * Display & format message as ```error``` level. See {@link Log#formatMsg|formatMsg} for details
+   *
+   * @method
+   * @param  {...any} params
+   */
+  error = (...params) => {
+    this.formatMsg('error', ...params)
+  }
+
+  /**
+   * Display & format message as ```fatal``` level. See {@link Log#formatMsg|formatMsg} for details
+   *
+   * @method
+   * @param  {...any} params
+   */
+  fatal = (...params) => {
+    this.formatMsg('fatal', ...params)
+  }
+
+  silent = (...params) => {
+    this.formatMsg('silent', ...params)
+  }
+}
+
+export default Log

package/class/base/plugin.js

@@ -0,0 +1,168 @@
+import lodash from 'lodash'
+import omittedPluginKeys from '../../lib/omitted-plugin-keys.js'
+import Log from './log.js'
+import Print from './print.js'
+import Err from './err.js'
+import fastGlob from 'fast-glob'
+import { sprintf } from 'sprintf-js'
+import outmatch from 'outmatch'
+import dayjs from '../../lib/dayjs.js'
+import fs from 'fs-extra'
+import aneka from 'aneka/index.js'
+
+function outmatchNs (source, pattern) {
+  const { breakNsPath } = this.app.bajo
+  const [src, subSrc] = source.split(':')
+  if (!subSrc) return pattern === src
+  try {
+    const { fullNs, path } = breakNsPath(pattern)
+    const isMatch = outmatch(path)
+    return src === fullNs && isMatch(subSrc)
+  } catch (err) {
+    return false
+  }
+}
+
+const lib = {
+  _: lodash,
+  fs,
+  fastGlob,
+  sprintf,
+  outmatch,
+  dayjs,
+  aneka
+}
+
+const { get, isEmpty, cloneDeep, omit, isPlainObject, camelCase } = lodash
+
+/**
+ * This is the base class of bajo's plugin system.
+ *
+ * @class
+ */
+class 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) {
+    /**
+     * Package name, the one from package.json
+     * @type {string}
+     */
+    this.pkgName = pkgName
+
+    /**
+     * Plugin name. Simply the camel cased version of plugin's package name
+     *
+     * @type {string}
+     */
+    this.name = camelCase(pkgName)
+
+    /**
+     * Reference to app instance
+     *
+     * @type {Object}
+     */
+    this.app = app
+
+    /**
+     * Config object
+     *
+     * @type {Object}
+     */
+    this.config = {}
+
+    /**
+     * Property to give you direct access to the most commonly used 3rd party library in a bajo based app.
+     * No manual import necessary, always available, everywhere, anytime!
+     *
+     * Example:
+     * ```javascript
+     * const { camelCase, kebabCase } = this.lib._
+     * console.log(camelCase('Elit commodo sit et aliqua'))
+     * ```
+     *
+     * @type {Object}
+     * @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
+     */
+    this.lib = lib
+    this.lib.outmatchNs = outmatchNs.bind(this)
+  }
+
+  /**
+   * Get plugin's config value
+   *
+   * @method
+   * @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
+   */
+  getConfig = (path, options = {}) => {
+    let obj = isEmpty(path) ? this.config : get(this.config, path, options.defValue ?? {})
+    options.omit = options.omit ?? omittedPluginKeys
+    if (isPlainObject(obj) && !isEmpty(options.omit)) obj = omit(obj, options.omit)
+    if (!options.noClone) obj = cloneDeep(obj)
+    return obj
+  }
+
+  /**
+   * Initialize log. Please refer to {@link Log} class for more info
+   *
+   * @method
+   */
+  initLog = () => {
+    this.log = new Log(this)
+    this.log.init()
+  }
+
+  /**
+   * Initialize print engine. Please refer to {@link Print} class for more info
+   *
+   * @method
+   * @param {Object} [options] - Print options
+   */
+  initPrint = (options) => {
+    this.print = new Print(this, options)
+    this.print.init()
+  }
+
+  /**
+   * Create an instance of {@link Err} object
+   *
+   * @method
+   * @param {msg} msg - Error message
+   * @param  {...any} [args] - Argument variables you might want to add to the error object
+   * @returns {Object} Err instance
+   */
+  error = (msg, ...args) => {
+    if (!this.print) return new Error(msg, ...args)
+    const error = new Err(this, msg, ...args)
+    return error.write()
+  }
+
+  /**
+   * Create an instance of Err object, display it on screen and then force
+   * terminate the app process
+   *
+   * @method
+   * @param {msg} msg - Error message
+   * @param  {...any} [args] - Argument variables you might want to add to the error object
+   */
+  fatal = (msg, ...args) => {
+    if (!this.print) return new Error(msg, ...args)
+    const error = new Err(this, msg, ...args)
+    error.fatal()
+  }
+}
+
+export default BasePlugin

package/class/base/print.js

@@ -0,0 +1,272 @@
+import ora from 'ora'
+import lodash from 'lodash'
+import fs from 'fs-extra'
+import Sprintf from 'sprintf-js'
+const { sprintf } = Sprintf
+let unknownLangWarning = false
+
+const { isString, last, isPlainObject, get, without, reverse, map } = lodash
+
+/**
+ * Print class. Use sprintf to interpolate pattern and variable. Support
+ * many methods to display things on screen including {@link https://github.com/sindresorhus/ora|ora} based spinner.
+ *
+ * It also serve as the foundation of Bajo's I18n lightweight system.
+ *
+ * @class
+ */
+class Print {
+  /**
+   * Class constructor
+   *
+   * @param {Object} plugin - Plugin instance
+   * @param {Object} [opts={}] - Options to pass to {@link https://github.com/sindresorhus/ora|ora}
+   */
+  constructor (plugin, opts = {}) {
+    this.opts = opts
+    this.plugin = plugin
+    this.startTime = this.plugin.app.bajo.lib.dayjs()
+    this.setOpts()
+    this.ora = ora(this.opts)
+    this.intl = {}
+  }
+
+  /**
+   * Initialize print engine and read plugin's translation files
+   *
+   * @method
+   */
+  init = () => {
+    for (const l of this.plugin.app.bajo.config.intl.supported) {
+      this.intl[l] = {}
+      const path = `${this.plugin.dir.pkg}/extend/bajo/intl/${l}.json`
+      if (!fs.existsSync(path)) continue
+      const trans = fs.readFileSync(path, 'utf8')
+      try {
+        this.intl[l] = JSON.parse(trans)
+      } catch (err) {}
+    }
+  }
+
+  /**
+   * Interpolate and translate text according to the chosen language
+   *
+   * @method
+   * @param {string} text - Text pattern to translate. See {@link https://github.com/alexei/sprintf.js|sprintf} for all supported token & format
+   * @param {...any} [args] - Variables to interpolate with text pattern above. If the last argument is an object, it will be use to override default translation option. Example: to force language to 'id', pass the last argument as "{ lang: 'id' }"
+   * @returns {string} Interpolated & translated text
+   */
+  write = (text, ...args) => {
+    const opts = last(args)
+    let lang = this.plugin.app.bajo.config.lang
+    if (isPlainObject(opts)) {
+      args.pop()
+      if (opts.lang) lang = opts.lang
+    }
+    const { fallback, supported } = this.plugin.app.bajo.config.intl
+    if (!unknownLangWarning && !supported.includes(lang)) {
+      unknownLangWarning = true
+      this.plugin.app.bajo.log.warn('unsupportedLangFallbackTo%s', fallback)
+    }
+    const plugins = reverse(without([...this.plugin.app.bajo.pluginNames], this.plugin.name))
+    plugins.unshift(this.plugin.name)
+    plugins.push('bajo')
+
+    let trans
+    for (const p of plugins) {
+      const root = get(this, `plugin.app.${p}.print.intl.${lang}`, {})
+      trans = get(root, text)
+      if (trans) break
+    }
+    if (!trans) {
+      for (const p of plugins) {
+        const root = get(this, `plugin.app.${p}.print.intl.${fallback}`, {})
+        trans = get(root, text)
+        if (trans) break
+      }
+    }
+    if (!trans) trans = text
+    const params = map(args, a => {
+      if (!isString(a)) return a
+      return a
+    })
+    return sprintf(trans, ...params)
+  }
+
+  /**
+   * Set spinner options
+   *
+   * @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 config = this.plugin.app.bajo.config
+    let opts = {}
+    if (isPlainObject(args.slice(-1)[0])) opts = args.pop()
+    this.opts.isSilent = !!(config.silent || this.opts.isSilent)
+    this.opts = this.plugin.lib.aneka.defaultsDeep(opts, this.opts)
+  }
+
+  /**
+   * Set spinner 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 options
+   * @returns {Object} Return itself, usefull to chain methods
+   */
+  setText = (text, ...args) => {
+    text = this.write(text, ...args)
+    this.setOpts(args)
+    const prefixes = []
+    const texts = []
+    if (this.opts.showDatetime) prefixes.push('[' + this.plugin.app.bajo.lib.dayjs().toISOString() + ']')
+    if (this.opts.showCounter) texts.push('[' + this.getElapsed() + ']')
+    if (prefixes.length > 0) this.ora.prefixText = this.ora.prefixText + prefixes.join(' ')
+    if (texts.length > 0) text = texts.join(' ') + ' ' + text
+    this.ora.text = text
+    return this
+  }
+
+  /**
+   * Get elapsed time since print 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
+   */
+  getElapsed = (unit = 'hms') => {
+    const u = unit === 'hms' ? 'second' : unit
+    const elapsed = this.plugin.lib.dayjs().diff(this.startTime, u)
+    return unit === 'hms' ? this.plugin.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 options
+   * @returns {Object} Return itself, usefull to chain methods
+   */
+  start = (text, ...args) => {
+    this.setOpts(args)
+    this.setText(text, ...args)
+    this.ora.start()
+    return this
+  }
+
+  /**
+   * Stop the spinner
+   *
+   * @method
+   * @returns {Object} Return itself, usefull to chain methods
+   */
+  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 {Object} Return itself, usefull to chain methods
+   */
+  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 {Object} Return itself, usefull to chain methods
+   */
+  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 {Object} Return itself, usefull to chain methods
+   */
+  warn = (text, ...args) => {
+    this.setText(text, ...args)
+    this.ora.warn()
+    return this
+  }
+
+  /**
+   * Print failed 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 {Object} Return itself, usefull to chain methods
+   */
+  info = (text, ...args) => {
+    this.setText(text, ...args)
+    this.ora.info()
+    return this
+  }
+
+  /**
+   * Clear spinner text
+   *
+   * @method
+   * @returns {Object} Return itself, usefull to chain methods
+   */
+  clear = () => {
+    this.ora.clear()
+    return this
+  }
+
+  /**
+   * Force render spinner
+   *
+   * @method
+   * @returns {Object} Return itself, usefull to chain methods
+   */
+  render = () => {
+    this.ora.render()
+    return this
+  }
+
+  /**
+   * Print failed message, prefixed with a cross icon and terminate the app process
+   *
+   * @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) => {
+    this.setText(text, ...args)
+    this.ora.fail()
+    process.kill(process.pid, 'SIGINT')
+  }
+
+  /**
+   * Create a new spinner
+   *
+   * @method
+   * @returns {Object} Return new instance
+   */
+  spinner = () => {
+    return new Print(this.plugin)
+  }
+}
+
+export default Print