@handy-common-utils/oclif-utils

oclif (https://oclif.io/) related utilities

Features

With this utility library, you will be able to:

• Make type information of options.args available
• Update README.md file by ./bin/run --update-readme.md for inserting properly formated CLI manual information
• Prepend command line name to the examples
• Reconstruct the full command line as a string

How to use

First add it as a dependency:

npm install @handy-common-utils/oclif-utils

Then you can use it in the code:

import { Command, flags } from '@oclif/command';
import { CommandArgs, CommandFlags, CommandOptions, OclifUtils } from '@handy-common-utils/oclif-utils';

class AwsServerlessDataflow extends Command {
  // You can use "typeof AwsServerlessDataflow.Options" in other places to refer to the type
  static Options: CommandOptions<typeof AwsServerlessDataflow>

  // ... other code ...

  static flags = {
    version: flags.version({ char: 'v' }),
    help: flags.help({ char: 'h' }),
    'update-readme.md': flags.boolean({ hidden: true, description: 'For developers only, don\'t use' }),
    debug: flags.boolean({ char: 'd', name: 'debug' }),
    // ... other code ...
  }

  static args = [
    { name: 'path' as const, default: 'dataflow', description: 'path for putting generated website files' },
    //             ^----- this is needed for the "path" property of options.args to be known to the compiler
  ];

  static examples = [
    '^ -r ap-southeast-2 -s',
    `^ -r ap-southeast-2 -s -i '*boi*' -i '*datahub*' \\
      -x '*jameshu*' -c`,
    `^ -r ap-southeast-2 -s -i '*lr-*' \\
      -i '*lead*' -x '*slack*' -x '*lead-prioritization*' \\
      -x '*lead-scor*' -x '*LeadCapture*' -c`,
  ];

  protected async init(): Promise<any> {
    OclifUtils.prependCliToExamples(this);  // "^" at the beginning of the examples will be replaced by the actual command
    return super.init();
  }

  async run(argv?: string[]): Promise<void> {
    const options = this.parse<CommandFlags<typeof AwsServerlessDataflow>, CommandArgs<typeof AwsServerlessDataflow>>(AwsServerlessDataflow, argv);
    if (options.flags['update-readme.md']) {
      OclifUtils.injectHelpTextIntoReadmeMd(this); // you need to have <!-- help start -->...<!-- help end --> in your README.md
      return;
    }
    // This would be helpful if a complex command line needs to be shared
    if (options.flags.debug) {
      console.log(`Command line: ${OclifUtils.reconstructCommandLine(this, options)}`);
    }

    // Now the compiler knows that options.args has a property named "path"
    console.log(options.args.path);

    // You can add this in the scripts section of your package.json:  "preversion": "./bin/run --update-readme.md && git add README.md"

    // ... other code ...
  }
}
export = AwsServerlessDataflow

You can either import and use the class as shown above, or you can import individual functions directly like below:

import { prependCliToExamples } from '@handy-common-utils/oclif-utils';

API

@handy-common-utils/oclif-utils

@handy-common-utils/oclif-utils

Table of contents

Modules

• cli-console
• index
• oclif-utils

Classes

@handy-common-utils/oclif-utils / cli-console / CliConsole

Class: CliConsole<DEBUG_FUNC, INFO_FUNC, WARN_FUNC, ERROR_FUNC>

cli-console.CliConsole

Encapsulation of console output functions.

Type parameters

Name	Type
DEBUG_FUNC	extends Function
INFO_FUNC	extends Function
WARN_FUNC	extends Function
ERROR_FUNC	extends Function

Table of contents

Constructors

• constructor

Properties

• debug
• error
• info
• isDebug
• isQuiet
• warn
• NO_OP_FUNC

Methods

• default
• withColour

Constructors

constructor

• new CliConsole<DEBUG_FUNC, INFO_FUNC, WARN_FUNC, ERROR_FUNC>(debugFunction, infoFunction, warnFunction, errorFunction, isDebug?, isQuiet?)

Constructor

Type parameters

Name	Type
DEBUG_FUNC	extends Function
INFO_FUNC	extends Function
WARN_FUNC	extends Function
ERROR_FUNC	extends Function

Parameters

Name	Type	Default value	Description
debugFunction	DEBUG_FUNC	undefined	function for outputting debug information
infoFunction	INFO_FUNC	undefined	function for outputting info information
warnFunction	WARN_FUNC	undefined	function for outputting warn information
errorFunction	ERROR_FUNC	undefined	function for outputting error information
isDebug	boolean	false	is debug output enabled or not
isQuiet	boolean	false	is quiet mode enabled or not. When quiet mode is enabled, debug and info output would be discarded.

Properties

debug

• debug: DEBUG_FUNC

---

error

• error: ERROR_FUNC

---

info

• info: INFO_FUNC

---

isDebug

• isDebug: boolean = false

---

isQuiet

• isQuiet: boolean = false

---

warn

• warn: WARN_FUNC

---

NO_OP_FUNC

▪ Static Protected NO_OP_FUNC: () => void

Type declaration

▸ (): void

####### Returns

void

Methods

default

▸ Static default<FLAGS>(flags, debugFlagName?, quietFlagName?): CliConsole<fn, fn, fn, fn>

Build an instance with console.log/info/warn/error.

Type parameters

Name	Type
FLAGS	extends Record<string, any>

Parameters

Name	Type	Default value	Description
flags	FLAGS	undefined	The flag object that contains fields for knowning whether debug is enabled and whether quiet mode is enabled. Those fields are evaluated only once within the function. They are not evaluated when debug/info/warn/error functions are called.
debugFlagName	keyof FLAGS	'debug'	Name of the debug field in the flags object
quietFlagName	keyof FLAGS	'quiet'	Name of the quiet field in the flags object

Returns

CliConsole<fn, fn, fn, fn>

An instance that uses console.log/info/warn/error.

---

withColour

▸ Static withColour<FLAGS, COLOURER>(flags, colourer, debugColourFuncName?, infoColourFuncName?, warnColourFuncName?, errorColourFuncName?, debugFlagName?, quietFlagName?): CliConsole<fn, fn, fn, fn>

Build an instance with console.log/info/warn/error and chalk/colors/cli-color.

Type parameters

Name	Type
FLAGS	extends Record<string, any>
COLOURER	extends Record<string, any>

Parameters

Name	Type	Default value	Description
flags	FLAGS	undefined	The flag object that contains fields for knowning whether debug is enabled and whether quiet mode is enabled. Those fields are evaluated only once within the function. They are not evaluated when debug/info/warn/error functions are called.
colourer	COLOURER	undefined	Supplier of the colouring function, such as chalk or colors or cli-color
debugColourFuncName	keyof COLOURER	'grey'	Name of the function within colourer that will be used to add colour to debug messages, or null if colouring is not desired.
infoColourFuncName?	keyof COLOURER	undefined	Name of the function within colourer that will be used to add colour to info messages, or null if colouring is not desired.
warnColourFuncName	keyof COLOURER	'yellow'	Name of the function within colourer that will be used to add colour to warn messages, or null if colouring is not desired.
errorColourFuncName	keyof COLOURER	'red'	Name of the function within colourer that will be used to add colour to error messages, or null if colouring is not desired.
debugFlagName	keyof FLAGS	'debug'	Name of the debug field in the flags object
quietFlagName	keyof FLAGS	'quiet'	Name of the quiet field in the flags object

Returns

CliConsole<fn, fn, fn, fn>

An instance that uses console.log/info/warn/error and also adds colour to the messages using chalk/colors/cli-color.

@handy-common-utils/oclif-utils / oclif-utils / OclifUtils

Class: OclifUtils

oclif-utils.OclifUtils

Table of contents

Constructors

• constructor

Methods

• generateHelpText
• getCommandConfig
• injectHelpTextIntoReadmeMd
• parseCommandLine
• prependCliToExamples
• reconstructCommandLine

Constructors

constructor

• new OclifUtils()

Methods

generateHelpText

▸ Static generateHelpText(commandInstance, options?): string

Generate formatted text content of help to a command

Parameters

Name	Type	Description
commandInstance	default	instance of the Command
options?	Partial<HelpOptions>	format options

Returns

string

help content

---

getCommandConfig

▸ Static getCommandConfig(commandInstance): Command

Parameters

Name	Type
commandInstance	default

Returns

Command

---

injectHelpTextIntoReadmeMd

▸ Static injectHelpTextIntoReadmeMd(commandInstance, options?): Promise<void>

Parameters

Name	Type
commandInstance	default
options?	Partial<HelpOptions>

Returns

Promise<void>

---

parseCommandLine

▸ Static parseCommandLine<T>(commandInstance): CommandOptions<T>

Type parameters

Name	Type
T	extends Object

Parameters

Name	Type
commandInstance	InstanceType<T>

Returns

CommandOptions<T>

---

prependCliToExamples

▸ Static prependCliToExamples(commandInstance): void

Use this function to prepend command line to examples. This function needs to be called from init() function of the Command.

Parameters

Name	Type	Description
commandInstance	default	instance of the Command

Returns

void

void

---

reconstructCommandLine

▸ Static reconstructCommandLine<T>(commandInstance, options?): string

Reconstruct the command line from already parsed options.

Type parameters

Name	Type
T	extends Object

Parameters

Name	Type	Description
commandInstance	InstanceType<T>	When calling from the subclass of Command, just pass this
options?	CommandOptions<T>	already parsed options

Returns

string

the command line string corresponding to the parsed options

Interfaces

@handy-common-utils/oclif-utils / oclif-utils / OclifHelpContent

Interface: OclifHelpContent

oclif-utils.OclifHelpContent

Table of contents

Properties

• aliases
• args
• description
• examples
• flags
• usage

Properties

aliases

• Optional aliases: string

---

args

• Optional args: string

---

description

• Optional description: string

---

examples

• Optional examples: string

---

flags

• Optional flags: string

---

usage

• Optional usage: string

Modules

@handy-common-utils/oclif-utils / cli-console

Module: cli-console

Table of contents

Classes

• CliConsole

Type aliases

• DefaultCliConsole

Functions

• cliConsole
• cliConsoleWithColour

Type aliases

DefaultCliConsole

Ƭ DefaultCliConsole: ReturnType<typeof default>

CliConsole that has function signatures based on console.log/info/warn/error.

Functions

cliConsole

▸ Const cliConsole<FLAGS>(flags, debugFlagName?, quietFlagName?): CliConsole<fn, fn, fn, fn>

Build an encapsulation of console output functions with console.log/info/warn/error.

Type parameters

Name	Type
FLAGS	extends Record<string, any>

Parameters

Name	Type	Default value	Description
flags	FLAGS	undefined	The flag object that contains fields for knowning whether debug is enabled and whether quiet mode is enabled. Those fields are evaluated only once within the function. They are not evaluated when debug/info/warn/error functions are called.
debugFlagName	keyof FLAGS	'debug'	Name of the debug field in the flags object
quietFlagName	keyof FLAGS	'quiet'	Name of the quiet field in the flags object

Returns

CliConsole<fn, fn, fn, fn>

An CliConsole instance that uses console.log/info/warn/error.

---

cliConsoleWithColour

▸ Const cliConsoleWithColour<FLAGS, COLOURER>(flags, colourer, debugColourFuncName?, infoColourFuncName?, warnColourFuncName?, errorColourFuncName?, debugFlagName?, quietFlagName?): CliConsole<fn, fn, fn, fn>

Build an encapsulation of console output functions with console.log/info/warn/error and chalk/colors/cli-color.

Type parameters

Name	Type
FLAGS	extends Record<string, any>
COLOURER	extends Record<string, any>

Parameters

Name	Type	Default value	Description
flags	FLAGS	undefined	The flag object that contains fields for knowning whether debug is enabled and whether quiet mode is enabled. Those fields are evaluated only once within the function. They are not evaluated when debug/info/warn/error functions are called.
colourer	COLOURER	undefined	Supplier of the colouring function, such as chalk or colors or cli-color
debugColourFuncName	keyof COLOURER	'grey'	Name of the function within colourer that will be used to add colour to debug messages, or null if colouring is not desired.
infoColourFuncName?	keyof COLOURER	undefined	Name of the function within colourer that will be used to add colour to info messages, or null if colouring is not desired.
warnColourFuncName	keyof COLOURER	'yellow'	Name of the function within colourer that will be used to add colour to warn messages, or null if colouring is not desired.
errorColourFuncName	keyof COLOURER	'red'	Name of the function within colourer that will be used to add colour to error messages, or null if colouring is not desired.
debugFlagName	keyof FLAGS	'debug'	Name of the debug field in the flags object
quietFlagName	keyof FLAGS	'quiet'	Name of the quiet field in the flags object

Returns

CliConsole<fn, fn, fn, fn>

An CliConsole instance that uses console.log/info/warn/error and also adds colour to the messages using chalk/colors/cli-color.

@handy-common-utils/oclif-utils / index

Module: index

Table of contents

References

• CliConsole
• CommandArgNames
• CommandArgs
• CommandFlags
• CommandOptions
• DefaultCliConsole
• Flags
• OclifHelpContent
• OclifUtils
• cliConsole
• cliConsoleWithColour
• generateHelpText
• getCommandConfig
• injectHelpTextIntoReadmeMd
• parseCommandLine
• prependCliToExamples
• reconstructCommandLine

References

CliConsole

Re-exports: CliConsole

---

CommandArgNames

Re-exports: CommandArgNames

---

CommandArgs

Re-exports: CommandArgs

---

CommandFlags

Re-exports: CommandFlags

---

CommandOptions

Re-exports: CommandOptions

---

DefaultCliConsole

Re-exports: DefaultCliConsole

---

Flags

Re-exports: Flags

---

OclifHelpContent

Re-exports: OclifHelpContent

---

OclifUtils

Re-exports: OclifUtils

---

cliConsole

Re-exports: cliConsole

---

cliConsoleWithColour

Re-exports: cliConsoleWithColour

---

generateHelpText

Re-exports: generateHelpText

---

getCommandConfig

Re-exports: getCommandConfig

---

injectHelpTextIntoReadmeMd

Re-exports: injectHelpTextIntoReadmeMd

---

parseCommandLine

Re-exports: parseCommandLine

---

prependCliToExamples

Re-exports: prependCliToExamples

---

reconstructCommandLine

Re-exports: reconstructCommandLine

@handy-common-utils/oclif-utils / oclif-utils

Module: oclif-utils

Table of contents

Classes

• OclifUtils

Interfaces

• OclifHelpContent

Type aliases

• CommandArgNames
• CommandArgs
• CommandFlags
• CommandOptions
• Flags

Functions

• generateHelpText
• getCommandConfig
• injectHelpTextIntoReadmeMd
• parseCommandLine
• prependCliToExamples
• reconstructCommandLine

Type aliases

CommandArgNames

Ƭ CommandArgNames<T>: T extends { name: infer A }[] ? A : never

Type parameters

Name
T

---

CommandArgs

Ƭ CommandArgs<T>: { [x in CommandArgNames<T["args"]>]: string}

Type parameters

Name	Type
T	extends Object

---

CommandFlags

Ƭ CommandFlags<T>: T extends Parser.Input<infer F> ? F : never

Type parameters

Name
T

---

CommandOptions

Ƭ CommandOptions<T>: Parser.Output<CommandFlags<T>, CommandArgs<T>>

Type parameters

Name	Type
T	extends Object

---

Flags

Ƭ Flags<T>: T extends Parser.flags.Input<infer F> ? F : never

Get the flag object type from flags configuration type

Type parameters

Name
T

Functions

generateHelpText

▸ Const generateHelpText(commandInstance, options?): string

Parameters

Name	Type
commandInstance	default
options?	Partial<HelpOptions>

Returns

string

---

getCommandConfig

▸ getCommandConfig(commandInstance): Config.Command

Parameters

Name	Type
commandInstance	Command

Returns

Config.Command

---

injectHelpTextIntoReadmeMd

▸ Const injectHelpTextIntoReadmeMd(commandInstance, options?): Promise<void>

Parameters

Name	Type
commandInstance	default
options?	Partial<HelpOptions>

Returns

Promise<void>

---

parseCommandLine

▸ Const parseCommandLine<T>(commandInstance): CommandOptions<T>

Type parameters

Name	Type
T	extends Object

Parameters

Name	Type
commandInstance	InstanceType<T>

Returns

CommandOptions<T>

---

prependCliToExamples

▸ Const prependCliToExamples(commandInstance): void

Parameters

Name	Type
commandInstance	default

Returns

void

---

reconstructCommandLine

▸ Const reconstructCommandLine<T>(commandInstance, options?): string

Type parameters

Name	Type
T	extends Object

Parameters

Name	Type
commandInstance	InstanceType<T>
options?	CommandOptions<T>

Returns

string