Skip to content
/ help Public

Generate formatted help text for Node.js CLIs

License

Notifications You must be signed in to change notification settings

theurgi/help

Repository files navigation


Generate formatted help text for Node.js CLIs.


help doesn't attempt to parse arguments as some more comprehensive CLI frameworks do. Instead, it aims to be an unopinionated primitive that can be used as a stand-alone utility or as a building block within a more comprehensive CLI framework

Features

  • A simple and intuitive functional API
  • Flexibility: Makes no assumptions about your CLI's argument scheme
  • Dynamic line wrapping based on terminal width
  • Extensible built-in functions
  • Full TypeScript type support

Install

pnpm install @theurgi/help

Usage

Extended examples

Basic example

import { help, heading, paragraph, space, table } from '@theurgi/help'

console.log(
  help({
    display: [
      paragraph('My awesome CLI'),
      space(),
      heading('Usage'),
      paragraph('$ cli <command> [options]', { indentLevel: 1 }),
      space(),
      heading('Commands'),
      table([
        ['create', 'Create something'],
        ['update', 'Update something'],
      ]),
      space(),
      heading('Options'),
      table([
        ['-h, --help', 'Show help'],
        ['-v, --version', 'Show version'],
      ]),
    ],
  })
)

API

Exports

Functions

Types

Functions

help

help(helpConfig): string

Generate formatted help text for Node.js CLIs.

Parameters
Name Type Description
helpConfig HelpConfig The help configuration.
Returns

string


heading

heading(text, options?): RenderFunction

Generate a heading.

Parameters
Name Type Description
text string The heading text.
options? Partial<HeadingOptions> The heading options.
Returns

RenderFunction


paragraph

paragraph(text, options?): RenderFunction

Generate a paragraph.

Parameters
Name Type Description
text string The paragraph text.
options? Partial<ParagraphOptions> The paragraph options.
Returns

RenderFunction


space

space(newlines?): RenderFunction

Generate blank newlines.

Parameters
Name Type Description Default
newlines? number The number of newlines to render. 1
Returns

RenderFunction


table

table(data, options?): RenderFunction

Generate a 2 column table.

Parameters
Name Type Description
data [string, string][] An array of string tuples where data[n][0] is typically a CLI command or option and data[n][1] is typically a description of data[n][0].
options? Partial<TableOptions> The table options.
Returns

RenderFunction

Type Aliases

Generator

Ƭ Generator<T>: (...parameters: Parameters<T>) => RenderFunction

NOTE: A Generator in the context of help has no relation to JavaScript Generators.

A Generator is a function that is called inside the HelpConfig.display array of the main help function and returns a RenderFunction.

Built-in Generators
Type parameters
Name Type
T extends (...parameters: any) => RenderFunction
Type declaration

▸ (...parameters): RenderFunction

Parameters
Name Type
...parameters Parameters<T>
Returns

RenderFunction


HeadingOptions

Ƭ HeadingOptions: Object

Type declaration
Name Type Description Default
indentLevel IndentLevel The level of indentation for the heading. 0

HelpConfig

Ƭ HelpConfig: Object

Type declaration
Name Type Description
display RenderFunction[] An array in which to call Generator functions to render portions of the help text.
options? Partial<HelpOptions> Global options for the help text.

HelpOptions

Ƭ HelpOptions: Object

Type declaration
Name Type Description Default
indentSpaces IndentSpaces The number of spaces used for each indentation level. 2
maxWidth number The maximum width of the help text in characters. The terminal width.

IndentLevel

Ƭ IndentLevel: number

The number of times to left pad a string with IndentSpaces spaces.


IndentSpaces

Ƭ IndentSpaces: number

The number of spaces per IndentLevel.


ParagraphOptions

Ƭ ParagraphOptions: Object

Type declaration
Name Type Description Default
indentLevel IndentLevel The level of indentation for the paragraph. 0

RenderFunction

Ƭ RenderFunction: (helpOptions: HelpOptions) => string

Type declaration

▸ (helpOptions): string

The type of function that must be returned by a Generator. This function will be called with global HelpOptions by the main help function to render a formatted string.

Parameters
Name Type
helpOptions HelpOptions
Returns

string


TableAlignment

Ƭ TableOptions: 'center' | 'justify' | 'left' | 'right'

The horizontal alignment of a table column.


TableOptions

Ƭ TableOptions: Object

Type declaration
Name Type Description Default
columnGap number The number of spaces between columns. 2
indentLevel IndentLevel The level of indentation for the table. 1
leftColAlign TableAlignment The alignment of the left column. 'left'
rightColAlign TableAlignment The alignment of the right column 'left'