bajo 2.0.1 → 2.1.0

package/wiki/USER-GUIDE.md

@@ -0,0 +1,256 @@
+# User Guide
+
+## Overview
+
+### Definitions
+
+Before proceeding, familiarize yourself with these terminologies used throughout this documentation:
+
+1. ```{appDir}```: The application's project directory where all your code residese.
+2. ```{dataDir}```: The directory for all data; defaults to ```{appDir}/data``` and is created automatically if missing.
+3. ```{tmpDir}```: The temporary directory, defaults to the OS temporary directory.
+4. ```{pkgName}```: The plugin's package name, typically matching its npm listing.
+5. ```{ns}```: The plugin name or namespace, which is the camel-cased version of the package name.
+6. ```{mainNs}```: The special main namespace and directory named main within your ```{appDir}```; this is where all application code should be written.
+
+### Directory Structure
+
+Your typical Bajo app directory structure should look like this:
+
+```
+.
+└── {appDir}
+    ├── {dataDir}
+    │   ├── config
+    │   │   ├── .plugin
+    │   │   ├── bajo.json
+    │   │   ├── main.json
+    │   │   └── ...
+    │   └── plugins
+    │       └── ...
+    ├── main
+    │   ├── extend
+    │   │   └── ...
+    │   ├── index.js
+    │   └── ...
+    ├── package.json
+    ├── index.js
+    └── ...
+```
+
+1. You can move ```{dataDir}``` out of ```{appDir}``` if you want, but you need to tell Bajo where to find it. For more on this, please follow along.
+2. ```{dataDir}``` should be the only place Bajo **writes** anything. Bajo and its plugins should **never** be allowed to write anything outside ```{dataDir}``` on their own.
+3. ```config``` is a special directory within ```{dataDir}``` where your configuration files should reside. Inside this directory, you should find:
+   - a special file named ```.plugins``` that tells Bajo which plugins should be loaded
+   - a file named ```bajo.json``` to configure global settings
+   - all plugin-specific config files, named after their namespace
+4. The ```main``` directory, or ```{mainNs}``` namespace, is the special plugin where you put your application code. And yes, it is actually a normal Bajo plugin! This means everything in there will be handled just like a regular plugin—it has the ability to extend other plugins, has its own config file, and more — with a few differences:
+   - it's always available and can't be disabled
+   - it's always the last one to start
+   - if this directory is missing, it will be created automatically on startup
+   - if the plugin's factory function is missing (```index.js```), it will be created dynamically
+5. ```index.js``` is the main entry point for your app.
+
+To set your ```{dataDir}``` somewhere else, you need to tell Bajo where to find it by using an argument switch.
+
+Assuming your data directory is ```my-data-dir``` at the same level as your app directory, run your app like this:
+
+```bash
+$ node index.js --dir-data=../my-data-dir
+```
+
+If using program arguments seems a bit like a hassle for you, just use Bajo's [dotenv](https://github.com/motdotla/dotenv) support. Create a ```.env``` file in your app directory and put this inside:
+
+```text
+DIR__DATA=../my-data-dir              # double underscores!!!
+```
+
+From now on, you can start the app just by typing:
+
+```bash
+$ node index.js
+```
+
+### Runtime
+
+Bajo should run perfectly fine on Node.js version 20 or higher. Using the latest stable runtime is recommended. Bajo-based apps are also known to run with **Bun** without any problems. But Bajo **cannot** run on Deno due to its heavy reliance on Node.js-specific libraries and environments. 
+
+Bajo is a pure ES6 framework that utilizes dynamic imports ```a lot```. Running on a system with a fast disk (e.g., SSD) and enough RAM is highly recommended, especially when you load a lot of plugins.
+
+## Configuration
+
+### General Rules
+
+- All configuration files must be placed in the ```{dataDir}/config``` subfolder.
+- Config files must be named after their plugin namespace.
+- The file format should be either ```.json``` or ```.js```. If a ```.js``` file is used, it must be in ES6 format and should export either a plain JavaScript object or a function. Both synchronous and asynchronous functions are supported. If it returns a function, this function will be called within its plugin scope and should return a plain JS object.
+- Other formats (```.yml```, ```.yaml```, and ```.toml```) can also be used by installing and loading the [bajoConfig](https://github.com/ardhi/bajo-config) plugin.
+- Other formats (```.yml```, ```.yaml``` and ```.toml```) can also be used by installing & loading [bajoConfig](https://github.com/ardhi/bajo-config) plugin
+- The order of precedence is ```.js``` > ```.json``` > ```.yml``` > ```.yaml``` > ```.toml```. This means that if a .js file exists, it will be used instead of a .json file or any other format.
+
+Example: bajo.json
+```json
+{
+  "env": "prod",
+  "log": {
+    "pretty": true,
+    "timeTaken": true
+  },
+  "lang": "id"
+}
+```
+
+### Using Plugins
+
+Plugins are what make the Bajo Framework so great and flexible: they extend app features and functionalities!
+
+To use plugins, follow these steps:
+
+1. Install it with ```npm install {package}```, where ```{package}``` is the plugin's package name. You can install as many plugins as you want; for a complete list of plugins, please [click here](ecosystem.md).
+2. Optionally, create ```{dataDir}/config/{ns}.json``` to customize the plugin's settings, where ```{ns}``` is the namespace or plugin name.
+3. Open or create ```{dataDir}/config/.plugins``` and list the plugin's ```{package}``` name in it, one per line.
+
+For example, the text below will load ```bajo-config```, ```bajo-extra```, and ```bajo-template```:
+
+```text
+# .plugin file
+bajo-config
+bajo-extra
+bajo-template
+```
+
+If you later decide to disable one or more plugins, you just need to remove them from the ```.plugins``` file or place a ```#``` hash mark in front of the package name and restart your app.
+
+> **Warning**: Please do not confuse ```{package}``` and ```{ns}```. The plugin package is the name of the JS package listed on npm, while ```{ns}``` is the namespace or plugin name, which is basically the camel-cased version of the plugin's package name.
+
+### Environment Support
+
+Configuration file support for different environments is also available. All you need to do is create a ```{ns}-{env}.json``` file in your ```{dataDir}/config```, where:
+
+- ```{ns}```: the namespace/plugin name
+- ```{env}```: your desired environment (```dev``` or ```prod```)
+- App-wide settings with ```bajo-{env}.json``` are also possible.
+
+Bajo is smart enough to select which config file will be used based on the following order of precedence:
+
+1. Use ```{ns}-{env}.json``` if the file exists.
+2. If not, use ```{ns}.json```.
+3. If that also doesn't exist, then use the plugin's default config values.
+
+### Runtime Override
+
+You can easily override ANY key-value pair setting with environment variables and program argument switches. Bajo also supports [dotenv](https://github.com/motdotla/dotenv) with a ```.env``` file.
+
+The order of precedence is: environment variable > argument switches > config files > default, built-in values.
+
+All values (whether they come from environment variables, argument switches, or config files) will be parsed using [dotenv-parse-variables](https://github.com/ladjs/dotenv-parse-variables), so please make sure you visit the repository to fully understand how it works.
+
+#### dotenv
+
+- Create or open ```{appDir}/.env```
+- Use ```__``` (double underscores) as replacement for dots in an object.
+- ```DIR__DATA```: Sets the ```{dataDir}``` data directory.
+- ```DIR__TMP```: Sets ```{tmpDir}``` temporary directory.
+- For every key in ```{ns|bajo}.json```, use its snake-cased, upper-cased version. For example:
+  - ```env: 'prod'``` → ```ENV=prod```
+  - ```log.dateFormat: 'YYYY-MM-DD'``` → ```LOG__DATE_FORMAT=YYYY-MM-DD```
+  - ```exitHandler: true``` → ```EXIT_HANDLER=true```
+- To override a plugin's config, prepend every key in the plugin's config with the snake-cased, upper-cased version of the namespace followed by a dot. For example:
+  - ```key``` in ```myPlugin``` → ```MY_PLUGIN.KEY=...```
+  - ```key.subKey.subSubKey``` in ```myPlugin``` → ```MY_PLUGIN.KEY__SUB_KEY__SUB_SUB_KEY=...```
+
+Example:
+```text
+# .env file
+ENV=prod
+LOG__PRETTY=true
+LOG__TIME_TAKEN=true
+LANG=id
+```
+
+#### Argument Switches
+
+- Use switches, for example: ```node index.js --xxx=one --yyy=two```
+- Use ```-``` as the replacement for dots in an object.
+- ```--dir-data```: Sets the ```{dataDir}``` data directory.
+- ```--dir-tmp```: Sets the ```{tmpDir}``` temporary directory.
+- For every key in ```{ns|bajo}.json```, add ```--``` prefix. For example:
+  - ```env: 'prod'``` → ```--env=prod```
+  - ```log.dateFormat: 'YYYY-MM-DD'``` → ```--log-dateFormat=YYYY-MM-DD```
+  - ```exitHandler: true``` → ```--exitHandler```
+- To override a plugin's config, prepend every key in the plugin's config with the plugin name followed by a colon ```:```. For example:
+  - ```key``` in ```myPlugin``` → ```--myPlugin:key=...```
+  - ```key.subKey.subSubKey``` in ```myPlugin``` → ```--myPlugin:key-subKey-subSubKey=...```
+
+Example:
+```bash
+$ node index.js --env=prod --log-pretty --log-timeTaken --lang=id
+```
+
+## System Hook
+
+A **hook** refers to a mechanism that allows you to inject a custom function to extend Bajo's functionality at specific points. These points are typically predefined by the framework, providing opportunities to execute code before, during, or after a particular operation.
+
+### Usage
+
+In Bajo, hooks can be created anywhere very easily. Simply call the ```runHook``` method followed by the parameters you want to pass.
+
+The hook name is always in the form of [TNsPairs](global.html#TNsPathPairs), while its parameters are a rest parameter. This means you can pass any number of parameters to the function, or none at all.
+
+Example:
+
+1. In your JavaScript file, add the following code snippet:
+
+   ```javascript
+   const { runHook } = this.app.bajo
+   await runHook('main:sayHello', 'Don', 'Meri', { movie: 'Jumbo', year: 2025 })
+   ````
+2. Go to directory ```{appDir}/main/extend/bajo/hook```. Create one if it doesn't exist yet.
+3. Create file ```main@say-hello.js``` in the directory above.
+4. Enter these lines:
+   ```javascript
+   async function sayHello (...params) {
+     const [mainChar, friend, payload] = params
+     console.log(mainChar, friend, payload) // output: Don, Meri, { movie: 'Jumbo', year: 2025 }
+   }
+
+   export default sayHello
+   ```
+
+Note the hook name and its associated file name:
+
+```main:sayHello``` → ```main@say-hello.js```
+
+Because a colon (```:```) is prohibited in a file name, Bajo replaces it with the ```@``` symbol.
+
+During the boot process, Bajo will scan for hook files and load them into the hook list. When your ```runHook``` is executed, Bajo will find its related object from the list. If such a hook exists, its function handler will be called.
+
+### Anatomy
+
+Many times, there are more than one handler listening for a particular hook name. Especially in a framework that uses plugins extensively like Bajo, many plugins can listen to one hook at the same time. This creates a problem with call order.
+
+To overcome this problem, Bajo gives you the opportunity to set a ```level```. Functions with a lower level will be called earlier. Functions with no level will be assigned level 999 by default.
+
+Now, change your ```main@say-hello.js``` file above to export an object instead of a function:
+
+```javascript
+const sayHello = {
+  level: 10, // <-- will get called early
+  handler: async function (...params) {
+    const [mainChar, friend, payload] = params
+    console.log(mainChar, friend, payload) // output: Don, Meri, { movie: 'Jumbo', year: 2025 }
+  }
+}
+```
+
+### Caveats
+
+Hooks give you a lot of flexibility and freedom, but you need to be aware of the following caveats:
+
+1. You need to use an **asynchronous** function. Even if your function is synchronous, it will be called as an asynchronous one—and as you know, there is a performance degradation when using asynchronous operations
+2. **Stay away** from using ```runHook``` inside a hook! Even though it's possible, your code will become unreadable and messy pretty soon.
+3. It's hard to trace errors in a hook. Because of its sequential nature, if a handler that's called earlier than yours throws an error, your hook won't be called at all.
+4. If you use so many plugins that use the hook system so extensively with so many files, your app's boot time can take much longer than it's supposed to.
+
+My advice is to **use it wisely**. Don't use hooks unless necessary; this will make your app or plugin clean and easy to understand.
+

package/class/base/log.js

@@ -1,205 +0,0 @@
-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

@@ -1,168 +0,0 @@
-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