bajo 2.23.0 → 2.24.0

package/wiki/tutorials/02_GETTING_STARTED.md

@@ -0,0 +1,366 @@
+# Getting Started
+
+Welcome! In this guide, we will take our first steps with Bajo together.
+
+If this is your first time working with this framework, that is completely fine. We will move step by step: installation, project structure, basic configuration, and your first small app. Along the way, you will also meet two important ideas in Bajo: plugins and hook/lifecycle.
+
+By the end of this tutorial, you should feel comfortable enough to continue to Bajo's sub-frameworks, such as Dobo and Waibu.
+
+## Installation
+
+First, create a new empty directory named ```my-project```. We will use this as the app directory throughout the tutorial. Then, move into that directory with ```cd``` and run:
+
+```bash
+$ npm init
+```
+
+You will be asked for information such as project name, description, and author. Continue until the *package.json* file is created.
+
+Next, open that file in your editor and add the following lines:
+
+```javascript
+...
+  "type": "module",
+  "bajo": {
+    "type": "app"
+  },
+...
+```
+
+After that, install Bajo:
+
+```bash
+$ npm install bajo
+```
+
+Now create a bootstrap file named `index.js` and add:
+
+```javascript
+// index.js file
+import { boot } from 'bajo'
+await boot()
+```
+
+A Bajo app **always** needs a data directory for configuration files and related resources. This directory can be inside or outside your app directory.
+
+If the directory does not exist yet, Bajo will ask you whether to create one automatically or to abort. If you decide to create it, Bajo will make a directory named `data`, next to your `index.js` file. By default, this becomes your data directory.
+
+Now run your app:
+
+```bash
+$ node index.js
+```
+
+Great work. Your first Bajo app is now running.
+
+## Playing Around
+
+At this point, your project structure should look like this:
+
+```
+.
+└── my-project
+    ├── data
+    │   └── config
+    ├── main
+    │   └── index.js
+    ├── node_modules
+    │   └── ...
+    ├── index.js
+    ├── package.json
+    └── package-lock.json
+```
+
+Bajo automatically creates a `main` plugin for you. This is the main plugin of your app, and it is where you will put your code.
+
+By default, the app runs in the `dev` environment. In this mode, the log level is set to `debug`. You can override it using program arguments to something like `trace`, which is the most verbose level, and some other options:
+
+```bash
+$ node index.js --log-level=trace --log-timeTaken --log-pretty
+```
+
+You should now see more colorful logs, including timing information for each step. This is very useful for debugging and for finding slow parts of the startup process.
+
+Typing arguments every time can feel repetitive, so let's move those settings into a config file. Create `data/config/bajo.yml` and add:
+
+```yaml
+env: dev
+log:
+  pretty: true
+  level: trace
+  timeTaken: true
+```
+
+> If you like JSON, you can also use `bajo.json` instead of `bajo.yml`. Bajo supports both formats.
+
+Now try running the app again without extra arguments:
+
+```bash
+$ node index.js
+```
+
+Much easier.
+
+You can combine config values, program arguments, environment variables, and even use a dotenv file (`.env`) whenever needed. For a deeper explanation, please see the *User Guide*.
+
+## Your First Project
+
+Now let's build a simple **Hello World** example, Bajo style.
+
+Our goals are:
+1. Read values from configuration.
+2. Copy those values into plugin properties during initialization.
+3. Display the values while the app is running.
+4. Print a message when the app exits.
+
+Let's begin.
+
+### Config Object
+
+Open `data/config/main.yml` (or create it if it does not exist). This is the configuration file for the main plugin.
+
+Add:
+
+```yaml
+firstName: Tanjiro
+lastName: Kamado
+age: 15
+```
+
+Each Bajo plugin can read its configuration from `{dataDir}/config/{ns}.yml`, where `{dataDir}` is your data directory and `{ns}` is the plugin namespace or name. You can read more in the {@tutorial 03_USER_GUIDE}.
+
+In Bajo, most features are built through plugins. For small projects, using the built-in `main` plugin is usually enough. As your project grows, you can split responsibilities into smaller independent plugins.
+
+If you want to build your own plugin, please continue with the {@tutorial 04_DEV_GUIDE}.
+
+### Plugin Factory
+
+Now open `main/index.js` and update it like this:
+
+This file is your main plugin factory. Bajo creates it automatically when needed.
+
+```javascript
+async function factory (pkgName) {
+  const me = this
+
+  return class Main extends this.app.baseClass.Base {
+    constructor () {
+      super(pkgName, me.app)
+      this.config = {}
+    }
+
+    // start adding these lines
+    init = async () =>  {
+      this.firstName = this.config.firstName
+      this.lastName = this.config.lastName
+      this.age = this.config.age
+    }
+
+    start = async () => {
+      this.log.info('First name: %s, Last name: %s, age: %d', this.firstName, this.lastName, this.age)
+    }
+
+    exit = async () => {
+      this.log.warn('Program aborted')
+    }
+    // end of added lines
+  }
+}
+
+export default factory
+```
+
+Here is what happens during the lifecycle:
+
+- During boot, the main plugin reads `main.yml` and merges it with matching program arguments and environment variables to build the plugin's configuration object.
+- Next, initialization runs through main plugin `init` method. In this example, we copy values from `this.config` into plugin properties.
+- Then the plugin starts through the `start` method, where we print the values to the logger.
+- Finally, when the app exits, the `exit` method runs.
+
+This is the standard lifecycle pattern for all Bajo plugins, including the special main plugin.
+
+But if you run it now, you will likely get an error. The reason is that keys from the config file (`firstName`, `lastName`, and `age`) are not yet declared in `this.config`, so they are ignored during initialization.
+
+Let's fix that by defining default values first:
+
+```javascript
+...
+    constructor () {
+      super(pkgName, me.app)
+      this.config = {
+        firstName: 'John',
+        lastName: 'Doe',
+        age: 50
+      }
+    }
+...
+```
+
+The `this.config` object in the constructor acts as the default configuration. During startup, Bajo merges it with values from configuration files or program options. If any key is missing in the file, the default value is used.
+
+Run the app again, and this time let's keep output concise with:
+
+```bash
+$ node index.js --log-level=info
+2025-09-12T00:09:38.946Z +97ms INFO: main First name: Tanjiro, Last name: Kamado, age: 15
+2025-09-12T00:09:38.949Z +3ms WARN: main Program aborted
+```
+
+Nice!
+
+## The Hook System
+
+### Tapping a Hook
+
+Bajo has a very powerful, yet so simple hook system so you can add custom behavior at specific moments. We will start with a simple case: running code right after boot completes.
+
+Create `main/extend/bajo/hook/bajo@after-boot.js`. If the naming looks unusual, that is expected; please read {@link module:Hook} file naming instructions for more.
+
+```javascript
+async function afterBootComplete () {
+  this.log.info('Hook after boot complete')
+}
+
+export default afterBootComplete
+```
+
+That is your first hook listener. It taps into the `bajo:afterBoot` hook, which runs after the boot process completes. You can check the full list of hooks {@link module:Hook|here}.
+
+### Your Own Hook
+
+Now let's write your own custom hook. For this small example it may feel too over the top, but it shows how flexible Bajo can be.
+
+This time, we will update all properties through a hook.
+
+Open `index.js` and update it like this:
+
+```javascript
+...
+    init = async () => {
+      const { runHook } = this.app.bajo // add this line
+      this.firstName = this.config.firstName
+      this.lastName = this.config.lastName
+      this.age = this.config.age
+      await runHook('main:myHook') // and this line
+    }
+...
+```
+
+This will add a hook named `main:myHook` during app boot.
+
+Now create a new file as the hook listener for the hook you just created: `main/extend/bajo/hook/main@my-hook.js`
+
+```javascript
+async function myHook () {
+  // 'this' is bound to the owner plugin, that is the main plugin in this case
+  this.lastName = 'THE Daemon Slayer'
+}
+
+export default myHook
+```
+
+In Bajo, class methods, hooks, and handlers run within its plugin scope, so setting `this.lastName` directly inside the hook is enough.
+
+Run the app again. You should see output similar to this:
+
+```bash
+2025-09-12T12:09:09.004Z +115ms INFO: main First name: Tanjiro, Last name: THE Daemon Slayer, age: 15
+2025-09-12T12:09:09.008Z +4ms INFO: main Hook after boot complete
+2025-09-12T12:09:09.009Z +1ms WARN: main Program aborted
+```
+
+As you can see, `this.lastName` was updated by the hook successfully. You can also see the `afterBoot` hook running after the main plugin starts.
+
+## Using External Plugins
+
+Bajo is designed as an ecosystem of small plugins. You can think of them like building blocks: combine the ones you need to create your own app behavior.
+
+In this section, we will use plugins to extend the app.
+
+### TOML File Format
+
+Let's switch the configuration format to TOML.
+
+1. TOML support is provided by the `bajo-config` plugin, so install it first:
+   ```bash
+   $ npm install bajo-config
+   ```
+2. Open `data/config/.plugins` and add `bajo-config` in it. If the file does not exist yet, create it first. Plugin order is usually resolved automatically by Bajo.
+3. Remove `data/config/main.yml` and create `data/config/main.toml`.
+4. Add the same object as before, now in TOML:
+   ```
+   firstName = "Tanjiro"
+   lastName = "Kamado"
+   age = 15
+   ```
+5. Run the app and check the result. It should match the previous behavior, except for different timestamps.
+
+### Applet Mode
+
+**Applets** are small tools embedded within plugins that run when Bajo is in **applet mode**. They have their own lifecycle, separate from the main program, but they can still reuse shared resources and config.
+
+To run Bajo in applet mode, use `--applet` or `-a`:
+
+```bash
+$ node index.js -a
+```
+
+Applet mode needs `bajo-cli`, so install it first:
+
+```bash
+$ npm install bajo-cli
+```
+
+Then add `bajo-cli` to the `data/config/.plugins` file. Again, plugin order is not a concern in this case.
+
+If you run it now, your terminal may show something like this:
+
+```bash
+ℹ App runs in applet mode
+? Please select: (Use arrow keys)
+❯ bajoConfig
+  bajoCli
+```
+
+Notice that the app reports it is running in applet mode. The interface becomes an interactive CLI view, and regular logs are hidden.
+
+By default, logs are disabled in applet mode to keep the console clean. During debugging, you can enable logs again by adding `--log-applet` to your command.
+
+Applets are optional utilities provided by plugin authors, so it could be the case that some plugins have many applets in it while others have none.
+
+### System Info
+
+Now let's install one more plugin: `bajo-sysinfo`. It is a thin wrapper over [systeminformation](https://github.com/sebhildebrandt/systeminformation) with a few helpful additions:
+
+- It can be called directly as an applet.
+- It is also exposed as Waibu REST API endpoints. We will cover it much later.
+
+If you run the app like this (yes, `--applet` can take a value; details are {@link module:Applet|here}, you may see output like the following after loading:
+
+```bash
+$ node index.js -a bajoSysinfo:battery
+ℹ App runs in applet mode
+ℹ Done!
+┌──────────────────┬─────────────────────┐
+│ hasBattery       │ true                │
+├──────────────────┼─────────────────────┤
+│ cycleCount       │ 0                   │
+├──────────────────┼─────────────────────┤
+│ isCharging       │ true                │
+├──────────────────┼─────────────────────┤
+│ designedCapacity │ 61998               │
+├──────────────────┼─────────────────────┤
+│ maxCapacity      │ 51686               │
+├──────────────────┼─────────────────────┤
+...
+```
+
+## More
+
+Bajo offers much more beyond this tiny introduction. When you are ready, continue with these sub-framework guides below. In
+the mean time, please feel free to also explore the {@tutorial 03_USER_GUIDE} and {@tutorial 04_DEV_GUIDE}.
+
+- [Dobo DBMS](https://github.com/ardhi/dobo/wiki/GETTING-STARTED.md)
+- [Waibu Web Framework](https://github.com/ardhi/waibu/wiki/GETTING-STARTED.md)
+- [Sumba Biz Suites](https://github.com/ardhi/sumba/wiki/GETTING-STARTED.md)
+- [Masohi Messaging](https://github.com/ardhi/masohi/wiki/GETTING-STARTED.md)

package/wiki/tutorials/03_USER_GUIDE.md

@@ -0,0 +1,262 @@
+# User Guide
+
+## Overview
+
+### Definitions
+
+Before we go any further, let's define some terms that will be used throughout this guide:
+
+1. `{appDir}` - The application directory, which is the root directory of your Bajo app. This is where all your application files reside, and it is typically the directory where you run your app from.
+2. `{dataDir}` - The data directory, which is where Bajo stores its configuration files, plugin data, and other persistent information. By default, this is a subdirectory named `data` within your `{appDir}`.
+3. `{tmpDir}` - The temporary directory, which is where Bajo stores temporary files and caches. By default, Bajo will simply use the system's temporary directory, but you can configure it to be a directory of your choice.
+4. `{pkgName}` - The plugin's package name, that is the name in `package.json`, typically matching its npm listing.
+5. `{ns}`: The plugin namespace or name for short, which is the camel-cased version of the package name.
+6. `{mainNs}` - The special plugin's `main` namespace and directory named `main` within your `{appDir}`; this is where all application code should be written. It is created automatically if it doesn't exist yet.
+
+### Directory Structure
+
+Your typical Bajo app directory structure should look like this:
+
+```
+.
+└── {appDir}
+    ├── {dataDir}
+    │   ├── config
+    │   │   ├── .plugin
+    │   │   ├── bajo.yml
+    │   │   ├── main.yml
+    │   │   └── ...
+    │   └── plugins
+    │       └── ...
+    ├── main
+    │   ├── extend
+    │   │   └── ...
+    │   ├── index.js
+    │   └── ...
+    ├── package.json
+    ├── index.js
+    └── ...
+```
+
+This to note:
+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.yml` to override global settings
+   - all plugin-specific config files, named after their namespace
+   - you can use `.json` if you prefer, but `.yml` is recommended for better readability
+4. The `main` directory, or `{mainNs}` namespace, is the {@link Main|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 like 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
+   - {@link Main|click here} for more details about the `main` plugin
+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 `.yml`, `.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 e.g. `.toml` can also be used by installing and loading the [bajoConfig](https://ardhi.github.io/bajo-config) plugin.
+- The order of precedence is `.js` > `.json` > `.yml` > `.toml`. This means that if a `.js` file exists, it will be used instead of a `.json` file or any other format.
+
+Example: bajo.yml
+```yaml
+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 {pkgName}`, where `{pkgName}` is the plugin's package name. You can install as many plugins as you want; for a complete list of plugins, please {@tutorial 05_ECOSYSTEM}.
+2. Optionally, create `{dataDir}/config/{ns}.yml` to customize the plugin's settings, where `{ns}` is the plugin namespace/name.
+3. Open or create `{dataDir}/config/.plugins` and list the plugin's `{pkgName}` name in it, one per line. Use a `#` hash mark in front of the package name to disable it. The order of the plugins in this file is mostly NOT important, as Bajo will detect automatically.
+
+For example, the text below will load `bajo-config`, `bajo-extra`, and `bajo-template` plugins:
+
+```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 `{pkgName}` and `{ns}`. The plugin package name is the name of the JS package listed on npm, while `{ns}` is the plugin namespace or name for short, 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}.yml` file in your `{dataDir}/config`, where:
+
+- `{ns}`: the namespace/plugin name
+- `{env}`: your desired environment (`dev` or `prod`)
+
+App-wide settings with `bajo-{env}.yml` 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}.yml` if the file exists.
+2. If not, use `{ns}.yml`.
+3. If that also doesn't exist, then use the plugin's default config values.
+
+### Runtime Override
+
+#### Environment Variables
+
+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 always: 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.
+
+- 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}.yml`, use its snake-cased, upper-cased version, e.g.:
+  - `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
+
+You can also override ANY key-value pair setting with argument switches. This is especially useful when you want to run your app with different settings without changing the `.env` file or config files:
+
+- Use switches, e.g.: `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}.yml`, add `--` prefix. E.g.:
+  - `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 `:`. E.g.:
+  - `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, or after a particular operation.
+
+### Usage
+
+In Bajo, hooks can be created anywhere very easily. Simply call the `runHook` method followed by a number of parameters you want to pass or none at all. The hook name is always in the form of {@link Bajo.TNsPathPairs}, and represents the hook point any plugin can hook into.
+
+You can then create a hook listener in your `main` plugin hook directory, which will be called when the hook is executed.
+
+For more info, please read the {@link module:Hook|here}.
+
+Example:
+
+1. Somewhere 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`
+
+This is because a colon (`:`) is prohibited in a file name, so Bajo replaces it with the `@` symbol. And yes, the file name is case-sensitive and must match a correct hook name, so make sure you use the exact same name in both places. But
+you are also allowed to use the kebab-cased version of the hook name (in fact this is the recommended way to make your file name more readable).
+
+During the boot process, Bajo will scan for hook files and load them into the app hook list. When your `runHook` is executed, Bajo will find its related hook 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`. Function handlers 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 earlier than any other handler with a higher level
+  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.
+
+Our advice is to **use it wisely**. Don't use hooks unless necessary; this will make your app or plugin clean and easy to understand.
+