bajo 1.2.9 → 2.0.0

package/misc-docs/getting-started.md

@@ -0,0 +1,142 @@
+# Getting Started
+
+## Overview
+
+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()
+```
+
+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 importance: ```.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;```applet``` | ```boolean``` | no | ```false``` | Set to ```true``` if you want to show log even in [applet mode](#applet-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```, ```bajoExtra``` and ```bajoTemplate```:
+
+```
+bajo-config
+bajo-extra
+bajo-template
+```
+
+If you later decide to NOT load one or more plugins from your app, you just need to remove those from ```.plugins``` file or put ```#``` hash mark in front of package name 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
+- Use 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```

package/misc-docs/toc.json

@@ -0,0 +1,17 @@
+{
+  "getting-started": {
+    "title": "Getting Started"
+  },
+  "user-guide": {
+    "title": "User Guide"
+  },
+  "plugin-dev": {
+    "title": "Plugin Development"
+  },
+  "ecosystem": {
+    "title": "Ecosystem"
+  },
+  "contribution": {
+    "title": "Contribution"
+  }
+}

package/misc-docs/user-guide.md

@@ -0,0 +1 @@
+# User Guide

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "bajo",
-  "version": "1.2.9",
+  "version": "2.0.0",
   "description": "A framework to build a giant monstrous app rapidly",
-  "main": "boot/index.js",
+  "main": "index.js",
   "scripts": {
     "build-doc": "jsdoc -c .jsdoc.conf.json",
     "test": "mocha"
@@ -27,31 +27,32 @@
   "dependencies": {
     "add-filename-increment": "^1.0.0",
     "aneka": "^0.1.4",
-    "chalk": "^5.5.0",
+    "chalk": "^5.6.0",
     "dayjs": "^1.11.13",
     "deep-freeze-strict": "^1.1.1",
     "delay": "^6.0.0",
-    "dotenv": "^16.4.7",
+    "dotenv": "^17.2.1",
     "dotenv-parse-variables": "^2.0.0",
     "empty-dir": "^3.0.0",
     "fast-glob": "^3.3.3",
     "flat": "^6.0.1",
-    "fs-extra": "^11.2.0",
+    "fs-extra": "^11.3.1",
     "get-global-path": "^0.0.1",
     "lodash": "^4.17.21",
     "ms": "^2.1.3",
-    "nanoid": "^5.0.9",
+    "nanoid": "^5.1.5",
     "omit-deep": "^0.3.0",
-    "ora": "^8.1.1",
+    "ora": "^8.2.0",
     "outmatch": "^1.0.0",
-    "semver": "^7.6.3",
+    "semver": "^7.7.2",
     "sprintf-js": "^1.1.3",
-    "yargs": "^17.7.2"
+    "yargs": "^18.0.0"
   },
   "devDependencies": {
-    "@faker-js/faker": "^8.0.2",
-    "chai": "^4.3.7",
-    "clean-jsdoc-theme": "^4.2.7",
-    "sinon": "^15.1.2"
+    "@faker-js/faker": "^9.9.0",
+    "chai": "^6.0.0",
+    "clean-jsdoc-theme": "^4.3.0",
+    "docdash": "^2.0.2",
+    "sinon": "^21.0.0"
   }
 }

package/bajoBook/book/doc/.metadata.json

@@ -1,28 +0,0 @@
-{
-  "book": {
-    "title": "Bajo Framework - User Guides",
-    "description": "Getting started for new user, the basics and advanced topics",
-    "author": "Ardhi Lukianto <ardhi@lukianto.com>",
-    "meta": {
-      "externalLink": {
-        "Github": "https://github.com/ardhi/bajo",
-        "NPM": "https://www.npmjs.com/package/bajo"
-      },
-      "coverImage": "How-to-Make-a-Paper-Boat-564x400@2x.jpg"
-    }
-  },
-  "pages": {
-    "guides": {
-      "level": "1"
-    },
-    "guides/definition": {
-      "level": "1.1"
-    },
-    "guides/intro": {
-      "level": "1.2"
-    },
-    "guides/setup": {
-      "level": "1.3"
-    }
-  }
-}

package/bajoBook/book/doc/pages/guides/definition.md

@@ -1,7 +0,0 @@
-#### Book
-
-#### Chapter
-
-#### Section
-
-#### Page

package/bajoBook/book/doc/pages/guides/intro.md

@@ -1,3 +0,0 @@
----
-title: Introduction
----

package/bajoBook/book/doc/pages/guides/setup.md

@@ -1,22 +0,0 @@
----
-title: Instalation & Setup
----
-
-Installation is quite straight forward; in your app project directory, enter following command:
-
-```sh
-$ npm install bajo-book
-```
-
-Then in your data directory, find ```config``` folder and add the package in ```bajo.json``` file:
-
-```json
-{
-  "log": {
-    "level": "debug"
-  },
-  "plugins": ["bajo-db", "bajo-web", "bajo-web-mpa", "bajo-web-static", "bajo-book"]
-}
-```
-
-After app restart, all books found in plugins will be rebuilt and displayed as web pages in ```/book``` mountpoint (or any prefix you've put in ```bajoBook.json```)

package/bajoBook/book/reference/.metadata.json

@@ -1,152 +0,0 @@
-{
-  "book": {
-    "title": "Bajo Framework - Reference",
-    "description": "Framework reference, API and developer related documentation",
-    "author": "Ardhi Lukianto <ardhi@lukianto.com>",
-    "meta": {
-      "externalLink": {
-        "Github": "https://github.com/ardhi/bajo",
-        "NPM": "https://www.npmjs.com/package/bajo"
-      },
-      "coverImage": "concept-leadership-business-with-paper-boats.jpg",
-      "coverImageAttr": "<a href=\"https://www.freepik.com/free-photo/concept-leadership-business-with-paper-boats_40312961.htm#page=2&query=paper%20boat&position=45&from_view=search&track=ais\">Image by atlascompany</a> on Freepik"
-    }
-  },
-  "pages": {
-    "configuration": {
-      "level": "1"
-    },
-    "configuration/configuration-file": {
-      "level": "1.1"
-    },
-    "helper": {
-      "level": "2"
-    },
-    "helper/break-ns-path": {
-      "level": "2.1"
-    },
-    "helper/build-collections": {
-      "level": "2.2"
-    },
-    "helper/call-helper-or-handler": {
-      "level": "2.3"
-    },
-    "helper/current-loc": {
-      "level": "2.4"
-    },
-    "helper/dayjs": {
-      "level": "2.5"
-    },
-    "helper/defaults-deep": {
-      "level": "2.6"
-    },
-    "helper/dump": {
-      "level": "2.7"
-    },
-    "helper/each-plugins": {
-      "level": "2.8"
-    },
-    "helper/envs": {
-      "level": "2.9"
-    },
-    "helper/error": {
-      "level": "2.10"
-    },
-    "helper/fatal": {
-      "level": "2.11"
-    },
-    "helper/freeze": {
-      "level": "2.12"
-    },
-    "helper/generate-id": {
-      "level": "2.13"
-    },
-    "helper/get-config": {
-      "level": "2.14"
-    },
-    "helper/get-global-module-dir": {
-      "level": "2.15"
-    },
-    "helper/get-helper": {
-      "level": "2.16"
-    },
-    "helper/get-item-by-name": {
-      "level": "2.17"
-    },
-    "helper/get-key-by-value": {
-      "level": "2.18"
-    },
-    "helper/get-module-dir": {
-      "level": "2.19"
-    },
-    "helper/get-plugin": {
-      "level": "2.20"
-    },
-    "helper/get-plugin-data-dir": {
-      "level": "2.21"
-    },
-    "helper/get-plugin-name": {
-      "level": "2.22"
-    },
-    "helper/import-module": {
-      "level": "2.23"
-    },
-    "helper/import-pkg": {
-      "level": "2.24"
-    },
-    "helper/is-empty-dir": {
-      "level": "2.25"
-    },
-    "helper/is-log-in-range": {
-      "level": "2.26"
-    },
-    "helper/is-set": {
-      "level": "2.27"
-    },
-    "helper/is-valid-app": {
-      "level": "2.28"
-    },
-    "helper/is-valid-plugin": {
-      "level": "2.29"
-    },
-    "helper/log": {
-      "level": "2.30"
-    },
-    "helper/log-levels": {
-      "level": "2.31"
-    },
-    "helper/paginate": {
-      "level": "2.32"
-    },
-    "helper/pascal-case": {
-      "level": "2.33"
-    },
-    "helper/print": {
-      "level": "2.34"
-    },
-    "helper/read-config": {
-      "level": "2.35"
-    },
-    "helper/read-json": {
-      "level": "2.36"
-    },
-    "helper/resolve-path": {
-      "level": "2.37"
-    },
-    "helper/resolve-tpl-path": {
-      "level": "2.38"
-    },
-    "helper/run-hook": {
-      "level": "2.39"
-    },
-    "helper/save-as-download": {
-      "level": "2.40"
-    },
-    "helper/titleize": {
-      "level": "2.41"
-    },
-    "helper/white-space": {
-      "level": "2.42"
-    }
-  }
-}

package/bajoBook/book/reference/pages/configuration/configuration-file.md

@@ -1,52 +0,0 @@
-Configuration file should be placed inside app data directory: ```<data dir>/config/bajo.json```. Supported format: **.json** and **.js** file. If you use ```bajo-config```, you can also write config
-file in YAML or TOML format. But we recommend to stick with good old JSON file.
-
-The following table lists all keys used to control running app:
-
-| Key | Type | Default | Description |
-| --- | ---- | ------- | ----------- |
-| ```dir``` | object |||
-| &nbsp;&nbsp;&nbsp;&nbsp;```base``` | string | _Autodetect_ | Your app base directory. _Readonly_ |
-| &nbsp;&nbsp;&nbsp;&nbsp;```pkg``` | string | _Autodetect_ | **bajo** package directory. _Readonly_ |
-| &nbsp;&nbsp;&nbsp;&nbsp;```data``` | string | ```data``` sub directory under ```dir.base``` | Your data directory. Can be anywhere in your file system |
-| &nbsp;&nbsp;&nbsp;&nbsp;```tmp``` | string | Sub directory ```bajo``` in your default OS temp directory | Temp directory. Can be anywhere in your file system |
-| ```log``` | object |||
-| &nbsp;&nbsp;&nbsp;&nbsp;```level``` | string | ```debug``` | Log level. Choices: **trace**, **debug**, **info**, **warn**, **error**, **fatal**, **silent** |
-| &nbsp;&nbsp;&nbsp;&nbsp;```dateFormat``` | string | ```YYYY-MM-DDTHH:MM:ss.SSS[Z]``` | Using Pino format |
-| &nbsp;&nbsp;&nbsp;&nbsp;```tool``` | boolean | ```false``` | If _true_ log will still be shown even when app is running in **sidetool** mode |
-| ```lang``` | string | ```en-US``` | Language used |
-| ```env``` | string | ```dev``` | Running environment: **prod** for production, **dev** for development |
-| ```plugins``` | array | ```['app']``` | List of plugins used by your app |
-| ```exitHandler``` | boolean | ```true``` | If _true_, error will be handled automatically |
-
-#### Example
-
-Using JSON file:
-
-```json
-{
-  "dir": {
-    "data": "/home/me/app/data"
-  },
-  "log": {
-    "level": "trace"
-  },
-  "lang": "id"
-}
-```
-
-Using JS file:
-
-```javascript
-async function () {
-  return {
-    dir: {
-      data: '/home/me/app/data'
-    },
-    log: {
-      level: 'trace'
-    },
-    lang: 'id'
-  }
-}
-```

package/bajoBook/book/reference/pages/helper/break-ns-path.md

@@ -1,24 +0,0 @@
----
-title: function breakNsPath()
----
-
-Bajo uses this common format ```<ns>:<path>``` everywhere to describe a path (variable, function name, etc) belongs to what namespace/plugin. This function helps you to get the right **ns** and **path** pair by validating named namespace.
-
-###### Parameters:
-
-| Name | Type | Default Value | Description |
-| ---- | ---- | ------------- | ----------- |
-| ```item``` | string | ```''``` | ```<ns>:<path>``` pair |
-
-###### Returns:
-
-```array``` of **ns** and **path**
-
-#### Example
-
-```javascript
-...
-const { breakNsPath } = this.bajo.helper
-console.log(breakNsPath('bajoWeb:/my/path'))
-// ['bajoWeb', '/my/path']
-```

package/bajoBook/book/reference/pages/helper/build-collections.md

@@ -1,19 +0,0 @@
----
-title: async function buildCollections()
----
-
-A function helper to collect and format data from a plugin's config entries.
-
-###### Parameters:
-
-| Name | Type | Default Value | Description |
-| ---- | ---- | ------------- | ----------- |
-| ```options``` | object | ```{}``` ||
-|     ```plugin``` | string | _Autodetect_ | Plugin name from which collections are gathered |
-|     ```handler``` | function || Extraction function handler. _Required_ |
-|     ```dupChecks``` | array | ```[]``` | Array of keys to check for duplications. If none is provided, ignore duplication checks |
-|     ```container``` | string | ```connections``` | Plugin's config key used as container |
-
-###### Returns:
-
-```array```

package/bajoBook/book/reference/pages/helper/call-helper-or-handler.md

@@ -1,35 +0,0 @@
----
-title: async function callHelperOrHandler()
----
-
-Helper that call a function based on 1st parameter supplied:
-
-- if it a function (handler), than it will be call it right away.
-- if it a string and a valid helper name, it will call its underlaying function.
-
-Any other parameters will be passed through as its arguments
-
-###### Parameters:
-
-| Name | Type | Default Value | Description |
-| ---- | ---- | ------------- | ----------- |
-| ```nameOrFn``` | string or function || see above |
-| ```...args``` | ```any``` || rest parameter |
-
-###### Returns:
-
-```any```
-
-
-#### Example
-
-```javascript
-...
-const { callHelperOrHandler } = this.bajo.helper
-
-const add = (a, b) => a + b
-const newId = 'bajo:generateId'
-
-console.log(await callHelperOrHandler(add, 5, 6)) // returns: 11
-console.log(await callHelperOrHandler(newId)) // returns: '<generated id>'
-```

package/bajoBook/book/reference/pages/helper/current-loc.md

@@ -1,28 +0,0 @@
----
-title: function currentLoc()
----
-
-In ES 6, there is no *__dirname* nor *__filename*. This helper simply provides a simple way to get what you want
-
-###### Parameters:
-
-| Name | Type | Default Value | Description |
-| ---- | ---- | ------------- | ----------- |
-| ```meta``` ||| imported meta |
-
-###### Returns:
-
-```object``` of
-- ```dir```: current script directory
-- ```file```: current script file
-- ```__dirname```: alias of ```dir```
-- ```__filename```: alias of ```file```
-
-#### Example
-
-```javascript
-...
-const { currentLoc } = this.bajo.helper
-const { dir, file } = currentLoc(import.meta)
-console.log(dir) // prints: '/home/me/apps/current/dir'
-```

package/bajoBook/book/reference/pages/helper/dayjs.md

@@ -1,13 +0,0 @@
----
-title: function dayjs()
----
-
-###### Parameters:
-
-| Name | Type | Default Value | Description |
-| ---- | ---- | ------------- | ----------- |
-
-###### Returns:
-
-
-#### Example

package/bajoBook/book/reference/pages/helper/defaults-deep.md

@@ -1,29 +0,0 @@
----
-title: function defaultsDeep()
----
-
-Similar to lodash's [defaultsDeep](https://lodash.com/docs/4.17.15#defaultsDeep), but without mutating the source object, and no merging of arrays.
-
-Based on [@nodeutils/defaults-deep](https://github.com/nodeutils/defaults-deep), customized to work
-in Bajo environment
-
-###### Parameters:
-
-| Name | Type | Default Value | Description |
-| ---- | ---- | ------------- | ----------- |
-| ```...args``` | ...object || rest parameter of objects |
-
-###### Returns:
-
-```object``` of merged argument's objects
-
-
-#### Example
-
-```javascript
-...
-const { defaultsDeep } = this.bajo.helper
-const a = { one: 1, two: 2 }
-const b = { one: 'one', three: 'three' }
-console.log(defaultsDeep(b, a)) // returns: { one: 'one', two: 2, three: 'three' }
-```