bajo 2.22.0 → 2.24.0

package/lib/helper.js

@@ -7,12 +7,14 @@ import semver from 'semver'
 import aneka from 'aneka/index.js'
 import outmatch from 'outmatch'
 import fastGlob from 'fast-glob'
+import * as readline from 'readline/promises'
 import { sprintf } from 'sprintf-js'
 import dayjs from 'dayjs'
 import utc from 'dayjs/plugin/utc.js'
 import customParseFormat from 'dayjs/plugin/customParseFormat.js'
 import localizedFormat from 'dayjs/plugin/localizedFormat.js'
 import weekOfYear from 'dayjs/plugin/weekOfYear.js'
+import defConfig from './config.js'
 const { resolvePath } = aneka
 const {
   isFunction, isPlainObject, cloneDeep, merge, forOwn, groupBy, find, reduce, map,
@@ -21,74 +23,40 @@ const {
 } = lodash
 
 /**
+ * # Helper
+ *
  * Internal helpers called by Bajo and other classes. It should remains
- * hidden and not to be imported by any program.
+ * hidden and not to be imported by any program. It listed here for documentation purpose only.
  *
  * @module Helper
  */
 
 const omitted = ['spawn', 'cwd', 'name', 'alias', 'applet', 'a', 'plugins']
 
-const defConfig = {
-  env: 'dev',
-  runtime: {
-    noWarning: false
-  },
-  log: {
-    timeTaken: false,
-    dateFormat: 'YYYY-MM-DDTHH:mm:ss.SSS',
-    useUtc: false,
-    pretty: false,
-    applet: false,
-    traceHook: false,
-    save: false,
-    rotation: {
-      cycle: 'none', // none, daily, weekly, monthly
-      compressOld: true,
-      byPlugin: false,
-      retain: 5
-    }
-  },
-  dump: {
-    depth: 2,
-    compact: false,
-    colors: true,
-    breakLength: 80,
-    caller: true,
-    frame: {
-      titleAllignment: 'center',
-      padding: 1,
-      margin: 1,
-      borderStyle: 'round'
-    }
-  },
-  lang: Intl.DateTimeFormat().resolvedOptions().lang ?? 'en-US',
-  intl: {
-    supported: ['en-US', 'id'],
-    fallback: 'en-US',
-    lookupOrder: [],
-    format: {
-      emptyValue: '',
-      datetime: { dateStyle: 'medium', timeStyle: 'short', timeZone: 'UTC' },
-      date: { dateStyle: 'medium', timeZone: 'UTC' },
-      time: { timeStyle: 'short', timeZone: 'UTC' },
-      float: { maximumFractionDigits: 2 },
-      double: { maximumFractionDigits: 5 },
-      smallint: {},
-      integer: {}
-    },
-    unitSys: {
-      'en-US': 'imperial',
-      id: 'metric'
-    }
-  },
-  exitHandler: true,
-  cache: {
-    purge: [],
-    purgeIntvDur: '5m'
-  }
-}
-
+/**
+ * Main plugin class. This is the special plugin created by Bajo during the boot process, solely made
+ * for you to write your own code for your application. It behaves like any other plugin, with a few differences:
+ *
+ * - It always there, can't be disabled nor removed, reside in the app's root directory named `main`.
+ *   If it's folder is missing, Bajo will create it during the boot process with the default template and settings.
+ * - You don't have to put this plugin in your `.plugin` file or `package.json` file,
+ *   it is always present and always loaded as the **last** plugin to load.
+ * - You write your app the same way you would do it with plugin:
+ *   - by creating properties & methods within your class
+ *   - by extending other plugins inside `/main/extend/{pluginNs}` folder
+ *   - by tapping hooks inside `/main/extend/bajo/hook` folder or `/main/extend/bajo/hook.js` file
+ *   - you even have your own config file in `{dataDir}/config/main.{ext}`
+ *
+ * Why it has to be a plugin? Because Bajo is a plugin-based framework, and everything is a plugin.
+ * This brings some flexibilities, e.g. when someday you think your main plugin become too big,
+ * just turn it into a separate plugin and move it to its own package with almost no code changes at all.
+ *
+ * For more on this, see {@link Plugin} and {@link module:Hook}
+ *
+ * @class
+ * @global
+ * @name Main
+ */
 const defMain = `async function factory (pkgName) {
   const me = this
 
@@ -103,7 +71,19 @@ const defMain = `async function factory (pkgName) {
 export default factory
 `
 
-function outmatchNs (source, pattern) {
+/**
+ * Outmacth with support for scoped source and pattern. Scoped source/pattern is a source/pattern that has a plugin's namespace prefix,
+ * separated by `:` symbol.
+ *
+ * This function is usefull for matching a source/pattern that is scoped to a specific plugin's namespace.
+ * For example, if you have a source `myPlugin:foo/bar` and a pattern `myPlugin:foo/*`,
+ * this function will return `true` because the source matches the pattern within the same namespace.
+ *
+ * @param {string} source - Scoped source to match against the pattern. It should be in the format of `ns:path`
+ * @param {string} pattern - Scoped pattern to match against the source. It should be in the format of `ns:path`
+ * @returns {boolean} Returns `true` if the source matches the pattern, otherwise `false`.
+ */
+export function outmatchNs (source, pattern) {
   const { breakNsPath } = this.bajo
   const [src, subSrc] = source.split(':')
   if (!subSrc) return pattern === src
@@ -116,7 +96,20 @@ function outmatchNs (source, pattern) {
   }
 }
 
-function parseObject (obj, options = {}) {
+/**
+ * Parse object and normalize their values.
+ *
+ * Support automatic value translation for keys with `t:` prefix. The keys are then
+ * converted to the one without the `t:` prefix, and the original key is removed from the object.
+ *
+ * See {@link https://ardhi.github.io/aneka/global.html#parseObject|aneka.parseObject()} for more details.
+ *
+ * @method
+ * @param {*} obj - The object to parse and normalize.
+ * @param {object} [options={}] - Options for parsing and translation.
+ * @returns {object} The parsed and normalized object.
+ */
+export function parseObject (obj, options = {}) {
   const me = this
   const { ns = 'bajo', lang } = options
   options.translator = {
@@ -137,6 +130,15 @@ dayjs.extend(localizedFormat)
 dayjs.extend(weekOfYear)
 
 /**
+ * Most commonly used libraries by Bajo and its plugins. They are already imported and ready to use,
+ * so you don't have to import them again in your plugin.
+ *
+ * Example:
+ * ```javascript
+ * const { fs, dayjs } = this.app.lib
+ * fs.ensureDirSync('/path/to/dir')
+ * const now = dayjs().format('YYYY-MM-DD HH:mm:ss')
+ * ```
  * @typedef {Object} TLib
  * @memberof App
  * @property {Object} _ Access to {@link https://lodash.com|lodash}.
@@ -146,8 +148,11 @@ dayjs.extend(weekOfYear)
  * @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
+ * @property {Object} freeze Freeze object. See {@link module:Helper.freeze|freeze} for more details.
+ * @property {Object} findDeep Deep file file in an array of files. See {@link module:Helper.findDeep|findDeep} for more details.
+ * @property {Object} outmatchNs Like outmatch, but support scoped source & pattern. See {@link module:Helper.outmatchNs|outmatchNs} for more details.
+ * @property {Object} parseObject Parse object and normalize their values. Also support translation. See {@link module:Helper.parseObject|parseObject} for more details.
+ * @property {Object} [anekaSpatial] Access to {@link https://ardhi.github.io/bajo-spatial|aneka-spatial} helpers if `bajoSpatial` plugin is loaded.
  * @see App
  */
 export const lib = {
@@ -164,27 +169,49 @@ export const lib = {
   parseObject
 }
 
+export async function ask (question, ...args) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+  let answer
+  try {
+    answer = await rl.question(this.t(question, ...args))
+  } catch (err) {
+    console.error(err)
+  } finally {
+    rl.close()
+  }
+  return answer
+}
+
 /**
- * Building bajo base config. Mostly dealing with directory setups:
- * - determine base directory
- * - check whether data directory is valid. If not exist, create one inside app dir
- * - ensure data config directory is there
- * - ensure tmp dir is there
- * - read the list of plugins from ```.plugins``` file
+ * Build base configuration object for Bajo. This function is called by Bajo during the {@link Bajo#init|initialization process}:
+ * - it sets up the base directory,
+ * - it checks the validity of the data directory,
+ * - it ensures the temporary directory exists,
+ * - it reads the list of used plugins from the `package.json`, `.plugins` file or command line options.
  *
  * @async
  * @method
  */
 export async function buildBaseConfig () {
-  // dirs
   const { defaultsDeep, textToArray, currentLoc, resolvePath } = this.app.lib.aneka
-  this.config = defaultsDeep({}, this.app.argv._, this.app.envVars._)
+  // dirs
+  this.config = defaultsDeep({}, this.app.envVars._, this.app.argv._)
   set(this, 'dir.base', this.app.dir)
   const path = currentLoc(import.meta).dir + '/..'
   set(this, 'dir.pkg', resolvePath(path))
   if (get(this, 'config.dir.data')) set(this, 'dir.data', this.config.dir.data)
   if (!get(this, 'dir.data')) set(this, 'dir.data', `${this.dir.base}/data`)
   this.dir.data = resolvePath(this.dir.data)
+  if (!fs.existsSync(this.dir.data)) {
+    console.error("Data directory does not exist: '%s'", this.dir.data)
+    let answer
+    do {
+      answer = await ask.call(this, 'Create one now? (y/n) ', this.dir.data)
+      answer = answer.trim().toLowerCase()
+    } while (!['y', 'n'].includes(answer))
+    if (answer === 'n') this.app.exit(true, 'Aborted')
+    fs.ensureDirSync(this.dir.data)
+  }
   fs.ensureDirSync(`${this.dir.data}/config`)
   if (!this.dir.tmp) {
     this.dir.tmp = `${resolvePath(os.tmpdir())}/${this.ns}`
@@ -192,8 +219,8 @@ export async function buildBaseConfig () {
   }
   this.pkg = await this.getPkgInfo()
   let pluginPkgs = this.app.pluginPkgs
+  // collect list of plugins
   if (isEmpty(pluginPkgs)) {
-    // collect list of plugins
     const mainPkg = await this.getPkgInfo(this.app.dir)
     pluginPkgs = get(mainPkg, 'bajo.plugins', [])
     if (isEmpty(pluginPkgs)) {
@@ -208,12 +235,12 @@ export async function buildBaseConfig () {
 }
 
 /**
- * Building all plugins:
- * - load from app's pluginPkgs
- * - iterate through the list and build related plugins
- * - making sure main plugin is there. If not, create from template
- * - attach these plugins to the app instance
+ * Load, build and sanitize all plugins defined in `package.json` or `.plugins` file, and add them to the app's plugin list.
+ * It will also make sure the `main` plugin is there too, if not, it will be created with the default template and settings.
  *
+ * Finally, it will loop through all loaded plugins and its config and language files.
+ *
+ * This function is called by Bajo during the {@link Bajo#init|initialization process}.
  * @async
  */
 export async function buildPlugins () {
@@ -241,12 +268,17 @@ export async function buildPlugins () {
     this.app.addPlugin(plugin, ClassDef)
     this.log.trace('- ' + pkg)
   }
+  // load all plugins' config & language files
+  for (const ns of this.app.getAllNs()) {
+    await this.app[ns].loadConfig()
+    this.app[ns].print = new Print(this.app[ns])
+    this.app.loadIntl(ns)
+  }
   this.log.debug('buildPluginsComplete')
 }
 
 /**
- * Collect all config handlers, including the one provided by plugins
- *
+ * Collect all plugins' config handlers and push them to the app's {@link App#configHandlers|configHandlers} array.
  * @async
  */
 export async function collectConfigHandlers () {
@@ -267,14 +299,17 @@ export async function collectConfigHandlers () {
 }
 
 /**
- * Bajo extra config:
- * - reading config file
- * - merge config with arguments & environments values
- * - Set environment (```dev``` or ```prod```)
+ * Building Bajo configuration object. Called after all config handlers are collected,
+ * this function will read config files written in any of config handlers' supported formats:
+ * - if runtime configuration object is provided (the one passed to the app constructor), it will be
+ *   used as the base. Otherwise, files are read from the `{dataDir}/config`
+ * - then it will be merged with the configuration coming from the command line arguments and environment variables
+ * - doing some normalization and validation works, including setting the language, environment, log level, and cache purge settings
+ * - and setting up the app's log instance with the proper log level
  *
  * @async
  */
-export async function buildExtConfig () {
+export async function buildConfig () {
   // config merging
   const { defaultsDeep, includes } = this.app.lib.aneka
   const { parseObject } = this.app.lib
@@ -320,7 +355,8 @@ export async function buildExtConfig () {
 }
 
 /**
- * Setup plugins boot orders by reading plugin's ```.bootorder``` file if provided.
+ * Determine the boot order of plugins based on their `bajo.bootorder` property in their `package.json` file.
+ * If not provided, the plugin will be booted in the order they are listed in the `package.json` file or `.plugins` file.
  *
  * @async
  */
@@ -348,50 +384,36 @@ export async function bootOrder () {
 }
 
 /**
- * Build configurations
- *
- * @async
- */
-export async function buildConfigs () {
-  this.bajo.log.debug('readConfigs')
-  for (const ns of this.getAllNs()) {
-    await this[ns].loadConfig()
-    this[ns].print = new Print(this[ns])
-    this.loadIntl(ns)
-  }
-}
-
-/**
- * Ensure for names and aliases to be unique and no clashes with other plugins
- *
+ * Ensure the uniqueness of all plugins' name and alias. If there is a clash, an error will be thrown.
  * @async
  */
 export async function checkNameAliases () {
-  this.bajo.log.debug('checkAliasNameClash')
+  this.log.debug('checkAliasNameClash')
   const refs = []
-  for (const pkg of this.bajo.app.pluginPkgs) {
-    const plugin = this.bajo.app[camelCase(pkg)]
+  for (const pkg of this.app.pluginPkgs) {
+    const plugin = this.app[camelCase(pkg)]
     const { ns, alias } = plugin
     let item = find(refs, { ns })
-    if (item) throw this.bajo.error('pluginNameClash%s%s%s%s', ns, pkg, item.ns, item.pkg, { code: 'BAJO_NAME_CLASH' })
+    if (item) throw this.error('pluginNameClash%s%s%s%s', ns, pkg, item.ns, item.pkg, { code: 'BAJO_NAME_CLASH' })
     item = find(refs, { alias })
-    if (item) throw this.bajo.error('pluginNameClash%s%s%s%s', alias, pkg, item.alias, item.pkg, { code: 'BAJO_ALIAS_CLASH' })
+    if (item) throw this.error('pluginNameClash%s%s%s%s', alias, pkg, item.alias, item.pkg, { code: 'BAJO_ALIAS_CLASH' })
     refs.push({ ns, alias, pkg })
   }
 }
 
 /**
- * Ensure dependencies are met
+ * Ensure all plugins' dependencies are met. If there is a missing dependency, an error will be thrown.
  *
+ * Semver is also supported, so if a plugin requires a specific version of another plugin, it will be checked as well.
  * @async
  */
 export async function checkDependencies () {
-  const { join } = this.bajo
-  this.bajo.log.debug('checkDeps')
-  for (const pkg of this.bajo.app.pluginPkgs) {
-    const plugin = this.bajo.app[camelCase(pkg)]
+  const { join } = this
+  this.log.debug('checkDeps')
+  for (const pkg of this.app.pluginPkgs) {
+    const plugin = this.app[camelCase(pkg)]
     const { ns, dependencies } = plugin
-    this.bajo.log.trace('- %s', ns)
+    this.log.trace('- %s', ns)
     const odep = reduce(dependencies, (o, k) => {
       const item = map(k.split('@'), m => trim(m))
       if (k[0] === '@') o['@' + item[1]] = item[2]
@@ -400,15 +422,15 @@ export async function checkDependencies () {
     }, {})
     const deps = keys(odep)
     if (deps.length > 0) {
-      if (intersection(this.bajo.app.pluginPkgs, deps).length !== deps.length) {
-        throw this.bajo.error('dependencyUnfulfilled%s%s', pkg, join(deps), { code: 'BAJO_DEPENDENCY' })
+      if (intersection(this.app.pluginPkgs, deps).length !== deps.length) {
+        throw this.error('dependencyUnfulfilled%s%s', pkg, join(deps), { code: 'BAJO_DEPENDENCY' })
       }
       each(deps, d => {
         if (!odep[d]) return
-        const ver = get(this.bajo.app[camelCase(d)], 'pkg.version')
+        const ver = get(this.app[camelCase(d)], 'pkg.version')
         if (!ver) return
         if (!semver.satisfies(ver, odep[d])) {
-          throw this.bajo.error('semverCheckFailed%s%s', pkg, `${d}@${odep[d]}`, { code: 'BAJO_DEPENDENCY_SEMVER' })
+          throw this.error('semverCheckFailed%s%s', pkg, `${d}@${odep[d]}`, { code: 'BAJO_DEPENDENCY_SEMVER' })
         }
       })
     }
@@ -416,15 +438,14 @@ export async function checkDependencies () {
 }
 
 /**
- * Collect and build hooks and push them to the bajo's hook system
- *
+ * Collect all plugins' hooks and push them to the app's {@link App#hooks|hooks} array.
  * @async
  */
 export async function collectHooks () {
-  const { eachPlugins, runHook, isLogInRange, importModule } = this.bajo
-  const { isArray, isPlainObject } = this.lib._
-  const me = this // "this" is "app"
-  me.bajo.log.trace('collecting%s', this.t('hooks'))
+  const { eachPlugins, runHook, isLogInRange, importModule } = this
+  const { isArray, isPlainObject } = this.app.lib._
+  const me = this // "this" is "bajo"
+  this.log.trace('collecting%s', this.t('hooks'))
   await eachPlugins(async function ({ dir, file }) {
     let mod = await importModule(file, { asHandler: true })
     if (!mod) return undefined
@@ -435,11 +456,11 @@ export async function collectHooks () {
         if (!m.name) throw me.bajo.error('missing%s%s', 'name', file)
         if (isArray(m.name)) {
           for (const name of m.name) {
-            me.bajo.hooks.push(merge({}, m, { name, src: this.ns }))
+            me.hooks.push(merge({}, m, { name, src: this.ns }))
           }
         } else {
           m.src = this.ns
-          me.bajo.hooks.push(m)
+          me.hooks.push(m)
         }
       }
     } else {
@@ -449,81 +470,55 @@ export async function collectHooks () {
       for (let name of names) {
         name = name.split('.').map(n => camelCase(n)).join('.')
         const m = merge({}, mod, { name: `${name}:${camelCase(path)}`, src: this.ns })
-        me.bajo.hooks.push(m)
+        me.hooks.push(m)
       }
     }
-  }, { glob: ['hook/*.js', 'hook.js'], prefix: me.bajo.ns })
+  }, { glob: ['hook/*.js', 'hook.js'], prefix: this.ns })
   // for log trace purpose only
   if (isLogInRange('trace')) {
-    const items = groupBy(me.bajo.hooks, item => item.name)
+    const items = groupBy(this.hooks, item => item.name)
     forOwn(items, (v, k) => {
       const [name, path] = k.split(':')
-      me.bajo.log.trace('- %s:%s (%d)', name, path, v.length)
+      this.log.trace('- %s:%s (%s)', name, path, v.length)
     })
   }
 
-  await runHook('bajo:afterCollectHooks', this.bajo.hooks)
-  me.bajo.log.debug('collected%s%d', this.t('hooks'), me.bajo.hooks.length)
+  await runHook('bajo:afterCollectHooks', this.hooks)
+  this.log.debug('collected%s%d', this.t('hooks'), this.hooks.length)
 }
 
 /**
- * Finally, run all plugins
+ * Run all loaded plugins' `init()` and `start()` methods in the order determined previously during boot process.
  *
  * @async
- * @see module:Hook~bajo:beforeAllInit
- * @see module:Hook~{ns}:beforeInit
- * @see module:Hook~{ns}:afterInit
- * @see module:Hook~bajo:afterAllInit
- * @see module:Hook~bajo:beforeAllStart
- * @see module:Hook~{ns}:beforeStart
- * @see module:Hook~{ns}:afterStart
- * @see module:Hook~bajo:afterAllStart
+ * @see module:Hook
  */
-export async function run () {
+export async function runPlugins () {
   const me = this
-  const { runHook, eachPlugins, join } = me.bajo
-  const { freeze } = me.lib
+  const { runHook, eachPlugins, join } = this
+  const { freeze } = this.app.lib
   const methods = ['init']
-  if (!me.applet) methods.push('start')
+  if (!this.app.applet) methods.push('start')
   for (const method of methods) {
     await runHook(`bajo:${camelCase(`before all ${method}`)}`)
     await eachPlugins(async function () {
       const { ns } = this
       await runHook(`${ns}:${camelCase(`before ${method}`)}`)
-      await me[ns][method]()
+      await me.app[ns][method]()
       await runHook(`${ns}:${camelCase(`after ${method}`)}`)
-      if (method === 'start') freeze(me[ns].config)
+      if (method === 'start') freeze(me.app[ns].config)
     })
     await runHook(`bajo:${camelCase(`after all ${method}`)}`)
   }
-  if (me.bajo.config.log.level === 'trace') {
-    let text = join(map(me.bajo.app.pluginPkgs, b => camelCase(b)))
-    text += ` (${me.bajo.app.pluginPkgs.length})`
-    me.bajo.log.trace('loadedPlugins%s', text)
-  } else me.bajo.log.debug('loadedPlugins%s', me.bajo.app.pluginPkgs.length)
-}
-
-/**
- * Iterate through all plugins loaded and do:
- *
- * 1. {@link module:Helper/Base.buildConfigs|build configs}
- * 2. {@link module:Helper/Base.checkNameAliases|ensure names & aliases uniqueness}
- * 3. {@link module:Helper/Base.checkDependencies|ensure dependencies are met}
- * 4. {@link module:Helper/Base.collectHooks|collect hooks}
- * 5. {@link module:Helper/Base.run|run plugins}
- *
- * @async
- */
-export async function bootPlugins () {
-  await buildConfigs.call(this.app)
-  await checkNameAliases.call(this.app)
-  await checkDependencies.call(this.app)
-  await collectHooks.call(this.app)
-  await run.call(this.app)
+  if (this.config.log.level === 'trace') {
+    let text = join(map(this.app.pluginPkgs, b => camelCase(b)))
+    text += ` (${this.app.pluginPkgs.length})`
+    this.log.trace('loadedPlugins%s', text)
+  } else this.log.debug('loadedPlugins%s', this.app.pluginPkgs.length)
 }
 
 /**
- * Attach plugins exit handlers and make sure the app shutdowns gracefully
+ * Attach plugins exit handlers to make sure when the app shuts down, all plugins shut down gracefully first
  *
  * @async
  */
@@ -531,15 +526,14 @@ export async function exitHandler () {
   if (!this.config.exitHandler) return
 
   async function exit (signal) {
-    const { eachPlugins } = this
     if (signal) this.log.warn('signalReceived%s', signal)
-    const me = this
-    await eachPlugins(async function ({ ns }) {
+    const allNs = this.app.getAllNs().reverse()
+    for (const ns of allNs) {
       try {
-        await this.exit()
+        await this.app[ns].exit()
       } catch (err) {}
-      me.log.trace('exited%s', this.ns)
-    })
+      this.log.trace('exited%s', ns)
+    }
     this.log.debug('appShutdown')
     process.exit(0)
   }
@@ -585,11 +579,10 @@ export async function exitHandler () {
 }
 
 /**
- * If app is in ```applet``` mode, this little helper should take care plugin's applet boot process
+ * If app is in `applet` mode, this little helper should take care plugin's applet boot process
  *
  * @async
- * @fires {ns}:beforeAppletRun
- * @fires {ns}:afterAppletRun
+ * @see module:Applet
  */
 export async function runAsApplet () {
   const { isString, map, find } = this.app.lib._
@@ -622,27 +615,27 @@ export async function runAsApplet () {
  * Import file/module from any loaded plugins.
  *
  * E.g. your plugin structure looks like this:
- * ```
+ * `
  * |- src
  * |  |- lib
  * |  |  |- my-module.js
  * |- index.js
  * |- package.json
- * ```
+ * `
  *
- * And this is how to import ```my-module.js```:
- * ```javascript
+ * And this is how to import `my-module.js`:
+ * `javascript
  * const { importModule } = this.app.bajo
  * const myModule = await importModule('myPlugin:/src/lib/my-module.js')
- * ```
+ * `
  *
  * @method
  * @async
  * @param {TNsPathPairs} file File to import.
  * @param {Object} [options={}] Options.
- * @param {boolean} [options.asDefaultImport=true] If ```true``` (default), return default imported module.
- * @param {boolean} [options.asHandler] If ```true```, return as a {@link HandlerType|handler}.
- * @param {boolean} [options.noCache] If ```true```, always import as a fresh copy.
+ * @param {boolean} [options.asDefaultImport=true] If `true` (default), return default imported module.
+ * @param {boolean} [options.asHandler] If `true`, return as a {@link HandlerType|handler}.
+ * @param {boolean} [options.noCache] If `true`, always import as a fresh copy.
  * @returns {any}
  * @see Bajo#importModule
  */
@@ -658,6 +651,7 @@ export async function importModule (file, { asDefaultImport = true, asHandler, n
   if (this) file = this.app.getPluginFile(file)
   if (!fs.existsSync(file)) return
   let mod = await load(file, asDefaultImport, noCache)
+  if (!mod) return
   if (!asHandler) return mod
   if (isFunction(mod)) mod = { level: 999, handler: mod }
   if (!isPlainObject(mod)) {
@@ -672,7 +666,7 @@ export async function importModule (file, { asDefaultImport = true, asHandler, n
  *
  * @method
  * @param {Object} obj Object to freeze.
- * @param {boolean} [shallow=false] If ```false``` (default), deep freeze object.
+ * @param {boolean} [shallow=false] If `false` (default), deep freeze object.
  */
 export function freeze (obj, options = {}) {
   const { shallow = false, clone = false } = options

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "bajo",
-  "version": "2.22.0",
+  "version": "2.24.0",
   "description": "The ultimate framework for whipping up massive apps in no time",
   "main": "index.js",
   "scripts": {
     "build-doc": "jsdoc -c .jsdoc.conf.json",
-    "test": "mocha --recursive"
+    "test": "mocha --recursive",
+    "coverage": "c8 --all --include=class/**/*.js --include=lib/**/*.js --include=index.js --reporter=text --reporter=lcov mocha --recursive",
+    "coverage:html": "c8 report --reporter=html",
+    "coverage:check": "c8 --check-coverage --lines 90 --functions 80 --branches 55 --statements 90 mocha --recursive"
   },
   "type": "module",
   "repository": {
@@ -38,6 +41,7 @@
     "semver": "^7.8.5"
   },
   "devDependencies": {
+    "c8": "^12.0.0",
     "chai": "^6.2.1",
     "clean-jsdoc-theme": "^4.3.0",
     "docdash": "^2.0.2",