bajo 1.2.8 → 2.0.0

package/.jsdoc.conf.json

@@ -2,17 +2,20 @@
   "plugins": ["plugins/markdown"],
   "opts": {
     "encoding": "utf8",
-    "readme": "./README.md",
     "recurse": true,
     "verbose": true,
     "destination": "./docs",
     "template": "node_modules/clean-jsdoc-theme",
+    "tutorials": "./misc-docs",
     "theme_opts": {
-      "default_theme": "dark",
+      "default_theme": "light",
       "display-module-header": true,
       "title": "Bajo Framework",
       "homepageTitle": "Bajo Framework",
       "menu": [{
+        "title": "Bajo.app",
+        "link": "https://bajo.app"
+      }, {
         "title": "NPM",
         "link": "https://www.npmjs.com/package/bajo"
       }, {
@@ -24,7 +27,7 @@
   "source": {
     "include": ["."],
     "includePattern": ".+\\.js(doc|x)?$",
-    "exclude": ["node_modules", "doc", "lib", "package-lock.json"]
+    "exclude": ["node_modules", "docs", "test", "api-docs"]
   },
   "markdown": {
     "hardwrap": false,

package/README.md

@@ -2,156 +2,16 @@
 
 ![GitHub package.json version](https://img.shields.io/github/package-json/v/ardhi/bajo) ![NPM Version](https://img.shields.io/npm/v/bajo)
 
-> <br />**Attention**: I do NOT accept any pull request at the moment, thanks!<br /><br />
+> <br />**Attention**: I do NOT accept any pull request at the moment, thanks! ([Why?](misc-docs/contribution.md))<br /><br />
 
-## Overview
+## Documentations
 
-Before we go any further, below are some terminologies I use throughout these documentations:
-
-- ```<bajo-base-dir>```: project directory is where you write all your codes
-- ```<bajo-data-dir>```: data directory, defaults to ```<bajo-base-dir>/data``` if not specifically stated
-- ```<bajo-tmp-dir>```: temp directory, defaults to OS temporary directory
-- ```<package>```: plugin package name as normally showed on npm listing
-- ```<plugin>```: plugin name, which is camel cased version of package name
-
-## Installation
-
-Open your terminal and type:
-
-```bash
-$ npm install bajo
-```
-
-## Fire up!
-
-Create a new empty directory, this will be your project directory or your ```<bajo-base-dir>```. Now goto your newly created directory, and type:
-
-```bash
-$ npm init
-```
-
-You'll be asked to name your project etc. **IMPORTANT**: don't forget to mark your project as ES6 project by setting ```type``` key in your ```package.json``` to ```module```.
-
-After completing those steps, move on the the next one: crating bajo bootstrap.
-
-Inside your ```<bajo-base-dir>```, create the ```index.js``` file and put these lines below:
-
-```js
-import bajo from 'bajo'
-await bajo.default()
-```
-
-A bajo app **ALWAYS** needs a data directory to put configuration files, etc. This
-could be located inside or outside your ```<bajo-base-dir>```.
-
-Lets assume you're going to put your data directory inside your ```<bajo-base-dir>```. So please
-create a new directory called ```data``` first. After that, just type in your terminal:
-
-```bash
-$ node index.js --dir-data=data
-```
-
-Or you could utilize ```dotenv``` by creating ```.env``` file in the same directory as ```index.js```, and put this inside:
-
-```
-DIR_DATA = ./data
-```
-
-Now you can omit calling node with arguments, you just need to type:
-
-```bash
-$ node index.js
-```
-
-## Configuration
-
-### General rules
-
-- All configuration files must be placed in ```<bajo-data-dir>/config/``` subfolder
-- Config files should be named after its plugin name
-- File format should be in ```.json``` or ```.js``` format
-- If  ```.js``` file is used, it should be in ES6 format and should export either plain javascript object or a function (sync or async both 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 [bajoConfig](https://github.com/ardhi/bajo-config) plugin
-- Order of precedence: ```.js``` > ```.json``` > ```.yml``` > ```.yaml``` > ```.toml```
-
-### Main configuration File
-
-It should be named ```bajo.json``` with following keys:
-
-| Key | Type | Required | Default | Description |
-| --- | ---- | -------- | ------- | ----------- |
-| ```env``` | ```string``` | no | ```dev``` | App environment: ```dev``` or ```prod``` |
-| ```log``` | ```object``` | no || Logger setting |
-| &nbsp;&nbsp;```dateFormat``` | ```string``` | no | ```YYYY-MM-DDTHH:MM:ss.SSS[Z]```| Date format accoding to [dayjs](https://github.com/iamkun/dayjs) |
-| &nbsp;&nbsp;```tool``` | ```boolean``` | no | ```false``` | Set to ```true``` if you want to show log even in [tool mode](#tool-mode) |
-| &nbsp;&nbsp;```level``` | ```string``` | no || Set one of these: ```trace```, ```debug```, ```info```, ```warn```, ```error```, ```fatal``` and ```silent```. If it isn't set, it will auto selected based on environment |
-| ```lang``` | ```string``` | no || Language to use. If not set, it will be auto detected |
-| ```exitHandler``` | ```boolean``` | no | ```true``` | Set to ```false``` if you want your app **NOT** to exit gracefully |
-
-### Installed Plugins
-
-Plugins are what make Bajo Framework so great and flexible: they extends app features!
-
-To use plugins:
-
-1. Install with ```npm install <package>```
-2. Optionally create ```<bajo-data-dir>/config/<plugin>.json``` to customize plugin settings
-3. Open/create ```<bajo-data-dir>/config/.plugins``` and put ```<package>``` in it, line by line
-
-Example below will load ```bajoConfig```, ```bajoLogger``` and ```bajoMqtt```:
-
-```
-bajo-config
-bajo-logger
-bajo-mqtt
-```
-
-If you later decide to NOT load one or more plugins from your app, you just need to remove those from ```.plugins``` file and restart your app.
-
-> **Warning**: please do not confuse between ```<package>``` and ```<plugin>```. Plugin package is the name of JS package listed on npm, while plugin name is the name of a plugin - a camel cased version of plugin package
-
-### Configuration Overrides
-
-You can override ANY settings on ANY configuration files with dotenv variables and program's argument switches easily.
-
-Order of importance: dotenv variable > args switches > config files
-
-#### dotenv
-
-- Create/open ```<bajo-base-dir>/.env```
-- Use ```__``` (double underscores) as the replacement of the dot in object
-- ```DIR__DATA```: Set ```<bajo-data-dir>``` data directory
-- ```DIR__TMP```: Set ```<bajo-tmp-dir>``` temp directory
-- For every key in ```bajo.json```, use its snake cased, upper cased version, e.g:
-  - ```env``` => ```ENV```
-  - ```log.dateFormat``` => ```LOG__DATE_FORMAT```
-  - ```exitHandler``` => ```EXIT_HANDLER```
-- To override plugins config, prepend every key in plugin config with snake cased, upper cased version of the plugin name followed by a dot, e.g:
-  - ```key``` in ```myPlugin``` => ```MY_PLUGIN.KEY```
-  - ```key.subKey.subSubKey``` in ```myPlugin``` => ```MY_PLUGIN.KEY__SUB_KEY__SUB_SUB_KEY```
-
-#### Program argument switches
-- Execute with switches, e.g: ```node index.js --xxx=one --yyy=two```
-- Every switches must be prefixed with ```--```
-- Use ```-``` as the replacement of the dot in object
-- ```--dir-data```: Set ```<bajo-data-dir>``` data directory
-- ```--dir-tmp```: Set ```<bajo-tmp-dir>``` temp directory
-- For every key in ```bajo.json```, add prefix ```--``` e.g:
-  - ```env``` => ```--env=prod```
-  - ```log.dateFormat``` => ```--log-dateFormat=xxx```
-  - ```exitHandler``` => ```--exitHandler```
-- To override plugins config, prepend every key in plugin config with the plugin name  followed by a ```:```, e.g:
-  - ```key``` in ```myPlugin``` => ```--myPlugin:key```
-  - ```key.subKey.subSubKey``` in ```myPlugin``` => ```--myPlugin:key-subKey-subSubKey```
-
-## More Documentations
-
-- [Tutorial](docs/tutorial.md)
-- [User Guide](docs/user-guide.md)
-- [Plugin Development](docs/plugin-dev.md)
-- [API](docs/api.md)
-- [Ecosystem](docs/ecosystem.md)
+- [Getting Started](misc-docs/getting-started.md)
+- [User Guide](misc-docs/user-guide.md)
+- [Plugin Development](misc-docs/plugin-dev.md)
+- [Ecosystem](misc-docs/ecosystem.md)
+- [Contribution](misc-docs/contribution.md)
+- [API](docs)
 
 ## License
 

package/class/app.js

@@ -0,0 +1,113 @@
+import util from 'util'
+import lodash from 'lodash'
+import Bajo from './bajo.js'
+import resolvePath from '../lib/resolve-path.js'
+import parseArgsArgv from '../lib/parse-args-argv.js'
+import parseEnv from '../lib/parse-env.js'
+import {
+  buildBaseConfig,
+  buildExtConfig,
+  buildPlugins,
+  collectConfigHandlers,
+  bootOrder,
+  bootPlugins,
+  exitHandler,
+  runAsApplet
+} from './helper/bajo.js'
+
+const { last } = lodash
+
+/**
+ * App class. This is where everything starts, the boot process:
+ *
+ * 1. Parsing all arguments and environment values
+ * 2. Create {@link Bajo|Bajo} instance
+ * 3. Building {@link module:class/helper/bajo.buildBaseConfig|base config}
+ * 4. {@link module:class/helper/bajo.buildPlugins|Building plugins}
+ * 5. Collect all {@link module:class/helper/bajo.collectConfigHandlers|config handler}
+ * 6. Building {@link module:class/helper/bajo.buildExtConfig|extra config}
+ * 7. Setup {@link module:class/helper/bajo.bootOrder|boot order}
+ * 8. {@link module:class/helper/bajo.bootPlugins|Boot loaded plugins}
+ * 9. Attach {@link module:class/helper/bajo.exitHandler|exit handlers}
+ * 10. Finish
+ *
+ * After boot process is completed, event ```bajo:afterBootComplete``` is emitted.
+ *
+ * If app mode is ```applet```, it runs your choosen applet instead.
+ *
+ * @class
+ */
+class App {
+  /**
+   * Class constructor
+   *
+   * @param {string} cwd - Current working dirctory
+   */
+  constructor (cwd) {
+    if (!cwd) cwd = process.cwd()
+    const l = last(process.argv)
+    if (l.startsWith('--cwd')) {
+      const parts = l.split('=')
+      cwd = parts[1]
+    }
+    this.dir = resolvePath(cwd)
+    process.env.APPDIR = this.dir
+  }
+
+  /**
+   * Add a plugin to the app
+   *
+   * @method
+   * @param {Object} plugin - A valid bajo plugin
+   */
+  addPlugin = (plugin) => {
+    if (this[plugin.name]) throw new Error(`Plugin '${plugin.name}' added already`)
+    this[plugin.name] = plugin
+  }
+
+  /**
+   * Dumping variable on screen
+   *
+   * @method
+   * @param  {...any} args - any arguments passed will be displayed on screen. If the last argument is a boolean 'true', app will quit rightaway
+   */
+  dump = (...args) => {
+    const terminate = last(args) === true
+    if (terminate) args.pop()
+    for (const arg of args) {
+      const result = util.inspect(arg, false, null, true)
+      console.log(result)
+    }
+    if (terminate) process.kill(process.pid, 'SIGINT')
+  }
+
+  /**
+   * Booting the app
+   *
+   * @method
+   * @async
+   */
+  boot = async () => {
+    // argv/args
+    const { args, argv } = await parseArgsArgv.call(this.app) ?? {}
+    this.argv = argv
+    this.args = args
+    this.env = parseEnv() ?? {}
+
+    const bajo = new Bajo(this)
+    await buildBaseConfig.call(bajo)
+    await buildPlugins.call(bajo)
+    await collectConfigHandlers.call(bajo)
+    await buildExtConfig.call(bajo)
+    await bootOrder.call(bajo)
+    await bootPlugins.call(bajo)
+    await exitHandler.call(bajo)
+    // boot complete
+    const elapsed = new Date() - bajo.runAt
+    bajo.log.info('bootCompleted%s', bajo.lib.aneka.secToHms(elapsed, true))
+    await bajo.runHook('bajo:afterBootComplete')
+    if (bajo.applet) await runAsApplet.call(bajo)
+  }
+}
+
+export default App