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

• Coloring with chalk
• Extending built-in functions
• Cloning Astro's help text

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

• help
• heading
• paragraph
• space
• table

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

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

• heading
• paragraph
• space
• table

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