bajo 0.1.0 → 0.2.1

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

@@ -0,0 +1,28 @@
+{
+  "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

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

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

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

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

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

@@ -0,0 +1,152 @@
+{
+  "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

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

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

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

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

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

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

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

@@ -0,0 +1,29 @@
+---
+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' }
+```

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

@@ -0,0 +1,32 @@
+---
+title: function dump()
+---
+
+A ```console.log``` with untruncated, deep objects. Doesn't return anything, instead prints arguments as nested, deep object.
+
+###### Parameters:
+
+| Name | Type | Default Value | Description |
+| ---- | ---- | ------------- | ----------- |
+| ```...args``` | ...object || rest parameter of objects |
+
+###### Returns:
+
+```void```
+
+#### Example
+
+```javascript
+...
+const { dump } = this.bajo.helper
+const value = {
+  level1: {
+    level2: {
+      level3: {
+        level4: 'this is a test'
+      }
+    }
+  }
+}
+dump(value)
+```

package/bajoBook/book/reference/pages/helper/each-plugins.md

@@ -0,0 +1,24 @@
+---
+title: async function eachPlugins()
+---
+
+Walk through all loaded plugins and execute the callback handler.
+
+###### Parameters:
+
+| Name | Type | Default Value | Description |
+| ---- | ---- | ------------- | ----------- |
+| ```handler``` | async function || callback handler. _Required_ |
+| ```options``` | object |||
+|     ```key``` | string | ```name``` | Key of Bajo's config object that will be used as the key of returned object |
+|     ```glob``` | string/object || see above |
+|     ```ns``` | string | _Autodetect_ | If not set, it defaults to calling plugin |
+|     ```extend``` | string || see above |
+|     ```extendHandler``` | function | ```handler``` | see above |
+|     ```useBajo``` | boolean | ```false``` | weather to scan **bajo** package dir too |
+
+###### Returns:
+
+```object```
+
+#### Example

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

@@ -0,0 +1,11 @@
+---
+title: object envs
+---
+
+Variable of object holding all available environtments
+
+#### Example
+
+```javascript
+const { envs } = this.bajo.helper
+console.log(envs) // prints: { dev: 'development', prod: 'production' }

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

@@ -0,0 +1,29 @@
+---
+title: function error()
+---
+
+A shortcut to create an instance of Error with message and optionally rest parameter within a single line.
+
+Message can hold ```sprintf``` token. If it does, use rest parameter to replace its token.
+
+If last parameter is a plain object, it will be used as error payload.
+
+###### Parameters:
+
+| Name | Type | Default Value | Description |
+| ---- | ---- | ------------- | ----------- |
+| ```message``` | string || Error message. _Required_ |
+| ```...args``` | ...any || see above |
+
+###### Returns:
+
+```object``` new instance of node's Error
+
+#### Example
+
+```javascript
+...
+const { error } = this.bajo.helper
+const payload = { statusCode: 500, details: [{ field: 'username', error: 'Required' }] }
+throw error('This is a %s error, it should also hold some payloads', 'fatal', payload)
+```

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

@@ -0,0 +1,18 @@
+---
+title: function fatal()
+---
+
+Basically the same as [error()](2.9-error.md), with two extras:
+
+- prints error on screen
+- terminate running program with exit code 1
+
+###### Parameters:
+
+| Name | Type | Default Value | Description |
+| ---- | ---- | ------------- | ----------- |
+| ```...args``` | ...any || any arguments provided here will be passed through **error()** |
+
+###### Returns:
+
+```void```

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

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

package/bajoBook/book/reference/pages/helper/generate-id.md

@@ -0,0 +1,36 @@
+---
+title: function generateId()
+---
+
+ID generator based on [nanoid](https://github.com/ai/nanoid).
+
+By default, ```options.pattern``` is set to ```abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789``` so that resulted ID will be a full alphanumeric characters with the length of ```options.length``` (default: ```21```)
+
+If ```options.pattern``` is an object:
+
+- ```pattern```: characters to use
+- ```lowerCase```: if ```true```, only use lowercase
+- ```upperCase```: if ```true```, only use uppercase
+
+```lowerCase``` and ```upperCase``` is mutually exclusive, first one win.
+
+###### Parameters:
+
+| Name | Type | Default Value | Description |
+| ---- | ---- | ------------- | ----------- |
+| ```options``` | object |||
+|     ```pattern``` | string or object | all alphanumeric characters | see above |
+|     ```length``` | integer | ```21``` | length of generated ID |
+|     ```returnInstance``` | boolean | ```false``` | Set ```true``` to return a nanoid instance |
+
+###### Returns:
+
+```string``` or ```object```
+
+#### Example
+
+```javascript
+...
+const { generateId } = this.bajo.helper
+console.log(generateId()) // returns: <randomly generated characters>
+```

package/bajoBook/book/reference/pages/helper/get-config.md

@@ -0,0 +1,27 @@
+---
+title: function getConfig()
+---
+
+Get configuration object of **bajo** or its **plugin**
+
+###### Parameters:
+
+| Name | Type | Default Value | Description |
+| ---- | ---- | ------------- | ----------- |
+| ```name``` | string | ```bajo``` | A valid plugin name |
+| ```options``` | object |||
+|     ```full``` | boolean | ```false``` | If ```true```, returns ALL config objects belonging to named plugin. Otherwise, returns only subset of objects that can be changed through configuration file |
+|     ```clone``` | boolean | ```false``` | If ```true```, returns cloned object |
+
+###### Returns:
+
+```object```
+
+#### Example
+
+```javascript
+...
+const { getConfig } = this.bajo.helper
+const cfg = getConfig('bajoLogger')
+console.log(cfg)
+```

package/bajoBook/book/reference/pages/helper/get-global-module-dir.md

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

package/bajoBook/book/reference/pages/helper/get-helper.md

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

package/bajoBook/book/reference/pages/helper/get-item-by-name.md

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