@theurgi/help NPM

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'`

strip-ansi table term-size word-wrap

@everything-registry/sub-chunk-914

1.2.0

1 year ago

1.1.0

1 year ago

1.0.0

1 year ago