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
- Generator
- HeadingOptions
- HelpConfig
- HelpOptions
- IndentLevel
- IndentSpaces
- ParagraphOptions
- RenderFunction
- TableAlignment
- TableOptions
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
paragraph
▸ paragraph(text
, options?
): RenderFunction
Generate a paragraph.
Parameters
Name | Type | Description |
---|---|---|
text |
string |
The paragraph text. |
options? |
Partial <ParagraphOptions> |
The paragraph options. |
Returns
space
▸ space(newlines?
): RenderFunction
Generate blank newlines.
Parameters
Name | Type | Description | Default |
---|---|---|---|
newlines? |
number |
The number of newlines to render. | 1 |
Returns
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
Type Aliases
Generator
Ƭ Generator<T
>: (...parameters
: Parameters
<T
>) => RenderFunction
NOTE: A
Generator
in the context ofhelp
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
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' |