@handy-common-utils/oclif-utils
Advanced tools
oclif (https://oclif.io/) related utilities
With this utility library, you will be able to:
options.args available./bin/run --update-readme.md for inserting properly formated CLI manual informationCliConsole for logging with and without colouringIf you are using latest versions of @oclif/core(introduction, migration), just add latest version of this package as dependency:
npm install @handy-common-utils/oclif-utils@latest
Otherwise if the versions of oclif components you are using are older (that means you are still using @oclif/config, @oclif/command, @oclif/parser), you need to use the older version of this package:
npm install @handy-common-utils/oclif-utils@1.0.9
Then you can use it in the code:
import { Command, Flags } from '@oclif/core';
import { OclifUtils, cliConsole, cliConsoleWithColour } from '@handy-common-utils/oclif-utils';
class AwsServerlessDataflow extends Command {
// You can use "typeof AwsServerlessDataflow.Options" in other places to refer to the type, if you want this convenience
static Options: CommandOptions<typeof AwsServerlessDataflow>
// ... other code ...
static flags = {
version: Flags.version({ char: 'v' }),
help: { ...Flags.help({ char: 'h' }), parse: async (_: any, cmd: Command) => {
cmd.log(await OclifUtils.generateHelpText(cmd));
cmd.exit(0);
} },
'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(): Promise<void> {
const options = await this.parse() as CommandOptions<typeof AwsServerlessDataflow>; // as typeof AwsServerlessDataflow.Options
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) {
cliConsoleWithColour.info(`Command line: ${OclifUtils.reconstructCommandLine(this, options)}`);
}
// Now the compiler knows that options.args has a property named "path"
cliConsole.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';
cli-console.CliConsole
Encapsulation of console output functions.
| Name | Type |
|---|---|
DEBUG_FUNC | extends Function |
INFO_FUNC | extends Function |
WARN_FUNC | extends Function |
ERROR_FUNC | extends Function |
• new CliConsole<DEBUG_FUNC, INFO_FUNC, WARN_FUNC, ERROR_FUNC>(debugFunction, infoFunction, warnFunction, errorFunction, isDebug?, isQuiet?)
Constructor
| Name | Type |
|---|---|
DEBUG_FUNC | extends Function |
INFO_FUNC | extends Function |
WARN_FUNC | extends Function |
ERROR_FUNC | extends Function |
| 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. |
| Property | Description |
|---|---|
• debug: DEBUG_FUNC | |
• error: ERROR_FUNC | |
• info: INFO_FUNC | |
• isDebug: boolean = false | |
• isQuiet: boolean = false | |
• warn: WARN_FUNC | |
▪ Static Protected NO_OP_FUNC: () => void | Type declaration: ▸ (): voidReturns: void |
▸ Static default<FLAGS>(flags, debugFlagName?, quietFlagName?): CliConsole<(message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void>
Build an instance with console.log/info/warn/error.
| Name | Type |
|---|---|
FLAGS | extends Record<string, any> |
| 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 |
CliConsole<(message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void>
An instance that uses console.log/info/warn/error.
▸ Static withColour<FLAGS, COLOURER>(flags, colourer, debugColourFuncName?, infoColourFuncName?, warnColourFuncName?, errorColourFuncName?, debugFlagName?, quietFlagName?): CliConsole<(message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void>
Build an instance with console.log/info/warn/error and chalk/colors/cli-color.
| Name | Type |
|---|---|
FLAGS | extends Record<string, any> |
COLOURER | extends Record<string, any> |
| 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 |
CliConsole<(message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void>
An instance that uses console.log/info/warn/error and also adds colour to the messages using chalk/colors/cli-color.
oclif-utils.OclifUtils
• new OclifUtils()
▸ Static generateHelpText(commandInstance, options?): Promise<string>
Generate formatted text content of help to a command
| Name | Type | Description |
|---|---|---|
commandInstance | default | instance of the Command |
options? | HelpOptions | format options |
Promise<string>
help content
▸ Static getCommandConfig(commandInstance): Promise<Command>
| Name | Type |
|---|---|
commandInstance | default |
Promise<Command>
▸ Static injectHelpTextIntoReadmeMd(commandInstance, options?): Promise<void>
| Name | Type |
|---|---|
commandInstance | default |
options? | HelpOptions |
Promise<void>
▸ Static prependCliToExamples(commandInstance): void
Use this function to prepend command line to examples,
so that we don't have to hard code command name in the examples.
This function needs to be called from init() function of the Command.
| Name | Type | Description |
|---|---|---|
commandInstance | default | instance of the Command |
void
void
▸ Static reconstructCommandLine<T>(commandInstance, options): string
Reconstruct the command line from already parsed options.
| Name | Type |
|---|---|
T | extends Object |
| Name | Type | Description |
|---|---|---|
commandInstance | InstanceType<T> | When calling from the subclass of Command, just pass this |
options | CommandOptions<T> | Already parsed options. It can be got with const options = await OclifUtils.parseCommandLine(commandInstance); |
string
the command line string corresponding to the parsed options
Ƭ DefaultCliConsole: ReturnType<typeof default>
CliConsole that has function signatures based on console.log/info/warn/error.
▸ cliConsole<FLAGS>(flags, debugFlagName?, quietFlagName?): CliConsole<(message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void>
Build an encapsulation of console output functions with console.log/info/warn/error.
| Name | Type |
|---|---|
FLAGS | extends Record<string, any> |
| 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 |
CliConsole<(message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void>
An CliConsole instance that uses console.log/info/warn/error.
▸ cliConsoleWithColour<FLAGS, COLOURER>(flags, colourer, debugColourFuncName?, infoColourFuncName?, warnColourFuncName?, errorColourFuncName?, debugFlagName?, quietFlagName?): CliConsole<(message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void>
Build an encapsulation of console output functions with console.log/info/warn/error and chalk/colors/cli-color.
| Name | Type |
|---|---|
FLAGS | extends Record<string, any> |
COLOURER | extends Record<string, any> |
| 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 |
CliConsole<(message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void, (message?: any, ...optionalParams: any[]) => void>
An CliConsole instance that uses console.log/info/warn/error and also adds colour to the messages using chalk/colors/cli-color.
Ƭ CommandOptions<T>: Interfaces.ParserOutput<CommandFlags<T>, CommandArgs<T>>
| Name | Type |
|---|---|
T | extends Object |
▸ generateHelpText(commandInstance, options?): Promise<string>
| Name | Type |
|---|---|
commandInstance | default |
options? | HelpOptions |
Promise<string>
▸ getCommandConfig(commandInstance): Promise<Command>
| Name | Type |
|---|---|
commandInstance | default |
Promise<Command>
▸ injectHelpTextIntoReadmeMd(commandInstance, options?): Promise<void>
| Name | Type |
|---|---|
commandInstance | default |
options? | HelpOptions |
Promise<void>
▸ prependCliToExamples(commandInstance): void
| Name | Type |
|---|---|
commandInstance | default |
void
▸ reconstructCommandLine<T>(commandInstance, options): string
| Name | Type |
|---|---|
T | extends Object |
| Name | Type |
|---|---|
commandInstance | InstanceType<T> |
options | CommandOptions<T> |
string
FAQs
oclif related utilities
We found that @handy-common-utils/oclif-utils demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.