bajo 2.0.1 → 2.1.0

package/class/helper/{plugin.js → base.js}

@@ -1,8 +1,11 @@
-import createMethod from '../../lib/create-method.js'
 import semver from 'semver'
 import lodash from 'lodash'
+import Print from '../misc/print.js'
+import path from 'path'
+import resolvePath from '../../lib/resolve-path.js'
 
 const {
+  isFunction,
   merge,
   forOwn,
   groupBy,
@@ -18,7 +21,10 @@ const {
 } = lodash
 
 /**
- * @module
+ * Internal helpers called by Bajo & plugins that only used once for bootstrapping purpose.
+ * It should remains hidden and not to be imported by any program.
+ *
+ * @module Helper/Base
  */
 
 /**
@@ -27,12 +33,30 @@ const {
  * @async
  */
 export async function attachMethods () {
+  const { fastGlob } = this.lib
+
+  async function createMethod (dir) {
+    dir = resolvePath(dir)
+    const files = await fastGlob([`!${dir}/**/_*.{js,json}`, `${dir}/**/*.{js,json}`])
+    for (const f of files) {
+      const ext = path.extname(f)
+      const base = f.replace(dir, '').slice(0, -ext.length)
+      const name = camelCase(base)
+      let mod
+      if (ext === '.json') mod = this.app.bajo.readJson(f)
+      else mod = await this.app.bajo.importModule(f)
+      if (isFunction(mod)) mod = mod.bind(this)
+      this[name] = mod
+    }
+    return files.length
+  }
+
   const { eachPlugins } = this.bajo
   const me = this // the app
   me.bajo.log.debug('attachMethods')
   await eachPlugins(async function () {
-    const { name: ns, pkgName } = this
-    const dir = ns === me.bajo.mainNs ? (`${me.bajo.dir.base}/${me.bajo.mainNs}`) : me.bajo.getModuleDir(pkgName)
+    const { ns, pkgName } = this
+    const dir = ns === me.mainNs ? (`${me.bajo.dir.base}/${me.mainNs}`) : me.bajo.getModuleDir(pkgName)
     const num = await createMethod.call(me[ns], `${dir}/method`, pkgName)
     me.bajo.log.trace('- %s (%d)', ns, num)
   })
@@ -45,11 +69,10 @@ export async function attachMethods () {
  */
 export async function buildConfigs () {
   this.bajo.log.debug('readConfigs')
-  for (const pkg of this.bajo.pluginPkgs) {
-    const plugin = this[camelCase(pkg)]
-    await plugin.loadConfig()
-    plugin.initPrint()
-    plugin.initLog()
+  for (const ns of this.getAllNs()) {
+    await this[ns].loadConfig()
+    this[ns].print = new Print(this[ns])
+    this.loadIntl(ns)
   }
 }
 
@@ -63,7 +86,8 @@ export async function checkNameAliases () {
   this.bajo.log.debug('checkAliasNameClash')
   const refs = []
   await eachPlugins(async function () {
-    const { name: ns, pkgName, alias } = this
+    const { ns, pkgName } = this
+    const { alias } = this.constructor
     let item = find(refs, { ns })
     if (item) throw this.error('pluginNameClash%s%s%s%s', ns, pkgName, item.ns, item.pkgName, { code: 'BAJO_NAME_CLASH' })
     item = find(refs, { alias })
@@ -79,10 +103,11 @@ export async function checkNameAliases () {
  */
 export async function checkDependencies () {
   async function runner () {
-    const { name: ns, pkgName } = this
+    const { ns, pkgName } = this
     const { join } = this.app.bajo
     this.app.bajo.log.trace('- %s', ns)
-    const odep = reduce(this.dependencies, (o, k) => {
+    const { dependencies } = this.app.pluginClass[this.ns]
+    const odep = reduce(dependencies, (o, k) => {
       const item = map(k.split('@'), m => trim(m))
       if (k[0] === '@') o['@' + item[1]] = item[2]
       else o[item[0]] = item[1]
@@ -90,7 +115,7 @@ export async function checkDependencies () {
     }, {})
     const deps = keys(odep)
     if (deps.length > 0) {
-      if (intersection(this.app.bajo.pluginPkgs, deps).length !== deps.length) {
+      if (intersection(this.app.pluginPkgs, deps).length !== deps.length) {
         throw this.error('dependencyUnfulfilled%s%s', pkgName, join(deps), { code: 'BAJO_DEPENDENCY' })
       }
       each(deps, d => {
@@ -115,6 +140,7 @@ export async function checkDependencies () {
  * Collect and build hooks and push them to the bajo's hook system
  *
  * @async
+ * @fires bajo:afterCollectHooks
  */
 export async function collectHooks () {
   const { eachPlugins, runHook, isLogInRange, importModule, breakNsPathFromFile } = this.bajo
@@ -123,13 +149,13 @@ export async function collectHooks () {
   me.bajo.log.debug('collectHooks')
   // collects
   await eachPlugins(async function ({ dir, file }) {
-    const { name: ns } = this
+    const { ns } = this
     const { fullNs, path } = breakNsPathFromFile({ file, dir, baseNs: ns, suffix: '/hook/' })
     const mod = await importModule(file, { asHandler: true })
     if (!mod) return undefined
     merge(mod, { ns: fullNs, path, src: ns })
     me.bajo.hooks.push(mod)
-  }, { glob: 'hook/**/*.js', prefix: me.bajo.name })
+  }, { glob: 'hook/**/*.js', prefix: me.bajo.ns })
   // for log trace purpose only
   if (!isLogInRange('trace')) return
   const items = groupBy(me.bajo.hooks, 'ns')
@@ -139,31 +165,79 @@ export async function collectHooks () {
       me.bajo.log.trace('- %s:%s (%d)', k, k1, v1.length)
     })
   })
-  // run handler
-  await runHook('bajo:afterCollectHooks')
+
+  /**
+   * Run after hooks are collected
+   *
+   * @global
+   * @event bajo:afterCollectHooks
+   * @param {Object[]} hooks - Array of hook objects
+   * @see {@tutorial hook}
+   * @see module:Helper/Base.collectHooks
+   */
+  await runHook('bajo:afterCollectHooks', this.bajo.hooks)
 }
 
 /**
  * Finally, run all plugins
  *
  * @async
+ * @fires bajo:beforeAll{method}
+ * @fires {ns}:before{method}
+ * @fires {ns}:after{method}
+ * @fires bajo:afterAll{method}
  */
 export async function run () {
   const me = this
   const { runHook, eachPlugins, join } = me.bajo
   const { freeze } = me.bajo
   const methods = ['init']
-  if (!me.bajo.applet) methods.push('start')
+  if (!me.applet) methods.push('start')
+  me.bajo.log.debug('loadedPlugins%s', join(map(me.bajo.app.pluginPkgs, b => camelCase(b))))
   for (const method of methods) {
-    await runHook(`bajo:${camelCase(`before ${method} all plugins`)}`)
+    /**
+     * Run before all ```{method}``` executed. Accepted ```{method}```: ```Init``` or ```Start```
+     *
+     * @global
+     * @event bajo:beforeAll{method}
+     * @param {string} method - Accepted methods: ```Init```, ```Start```
+     * @see module:Helper/Base.run
+     */
+    await runHook(`bajo:${camelCase(`before all ${method}`)}`)
     await eachPlugins(async function () {
-      const { name: ns } = this
+      const { ns } = this
       if (method === 'start') freeze(me[ns].config)
+      /**
+       * Run before ```{method}``` is executed within ```{ns}``` context
+       *
+       * - ```{ns}``` - namespace
+       * - ```{method}``` - Accepted methods: ```Init``` or ```Start```
+       *
+       * @global
+       * @event {ns}:before{method}
+       * @see module:Helper/Base.run
+       */
       await runHook(`${ns}:${camelCase(`before ${method}`)}`)
       await me[ns][method]()
+      /**
+       * Run after ```{method}``` is executed within ```{ns}``` context
+       *
+       * - ```{ns}``` - namespace
+       * - ```{method}``` - Accepted methods: ```Init``` or ```Start```
+       *
+       * @global
+       * @event {ns}:after{method}
+       * @see module:Helper/Base.run
+       */
       await runHook(`${ns}:${camelCase(`after ${method}`)}`)
     })
-    await runHook(`bajo:${camelCase(`after ${method} all plugins`)}`)
+    /**
+     * Run after all ```{method}``` executed. Accepted ```{method}```: ```Init``` or ```Start```
+     *
+     * @global
+     * @event bajo:afterAll{method}
+     * @see module:Helper/Base.run
+     */
+    await runHook(`bajo:${camelCase(`after all ${method}`)}`)
   }
-  me.bajo.log.debug('loadedPlugins%s', join(map(me.bajo.pluginPkgs, b => camelCase(b))))
 }

package/class/{base → misc}/err.js

@@ -4,28 +4,60 @@ const { isPlainObject, each, isArray, get, isEmpty, merge } = lodash
 Error.stackTraceLimit = 15
 
 /**
- * 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.
+ * Bajo error class, a thin wrapper of node's Error object.
+ *
+ * Every Bajo {@link Plugin|plugin} has a built-in method called ```error``` which basically the shortcut to create a new Err instance.
+ * It helps you create this instance anywhere in your code quickly without the hassle of importing & instantiating:
+ *
+ * ```javascript
+ * ... anywhere inside your code
+ * if (notfound) throw this.error('Sorry, item is nowhere to be found!')
+ * ```
  */
 class Err {
   /**
-   * @param {Object} plugin - Plugin instance
+   * @param {Plugin} 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
+   * @param  {...any} [args] - Variables to interpolate with error message. Payload object can be pushed at the very last argument
    */
   constructor (plugin, msg, ...args) {
+    /**
+     * Attached plugin
+     * @type {Plugin}
+     */
     this.plugin = plugin
+
+    /**
+     * The app instance
+     * @type {App}
+     */
+    this.app = plugin.app
+
+    /**
+     * Error payload extracted from the last arguments
+     * @type {Object}
+     */
     this.payload = args.length > 0 && isPlainObject(args[args.length - 1]) ? args[args.length - 1] : {}
+
+    /**
+     * Original message before translation
+     * @type {string}
+     */
     this.orgMessage = msg
-    this.message = this.payload.noTrans ? msg : plugin.print.write(msg, ...args)
+
+    /**
+     * Translated message
+     * @type {string}
+     */
+    this.message = this.payload.noTrans ? msg : this.plugin.t(msg, ...args)
     this.write()
   }
 
   /**
-   * Create the error object
+   * Write message to the console
    *
    * @method
-   * @returns {Object} Error object
+   * @returns {Err} Error object, usefull for chaining
    */
   write = () => {
     let err
@@ -46,20 +78,20 @@ class Err {
       err[key] = value
     }
     if (!isEmpty(values)) err.values = values
-    err.ns = this.plugin.name
+    err.ns = this.plugin.ns
     err.orgMessage = this.orgMessage
     return err
   }
 
   /**
-   * Print error object on screen and terminate app process
+   * Print instance on console and terminate process
    *
    * @method
    */
   fatal = () => {
     const err = this.write()
     console.error(err)
-    process.kill(process.pid, 'SIGINT')
+    this.app.exit()
   }
 
   /**
@@ -70,21 +102,19 @@ class Err {
    * @returns {Object}
    */
   formatErrorDetails = (value) => {
-    const { isString } = this.plugin.app.bajo.lib._
+    const { isString } = this.app.lib._
     const result = {}
     const me = this
     each(value, (v, i) => {
-      const print = me.plugin.print
       if (isString(v)) v = { error: v }
       if (!v.context) return undefined
       v.context.message = v.message
-      // if (v.type === 'any.only') v.context.ref = print.write(`field.${get(v, 'context.valids.0.key')}`)
       if (v.type === 'any.only') v.context.ref = get(v, 'context.valids', []).join(', ')
       const field = get(v, 'context.key')
       const val = get(v, 'context.value')
       value[i] = {
         field,
-        error: print.write(`validation.${v.type}`, v.context ?? {}, {}),
+        error: me.plugin.t(`validation.${v.type}`, v.context ?? {}, {}),
         value: val,
         ext: { type: v.type, context: v.context }
       }

package/class/misc/log.js

@@ -0,0 +1,255 @@
+import os from 'os'
+import logLevels from '../../lib/log-levels.js'
+import chalk from 'chalk'
+import { stripVTControlCharacters } from 'node:util'
+import dayjs from 'dayjs'
+
+/**
+ * Log output in stringified JSON format. Returned when app run in ```prod``` environment
+ *
+ * @typedef TLogJson
+ * @property {string} prefix - Message prefix
+ * @property {string} message - The message itself
+ * @property {string} level - Log level
+ * @property {number} time - Time in millisecond
+ * @property {number} pid - Process ID
+ * @property {string} hostname - Hostname
+ * @property {Object} [data] - Payload data, if any
+ * @see Log#formatMsg
+ */
+
+/**
+ * A thin & fast logger system.
+ *
+ * An instance is created by the {@link App|app} and available to use anywhere like this:
+ *
+ * ```javascript
+ * ... anywhere inside your code
+ * this.app.log.debug(...)
+ * ```
+ *
+ * Shortcuts to log's methods are also available on every Bajo {@link Plugin|plugin}. Call on
+ * these shortcuts will be prefixed with it's plugin name automatically:
+ *
+ * ```javascript
+ * ... anywhere inside your code
+ * if (!isValid) this.log.error('Invalid value!')
+ * ```
+ *
+ * @class
+ */
+class Log {
+  /**
+   * @param {App} app - App instance
+   */
+  constructor (app) {
+    this.lastDelta = 0
+    /**
+     * The app instance
+     * @type {App}
+     */
+    this.app = app
+
+    const { fs } = this.app.lib
+    this.logDir = `${this.app.bajo.dir.data}/log`
+    if (this.app.bajo.config.log.save) fs.ensureDirSync(this.logDir)
+  }
+
+  /**
+   * Display & format message according to one of these rules:
+   * 1. ```level``` ```prefix``` ```text``` ```var 1``` ```var 2``` ```...var n``` - Translate ```text``` and interpolate with ```vars``` for level ```level```
+   * 2. ```level``` ```prefix``` ```data``` ```text``` ```var 1``` ```var 2``` ```...var n``` - As above, and append stringified ```data```
+   * 3. ```level``` ```prefix``` ```error``` - Format as {@link Err} object. If current log level is _trace_, dump it on screen
+   *
+   * In ```prod``` environment, log will be delivered as JSON stringified object. See {@link TLogJson} for more info
+   *
+   * @method
+   * @param {string} level - Log level to use
+   * @param {string} prefix - Prefix to the message
+   * @param {...any} params - See format above
+   * @see Err
+   * @see TLogJson
+   */
+  formatMsg = (level, prefix, ...params) => {
+    const { dayjs } = this.app.lib
+    const { isEmpty, merge, without } = this.app.lib._
+
+    if (this.app.bajo.config.log.level === 'silent') return
+    if (!this.app.bajo.isLogInRange(level)) return
+    const { useUtc, timeTaken, dateFormat, pretty } = this.app.bajo.config.log
+    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.app.t(prefix, msg, ...args)
+    let text
+    const dt = dayjs()
+    let diff = null
+    if (timeTaken) {
+      const delta = dt.diff(this.app.runAt, 'ms')
+      diff = delta - this.lastDelta
+      this.lastDelta = delta
+    }
+    if (this.app.bajo.config.env === 'prod') {
+      const json = { prefix, msg, level: logLevels[level].number, time: dt.valueOf(), pid: process.pid, hostname: os.hostname() }
+      if (!isEmpty(data)) merge(json, { data })
+      if (timeTaken) merge(json, { timeTaken: diff })
+      text = JSON.stringify(json)
+    } else {
+      let date = dt.clone()
+      if (useUtc) date = dayjs.utc(dt)
+      date = date.format(dateFormat)
+      let tdate = pretty ? chalk.cyan(date) : `[${date}]`
+      if (timeTaken) {
+        const tdiff = pretty ? chalk.cyan(`+${diff}ms`) : `[+${diff}ms]`
+        tdate += ` ${tdiff}`
+      }
+      const tlevel = pretty ? `${chalk[logLevels[level].color](level.toUpperCase())}:` : `[${level.toUpperCase()}]`
+      const tprefix = pretty ? chalk.bgBlue(`${prefix}`) : `[${prefix}]`
+      text = `${tdate} ${tlevel} ${tprefix} ${msg}`
+      if (!isEmpty(data)) text += '\n' + JSON.stringify(data)
+    }
+    console.log(text)
+    if (data instanceof Error && level === 'trace') console.error(data)
+    if (this.app.bajo.config.log.save) this.save(text, prefix)
+  }
+
+  /**
+   * Calculate pattern used for log rotation
+   *
+   * @method
+   * @param {boolean} isPrev - If true, calculate previous rotation pattern
+   * @returns {string} Calculated pattern
+   */
+  getRotationPattern = (isPrev) => {
+    const { dayjs } = this.app.lib
+    const { cycle } = this.app.bajo.config.log.rotation
+    if (cycle === 'none') return
+    let pattern
+    const now = dayjs()
+    switch (cycle) {
+      case 'monthly': {
+        const dt = isPrev ? now.subtract(1, 'month') : now
+        pattern = dt.format('YYYY-MM')
+        break
+      }
+      case 'weekly': {
+        const dt = isPrev ? now.subtract(1, 'week') : now
+        pattern = dt.format(`YYYY-W${dt.week()}`)
+        break
+      }
+      case 'daily': {
+        const dt = isPrev ? now.subtract(1, 'day') : now
+        pattern = dt.format('YYYY-MM-DD')
+        break
+      }
+    }
+    return pattern
+  }
+
+  /**
+   * Save log to file in {dataDir}/log
+   *
+   * @method
+   * @param {string} text - Log message to save
+   * @param {string} prefix - Use prefix as basename. Defaults to 'bajo'
+   */
+  save = (text, prefix = 'bajo') => {
+    const { fs } = this.app.lib
+    let fname = this.app.bajo.config.log.rotation.byPlugin ? prefix : 'bajo'
+    let file = `${this.logDir}/${fname}.log`
+    const content = stripVTControlCharacters(text)
+    const pattern = this.getRotationPattern()
+    if (pattern) {
+      file = `${this.logDir}/${fname}.${pattern}.log`
+    }
+    fs.appendFileSync(file, `${content}\n`, 'utf8')
+    // TODO: symlink bajo.log to target
+  }
+
+  /**
+   * Display & format message in ```trace``` level. See {@link Log#formatMsg|formatMsg} for details
+   *
+   * @method
+   * @param {string} prefix - Message prefix
+   * @param {...any} params - Parameters
+   */
+  trace = (prefix, ...params) => {
+    this.formatMsg('trace', prefix, ...params)
+  }
+
+  /**
+   * Display & format message in ```debug``` level. See {@link Log#formatMsg|formatMsg} for details
+   *
+   * @method
+   * @param {string} prefix - Message prefix
+   * @param {...any} params - Parameters
+   */
+  debug = (prefix, ...params) => {
+    this.formatMsg('debug', prefix, ...params)
+  }
+
+  /**
+   * Display & format message in ```info``` level. See {@link Log#formatMsg|formatMsg} for details
+   *
+   * @method
+   * @param {string} prefix - Message prefix
+   * @param {...any} params - Parameters
+   */
+  info = (prefix, ...params) => {
+    this.formatMsg('info', prefix, ...params)
+  }
+
+  /**
+   * Display & format message in ```warn``` level. See {@link Log#formatMsg|formatMsg} for details
+   *
+   * @method
+   * @param {string} prefix - Message prefix
+   * @param {...any} params - Parameters
+   */
+  warn = (prefix, ...params) => {
+    this.formatMsg('warn', prefix, ...params)
+  }
+
+  /**
+   * Display & format message in ```error``` level. See {@link Log#formatMsg|formatMsg} for details
+   *
+   * @method
+   * @param {string} prefix - Message prefix
+   * @param {...any} params - Parameters
+   */
+  error = (prefix, ...params) => {
+    this.formatMsg('error', prefix, ...params)
+  }
+
+  /**
+   * Display & format message in ```fatal``` level. See {@link Log#formatMsg|formatMsg} for details
+   *
+   * @method
+   * @param {string} prefix - Message prefix
+   * @param {...any} params - Parameters
+   */
+  fatal = (prefix, ...params) => {
+    this.formatMsg('fatal', prefix, ...params)
+  }
+
+  /**
+   * Display & format message in ```silent``` level. See {@link Log#formatMsg|formatMsg} for details
+   *
+   * @method
+   * @param {string} prefix - Message prefix
+   * @param {...any} params - Parameters
+   */
+  silent = (prefix, ...params) => {
+    this.formatMsg('silent', prefix, ...params)
+  }
+}
+
+export default Log