cli-toolbox

A convenient aggregation of useful quality modules related to writing CLI node apps.

Introduction

This module is an aggregation of frequently used terminal / CLI related modules that frequently work together.

When writing a CLI script/tool, if you don't mind the extra space, you just need this single dep + the interface is cleaner!

Goals:

• not have to depend on a flurry of small modules, depend on this single one instead
• wrap some modules for a more uniform API

usage

framework/cli-interface

Based on:

• meow v12.1.1
  • CLI app helper

import createCliInterface from '@offirmo/cli-toolbox/framework/cli-interface'

const cli = createCliInterface('build', {
	importMeta: import.meta,
	flags: {
		watch: {
			type: 'boolean',
			default: false,
		},
	},
})

console.log('building…', { flags: cli.flags })

output:

building… { flags: { watch: false } }

fs/json

Based on:

• write-json-file v5.0.0
  • Stringify and write JSON to a file atomically
• load-json-file v7.0.1
  • Read and parse a JSON file

import json from '@offirmo/cli-toolbox/fs/extra/json'

const filepath = path.join(__dirname, '..', 'package.json')

function process_data({name, version, description, author, license}) {
	console.log({name, version, description, author, license})
}

process_data(json.readSync(filepath))

return json.read(filepath)
	.then(data => {
		process_data(data)
		return json.write('foo.json', data)
	})
// 2x output 1) sync 2) async

output:

{
  name: '@offirmo/cli-toolbox',
  version: '2.0.0',
  description: 'An aggregation of useful quality modules related to writing CLI node apps',
  author: 'Offirmo <[email protected]>',
  license: 'Unlicense'
}
{
  name: '@offirmo/cli-toolbox',
  version: '2.0.0',
  description: 'An aggregation of useful quality modules related to writing CLI node apps',
  author: 'Offirmo <[email protected]>',
  license: 'Unlicense'
}

fs/extra

Based on:

• fs-extra v11.1.1
  • https://github.com/jprichardson/node-fs-extra
  • fs-extra contains methods that aren't included in the vanilla Node.js fs package. Such as recursive mkdir, copy, and remove.

import fs from '@offirmo/cli-toolbox/fs/extra'

let dirs = fs.lsDirsSync(path.join(__dirname, '..'))
console.log('full path', dirs)

dirs = fs.lsDirsSync(path.join(__dirname, '..'), { full_path: false })
console.log('short path', dirs)

let files = fs.lsFilesSync(path.join(__dirname, '..'))
console.log('full path', files)

files = fs.lsFilesSync(path.join(__dirname, '..'), { full_path: false })
console.log('short path', files)

files = fs.lsFilesRecursiveSync(path.join(__dirname, '..', 'fs'))
console.log('recursive', files)

output:

full path [
  '/Users/offirmo/work/src/off/offirmo-monorepo/stack--2022/3-advanced--node/cli-toolbox/_doc',
  '/Users/offirmo/work/src/off/offirmo-monorepo/stack--2022/3-advanced--node/cli-toolbox/_tosort',
  '/Users/offirmo/work/src/off/offirmo-monorepo/stack--2022/3-advanced--node/cli-toolbox/framework',
  '/Users/offirmo/work/src/off/offirmo-monorepo/stack--2022/3-advanced--node/cli-toolbox/fs',
  '/Users/offirmo/work/src/off/offirmo-monorepo/stack--2022/3-advanced--node/cli-toolbox/node_modules',
  '/Users/offirmo/work/src/off/offirmo-monorepo/stack--2022/3-advanced--node/cli-toolbox/stdout',
  '/Users/offirmo/work/src/off/offirmo-monorepo/stack--2022/3-advanced--node/cli-toolbox/string'
]
short path [
  '_doc',
  '_tosort',
  'framework',
  'fs',
  'node_modules',
  'stdout',
  'string'
]
full path [
  '/Users/offirmo/work/src/off/offirmo-monorepo/stack--2022/3-advanced--node/cli-toolbox/.npmrc',
  '/Users/offirmo/work/src/off/offirmo-monorepo/stack--2022/3-advanced--node/cli-toolbox/.tabset',
  '/Users/offirmo/work/src/off/offirmo-monorepo/stack--2022/3-advanced--node/cli-toolbox/CHANGELOG.md',
  '/Users/offirmo/work/src/off/offirmo-monorepo/stack--2022/3-advanced--node/cli-toolbox/LICENSE',
  '/Users/offirmo/work/src/off/offirmo-monorepo/stack--2022/3-advanced--node/cli-toolbox/NOTES.md',
  '/Users/offirmo/work/src/off/offirmo-monorepo/stack--2022/3-advanced--node/cli-toolbox/README.md',
  '/Users/offirmo/work/src/off/offirmo-monorepo/stack--2022/3-advanced--node/cli-toolbox/index.js',
  '/Users/offirmo/work/src/off/offirmo-monorepo/stack--2022/3-advanced--node/cli-toolbox/package.json'
]
short path [
  '.npmrc',
  '.tabset',
  'CHANGELOG.md',
  'LICENSE',
  'NOTES.md',
  'README.md',
  'index.js',
  'package.json'
]
recursive [
  '/Users/offirmo/work/src/off/offirmo-monorepo/stack--2022/3-advanced--node/cli-toolbox/fs/extra/index.cjs',
  '/Users/offirmo/work/src/off/offirmo-monorepo/stack--2022/3-advanced--node/cli-toolbox/fs/extra/index.mjs',
  '/Users/offirmo/work/src/off/offirmo-monorepo/stack--2022/3-advanced--node/cli-toolbox/fs/extra/json/index.cjs',
  '/Users/offirmo/work/src/off/offirmo-monorepo/stack--2022/3-advanced--node/cli-toolbox/fs/extra/json/index.mjs',
  '/Users/offirmo/work/src/off/offirmo-monorepo/stack--2022/3-advanced--node/cli-toolbox/fs/extra/ls/index.cjs',
  '/Users/offirmo/work/src/off/offirmo-monorepo/stack--2022/3-advanced--node/cli-toolbox/fs/extra/ls/index.mjs'
]

stdout/clear-cli

Based on:

• ansi-escapes v6.2.0
  • ANSI escape codes for manipulating the terminal

import clearCli from '@offirmo/cli-toolbox/stdout/clear-cli'

//clearCli()

output:

string/stylize-string

Based on:

• chalk v5.3.0
  • Terminal string styling done right

import stylize_string from '@offirmo/cli-toolbox/string/stylize'

console.log(stylize_string.red.bold.underline('Hello', 'world'))
console.log(stylize_string.red('red'),         stylize_string.bold.red('bold'))
console.log(stylize_string.green('green'),     stylize_string.bold.green('green'))
console.log(stylize_string.yellow('yellow'),   stylize_string.bold.yellow('yellow'))
console.log(stylize_string.blue('blue'),       stylize_string.bold.blue('blue'))
console.log(stylize_string.magenta('magenta'), stylize_string.bold.magenta('magenta'))
console.log(stylize_string.cyan('cyan'),       stylize_string.bold.cyan('cyan'))
console.log(stylize_string.white('white'),     stylize_string.bold.white('white'))
console.log(stylize_string.gray('gray'),       stylize_string.bold.gray('gray'))

output:

Hello world
red bold
green green
yellow yellow
blue blue
magenta magenta
cyan cyan
white white
gray gray

string/boxify

Based on:

• boxen v7.1.1
  • Create boxes in the terminal

import boxify from '@offirmo/cli-toolbox/string/boxify'

console.log(boxify('Hello'))

output:

┌─────┐
│Hello│
└─────┘

string/columnify

Based on:

• cli-columns v4.0.0
  • https://github.com/shannonmoeller/cli-columns#readme
  • Columnated lists for the CLI.

import columnify from '@offirmo/cli-toolbox/string/columnify'

const data = (await import('pokemon')).all()

console.log(columnify(data))

output:

Abomasnow     Chespin       Electivire    Heatmor       Magmortar     Phanpy        Shelgon       Torchic
Abra          Chewtle       Electrike     Heatran       Magnemite     Phantump      Shellder      Torkoal
Absol         Chikorita     Electrode     Heliolisk     Magneton      Pheromosa     Shellos       Tornadus
Accelgor      Chimchar      Elekid        Helioptile    Magnezone     Phione        Shelmet       Torracat
Aegislash     Chimecho      Elgyem        Heracross     Makuhita      Pichu         Shieldon      Torterra
Aerodactyl    Chinchou      Emboar        Herdier       Malamar       Pidgeot       Shiftry       Totodile
Aggron        Chingling     Emolga        Hippopotas    Mamoswine     Pidgeotto     Shiinotic     Toucannon
[truncated]

string/arrayify

Based on:

• columnify v1.6.0
  • https://github.com/timoxley/columnify
  • Render data in text columns. Supports in-column text-wrap.

import arrayify from '@offirmo/cli-toolbox/string/arrayify'

const data = {
	"[email protected]": 1,
	"[email protected]": 3,
	"[email protected]": 2,
	"[email protected]": 3
}

console.log(arrayify(data))

output:

KEY              VALUE
[email protected]  1
[email protected] 3
[email protected]     2
[email protected]    3

string/log-symbols

Based on:

• log-symbols v5.1.0
  • Colored symbols for various log levels. Example: ✔︎ Success

import logSymbols from '@offirmo/cli-toolbox/string/log-symbols'

console.log(logSymbols.info, 'info')
console.log(logSymbols.success, 'success')
console.log(logSymbols.warning, 'warning')
console.log(logSymbols.error, 'error')

output:

ℹ info
✔ success
⚠ warning
✖ error