bajo 2.22.0 → 2.24.0

package/test/unit/index.test.js

@@ -0,0 +1,40 @@
+/* global describe, it, beforeEach, afterEach */
+
+import path from 'node:path'
+import fs from 'fs-extra'
+import { expect } from 'chai'
+import boot from '../../index.js'
+
+describe('index (unit)', () => {
+  let root
+
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join('/tmp', 'bajo-index-unit-'))
+  })
+
+  afterEach(() => {
+    if (root) fs.rmSync(root, { recursive: true, force: true })
+  })
+
+  it('boot returns app instance for valid module app', async function () {
+    this.timeout(10000)
+    await fs.writeJson(path.join(root, 'package.json'), { name: 'app', type: 'module', bajo: { plugins: [] } })
+    await fs.ensureDir(path.join(root, 'data', 'config'))
+    await fs.writeJson(path.join(root, 'data', 'config', 'bajo.json'), { log: { level: 'silent', save: false }, exitHandler: false, cache: { purgeIntvDur: '1h' } })
+
+    const old = global.setInterval
+    const ids = []
+    global.setInterval = (fn, delay, ...args) => {
+      const id = old(fn, delay, ...args)
+      ids.push(id)
+      return id
+    }
+
+    const app = await boot({ cwd: root })
+    expect(app).to.be.an('object')
+    expect(app.bajo).to.be.an('object')
+
+    global.setInterval = old
+    for (const id of ids) clearInterval(id)
+  })
+})

package/test/unit/log.test.js

@@ -0,0 +1,84 @@
+/* global describe, it, beforeEach, afterEach */
+
+import path from 'node:path'
+import fs from 'fs-extra'
+import lodash from 'lodash'
+import dayjs from 'dayjs'
+import { expect } from 'chai'
+import App from '../../class/app.js'
+import Log, { logLevels } from '../../class/log.js'
+
+describe('log (unit)', () => {
+  let root
+  let app
+  let log
+
+  beforeEach(async () => {
+    root = fs.mkdtempSync(path.join('/tmp', 'bajo-log-unit-'))
+    await fs.ensureDir(path.join(root, 'data'))
+    app = new App({ cwd: root })
+    app.lib._ = lodash
+    app.lib.dayjs = dayjs
+    app.t = (_prefix, text, ...args) => args.length ? `${text}${args.join('')}` : text
+    app.bajo = {
+      dir: { data: path.join(root, 'data') },
+      config: { env: 'dev', log: { level: 'trace', save: false, pretty: false, useUtc: false, timeTaken: true, dateFormat: 'YYYY-MM-DD', rotation: { cycle: 'none', byPlugin: false } } },
+      isLogInRange: () => true
+    }
+    log = new Log(app)
+  })
+
+  afterEach(() => {
+    if (root) fs.rmSync(root, { recursive: true, force: true })
+  })
+
+  it('exports known log levels', () => {
+    expect(logLevels.trace.number).to.equal(10)
+    expect(logLevels.silent.number).to.equal(99)
+  })
+
+  it('getErrorMessage handles message and fallback fields', () => {
+    expect(log.getErrorMessage(new Error('x'))).to.equal('x')
+    expect(log.getErrorMessage({ message: '', code: 'E' })).to.equal('E')
+  })
+
+  it('getRotationPattern supports none/daily/weekly/monthly', () => {
+    app.bajo.config.log.rotation.cycle = 'none'
+    expect(log.getRotationPattern()).to.equal(undefined)
+    app.bajo.config.log.rotation.cycle = 'daily'
+    expect(log.getRotationPattern()).to.be.a('string')
+    app.bajo.config.log.rotation.cycle = 'weekly'
+    expect(log.getRotationPattern()).to.be.a('string')
+    app.bajo.config.log.rotation.cycle = 'monthly'
+    expect(log.getRotationPattern()).to.be.a('string')
+  })
+
+  it('formatMsg handles string payload and error payload paths', () => {
+    log.formatMsg('info', 'demo', 'hi%s', 'x')
+    log.formatMsg('error', 'demo', new Error('boom'))
+  })
+
+  it('save writes clean lines to log files', () => {
+    app.bajo.config.log.save = true
+    app.bajo.config.log.rotation.cycle = 'daily'
+    fs.ensureDirSync(log.logDir)
+    log.save('line', 'demo')
+    const files = fs.readdirSync(log.logDir)
+    expect(files.length).to.be.greaterThan(0)
+  })
+
+  it('trace/debug/info/warn/error/fatal/silent wrappers call format path', () => {
+    log.trace('d', 'a')
+    log.debug('d', 'a')
+    log.info('d', 'a')
+    log.warn('d', 'a')
+    log.error('d', 'a')
+    log.fatal('d', 'a')
+    log.silent('d', 'a')
+  })
+
+  it('dispose clears app reference', async () => {
+    await log.dispose()
+    expect(log.app).to.equal(null)
+  })
+})

package/test/unit/plugin.test.js

@@ -0,0 +1,95 @@
+/* global describe, it, beforeEach, afterEach */
+
+import path from 'node:path'
+import fs from 'fs-extra'
+import lodash from 'lodash'
+import { expect } from 'chai'
+import Plugin from '../../class/plugin.js'
+
+const mk = async () => fs.mkdtemp(path.join('/tmp', 'bajo-plugin-unit-'))
+
+describe('plugin (unit)', () => {
+  let dir
+  let app
+  let plugin
+
+  beforeEach(async () => {
+    dir = await mk()
+    await fs.writeJson(path.join(dir, 'package.json'), { name: 'pkg', version: '1.2.3', description: 'd', author: 'a', license: 'MIT', homepage: 'h', bajo: { type: 'plugin' } })
+    app = {
+      lib: { _: lodash, fs },
+      log: { trace: () => {}, debug: () => {}, info: () => {}, warn: () => {}, error: () => {}, fatal: () => {}, silent: () => {} },
+      t: (_ns, text, ...args) => args.length ? `${text}:${args.join(',')}` : text,
+      te: () => true,
+      dump: () => {}
+    }
+    plugin = new Plugin('demo-plugin', app)
+    plugin.dir = { pkg: dir }
+  })
+
+  afterEach(() => {
+    if (dir) fs.rmSync(dir, { recursive: true, force: true })
+  })
+
+  it('constructor maps namespace and log wrappers', () => {
+    expect(plugin.pkgName).to.equal('demo-plugin')
+    expect(plugin.ns).to.equal('demoPlugin')
+    expect(plugin.alias).to.equal(null)
+    expect(plugin.config).to.deep.equal({})
+    plugin.log.info('x')
+  })
+
+  it('getPkgInfo returns selected keys and full package', () => {
+    const selected = plugin.getPkgInfo()
+    const full = plugin.getPkgInfo(undefined, [])
+    expect(selected).to.deep.equal({ name: 'pkg', version: '1.2.3', description: 'd', author: 'a', license: 'MIT', homepage: 'h', bajo: { type: 'plugin' } })
+    expect(full.name).to.equal('pkg')
+  })
+
+  it('getConfig supports path, defaults, omit and noClone', () => {
+    plugin.config = { a: { b: 1, c: 2 } }
+    const p = plugin.getConfig('a', { omit: ['c'] })
+    expect(p).to.deep.equal({ b: 1 })
+    const def = plugin.getConfig('a.d', { defValue: 9 })
+    expect(def).to.equal(9)
+    const nc = plugin.getConfig('a', { noClone: true })
+    nc.b = 7
+    expect(plugin.config.a.b).to.equal(7)
+  })
+
+  it('error/fatal return native Error when print is absent', () => {
+    const e = plugin.error('m')
+    const f = plugin.fatal('n')
+    expect(e).to.be.instanceOf(Error)
+    expect(f).to.be.instanceOf(Error)
+  })
+
+  it('t and te delegate to app translation APIs', () => {
+    expect(plugin.t('hello', 'a')).to.equal('hello:a')
+    expect(plugin.te('hello')).to.equal(true)
+  })
+
+  it('bindThis binds string and function entries', () => {
+    plugin.value = 'ok'
+    plugin.one = function () { return this.value }
+    function two () { return this.pkgName }
+    plugin.bindThis('one', two)
+    const a = plugin.one
+    const b = plugin.two
+    expect(a()).to.equal('ok')
+    expect(b()).to.equal('demo-plugin')
+  })
+
+  it('dump forwards call to app.dump', () => {
+    let args
+    app.dump = (...a) => { args = a }
+    plugin.dump('x', 1)
+    expect(args).to.deep.equal(['x', 1])
+  })
+
+  it('dispose clears app and config references', async () => {
+    await plugin.dispose()
+    expect(plugin.app).to.equal(null)
+    expect(plugin.config).to.equal(null)
+  })
+})

package/test/unit/print.test.js

@@ -0,0 +1,72 @@
+/* global describe, it */
+
+import dayjs from 'dayjs'
+import { expect } from 'chai'
+import Print from '../../class/print.js'
+
+describe('print (unit)', () => {
+  const make = () => {
+    let exited = false
+    const plugin = {
+      ns: 'demo',
+      t: (text, ...args) => args.length ? `${text}${args.join('')}` : text,
+      app: {
+        applet: false,
+        lib: { dayjs },
+        bajo: { config: { silent: false, counter: false, datetime: false } },
+        exit: () => { exited = true }
+      }
+    }
+    return { print: new Print(plugin, { ora: { isEnabled: false }, showCounter: true, showDatetime: true }), getExited: () => exited }
+  }
+
+  it('setOpts updates options with silent inheritance', () => {
+    const { print } = make()
+    print.setOpts({ silent: false })
+    expect(print.options.silent).to.equal(false)
+  })
+
+  it('buildText prefixes datetime and counter', () => {
+    const { print } = make()
+    const t = print.buildText('hello')
+    expect(t).to.include('hello')
+    expect(t.startsWith('[')).to.equal(true)
+  })
+
+  it('setText updates spinner text', () => {
+    const { print } = make()
+    print.setText('abc')
+    expect(print.ora.text).to.include('abc')
+  })
+
+  it('getElapsed supports default and custom units', () => {
+    const { print } = make()
+    expect(print.getElapsed('hms')).to.be.a('string')
+    expect(print.getElapsed('ms')).to.be.a('number')
+  })
+
+  it('start/stop/succeed/fail/warn/info/clear/render are chainable', () => {
+    const { print } = make()
+    expect(print.start('a')).to.equal(print)
+    expect(print.stop()).to.equal(print)
+    expect(print.succeed('b')).to.equal(print)
+    expect(print.fail('c')).to.equal(print)
+    expect(print.warn('d')).to.equal(print)
+    expect(print.info('e')).to.equal(print)
+    expect(print.clear()).to.equal(print)
+    expect(print.render()).to.equal(print)
+  })
+
+  it('fatal handles Error and exits app', () => {
+    const { print, getExited } = make()
+    print.fatal(new Error('bad'))
+    expect(getExited()).to.equal(true)
+  })
+
+  it('spinner creates new instance sharing baseline time', () => {
+    const { print } = make()
+    const s = print.spinner()
+    expect(s).to.be.instanceOf(Print)
+    expect(s.startTime.valueOf()).to.equal(print.startTime.valueOf())
+  })
+})

package/test/unit/tools.test.js

@@ -0,0 +1,29 @@
+/* global describe, it */
+
+import { expect } from 'chai'
+import Tools from '../../class/tools.js'
+
+describe('tools (unit)', () => {
+  it('constructor stores plugin and app references', () => {
+    const plugin = { app: { name: 'app' } }
+    const t = new Tools(plugin)
+    expect(t.plugin).to.equal(plugin)
+    expect(t.app).to.equal(plugin.app)
+  })
+
+  it('selfBind binds methods to instance context', () => {
+    const t = new Tools({ app: {} })
+    t.value = 42
+    t.getValue = function () { return this.value }
+    t.selfBind(['getValue'])
+    const fn = t.getValue
+    expect(fn()).to.equal(42)
+  })
+
+  it('dispose clears internal references', async () => {
+    const t = new Tools({ app: { ok: true } })
+    await t.dispose()
+    expect(t.app).to.equal(null)
+    expect(t.plugin).to.equal(null)
+  })
+})

package/wiki/CHANGES.md

@@ -1,5 +1,14 @@
 # Changes
 
+## 2026-07-23
+
+- [2.24.0] Revamped documentations and test cases
+- [2.24.0] `plugin.bindThis()` now accepts rest parameters
+
+## 2026-07-13
+
+- [2.23.0] Add `getDownloadDir()`
+
 ## 2026-07-08
 
 - [2.22.0] Update documentations

package/wiki/tutorials/01_WELCOME.md

@@ -0,0 +1,18 @@
+# Welcome to Bajo
+
+Welcome to Bajo, __the ultimate framework for whipping up a massive app in no time!__
+
+Bajo is a framework that allows you to build apps with ease, whether it's a command line app or web app of any size. It is designed to be simple, yet powerful, and can be used for a wide range of applications.
+
+Bajo grew out of the need for a framework that:
+- is easy to use and understand even for beginners.
+- is modular and extensible. It's like playing with Lego blocks, you can build anything you want by combining different plugins with each other.
+- is plug & play, yet easy to customize through configurations only. Less code is always better.
+- is fast and efficient, yet easy to scale.
+- and last but not least: so much magic! Many people will be critical about it, but hey, who doesn't like magic?
+
+In Bajo philosophy, everything is a plugin. A plugin should be handling a single responsibility, and can be extended by other plugins. This allows for a very flexible and modular architecture, where you can easily add or remove features as needed.
+
+A typical Bajo app should be able to run within a few minutes: create a new project directory, create `package.json` file, create a {@link boot|boot file}, install as many plugins as you want, done! Yes, it's that simple.
+
+Now dive in to the tutorials to learn more about Bajo and how to use it to build your next app.