bajo 0.0.1 → 0.1.0

package/.jsdoc.conf.json

@@ -0,0 +1,38 @@
+{
+  "plugins": ["plugins/markdown"],
+  "opts": {
+    "encoding": "utf8",
+    "readme": "./README.md",
+    "recurse": true,
+    "verbose": true,
+    "destination": "./docs",
+    "template": "node_modules/clean-jsdoc-theme",
+    "theme_opts": {
+      "default_theme": "dark",
+      "display-module-header": true,
+      "title": "Bajo Framework",
+      "homepageTitle": "Bajo Framework",
+      "menu": [{
+        "title": "NPM",
+        "link": "https://www.npmjs.com/package/bajo"
+      }, {
+        "title": "Github",
+        "link": "https://github.com/ardhi/bajo"
+      }]
+    }
+  },
+  "source": {
+    "include": ["."],
+    "includePattern": ".+\\.js(doc|x)?$",
+    "exclude": ["node_modules", "doc", "lib", "package-lock.json"]
+  },
+  "markdown": {
+    "hardwrap": false,
+    "idInHeadings": true
+  },
+  "sourceType": "module",
+  "templates": {
+    "cleverLinks": false,
+    "monospaceLinks": false
+  }
+}

package/README.md

@@ -1,3 +1,57 @@
-# bajo
-
-In development. Stay tune!
+# Bajo Framework
+
+## Installation
+
+> Note: you must have a proper install of ```node```, ```npm``` and/or ```yarn``` before
+
+Open your terminal and type:
+
+```
+npm install bajo
+# or
+yarn add bajo
+```
+
+## Fire up!
+
+Goto your project directory, create the ```index.js``` file and put this in it:
+
+```js
+const bajo = require('bajo')
+bajo.boot()
+  .then(scope => {
+  })
+  .catch(err => {
+    console.trace(err)
+  })
+```
+
+Bajo application **ALWAYS** need a data directory to put configuration files, etc. This
+cloud be located inside or outside your project directory.
+
+Lets assume you're going to put your data directory inside your project directory. So please
+create a new directory called ```data``` first. After that, just type in your terminal:
+
+```
+node index.js --dir-data=data
+```
+
+Or you could use ```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:
+
+```
+node index.js
+```
+
+## Documentation
+
+[API](https://ardhi.github.io/bajo)
+
+## License
+
+[MIT](LICENSE) License

package/boot/attach-helper.js

@@ -0,0 +1,26 @@
+import buildHelper from './lib/build-helper.js'
+import logger from './lib/logger.js'
+import fs from 'fs-extra'
+import dayjs from 'dayjs'
+import utc from 'dayjs/plugin/utc.js'
+import customParseFormat from 'dayjs/plugin/customParseFormat.js'
+import deepFreeze from 'deep-freeze-strict'
+import currentLoc from './helper/current-loc.js'
+
+dayjs.extend(utc)
+dayjs.extend(customParseFormat)
+
+export default async function () {
+  this.bajo.helper = await buildHelper.call(this, `${currentLoc(import.meta).dir}/helper`)
+  this.bajo.helper.freeze = (o, shallow) => {
+    if (shallow) Object.freeze(o)
+    else deepFreeze(o)
+  }
+  this.bajo.helper.log = logger.call(this)
+  this.bajo.helper.dayjs = dayjs
+  this.bajo.helper.freeze(this.bajo.helper, true)
+  // last cleanup
+  if (!fs.existsSync(this.bajo.config.dir.data)) {
+    this.bajo.helper.log.warn('Data directory \'%s\' is not set yet!', this.bajo.config.dir.data)
+  }
+}

package/boot/boot-order.js

@@ -0,0 +1,34 @@
+import { reduce, map, isNaN, trim, forOwn, orderBy } from 'lodash-es'
+import fs from 'fs-extra'
+import getModuleDir from './helper/get-module-dir.js'
+
+async function bootOrder () {
+  const { log, envs, error } = this.bajo.helper
+  log.debug('Setup boot order')
+  const config = this.bajo.config
+  const order = reduce(config.plugins, (o, k, i) => {
+    const key = map(k.split(':'), m => trim(m))
+    if (key[1] && !isNaN(Number(key[1]))) o[key[0]] = Number(key[1])
+    else o[key[0]] = 10000 + i
+    return o
+  }, {})
+  const norder = {}
+  for (let n of config.plugins) {
+    n = map(n.split(':'), m => trim(m))[0]
+    const dir = n === 'app' ? (config.dir.base + '/app') : getModuleDir(n)
+    if (n !== 'app' && !fs.existsSync(`${dir}/bajo`)) throw error('Package \'%s\' not found or isn\'t a valid Bajo package', n)
+    norder[n] = NaN
+    try {
+      norder[n] = Number(trim(await fs.readFile(`${dir}/bajo/.bootorder`, 'utf8')))
+    } catch (err) {}
+  }
+  const result = []
+  forOwn(order, (v, k) => {
+    const item = { k, v: isNaN(norder[k]) ? v : norder[k] }
+    result.push(item)
+  })
+  config.plugins = map(orderBy(result, ['v']), 'k')
+  log.info('Run in \'%s\' environment', envs[config.env])
+}
+
+export default bootOrder

package/boot/build-config.js

@@ -0,0 +1,94 @@
+/**
+ * @module boot/buildConfig
+ */
+
+import os from 'os'
+import fs from 'fs-extra'
+import { get, set, pick, values, keys, uniq, without, filter, map, isEmpty, trim } from 'lodash-es'
+import omitDeep from 'omit-deep'
+import resolvePath from './helper/resolve-path.js'
+import readConfig from './helper/read-config.js'
+import getKeyByValue from './helper/get-key-by-value.js'
+import envs from './helper/envs.js'
+import defaultsDeep from './helper/defaults-deep.js'
+import parseArgsArgv from './lib/parse-args-argv.js'
+import parseEnv from './lib/parse-env.js'
+import error from './helper/error.js'
+
+const configFilePick = ['log', 'plugins', 'env', 'run']
+const configFileOmit = ['tool', 'spawn', 'cwd']
+
+const defConfig = {
+  dir: {},
+  log: {
+    dateFormat: 'YYYY-MM-DDTHH:MM:ss.SSS[Z]',
+    report: [],
+    tool: false
+  },
+  lang: Intl.DateTimeFormat().resolvedOptions().lang,
+  plugins: ['app'],
+  env: 'dev',
+  tool: false,
+  exitHandler: true
+}
+
+/**
+ * Building configuration object. Read configurtion file from app data directory, program
+ * arguments and envoronment variables with following priority: ```Env > Args > Config file >
+ * defaults config```
+ *
+ * If data directory is provided and doesn't exist yet, it will be automatically created.
+ *
+ * Config file must be located in: ```<data dir>/config/bajo.<format>```, and support either
+ * ```.json``` or ```.js``` format. JS format must be a nodejs module that wrap an async
+ * function and return an object
+ *
+ * If app run tool, by default log is in silent. To activate, set log.tool to true
+ *
+ * By default, if 'app' is a bajo app, it is always the last plugins to boot. To overide this
+ * behavior, you should configure it at plugin level (i.e. using .bootorder file)
+ *
+ * @instance
+ * @async
+ * @throws Will throw if data directory is not provided
+ *
+ * @returns {Object} config
+ */
+
+async function buildConfig (cwd) {
+  const { args, argv } = await parseArgsArgv()
+  const env = parseEnv()
+  const envArgv = defaultsDeep({}, env.root, argv.root)
+  // directories
+  set(envArgv, 'dir.base', cwd)
+  if (!get(envArgv, 'dir.data')) set(envArgv, 'dir.data', `${envArgv.dir.base}/data`)
+  envArgv.dir.data = resolvePath(envArgv.dir.data)
+  if (!envArgv.dir.tmp) {
+    envArgv.dir.tmp = resolvePath(os.tmpdir()) + '/bajo'
+    fs.ensureDirSync(envArgv.dir.tmp)
+  }
+  // config merging
+  let resp = await readConfig.call(this, `${envArgv.dir.data}/config/bajo.*`, { ignoreError: true })
+  resp = omitDeep(pick(resp, configFilePick), configFileOmit)
+  const config = defaultsDeep({}, envArgv, resp, defConfig)
+  // force init
+  config.args = args
+  config.env = config.env.toLowerCase()
+  if (values(envs).includes(config.env)) config.env = getKeyByValue(envs, config.env)
+  if (!keys(envs).includes(config.env)) config.env = 'dev'
+  process.env.NODE_ENV = envs[config.env]
+  if (!config.log.level) config.log.level = config.env === 'dev' ? 'debug' : 'info'
+  if (config.silent) config.log.level = 'silent'
+  // sanitize plugins
+  config.plugins = without(config.plugins, 'app')
+  if (fs.existsSync(`${config.dir.base}/app/bajo`)) config.plugins.push('app')
+  config.plugins = filter(uniq(map(config.plugins, b => trim(b))), b => !isEmpty(b))
+  if (config.tool) {
+    if (!config.plugins.includes('bajo-cli')) throw error('Sidetool needs to have \'bajo-cli\' package loaded first')
+    if (!config.log.tool) config.log.level = 'silent'
+    config.exitHandler = false
+  }
+  this.bajo.config = config
+}
+
+export default buildConfig

package/boot/create-scope.js

@@ -0,0 +1,36 @@
+/**
+ * @module boot/createScope
+ */
+
+import { isFunction } from 'lodash-es'
+import readJson from './helper/read-json.js'
+import importModule from './helper/import-module.js'
+
+async function defHandler (file) {
+  let mod = await importModule(file)
+  if (isFunction(mod)) mod = await mod.call(this)
+  return mod
+}
+
+const configHandlers = [
+  { ext: '.js', handler: defHandler },
+  { ext: '.mjs', handler: defHandler },
+  { ext: '.json', handler: readJson }
+]
+
+const bajo = {
+  runAt: new Date(),
+  configHandlers
+}
+
+/**
+ * @instance
+ * @async
+ * @returns {Object} scope
+ */
+
+function createScope () {
+  return { bajo }
+}
+
+export default createScope

package/boot/exit-handler.js

@@ -0,0 +1,60 @@
+async function exit (signal) {
+  const { eachPlugins, log } = this.bajo.helper
+  log.warn('\'%s\' signal received', signal)
+  await eachPlugins(async function ({ plugin }) {
+    const handler = this.bajo.exitHandler[plugin]
+    if (!handler) return undefined
+    await handler.call(this)
+    log.debug('Exited: %s', plugin)
+  })
+  log.debug('Program shutdown')
+  process.exit(0)
+}
+
+async function exitHandler () {
+  const { log, getConfig } = this.bajo.helper
+  const config = getConfig()
+  if (!config.exitHandler) return
+
+  log.debug('Exit handlings')
+
+  process.on('SIGINT', async () => {
+    await exit.call(this, 'SIGINT')
+  })
+
+  process.on('SIGTERM', async () => {
+    await exit.call(this, 'SIGTERM')
+  })
+
+  process.on('uncaughtException', (error, origin) => {
+    const { getConfig } = this.bajo.helper
+    const config = getConfig()
+    if (config.log.report.includes('sys:uncaughtException')) log.fatal({ origin }, '%s', error.message)
+    setTimeout(() => {
+      console.error(error)
+      process.exit(1)
+    }, 50)
+  })
+
+  process.on('unhandledRejection', (reason, promise) => {
+    const stackFile = reason.stack.split('\n')[1]
+    let file
+    const info = stackFile.match(/\((.*)\)/) // file is in (<file>)
+    if (info) file = info[1]
+    else if (stackFile.startsWith('    at ')) file = stackFile.slice(7) // file is stackFile itself
+    if (!file) return
+    const parts = file.split(':')
+    const column = parseInt(parts[parts.length - 1])
+    const line = parseInt(parts[parts.length - 2])
+    parts.pop()
+    parts.pop()
+    file = parts.join(':')
+    log.error({ file, line, column }, '%s', reason.message)
+  })
+
+  process.on('warning', warning => {
+    log.error('%s', warning.message)
+  })
+}
+
+export default exitHandler

package/boot/helper/build-collections.js

@@ -0,0 +1,40 @@
+import { filter, isArray, each, pullAt, camelCase } from 'lodash-es'
+
+async function buildCollections ({ name, handler, dupChecks, container = 'connections' } = {}) {
+  const { getConfig, getPluginName, fatal, runHook } = this.bajo.helper
+  if (!name) name = getPluginName(4)
+  const options = getConfig(name, { full: true })
+  if (!options[container]) return []
+  if (!isArray(options[container])) options[container] = [options[container]]
+  options[container] = options[container] ?? []
+  await runHook(`${name}:${camelCase(`before build ${container}`)}`)
+  const deleted = []
+  for (const index in options[container]) {
+    const item = options[container][index]
+    const result = await handler.call(this, { item, index, options })
+    if (result) options[container][index] = result
+    else if (result === false) deleted.push(index)
+  }
+  if (deleted.length > 0) pullAt(options[container], deleted)
+
+  // check for duplicity
+  each(options[container], c => {
+    const checker = {}
+    each(dupChecks, d => {
+      checker[d] = c[d]
+    })
+    const match = filter(options[container], checker)
+    if (match.length > 1) fatal('One or more %s shared the same \'%s\'', container, dupChecks.join(', '), { code: 'BAJOMQTT_CONNECTION_NOT_UNIQUE' })
+  })
+  /*
+  each(dupChecks, item => {
+    const items = map(options[container], item)
+    const uItems = uniq(items)
+    if (items.length !== uItems.length) fatal('One or more %s shared the same \'%s\'', container, item, { code: 'BAJOMQTT_CONNECTION_NOT_UNIQUE' })
+  })
+  */
+  await runHook(`${name}:${camelCase(`after build ${container}`)}`)
+  return options[container]
+}
+
+export default buildCollections

package/boot/helper/call-helper-or-handler.js

@@ -0,0 +1,15 @@
+import { isString, isFunction } from 'lodash-es'
+import getHelper from './get-helper.js'
+
+async function callHelperOrHandler (nameOrFn, ...args) {
+  let result
+  if (isString(nameOrFn)) {
+    const helper = getHelper.call(this, nameOrFn)
+    if (isFunction(helper)) result = await helper(...args)
+  } else if (isFunction(nameOrFn)) {
+    result = await nameOrFn.call(this, ...args)
+  }
+  return result
+}
+
+export default callHelperOrHandler

package/boot/helper/current-loc.js

@@ -0,0 +1,11 @@
+import path from 'path'
+import resolvePath from './resolve-path.js'
+import { fileURLToPath } from 'url'
+
+const currentLoc = (meta) => {
+  const file = resolvePath(fileURLToPath(meta.url))
+  const dir = path.dirname(file)
+  return { dir, file, __dirname: dir, __filename: file }
+}
+
+export default currentLoc

package/boot/helper/defaults-deep.js

@@ -0,0 +1,14 @@
+import { mergeWith, isArray } from 'lodash-es'
+// taken from https://github.com/nodeutils/defaults-deep/blob/master/lib/index.js
+
+const defaultsDeep = (...args) => {
+  const output = {}
+  args.reverse().forEach(function (item) {
+    mergeWith(output, item, function (objectValue, sourceValue) {
+      return isArray(sourceValue) ? sourceValue : undefined
+    })
+  })
+  return output
+}
+
+export default defaultsDeep

package/boot/helper/dump.js

@@ -0,0 +1,10 @@
+import util from 'util'
+
+const dump = (...args) => {
+  for (const arg of args) {
+    const result = util.inspect(arg, false, null, true)
+    console.log(result)
+  }
+}
+
+export default dump

package/boot/helper/each-plugins.js

@@ -0,0 +1,94 @@
+import { camelCase, isString, omit, isPlainObject, slice } from 'lodash-es'
+import fastGlob from 'fast-glob'
+import path from 'path'
+import omittedPluginKeys from '../lib/omitted-plugin-keys.js'
+
+/**
+ * @module helper/eachPlugins
+ */
+
+/**
+ * Callback function that will be executed while walking through all Bajos
+ *
+ * @callback handlerFn
+ * @async
+ * @param {Object} argument - Provides information about current Bajo
+ * @param {string} argument.name - Bajo's name
+ * @param {string} argument.pkgName - Bajo's package name
+ * @param {Object} argument.cfg - Bajo's config object
+ * @returns {Object|boolean|undefined}
+ */
+
+/**
+ * Walk through all plugins and execute the callback handler
+ *
+ * @instance
+ * @async
+ * @param {function} handlerFn - [The callback]{@link module:helper/eachPlugins~handlerFn}
+ * @param {Object} [options] - Optional parameter
+ * @param {string} [options.key=name] - Key of Bajo's config object that will be used as the key of returned object
+ * @returns {Object} Results from callback execution through all Bajos
+ *
+ * @example
+ * const { eachPlugins } = this.bajo.helper
+ * await eachPlugins(async function ({ name }) => {
+ *   console.log(name)
+ * })
+ */
+
+async function eachPlugins (handler, { key = 'name', glob, ns } = {}) {
+  const { getConfig, getPluginName } = this.bajo.helper
+  const config = getConfig()
+  const result = {}
+  ns = ns ?? getPluginName(4)
+  for (const pkg of config.plugins) {
+    const plugin = camelCase(pkg)
+    let cfg = getConfig(plugin, { full: true })
+    const { alias, dir, dependencies } = cfg
+    cfg = omit(cfg, omittedPluginKeys)
+    let r
+    if (glob) {
+      const base = `${dir}/${ns}`
+      let pattern
+      let opts
+      if (isPlainObject(glob) && glob.pattern) pattern = glob.pattern
+      else {
+        if (isString(glob)) pattern = [glob]
+        for (const i in pattern) {
+          pattern[i] = `${base}/${pattern[i]}`
+        }
+      }
+      const files = await fastGlob(pattern, opts)
+      for (const f of files) {
+        const rel = f.replace(base, '')
+        const b = path.basename(rel, path.extname(rel))
+        const relDir = path.dirname(rel)
+        const relDirBase = `${relDir}/${b}`
+        const relName = slice(relDirBase.split('/'), 2).join('/')
+        const fileInfo = {
+          rel,
+          relDir,
+          relDirBase,
+          base: b,
+          name: camelCase(`${relName}`),
+          nameWithPlugin: camelCase(`${plugin} ${relName}`)
+        }
+        const resp = await handler.call(this, { plugin, pkg, cfg, alias, file: f, dir: base, dependencies, fileInfo })
+        if (resp === false) break
+        else if (resp === undefined) continue
+        else {
+          result[plugin] = result[plugin] ?? {}
+          result[plugin][f] = resp
+        }
+      }
+    } else {
+      r = await handler.call(this, { plugin, pkg, cfg, dir, alias, dependencies })
+      if (r === false) break
+      else if (r === undefined) continue
+      else result[plugin] = r
+    }
+  }
+  return result
+}
+
+export default eachPlugins

package/boot/helper/envs.js

@@ -0,0 +1,14 @@
+/**
+ * Supported environment
+ *
+ * @memberof module:helper
+ * @type Object
+ * @instance
+ */
+
+const envs = {
+  dev: 'development',
+  prod: 'production'
+}
+
+export default envs

package/boot/helper/error.js

@@ -0,0 +1,47 @@
+import { last, isPlainObject } from 'lodash-es'
+import print from './print.js'
+import getPluginName from './get-plugin-name.js'
+
+/**
+ * It's a shortcut to create an instance of Error with message and optional parameter
+ * in a single line
+ *
+ * @memberof helper
+ * @type Object
+ * @instance
+ * @param {string} msg - String that will be used as error message
+ * @param {options} [options] - Optional parameter
+ * @param {string} [options.code] - Error code
+ * @returns {error} Instance of Error
+ */
+
+Error.stackTraceLimit = 15
+
+function error (msg = 'Internal server error', ...args) {
+  let payload = last(args)
+  let ns
+  if (isPlainObject(payload)) {
+    payload = args.pop()
+    ns = payload.ns
+  }
+  if (!ns) ns = getPluginName.call(this, 3)
+  const message = print._format.call(this, ns, msg, ...args)
+  let err
+  if (isPlainObject(payload) && payload.class) err = payload.class(message)
+  else err = Error(message)
+  const stacks = err.stack.split('\n')
+  stacks.splice(1, 1) // this file
+  if (stacks[1].includes('/helper/fatal.js')) stacks.splice(1, 1) // if it goes to fatal.js
+  stacks.splice(1, 1) // for buildHelper.js
+  err.stack = stacks.join('\n')
+  if (isPlainObject(payload)) {
+    delete payload.class
+    delete payload.ns
+    for (const key in payload) {
+      err[key] = payload[key]
+    }
+  }
+  return err
+}
+
+export default error

package/boot/helper/fatal.js

@@ -0,0 +1,12 @@
+import error from './error.js'
+import getPluginName from './get-plugin-name.js'
+
+function fatal (...args) {
+  const ns = getPluginName.call(this, 3)
+  args.push({ ns })
+  const err = error(...args)
+  console.error(err)
+  process.exit(1)
+}
+
+export default fatal

package/boot/helper/generate-id.js

@@ -0,0 +1,19 @@
+import { cloneDeep, isPlainObject } from 'lodash-es'
+import { customAlphabet } from 'nanoid'
+
+const generateId = ({ pattern, length = 21, returnInstance } = {}) => {
+  let opts = {}
+  if (isPlainObject(pattern)) {
+    opts = cloneDeep(pattern)
+    returnInstance = opts.returnInstance
+    length = opts.length
+    pattern = opts.pattern
+  }
+  pattern = pattern ?? 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'
+  if (opts.lowerCase) pattern = 'abcdefghijklmnopqrstuvwxyz0123456789'
+  else if (opts.upperCase) pattern = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'
+  const nid = customAlphabet(pattern, length)
+  return returnInstance ? nid : nid()
+}
+
+export default generateId

package/boot/helper/get-config.js

@@ -0,0 +1,18 @@
+import { isEmpty, isPlainObject, cloneDeep, omit, find } from 'lodash-es'
+import omittedPluginKeys from '../lib/omitted-plugin-keys.js'
+
+function getConfig (name, { full, clone } = {}) {
+  if (name === 'bajo' || isEmpty(name)) return this.bajo.config
+  if (this[name] && isPlainObject(this[name].config) && this[name].config.name === name) {
+    const cfg = clone ? cloneDeep(this[name].config) : this[name].config
+    return full ? cfg : omit(cfg, omittedPluginKeys)
+  }
+  const ref = find(this.bajo.pluginRefs ?? [], { alias: name })
+  if (ref) {
+    const cfg = clone ? cloneDeep(this[ref.name].config) : this[ref.name].config
+    return full ? cfg : omit(cfg, omittedPluginKeys)
+  }
+  return {}
+}
+
+export default getConfig