bajo 2.23.0 → 2.24.0

package/index.js

@@ -5,26 +5,63 @@ import fs from 'fs-extra'
 shim()
 
 /**
- * Main entry point of a Bajo app. Returned value is the app instance itself.
+ * To be recognized as a valid Bajo app, your package must be an `ES6 module` and have a `package.json` file
+ * with the additional `bajo` property and at least the `type` property set to `app`.
  *
- * While you can code directly around it, you typically write your code the main plugin (```{mainNs}```) or
- * writing your own custom plugin.
+ * You can also add the `plugins` property to specify which plugins to load. But this will be overridden
+ * by the `{dataDir}/config/.plugins` file if it exists.
  *
- * I recommend the second method for its portability.
+ * Example:
+ * ```json
+ * {
+ *   "name": "my-app",
+ *   "version": "1.0.0",
+ *   "description": "My Bajo app",
+ *   "type": "module",
+ *   "main": "index.js",
+ *   "bajo": {
+ *     "type": "app",
+ *     "plugins": ["bajo-cli", "bajo-config"]
+ *   },
+ *   "dependencies": {
+ *     "bajo": "^2.23.0",
+ *     "bajo-cli": "^2.4.0",
+ *     "bajo-config": "^2.4.0"
+ *   }
+ * }
+ * ...
+ * ```
+ *
+ * > **Note**: The dot symbol in `package.json` has been replaced with `·` symbol because of JSDoc theme limitation
+ *
+ * @global
+ * @typedef package·json
+ */
+
+/**
+ * Main entry point of a Bajo app. Returned value is the {@link App} instance itself.
+ *
+ * Inside your `index.js` file in the root folder, write something like this:
+ * ```javascript
+ * import { boot } from 'bajo'
+ * const app = await boot()
+ * // At this point, your app should be ready to use
+ * // You can now use `app` to access all plugins and their features
+ * ```
+ *
+ * Even though you can write your codes directly after boot as shown above, we strongly suggest writing
+ * your code inside the {@link Main} plugin or even writing a custom {@link Plugin}.
+ *
+ * We recommend the second method for its portability.
  *
  * @global
  * @async
- * @param {Object} [options] App options.
- * @param {string} [options.cwd] Set current working directory. Defaults to the script directory.
- * @param {string[]} [options.plugins] Array of plugins to load. If provided, it override the list in ```package.json``` and ```.plugins``` file.
- * @param {Object} [options.config] Plugin's config object. If provided, plugin configs will no longer be read from its config files.
+ * @param {App.TOptions} [options] App options
  * @returns {App}
- * @example
- * // index.js file. Your main package entry point
- * import bajo from 'bajo'
- * await bajo()
+ * @see {@link App}
+ * @see {@link Bajo}
  */
-async function boot (options = {}) {
+export async function boot (options = {}) {
   if (!options.cwd) {
     const item = process.argv.find(item => item.startsWith('--cwd='))
     if (item) options.cwd = item.slice(6)
@@ -33,7 +70,7 @@ async function boot (options = {}) {
   const pkgFile = `${options.cwd}/package.json`
   const pkg = fs.readJsonSync(pkgFile)
   if (pkg.type !== 'module') {
-    console.error(`Please turn on ES6 parsing by adding "type": "module" to ${pkgFile}!`)
+    console.error('A Bajo app must be an ES6 module. Your package.json is missing the "type": "module" property')
     process.exit(1)
   }
   const app = new App(options)

package/lib/applet-hook.js

@@ -0,0 +1,325 @@
+/**
+ * # Applet
+ *
+ * Bajo has a built-in applet system that allows you to run your app as an applet.
+ * An applet is a small command-line app that can be embedded inside a plugin, purposefully designed
+ * to run a simple task mostly bound to the plugin itself. It is a convenient way to run a plugin's task
+ * without having to write a separate script.
+ *
+ * Since it is embedded inside a plugin, it behaves like running the whole app but doing only task
+ * that you want to run.
+ *
+ * Applet needs {@link https://ardhi.github.io/bajo-cli/|bajo-cli} plugin to be installed and loaded.
+ * This is because applet is a command-line app and `bajo-cli` plugin is specifically designed to provide
+ * the necessary command-line interface and function helpers to run command-line based app.
+ *
+ * So please make sure that `bajo-cli` is in your app's `package.json` file and in the `plugins`
+ * array of your app's config before you run an applet. Otherwise, it will throw an error.
+ *
+ * You can run an applet by using the following command:
+ * - `node index.js -a` or `node index.js --applet` to list all available applets and choose one to run
+ * - `node index.js -a <pluginNs>` to list all `pluginNs` only applets and choose one to run
+ * - `node index.js -a <pluginNs:appletName>` to run the specific applet directly
+ *
+ * On all cases, you might require to provide additional arguments and/or options to the applet.
+ *
+ * By default, applet won't show you any log output. This is by design because it could clutter your
+ * terminal output. If you insist on seeing the log output, you have to add the `--log-applet` option.
+ *
+ * > **Note**: all standard bajo's command line arguments and options are also available to applet,
+ * e.g. `--env=prod`, `--lang=id`, `--log-level=trace`, etc.
+ *
+ * > **Development** : Please visit {@link https://ardhi.github.io/bajo-cli/module-Applet.html|applet development}
+ * for more details on how to create an applet.
+ * @module Applet
+ */
+
+/**
+ * # Hook
+ *
+ * Bajo has a hook system that allows you to run custom code before or after certain events in the framework.
+ * You can use hooks to modify the behavior of the framework or to add new functionality.
+ *
+ * Your hook should be put in:
+ * - your plugin's hook folder (also valid for app's `main` plugin), which is located in `{pluginRoot}/extend/bajo/hook`. In this case:
+ *   - the file should be named as `{hookName}.js` for hook that listens for one name or `{hookName1}${hookName2}${hookName3}.js`
+ *     for hook that listens for many names. It should be exported as default export
+ *   - you can use the exact hook name or follow our convention to use kebab case for the file name, e.g. `bajo.override:after-read-config.js` for `bajo.override:afterReadConfig` hook
+ *   - content should be a single {@link module:Hook.THook} object. If `name` property is there, it will be used as
+ *     the hook name, otherwise it will be reconstructed from the file name. Hence the file name is important
+ *   - or simply a function that will be used as the hook handler. In this case, all missing properties will be set to their default values
+ * - or as array of hook object in `{pluginRoot}/extend/bajo/hook.js` file that follows the {@link module:Hook.THook} structure
+ *
+ * > **Note**: Hook handlers can have `.` dot symbol in their name, but in documentation, the dot symbol will be replaced with `·`
+ * symbol because of JSDoc limitation. For example, a hook handler named `bajo.override:afterReadConfig` will be
+ * documented as `bajo·override:afterReadConfig`.
+ *
+ * > **Warning**: Even though hooks is a powerfull and convenient feature, it should be used with caution. Overusing hooks can lead to code
+ * that is difficult to understand and maintain. Use hooks only when necessary and avoid using them for simple tasks
+ * that can be accomplished with regular code.
+ * @module Hook
+ */
+
+/**
+ * Hook structure definition. Your hook listener should be an object that follows this structure.
+ *
+ * @memberof module:Hook
+ * @typedef THook
+ * @type {Object}
+ * @property {string|string[]} name - Hook name or array of hook names
+ * @property {module:Hook.hookHandler} handler - Hook handler function
+ * @property {number} [level=999] - Hook level (lower number means higher priority)
+ * @property {string} src - Hook source (origin plugin name). Bajo will set this automatically, any value you set will be overriden.
+ * @property {boolean} [noWait=false] - If `true`, Bajo will not wait for this hook to complete before proceeding to the next hook. Default is `false`.
+ */
+
+/**
+ * This is the hook handler function that will be called when the hook is triggered.
+ * This handler is scoped to the owning plugin, so you can use `this` to access the plugin instance and
+ * its properties.
+ * @async
+ * @method
+ * @callback hookHandler
+ * @memberof module:Hook
+ * @param {...any} args - Arguments passed to the hook handler
+ * @returns {Promise<void>} The return value of the hook handler
+ */
+
+/**
+ * Hook handler that runs before boot process. You can use this hook to do some pre-boot process.
+ *
+ * @name bajo:beforeBoot
+ * @async
+ * @method
+ * @memberof module:Hook
+ */
+
+/**
+ * Hook handler that runs after boot process. You can use this hook to do some post-boot process.
+ *
+ * @name bajo:afterBoot
+ * @async
+ * @method
+ * @memberof module:Hook
+ */
+
+/**
+ * Hook handler that runs after hooks are collected. You can use this hook to modify the collected hooks before
+ * they are recognized as application hooks.
+ *
+ * @async
+ * @method
+ * @name bajo:afterCollectHooks
+ * @memberof module:Hook
+ * @param {Array<module:Hook~THook>} hooks - Array of hook objects
+ * @see module:Helper.collectHooks
+ */
+
+/**
+ * Hook handler that runs before all plugins are initialized. You can use this hook to do some pre-initialization process.
+ *
+ * @async
+ * @method
+ * @name bajo:beforeAllInit
+ * @memberof module:Hook
+ * @see module:Helper.run
+ */
+
+/**
+ * Hook handler that runs after all plugins are initialized. You can use this hook to do some post-initialization process.
+ *
+ * @async
+ * @method
+ * @memberof module:Hook
+ * @name bajo:afterAllInit
+ * @see module:Helper.run
+ */
+
+/**
+ * Hook handler that runs before all plugins are started. You can use this hook to do some pre-start process.
+ *
+ * @async
+ * @method
+ * @name bajo:beforeAllStart
+ * @memberof module:Hook
+ * @see module:Helper.run
+ */
+
+/**
+ * Hook handler that runs after all plugins are started. You can use this hook to do some post-start process.
+ *
+ * @async
+ * @method
+ * @name bajo:afterAllStart
+ * @memberof module:Hook
+ * @see module:Helper.run
+ */
+
+/**
+ * Hook handler that runs before `{ns}` plugins are initialized. You can use this hook to do some pre-initialization process.
+ *
+ * @async
+ * @method
+ * @memberof module:Hook
+ * @name {ns}:beforeInit
+ * @see module:Helper.run
+ */
+
+/**
+ * Hook handler that runs after `{ns}` plugins are initialized. You can use this hook to do some post-initialization process.
+ *
+ * @async
+ * @method
+ * @memberof module:Hook
+ * @name {ns}:afterInit
+ * @see module:Helper.run
+ */
+
+/**
+ * Hook handler that runs before `{ns}` plugins are started. You can use this hook to do some pre-start process.
+ *
+ * @async
+ * @method
+ * @memberof module:Hook
+ * @name {ns}:beforeStart
+ * @see module:Helper.run
+ */
+
+/**
+ * Hook handler that runs after `{ns}` plugins are started. You can use this hook to do some post-start process.
+ *
+ * @async
+ * @method
+ * @memberof module:Hook
+ * @name {ns}:afterStart
+ * @see module:Helper.run
+ */
+
+/**
+ * Hook handler that runs before applet is run. `{ns}` is the applet's namespace
+ *
+ * @name {ns}:beforeAppletRun
+ * @async
+ * @method
+ * @memberof module:Hook
+ * @param {...any} args - Arguments passed to the applet
+ * @see module:Helper.runAsApplet
+ */
+
+/**
+ * Hook handler that runs after applet is run. `{ns}` is the applet's namespace
+ *
+ * @name {ns}:afterAppletRun
+ * @async
+ * @method
+ * @memberof module:Hook
+ * @param {...any} args - Arguments passed to the applet
+ * @see module:Helper.runAsApplet
+ */
+
+/**
+ * Hook handler that runs after a non override/extended configuration file is read.
+ *
+ * @async
+ * @method
+ * @name bajo·default:afterReadConfig
+ * @memberof module:Hook
+ * @param {string} file - Config file path
+ * @param {string} orgObj - Original config object before parsing
+ * @param {object} options - readConfig options
+ */
+
+/**
+ * Hook handler that runs before a configuration file override is read.
+ *
+ * @async
+ * @method
+ * @name bajo·override:beforeReadConfig
+ * @memberof module:Hook
+ * @param {string} fileExt - Config file extension
+ * @param {object} options - readConfig options
+ */
+
+/**
+ * Hook handler that runs after a configuration file override is read.
+ *
+ * @async
+ * @method
+ * @name bajo·override:afterReadConfig
+ * @memberof module:Hook
+ * @param {string} fileExt - Config file extension
+ * @param {object} result - Resulting config object after parsing
+ * @param {object} options - readConfig options
+ */
+
+/**
+ * Hook handler that runs before a extended configuration file is read.
+ *
+ * @async
+ * @method
+ * @name bajo.extend:beforeReadConfig
+ * @memberof module:Hook
+ * @param {string} fileExt - Config file extension
+ * @param {object} options - readConfig options
+ */
+
+/**
+ * Hook handler that runs after a extended configuration file is read.
+ *
+ * @async
+ * @method
+ * @name bajo.extend:afterReadConfig
+ * @memberof module:Hook
+ * @param {string} fileExt - Config file extension
+ * @param {object} result - Resulting config object after parsing
+ * @param {object} options - readConfig options
+ */
+
+/**
+ * Hook handler that runs before a configuration file is read.
+ *
+ * @async
+ * @method
+ * @name bajo:beforeReadConfig
+ * @memberof module:Hook
+ * @param {string} file - Config file path
+ * @param {object} options - readConfig options
+ */
+
+/**
+ * Hook handler that runs after all read processes of a configuration file are completed.
+ *
+ * @async
+ * @method
+ * @name bajo:afterReadConfig
+ * @memberof module:Hook
+ * @param {string} file - Config file path
+ * @param {object} result - Resulting config object after parsing
+ * @param {object} options - readConfig options
+ */
+
+/**
+ * Hook handler that runs before a collection is built. `{ns}` is the collection's namespace. This hook is useful
+ * to modify the collection items before they are built.
+ *
+ * @async
+ * @method
+ * @name {ns}:beforeBuildCollection
+ * @memberof module:Hook
+ * @param {string} container - Collection container name
+ * @param {array<object>} items - Collection items
+ * @see Bajo#buildCollections
+ */
+
+/**
+ * Hook handler that runs after a collection is built. `{ns}` is the collection's namespace. This hook is useful
+ * to modify the collection items after they are built.
+ *
+ * @async
+ * @method
+ * @name {ns}:afterBuildCollection
+ * @memberof module:Hook
+ * @param {string} container - Collection container name
+ * @param {array<object>} items - Collection items
+ * @see Bajo#buildCollections
+ */

package/lib/config.js

@@ -0,0 +1,164 @@
+/**
+ * This is the default configuration object for Bajo and its plugins (see note below). It contains various settings that control the behavior of the framework.
+ * You can override these settings by providing your own configuration object through the following methods in the order of priority:
+ * 1. **Environment variables**:
+ *    You can set configuration options using environment variables too. `dotenv` is also supported.
+ *    The environment variable names should be in uppercase. Use double underscores instead of dots and single underscores
+ *    to form camel cased name. For example, `LOG__TIME_TAKEN=true` will set `log.timeTaken` to `true`
+ * 2. **Command-line arguments**:
+ *    You can pass configuration options as command-line arguments when starting the application. For example, you can use `--env=prod` to set the environment to `prod`.
+ *    For nested configuration options, use dash notation. For example, `--log-timeTaken` will set `log.timeTaken` to `true`.
+ * 3. **Configuration files**:
+ *    Create/open `{dataDir}/config/bajo.{ext}` file, where `{ext}` is the file extension of your choice.
+ *    This file is read during the boot process with app's {@link App#configHandlers} and merged with the default configuration object.
+ *
+ *    By default, the supported file extensions are `.js`, `.json`, and `.yml/.yaml`. More extensions can be added by plugins.
+ *    For example, the {@link https://ardhi.github.io/bajo-config bajo-config} plugin provides support for `.toml` format.
+ *
+ *    If the same filename with different extension exists, the one with higher priority will be used. The priorities are as follows:
+ *    1. `.js` - use this if you want to use dynamic config file that can be generated programmatically.
+ *    2. `.json` - use this if you want to use static config file that can be easily edited by humans.
+ *    3. `.yml/.yaml` - use this if you want to use static config file that can be easily edited by humans and supports comments.
+ *
+ *    To have an environment-specific configuration, create a file named `bajo-{env}.{ext}` where `{env}` is the environment name (e.g. `dev`, `prod`)
+ *    in the same folder.
+ *
+ * > **Note**: all plugin's configuration files follow the same rules as above, but with the following differences:
+ * > - The configuration file should be named as `{pluginName}.{ext}` or `{pluginName}-{env}.{ext}` for environment-specific configuration, where `{pluginName}` is the name of the plugin.
+ * > - Command-line arguments should be prefixed with the plugin name followed by a colon. For example, `--{pluginName}:my-configKey` will set `my.configKey` to the value provided for the plugin's configuration.
+ * > - Environment variables should be prefixed with the plugin name followed by a dot. For example, `{PLUGINNAME}.MY__CONFIG_KEY` will set `my.configKey` to the value provided for the plugin's configuration.
+ * >
+ * > Plugin's configuration objects are mutable only during the boot process. After a plugin is started, they are frozen and cannot be modified.
+ * Your only options to do modifications is to use `{pluginName}:{before|after}{Init|Start}` hooks.
+ *
+ * @typedef TConfig
+ * @global
+ * @type {Object}
+ */
+
+/**
+ * @typedef TConfig
+ * @memberof Bajo
+ * @type {Object}
+ * @property {string} env - Environment name (`dev` or `prod`)
+ * @property {Object} [runtime={}] - Runtime configuration
+ * @property {boolean} [runtime.noWarning=false] - If `true`, Bajo will not show any warning messages. Default is `false`
+ * @property {Object} [log={}] - Logging configuration
+ * @property {boolean} [log.timeTaken=false] - If `true`, Bajo will log the time taken for each operation. Default is `false`
+ * @property {string} [log.dateFormat='YYYY-MM-DDTHH:mm:ss.SSS'] - Date format for logging
+ * @property {boolean} [log.useUtc=false] - If `true`, Bajo will use UTC instead of local time for logging. Default is `false`
+ * @property {boolean} [log.pretty=false] - If `true`, Bajo will use pretty logging format. Default is `false`
+ * @property {boolean} [log.applet=false] - Whether to log when in applet mode or not. Default is `false`
+ * @property {boolean} [log.save=false] - Whether to save logs to file. Default is `false`
+ * @property {Object} [log.rotation={}] - Log rotation configuration, used only if `log.save` is `true`
+ * @property {string} [log.rotation.cycle='none'] - Rotation cycle (`none`, `daily`, `weekly`, `monthly`). Default is `none`
+ * @property {boolean} [log.rotation.compressOld=true] - Whether to compress old logs. Default is `true`
+ * @property {boolean} [log.rotation.byPlugin=false] - Whether to rotate logs by plugin. Default is `false`
+ * @property {number} [log.rotation.retain=5] - Number of old logs to retain. Default is `5`
+ * @property {Object} [dump={}] - Dump configuration
+ * @property {number} [dump.depth=2] - Depth of object to dump. Default is `2`
+ * @property {boolean} [dump.compact=false] - If `true`, Bajo will dump objects in compact format. Default is `false`
+ * @property {boolean} [dump.colors=true] - If `true`, Bajo will dump objects with colors. Default is `true`
+ * @property {number} [dump.breakLength=80] - Break length for dumping objects. Default is `80`
+ * @property {boolean} [dump.caller=true] - If `true`, Bajo will dump the caller of the dump function. Default is `true`
+ * @property {Object} [dump.frame={}] - Display frame configuration for dumping objects
+ * @property {string} [dump.frame.titleAlignment='center'] - Title alignment for dumping objects. Default is `center`
+ * @property {number} [dump.frame.padding=1] - Padding for dumping objects. Default is `1`
+ * @property {number} [dump.frame.margin=1] - Margin for dumping objects. Default is `1`
+ * @property {string} [dump.frame.borderStyle='round'] - Border style for dumping objects. Default is `round`
+ * @property {string} [lang] - Default language for internationalization. Default is the system language or `en-US` if not available
+ * @property {Object} [intl={}] - Internationalization configuration
+ * @property {string[]} [intl.supported=['en-US', 'id']] - Supported languages. Default is `en-US` and `id`. Add more if you want it
+ * @property {string} [intl.fallback='en-US'] - Fallback language if the requested language is not supported. Default is `en-US`
+ * @property {string[]} [intl.lookupOrder=[]] - Lookup order for languages. Default is empty array
+ * @property {Object} [intl.format={}] - Formatting configuration
+ * @property {string} [intl.format.emptyValue=''] - Value to use for empty values. Default is empty string
+ * @property {Object} [intl.format.datetime] - See {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat|Intl.DateTimeFormat} for more information
+ * @property {Object} [intl.format.date] - See {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat|Intl.DateTimeFormat} for more information
+ * @property {Object} [intl.format.time] - See {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat|Intl.DateTimeFormat} for more information
+ * @property {Object} [intl.format.float] - See {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat|Intl.NumberFormat} for more information
+ * @property {Object} [intl.format.double] - See {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat|Intl.NumberFormat} for more information
+ * @property {Object} [intl.format.smallint] - See {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat|Intl.NumberFormat} for more information
+ * @property {Object} [intl.format.integer] - See {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat|Intl.NumberFormat} for more information
+ * @property {Object} [intl.unitSys={}] - Unit system configuration. Object with keys as language codes and values as unit systems. Supported values are `metric`, `imperial` and `nautical`
+ * @property {string} [intl.unitSys.en-US='imperial'] - Unit system for `en-US`. Default is `imperial`
+ * @property {string} [intl.unitSys.id='metric'] - Unit system for `id`. Default is `metric`
+ * @property {boolean} [exitHandler=true] - Whether to attach exit handlers for graceful shutdown. Default is `true`
+ * @property {Object} [cache={}] - Cache configuration
+ * @property {string[]} [cache.purge=[]] - List of cache names to purge on startup. Default is empty array
+ * @property {string|number} [cache.purgeIntvDur='5m'] - Interval duration for purging cache. Default is `5m`
+ */
+const config = {
+  env: 'dev',
+  runtime: {
+    noWarning: false
+  },
+  log: {
+    timeTaken: false,
+    dateFormat: 'YYYY-MM-DDTHH:mm:ss.SSS',
+    useUtc: false,
+    pretty: false,
+    applet: 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: {
+      titleAlignment: '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'
+  }
+}
+
+export default config