bajo 1.2.9 → 2.0.0

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,177 @@
+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
+   */
+  err = (msg, ...args) => {
+    if (!this.print) return new Error(msg, ...args)
+    const error = new Err(this, msg, ...args)
+    return error.write()
+  }
+
+  /**
+   * Alias to err () method above
+   *
+   * @method
+   */
+  error = (msg, ...args) => {
+    return this.error(msg, ...args)
+  }
+
+  /**
+   * 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