bajo 2.18.0 → 2.20.0

package/index.js

@@ -12,20 +12,17 @@ shim()
  *
  * I recommend the second method for its portability.
  *
- * Example:
- * ```javascript
- * // index.js file. Your main package entry point
- * import bajo from 'bajo'
- * await bajo()
- * ```
- *
  * @global
  * @async
- * @param {Object} [options] - App options
- * @param {string} [options.cwd] - Set current working directory. Defaults to the script directory
- * @param {string[]} [options.plugins] - Array of plugins to load. If provided, it override the list in ```package.json``` and ```.plugins``` file
- * @param {Object} [options.config] - Plugin's config object. If provided, plugin configs will no longer be read from its config files
+ * @param {Object} [options] App options.
+ * @param {string} [options.cwd] Set current working directory. Defaults to the script directory.
+ * @param {string[]} [options.plugins] Array of plugins to load. If provided, it override the list in ```package.json``` and ```.plugins``` file.
+ * @param {Object} [options.config] Plugin's config object. If provided, plugin configs will no longer be read from its config files.
  * @returns {App}
+ * @example
+ * // index.js file. Your main package entry point
+ * import bajo from 'bajo'
+ * await bajo()
  */
 async function boot (options = {}) {
   if (!options.cwd) options.cwd = process.cwd()

package/lib/find-deep.js

@@ -1,12 +1,12 @@
 import fs from 'fs'
 
 /**
- * Find item deep in paths
+ * Find item deep in paths.
  *
  * @method
  * @memberof module:Lib
- * @param {string} item - Item to find
- * @param {Array} paths - Array of path to look for
+ * @param {string} item Item to find.
+ * @param {Array} paths Array of path to look for.
  * @returns {string}
  */
 function findDeep (item, paths) {

package/lib/formats.js

@@ -1,30 +1,30 @@
 /**
- * Supported data types
+ * Supported data types.
  *
  * @typedef {Object} TBajoDataType
  * @type {Array}
- * @property {string} 0 - string
- * @property {string} 1 - float
- * @property {string} 2 - double
- * @property {string} 3 - integer
- * @property {string} 4 - smallint
- * @property {string} 5 - date
- * @property {string} 6 - time
- * @property {string} 7 - datetime
- * @property {string} 8 - array
- * @property {string} 9 - object
- * @property {string} 10 - auto
+ * @property {string} 0 string
+ * @property {string} 1 float
+ * @property {string} 2 double
+ * @property {string} 3 integer
+ * @property {string} 4 smallint
+ * @property {string} 5 date
+ * @property {string} 6 time
+ * @property {string} 7 datetime
+ * @property {string} 8 array
+ * @property {string} 9 object
+ * @property {string} 10 auto
  */
 
 /**
- * General format types
+ * General format types,
  *
  * @typedef {Object} TBajoFormatType
  * @type {Array}
- * @property {string} 0 - speed
- * @property {string} 1 - distance
- * @property {string} 3 - area
- * @property {string} 4 - degree
+ * @property {string} 0 speed
+ * @property {string} 1 distance
+ * @property {string} 2 area
+ * @property {string} 3 degree
  */
 export const types = ['speed', 'distance', 'area', 'degree']
 

package/lib/freeze.js

@@ -1,12 +1,12 @@
 import deepFreezeStrict from 'deep-freeze-strict'
 
 /**
- * Freeze object
+ * Freeze object.
  *
  * @method
  * @memberof module:Lib
- * @param {Object} obj - Object to freeze
- * @param {boolean} [shallow=false] - If ```false``` (default), deep freeze object
+ * @param {Object} obj Object to freeze.
+ * @param {boolean} [shallow=false] If ```false``` (default), deep freeze object.
  */
 function freeze (obj, shallow = false) {
   if (shallow) Object.freeze(obj)

package/lib/import-module.js

@@ -6,9 +6,9 @@ const { resolvePath } = aneka
 const { isFunction, isPlainObject } = lodash
 
 /**
- * Import file/module from any loaded plugins
+ * Import file/module from any loaded plugins.
  *
- * Example: your plugin structure looks like this
+ * E.g. your plugin structure looks like this:
  * ```
  * |- src
  * |  |- lib
@@ -17,7 +17,7 @@ const { isFunction, isPlainObject } = lodash
  * |- package.json
  * ```
  *
- * And now this is how to import ```my-module.js```:
+ * And this is how to import ```my-module.js```:
  * ```javascript
  * const { importModule } = this.app.bajo
  * const myModule = await importModule('myPlugin:/src/lib/my-module.js')
@@ -26,11 +26,11 @@ const { isFunction, isPlainObject } = lodash
  * @method
  * @async
  * @memberof module:Lib
- * @param {TNsPathPairs} file - File to import
- * @param {Object} [options={}] - Options
- * @param {boolean} [options.asDefaultImport=true] - If ```true``` (default), return default imported module
- * @param {boolean} [options.asHandler] - If ```true```, return as a {@link HandlerType|handler}
- * @param {boolean} [options.noCache] - If ```true```, always import as a fresh copy
+ * @param {TNsPathPairs} file File to import.
+ * @param {Object} [options={}] Options.
+ * @param {boolean} [options.asDefaultImport=true] If ```true``` (default), return default imported module.
+ * @param {boolean} [options.asHandler] If ```true```, return as a {@link HandlerType|handler}.
+ * @param {boolean} [options.noCache] If ```true```, always import as a fresh copy.
  * @returns {any}
  * @see Bajo#importModule
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bajo",
-  "version": "2.18.0",
+  "version": "2.20.0",
   "description": "The ultimate framework for whipping up massive apps in no time",
   "main": "index.js",
   "scripts": {
@@ -44,6 +44,7 @@
   "devDependencies": {
     "chai": "^6.2.1",
     "clean-jsdoc-theme": "^4.3.0",
-    "docdash": "^2.0.2"
+    "docdash": "^2.0.2",
+    "mocha": "^11.7.6"
   }
 }

package/test/app.test.js

@@ -0,0 +1,183 @@
+/* global describe, it, beforeEach, afterEach */
+
+import os from 'node:os'
+import path from 'node:path'
+import { expect } from 'chai'
+import fs from 'fs-extra'
+
+import App from '../class/app.js'
+import Plugin from '../class/plugin.js'
+
+const createTempRoot = () => fs.mkdtempSync(path.join(os.tmpdir(), 'bajo-app-test-'))
+
+describe('App', () => {
+  let rootDir
+  let app
+
+  beforeEach(() => {
+    rootDir = createTempRoot()
+    app = new App({ cwd: rootDir })
+  })
+
+  afterEach(() => {
+    if (rootDir) fs.rmSync(rootDir, { recursive: true, force: true })
+  })
+
+  it('adds plugins and base class mappings', () => {
+    const plugin = new Plugin('my-plugin', app)
+    const MyBase = class {}
+
+    app.addPlugin(plugin, MyBase)
+
+    expect(app.myPlugin).to.equal(plugin)
+    expect(app.baseClass.MyPlugin).to.equal(MyBase)
+  })
+
+  it('throws when adding the same plugin namespace twice', () => {
+    const plugin = new Plugin('dup-plugin', app)
+    app.addPlugin(plugin)
+
+    expect(() => app.addPlugin(plugin)).to.throw("Plugin 'dupPlugin' added already")
+  })
+
+  it('lists namespaces and loaded plugins', () => {
+    app.pluginPkgs = ['alpha-plugin', 'beta-plugin']
+    app.alphaPlugin = { ns: 'alphaPlugin' }
+    app.betaPlugin = { ns: 'betaPlugin' }
+
+    expect(app.getAllNs()).to.deep.equal(['alphaPlugin', 'betaPlugin'])
+    expect(app.getPlugins()).to.deep.equal([app.alphaPlugin, app.betaPlugin])
+    expect(app.getPlugins(['betaPlugin'])).to.deep.equal([app.betaPlugin])
+    expect(app.getAllPlugins()).to.deep.equal([app.alphaPlugin, app.betaPlugin])
+  })
+
+  it('gets plugin by namespace, alias, and package name', () => {
+    const plugin = new Plugin('my-plugin', app)
+    plugin.alias = 'mine'
+    app.addPlugin(plugin)
+    app.bajo = { error: (code, value) => new Error(`${code}:${value}`) }
+
+    expect(app.getPlugin('myPlugin')).to.equal(plugin)
+    expect(app.getPlugin('mine')).to.equal(plugin)
+    expect(app.getPlugin('my-plugin')).to.equal(plugin)
+  })
+
+  it('supports silent and throwing behavior for missing plugin lookup', () => {
+    app.bajo = { error: (code, value) => new Error(`${code}:${value}`) }
+
+    expect(app.getPlugin('missing', true)).to.equal(false)
+    expect(() => app.getPlugin('missing')).to.throw('pluginWithNameAliasNotLoaded%s:missing')
+  })
+
+  it('creates and returns plugin data directory', () => {
+    const plugin = new Plugin('my-plugin', app)
+    app.addPlugin(plugin)
+    app.bajo = { dir: { data: path.join(rootDir, 'data') } }
+
+    const dir = app.getPluginDataDir('myPlugin')
+
+    expect(dir).to.equal(path.join(rootDir, 'data', 'plugins', 'myPlugin'))
+    expect(fs.existsSync(dir)).to.equal(true)
+  })
+
+  it('resolves plugin-scoped files and node_modules fallback paths', async () => {
+    const plugin = new Plugin('my-plugin', app)
+    plugin.dir = { pkg: path.join(rootDir, 'plugins', 'my-plugin') }
+    await fs.ensureDir(plugin.dir.pkg)
+    app.addPlugin(plugin)
+
+    app.bajo = {
+      breakNsPath: () => ({ ns: 'myPlugin', path: '/src/feature.js' })
+    }
+    expect(app.getPluginFile('myPlugin:/src/feature.js')).to.equal(path.join(plugin.dir.pkg, 'src/feature.js'))
+
+    const fallbackFile = path.join(rootDir, 'plugins', 'dep', 'index.js')
+    await fs.ensureDir(path.dirname(fallbackFile))
+    await fs.writeFile(fallbackFile, 'export default 1', 'utf8')
+    app.bajo.breakNsPath = () => ({ ns: 'myPlugin', path: 'node_modules/dep/index.js' })
+
+    expect(app.getPluginFile('myPlugin:node_modules/dep/index.js')).to.equal(`${plugin.dir.pkg}/../dep/index.js`)
+  })
+
+  it('translates and checks translation existence', () => {
+    app.pluginPkgs = ['my-plugin']
+    app.myPlugin = {
+      intl: {
+        id: {
+          greet: 'Halo %s',
+          list: 'Daftar: %s'
+        },
+        en: {
+          greet: 'Hello %s'
+        }
+      }
+    }
+    app.bajo = {
+      config: {
+        lang: 'id',
+        intl: {
+          fallback: 'en',
+          supported: ['id', 'en']
+        }
+      },
+      join: (items) => items.join(', '),
+      log: { warn: () => {} }
+    }
+
+    expect(app.t('myPlugin', 'greet', 'Ardhi')).to.equal('Halo Ardhi')
+    expect(app.t('myPlugin', 'list', ['A', 'B'])).to.equal('Daftar: A, B')
+    expect(app.t('myPlugin', 'unknown %s', 'X')).to.equal('unknown X')
+    expect(app.te('myPlugin', 'greet')).to.equal(true)
+    expect(app.te('myPlugin', 'not.exists')).to.equal(false)
+  })
+
+  it('returns supported config formats', () => {
+    app.configHandlers = [{ ext: '.json' }, { ext: '.yaml' }]
+
+    expect(app.getConfigFormats()).to.deep.equal(['.json', '.yaml'])
+  })
+
+  it('starts plugin by namespace with arguments', () => {
+    const calls = []
+    app.sample = {
+      start: (...args) => {
+        calls.push(args)
+      }
+    }
+
+    app.startPlugin('sample', 1, 'x')
+
+    expect(calls).to.deep.equal([[1, 'x']])
+  })
+
+  it('kills process with signal and exits abruptly when true is passed', () => {
+    const originalKill = process.kill
+    const originalExit = process.exit
+    const killCalls = []
+    let exitArg
+
+    process.kill = (...args) => {
+      killCalls.push(args)
+      return true
+    }
+    process.exit = (arg) => {
+      exitArg = arg
+      throw new Error('__EXIT__')
+    }
+
+    try {
+      app.exit('SIGTERM')
+      try {
+        app.exit(true)
+      } catch (err) {
+        if (err.message !== '__EXIT__') throw err
+      }
+    } finally {
+      process.kill = originalKill
+      process.exit = originalExit
+    }
+
+    expect(killCalls).to.deep.equal([[process.pid, 'SIGTERM']])
+    expect(exitArg).to.equal('1')
+  })
+})

package/test/bajo.test.js

@@ -0,0 +1,125 @@
+/* global describe, it, beforeEach, afterEach */
+
+import os from 'node:os'
+import path from 'node:path'
+import { expect } from 'chai'
+import fs from 'fs-extra'
+
+import App from '../class/app.js'
+import Bajo from '../class/bajo.js'
+
+const createTempRoot = () => fs.mkdtempSync(path.join(os.tmpdir(), 'bajo-core-test-'))
+
+describe('Bajo', () => {
+  let root
+  let app
+  let bajo
+
+  beforeEach(() => {
+    root = createTempRoot()
+    app = new App({ cwd: root })
+    bajo = new Bajo(app)
+    app.bajo = bajo
+    app.main = { dir: { pkg: root } }
+    app.mainNs = 'main'
+    app.main = { pkgName: 'main', dir: { pkg: root } }
+    app.demo = {
+      dir: { pkg: path.join(root, 'demo') },
+      greet: (name) => `hi ${name}`
+    }
+    bajo.config = {
+      env: 'dev',
+      lang: 'en-US',
+      intl: {
+        unitSys: { 'en-US': 'metric' },
+        format: {
+          emptyValue: '-',
+          datetime: { dateStyle: 'medium', timeStyle: 'short', timeZone: 'UTC' },
+          date: { dateStyle: 'medium', timeZone: 'UTC' },
+          time: { timeStyle: 'short', timeZone: 'UTC' },
+          float: { maximumFractionDigits: 2 },
+          double: { maximumFractionDigits: 2 },
+          integer: {},
+          smallint: {}
+        }
+      },
+      log: {
+        level: 'trace'
+      }
+    }
+    bajo.t = (text) => text
+  })
+
+  afterEach(() => {
+    if (root) fs.rmSync(root, { recursive: true, force: true })
+  })
+
+  it('builds and breaks namespace paths', () => {
+    const built = bajo.buildNsPath({ ns: 'demo', subNs: 'api', subSubNs: 'v1', path: '/users' })
+    const broken = bajo.breakNsPath('demo.api:/users/:id|42?q=x')
+
+    expect(built).to.equal('demo.api.v1:/users')
+    expect(broken).to.include({ ns: 'demo', subNs: 'api', path: '/users/:id', realPath: '/users/42' })
+    expect(broken.qs).to.deep.equal({ q: 'x' })
+  })
+
+  it('breaks ns path details from filename', () => {
+    const info = bajo.breakNsPathFromFile({
+      file: 'x/extend/route/demo.api@user-list.js',
+      dir: 'x/extend/',
+      suffix: '',
+      ns: 'demo',
+      getType: true
+    })
+
+    expect(info).to.include({ ns: 'demo', subNs: 'api', path: 'userList', type: 'route' })
+  })
+
+  it('returns unit format and formats values', () => {
+    const unit = bajo.getUnitFormat({ lang: 'en-US' })
+    const joined = bajo.format(['a', 'b'], 'array')
+    const integer = bajo.format(12345, 'integer')
+
+    expect(unit.unitSys).to.equal('metric')
+    expect(unit.format).to.be.an('object')
+    expect(joined).to.equal('a, b')
+    expect(integer).to.be.a('string')
+  })
+
+  it('gets method by ns path and supports non-throw mode', () => {
+    const fn = bajo.getMethod('demo:greet')
+    const miss = bajo.getMethod('demo:notFound', false)
+
+    expect(fn('a')).to.equal('hi a')
+    expect(miss).to.equal(undefined)
+  })
+
+  it('validates app/plugin package and utility helpers', async () => {
+    const appPkg = path.join(root, 'appdir')
+    const pluginPkg = path.join(root, 'plugindir')
+    await fs.ensureDir(appPkg)
+    await fs.ensureDir(pluginPkg)
+    await fs.ensureDir(path.join(root, 'empty'))
+    await fs.writeJson(path.join(appPkg, 'package.json'), { bajo: { type: 'app' } })
+    await fs.writeJson(path.join(pluginPkg, 'package.json'), { bajo: { type: 'plugin' } })
+
+    expect(bajo.isValidApp(appPkg)).to.equal(true)
+    expect(bajo.isValidPlugin(pluginPkg)).to.equal(true)
+    expect(bajo.join(['a', 'b', 'c'])).to.equal('a, b and c')
+    expect(bajo.numUnit('10mb', 'kb')).to.equal('10mb')
+    expect(await bajo.isEmptyDir(path.join(root, 'empty'))).to.equal(true)
+  })
+
+  it('reads/writes json helpers', async () => {
+    const file = path.join(root, 'x.json')
+    const content = bajo.toJson({ a: 1 })
+    await fs.writeFile(file, content, 'utf8')
+
+    expect(bajo.fromJson(content)).to.deep.equal({ a: 1 })
+    expect(bajo.readJson(file)).to.deep.equal({ a: 1 })
+
+    const out = path.join(root, 'out.json')
+    bajo.toJson({ b: 2 }, { writeToFile: true, saveAsFile: out })
+    expect(fs.existsSync(out)).to.equal(true)
+  })
+})

package/test/base.test.js

@@ -1,108 +1,75 @@
-import { expect } from 'chai'
-import Base from '../class/base.js'
-
-function makeMockApp ({ mainNs = 'app-main', throwOnDataConfig = false } = {}) {
-  // small lodash-like helpers used by Base.loadConfig
-  const _ = {
-    get: (obj, path, defVal) => {
-      if (!obj) return defVal
-      const parts = String(path).split('.')
-      let cur = obj
-      for (const p of parts) {
-        if (cur == null) return defVal
-        cur = cur[p]
-      }
-      return cur === undefined ? defVal : cur
-    },
-    kebabCase: s => String(s).replace(/([a-z0-9])([A-Z])/g, '$1-$2').replace(/[\s_]+/g, '-').toLowerCase(),
-    keys: obj => obj ? Object.keys(obj) : [],
-    pick: (obj, keys) => {
-      const out = {}
-      if (!obj) return out
-      for (const k of keys) if (k in obj) out[k] = obj[k]
-      return out
-    }
-  }
-
-  // simple defaultsDeep-ish helper suitable for these tests:
-  // later objects in args take precedence over earlier ones (shallow)
-  const defaultsDeep = (...objs) => Object.assign({}, ...objs.filter(Boolean))
-
-  // bajo helpers (file reads etc). readAllConfigs will be called twice by Base.loadConfig:
-  //  - once for module dir config
-  //  - once for data dir config (may throw)
-  let readAllCalls = 0
-  const readAllConfigs = async (path) => {
-    readAllCalls += 1
-    if (throwOnDataConfig && readAllCalls === 2) throw new Error('readAllConfigs data dir error')
-    // return a small config object to test merge/path logic
-    return { alpha: 'file', title: 'FromFile', other: 'ignore-me' }
-  }
-
-  return {
-    mainNs,
-    lib: { aneka: { defaultsDeep }, _ },
-    bajo: {
-      dir: { base: '/base', data: '/data' },
-      readAllConfigs,
-      readJson: async (p) => ({ name: 'bajo-foo', version: '1.2.3', description: 'pkg' }),
-      parseObject: (o) => o,
-      getModuleDir: (pkgName) => `/modules/${pkgName}`,
-      log: { trace: () => {} }
-    },
-    env: {},
-    argv: {}
-  }
-}
-
-describe('Base.loadConfig', () => {
-  it('derives alias from pkgName starting with "bajo-" using kebabCase', async () => {
-    const app = makeMockApp()
-    const inst = new Base('bajo-MyPlugin', app)
-    // ensure namespace used by loadConfig
-    inst.ns = 'myplugin'
-    // set an initial config shape so defKeys isn't empty
-    inst.config = { alpha: 'default', title: 'Default' }
-
-    await inst.loadConfig()
-
-    // alias is stored on the constructor
-    expect(inst.constructor.alias).to.equal('my-plugin')
-    // dir pkg should be set according to mainNs mismatch
-    expect(inst.dir.pkg).to.equal('/modules/bajo-MyPlugin')
-    // config should keep keys only from defKeys (alpha & title), parseObject ran (no throw)
-    expect(Object.keys(inst.config)).to.include('alpha')
-    expect(Object.keys(inst.config)).to.include('title')
-  })
-
-  it('when ns === app.mainNs uses app.mainNs as alias and sets title to alias', async () => {
-    const app = makeMockApp({ mainNs: 'mainns' })
-    const inst = new Base('bajo-mainpkg', app)
-    inst.ns = 'mainns'
-    inst.config = { title: undefined } // start with no title
-
-    await inst.loadConfig()
-
-    expect(inst.constructor.alias).to.equal('mainns')
-    // title should be set to alias when ns is mainNs
-    expect(inst.title).to.equal(inst.constructor.alias)
-  })
-
-  it('continues when readAllConfigs for data dir throws (tolerant behavior)', async () => {
-    const app = makeMockApp({ throwOnDataConfig: true })
-    const inst = new Base('bajo-throwtest', app)
-    inst.ns = 'throwtest'
-    inst.config = { alpha: 'start' }
-
-    // should not throw even if second readAllConfigs throws
-    let threw = false
-    try {
-      await inst.loadConfig()
-    } catch (err) {
-      threw = true
-    }
-    expect(threw).to.equal(false)
-    // config should still be an object and title present (or undefined but not crash)
-    expect(inst.config).to.be.an('object')
-  })
+/* global describe, it, beforeEach */
+
+import { expect } from 'chai'
+import lodash from 'lodash'
+
+import Base from '../class/base.js'
+
+describe('Base', () => {
+  let app
+
+  beforeEach(() => {
+    app = {
+      mainNs: 'main',
+      getAllNs: () => ['alpha', 'beta'],
+      lib: {
+        _: lodash,
+        aneka: {
+          defaultsDeep: (...objs) => lodash.defaultsDeep(...objs)
+        },
+        parseObject: (obj) => obj
+      },
+      bajo: {
+        dir: { base: '/app', data: '/data' },
+        config: { env: 'dev' },
+        log: { trace: () => {} },
+        getModuleDir: () => '/modules/my-plugin',
+        readAllConfigs: async () => ({ fromFile: true })
+      },
+      env: {
+        myPlugin: { x: 3 }
+      },
+      argv: {
+        myPlugin: { y: 2 }
+      },
+      options: {
+        config: {
+          myPlugin: { z: 1 }
+        }
+      }
+    }
+  })
+
+  it('initializes defaults', () => {
+    const base = new Base('my-plugin', app)
+
+    expect(base.ns).to.equal('myPlugin')
+    expect(base.dependencies).to.deep.equal([])
+    expect(base.state).to.deep.equal({})
+    expect(base.pkg).to.deep.equal({})
+  })
+
+  it('loads config and sets package/data directories', async () => {
+    const base = new Base('my-plugin', app)
+    base.config = { title: 'my app', z: 9, x: 0, y: 0 }
+
+    await base.loadConfig()
+
+    expect(base.dir).to.deep.equal({
+      pkg: '/modules/my-plugin',
+      data: '/data/plugins/myPlugin'
+    })
+    expect(base.getConfig('x')).to.equal(3)
+    expect(base.getConfig('y')).to.equal(2)
+    expect(base.getConfig('z')).to.equal(1)
+    expect(base.getConfig('title')).to.equal('my app')
+  })
+
+  it('runs no-op lifecycle methods and exits by disposing', async () => {
+    const base = new Base('my-plugin', app)
+
+    await base.init()
+    await base.start()
+    await base.stop()
+  })
 })