bajo 2.0.1 → 2.1.0

package/.github/FUNDING.yml

@@ -0,0 +1,13 @@
+github: ardhi
+patreon: bajoframework
+#open_collective: # Replace with a single Open Collective username
+#ko_fi: # Replace with a single Ko-fi username
+#tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+#community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+#liberapay: # Replace with a single Liberapay username
+#issuehunt: # Replace with a single IssueHunt username
+#lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+#polar: # Replace with a single Polar username
+#buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+#thanks_dev: # Replace with a single thanks.dev username
+custom: ["https://www.paypal.com/ncp/payment/EWLERL7SCUU64"]

package/.github/workflows/repo-lockdown.yml

@@ -0,0 +1,24 @@
+name: 'Repo Lockdown'
+
+on:
+  #issues:
+    #types: opened
+  pull_request_target:
+    types: opened
+  #schedule:
+    #- cron: '* */6 * * *'
+
+permissions:
+  #issues: write
+  pull-requests: write
+
+jobs:
+  action:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: dessant/repo-lockdown@v4
+        with:
+          pr-comment: >
+            This repository does not accept pull requests,
+            see the README.md for details.
+          skip-closed-pr-comment: true

package/.jsdoc.conf.json

@@ -6,21 +6,22 @@
     "verbose": true,
     "destination": "./docs",
     "template": "node_modules/clean-jsdoc-theme",
-    "tutorials": "./misc-docs",
+    "readme": "./docs/static/home.md",
     "theme_opts": {
       "default_theme": "light",
       "display-module-header": true,
-      "title": "Bajo Framework",
-      "homepageTitle": "Bajo Framework",
+      "title": "Bajo API",
+      "homepageTitle": "Bajo API",
+      "sections": ["Classes", "Events", "Modules", "Global"],
       "menu": [{
-        "title": "Bajo.app",
-        "link": "https://bajo.app"
-      }, {
         "title": "NPM",
         "link": "https://www.npmjs.com/package/bajo"
       }, {
         "title": "Github",
         "link": "https://github.com/ardhi/bajo"
+      }, {
+        "title": "Bajo",
+        "link": "https://bajo.app"
       }]
     }
   },

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Ardhi Lukianto
+Copyright (c) 2023-2025 Ardhi Lukianto
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,18 +1,50 @@
-# bajo
-
-![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! ([Why?](misc-docs/contribution.md))<br /><br />
-
-## Documentations
-
-- [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
-
-[MIT](LICENSE)
+# bajo
+
+The ultimate framework for whipping up a massive app in no time!
+
+![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! ([Why?](wiki/CONTRIBUTING.md))<br /><br />
+
+<a href="https://bajo.app"><img src="docs/static/logo.png" width="300" alt="bajo"></a>
+
+[Bajo](https://bajo.app) is one of a kind framework. Think of it as Lego blocks; you create your very own customized structure by attaching together only the needed blocks. This same principle for app building is now possible with Bajo: pick the right plugins, glue them together, and fire it up!
+
+From a simple command-line app to a monster-sized, multi-page web app, Bajo will deliver your app in no time just by adding more plugins.
+
+## Documentations
+
+- [Homepage](https://bajo.app/)
+- [Getting Started](wiki/GETTING-STARTED.md)
+- [User Guide](wiki/USER-GUIDE.md)
+- [Developer Guide](wiki/DEV-GUIDE.md)
+- [Config Object](wiki/CONFIG.md)
+- [Ecosystem](wiki/ECOSYSTEM.md)
+- [API](https://ardhi.github.io/bajo)
+- [Contributing](wiki/CONTRIBUTING.md)
+
+## Hire Me
+
+If you have a Bajo Framework-based project and need a professional service or assistance, please <a href="https://github.com/ardhi#professional-service">click here</a>. I'd be happy to work on it at a competitive price and with fast turnaround!
+
+## Support Me
+
+Please support me using the channels below. Your donation will motivate me to work faster and more diligently on future development.
+
+<a href="https://github.com/sponsors/ardhi">
+  <img src="https://img.shields.io/badge/Github-slategrey?style=flat&logo=github" height="50">
+</a>
+<a href="https://www.patreon.com/bajoframework">
+  <img src="https://img.shields.io/badge/Patreon-f2c3b2?style=flat&logo=patreon" height="50">
+</a>
+<a href="https://www.paypal.com/ncp/payment/EWLERL7SCUU64">
+  <img src="https://img.shields.io/badge/Paypal-blue?style=flat&logo=paypal" height="50">
+</a>
+
+<p>
+<div><img alt="bc1qwtv78cwp9ef8hnqaw84fxg5856l0pggqe32g6f" src="docs/static/bitcoin.jpeg" width="150" height="150" /><br>Bitcoin</div>
+</p>
+
+## License
+
+[MIT](LICENSE)

package/class/app.js

@@ -1,49 +1,239 @@
 import util from 'util'
 import lodash from 'lodash'
 import Bajo from './bajo.js'
+import fastGlob from 'fast-glob'
+import { sprintf } from 'sprintf-js'
+import outmatch from 'outmatch'
+import fs from 'fs-extra'
+import aneka from 'aneka/index.js'
+import Base from './base.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
+import { runAsApplet } from './helper/bajo.js'
+import dayjs from 'dayjs'
+import utc from 'dayjs/plugin/utc.js'
+import customParseFormat from 'dayjs/plugin/customParseFormat.js'
+import localizedFormat from 'dayjs/plugin/localizedFormat.js'
+import weekOfYear from 'dayjs/plugin/weekOfYear.js'
+
+dayjs.extend(utc)
+dayjs.extend(customParseFormat)
+dayjs.extend(localizedFormat)
+dayjs.extend(weekOfYear)
+
+const { isPlainObject, get, reverse, map, isString, last, without, keys } = lodash
+let unknownLangWarning = false
+
+function outmatchNs (source, pattern) {
+  const { breakNsPath } = this.bajo
+  const [src, subSrc] = source.split(':')
+  if (!subSrc) return pattern === src
+  try {
+    const { fullNs, path } = breakNsPath(pattern)
+    const isMatch = outmatch(path)
+    return src === fullNs && isMatch(subSrc)
+  } catch (err) {
+    return false
+  }
+}
 
 /**
- * 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.
+ * @typedef {Object} TAppEnv
+ * @property {string} dev=development
+ * @property {string} prod=production
+ * @see App
+ */
+
+/**
+ * @typedef {Object} TAppLib
+ * @property {Object} _ - Access to {@link https://lodash.com|lodash}
+ * @property {Object} fs - Access to {@link https://github.com/jprichardson/node-fs-extra|fs-extra}
+ * @property {Object} fastGlob - Access to {@link https://github.com/mrmlnc/fast-glob|fast-glob}
+ * @property {Object} sprintf - Access to {@link https://github.com/alexei/sprintf.js|sprintf}
+ * @property {Object} aneka - Access to {@link https://github.com/ardhi/aneka|aneka}
+ * @property {Object} outmatch - Access to {@link https://github.com/axtgr/outmatch|outmatch}
+ * @property {Object} dayjs - Access to {@link https://day.js.org|dayjs} with utc & customParseFormat plugin already applied
+ * @see App
+ */
+const lib = {
+  _: lodash,
+  fs,
+  fastGlob,
+  sprintf,
+  outmatch,
+  dayjs,
+  aneka
+}
+
+/**
+ * App class. This is the root. This is where all plugins call it home.
  *
  * @class
  */
 class App {
   /**
-   * Class constructor
+   * Your main namespace. And yes, you suppose to NOT CHANGE this
    *
+   * @memberof App
+   * @constant {string}
+   * @default 'main'
+   */
+  static mainNs = 'main'
+
+  /**
+   * App environments
+   * @memberof App
+   * @constant {TAppEnv}
+   */
+  static envs = { dev: 'development', prod: 'production' }
+
+  /**
    * @param {string} cwd - Current working dirctory
    */
   constructor (cwd) {
+    /**
+     * Date/time when your app start
+     * @type {Date}
+     */
+    this.runAt = new Date()
+
+    /**
+     * Applets
+     *
+     * @type {Array}
+     */
+    this.applets = []
+
+    /**
+     * List of all loaded plugin's package names
+     *
+     * @type {Array}
+     */
+    this.pluginPkgs = []
+
+    /**
+     * @typedef {Object} TAppConfigHandler
+     * @property {string} ext - File extension
+     * @property {function} [readHandler] - Function to call for reading
+     * @property {function} [writeHandler] - Function to call for writing
+     * @see App#configHandlers
+     */
+
+    /**
+     * Config handlers.
+     *
+     * By default, there are two built-in handlers available: ```.js```
+     * and ```.json```. Use plugins to add more, e.g {@link https://github.com/ardhi/bajo-config|bajo-config}
+     * lets you to use ```.yaml/.yml``` and ```.toml```
+     *
+     * @type {TAppConfigHandler[]}
+     */
+    this.configHandlers = []
+
+    /**
+     * Gives you direct access to the most commonly used 3rd party library in a Bajo based app.
+     * No manual import necessary, always available, anywhere, anytime!
+     *
+     * Example:
+     * ```javascript
+     * const { camelCase, kebabCase } = this.app.lib._
+     * console.log(camelCase('Elit commodo sit et aliqua'))
+     * ```
+     *
+     * @type {TAppLib}
+     */
+    this.lib = lib
+    this.lib.outmatchNs = outmatchNs.bind(this)
+
+    /**
+     * Instance of system log
+     *
+     * @type {Log}
+     */
+    this.log = {}
+
+    /**
+     * All plugin's class definitions are saved here as key-value pairs with plugin name as its key.
+     * The special key ```base``` is for {@link Base}'s class so anytime you want to
+     * create your own plugin, just use something like this:
+     *
+     * ```javascript
+     * class MyPlugin extends this.app.pluginClass.base {
+     *   ... your class
+     * }
+     */
+    this.pluginClass = { base: Base }
+
+    /**
+     * If app runs in applet mode, this will be the applet's name
+     *
+     * @type {string}
+     */
+    this.applet = undefined
+
+    /**
+     * Program arguments
+     *
+     * ```
+     * $ node index.js arg1 arg2
+     * ...
+     * console.log(this.args) // it should print: ['arg1', 'arg2']
+     * ```
+     *
+     * @type {string[]}
+     * @see module:Lib.parseArgsArgv
+     */
+    this.args = []
+
+    /**
+     * Program options.
+     *
+     * - Dash (```-```) breaks the string into object keys
+     * - While colon (```:```) is used as namespace separator. If no namespace found, it is saved under ```_``` key.
+     *
+     * Values are parsed automatically. See {@link https://github.com/ladjs/dotenv-parse-variables|dotenv-parse-variables}
+     * for details.
+     *
+     * ```
+     * $ node index.js --my-name-first=John --my-name-last=Doe --my-birthDay=secret --nameSpace:path-subPath=true
+     * ...
+     * // {
+     * //   _: {
+     * //    my: {
+     * //       name: { first: 'John', last: 'Doe' },
+     * //       birthDay: 'secret'
+     * //     }
+     * //   },
+     * //   nameSpace: { path: { subPath: true } }
+     * // }
+     * ```
+     *
+     * @type {Object}
+     * @see module:Lib.parseArgsArgv
+     */
+    this.argv = {}
+
+    /**
+     * Environment variables. Support dotenv (```.env```) file too!
+     *
+     * - Underscore (```_```) translates key to camel-cased one
+     * - Double underscores (```__```) breaks the key into object keys
+     * - While dot (```.```) is used as namespace separator. If no namespace found, it is saved under ```_``` key.
+     *
+     * Values are also parsed automatically using {@link https://github.com/ladjs/dotenv-parse-variables|dotenv-parse-variables}.
+     *
+     * Example:
+     *
+     * - ```MY_KEY=secret``` → ```{ _: { myKey: 'secret' } }```
+     * - ```MY_KEY__SUB_KEY=supersecret``` → ```{ _: { myKey: { subKey: 'supersecret' } } }```
+     * - ```MY_NS.MY_NAME=John``` → ```{ myNs: { myName: 'John' } }```
+     *
+     * @type {Object}
+     * @see module:Lib.parseEnv
+     */
+    this.envVars = {}
+
     if (!cwd) cwd = process.cwd()
     const l = last(process.argv)
     if (l.startsWith('--cwd')) {
@@ -54,19 +244,35 @@ class App {
     process.env.APPDIR = this.dir
   }
 
+  get mainNs () {
+    return this.constructor.mainNs
+  }
+
+  /**
+   * Add and save plugin and it's class definition (if provided)
+   *
+   * @method
+   * @param {TPlugin} plugin - A valid bajo plugin
+   * @param {Object} [pluginClass] - Plugin's class definition
+   */
+  addPlugin = (plugin, pluginClass) => {
+    if (this[plugin.ns]) throw new Error(`Plugin '${plugin.ns}' added already`)
+    this[plugin.ns] = plugin
+    if (pluginClass) this.pluginClass[plugin.ns] = pluginClass
+  }
+
   /**
-   * Add a plugin to the app
+   * Get all loaded plugin namesspaces
    *
    * @method
-   * @param {Object} plugin - A valid bajo plugin
+   * @returns {string[]}
    */
-  addPlugin = (plugin) => {
-    if (this[plugin.name]) throw new Error(`Plugin '${plugin.name}' added already`)
-    this[plugin.name] = plugin
+  getAllNs = () => {
+    return without(keys(this.pluginClass), 'base')
   }
 
   /**
-   * Dumping variable on screen
+   * Dumping variable on screen. Like ```console.log``` but with max 10 depth.
    *
    * @method
    * @param  {...any} args - any arguments passed will be displayed on screen. If the last argument is a boolean 'true', app will quit rightaway
@@ -75,38 +281,156 @@ class App {
     const terminate = last(args) === true
     if (terminate) args.pop()
     for (const arg of args) {
-      const result = util.inspect(arg, false, null, true)
+      const result = util.inspect(arg, { depth: 10, colors: true })
       console.log(result)
     }
     if (terminate) process.kill(process.pid, 'SIGINT')
   }
 
   /**
-   * Booting the app
+   * Boot process:
+   *
+   * - Parsing {@link module:Lib.parseArgsArgv|program arguments, options} and {@link module:Lib.parseEnv|environment values}
+   * - Create {@link Bajo|Bajo} instance & initialize it
+   * - {@link module:Helper/Bajo.runAsApplet|Run in applet mode} if ```-a``` or ```--applet``` is given
+   *
+   * After boot process is completed, event ```bajo:afterBootComplete``` is emitted.
+   *
+   * If app mode is ```applet```, it runs your choosen applet instead.
    *
    * @method
    * @async
+   * @returns {App}
+   * @fires bajo:afterBootComplete
    */
   boot = async () => {
-    // argv/args
-    const { args, argv } = await parseArgsArgv.call(this.app) ?? {}
-    this.argv = argv
+    // argv/args/env
+    this.bajo = new Bajo(this)
+    const { argv, args } = await parseArgsArgv.call(this) ?? {}
     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)
+    this.argv = argv
+    this.envVars = parseEnv.call(this)
+    this.applet = this.envVars._.applet ?? this.argv._.applet
+    await this.bajo.init()
     // 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)
+    const elapsed = new Date() - this.runAt
+    this.bajo.log.debug('bootCompleted%s', this.lib.aneka.secToHms(elapsed, true))
+    /**
+     * Run after boot process is completed
+     *
+     * @global
+     * @event bajo:afterBootComplete
+     * @see {@tutorial hook}
+     * @see App#boot
+     */
+    await this.bajo.runHook('bajo:afterBootComplete')
+    if (this.applet) await runAsApplet.call(this.bajo)
+    return this
+  }
+
+  /**
+   * Terminate the app and back to console
+   *
+   * @method
+   * @param {string} [signal=SIGINT] - Signal to send
+   */
+  exit = (signal = 'SIGINT') => {
+    process.kill(process.pid, 'SIGINT')
+  }
+
+  /**
+   * Load internationalization & languages files for particular plugin
+   *
+   * @method
+   * @param {string} ns - Plugin name
+   */
+  loadIntl = (ns) => {
+    this[ns].intl = {}
+    for (const l of this.bajo.config.intl.supported) {
+      this[ns].intl[l] = {}
+      const path = `${this[ns].dir.pkg}/extend/bajo/intl/${l}.json`
+      if (!fs.existsSync(path)) continue
+      const trans = fs.readFileSync(path, 'utf8')
+      try {
+        this[ns].intl[l] = JSON.parse(trans)
+      } catch (err) {}
+    }
+  }
+
+  /**
+   * Translate text and interpolate with given ```args```.
+   *
+   * There is a shortcut to this method attached on all plugins. You'll normally call that shorcut
+   * instead of this method, because it is bound to plugin's name already
+   *
+   * ```javascript
+   * ... within your main plugin
+   * const translated = this.app.t('main', 'My cute cat is %s', 'purring')
+   * // or
+   * const translated = this.t('My cute cat is %s', 'purring')
+   * ```
+   * @method
+   * @param {string} ns - Namespace
+   * @param {string} text - Text to translate
+   * @param  {...any} params - Arguments
+   * @returns {string}
+   */
+  t = (ns, text, ...params) => {
+    if (!text) {
+      text = ns
+      ns = 'bajo'
+    }
+    const opts = last(params)
+    let lang = this.bajo.config.lang
+    if (isPlainObject(opts)) {
+      params.pop()
+      if (opts.lang) lang = opts.lang
+    }
+    const { fallback, supported } = this.bajo.config.intl
+    if (!unknownLangWarning && !supported.includes(lang)) {
+      unknownLangWarning = true
+      this.bajo.log.warn(`Unsupported language, fallback to '${fallback}'`)
+    }
+    const plugins = reverse(without([...this.getAllNs()], ns))
+    plugins.unshift(ns)
+    plugins.push('bajo')
+
+    let trans
+    for (const p of plugins) {
+      const store = get(this, `${p}.intl.${lang}`, {})
+      trans = get(store, text)
+      if (trans) break
+    }
+    if (!trans) {
+      for (const p of plugins) {
+        const store = get(this, `${p}.intl.${fallback}`, {})
+        trans = get(store, text)
+        if (trans) break
+      }
+    }
+    if (!trans) trans = text
+    const values = map(params, a => {
+      if (!isString(a)) return a
+      return a
+    })
+    return sprintf(trans, ...values)
+  }
+
+  /**
+   * Helper method to list all supported config formats
+   *
+   * @returns {string[]}
+   */
+  getConfigFormats = () => {
+    return map(this.configHandlers, 'ext')
+  }
+
+  startPlugin = (ns, ...args) => {
+    this[ns].start(...args)
+  }
+
+  stopPlugin = (ns, ...args) => {
+    this[ns].stop(...args)
   }
 }