@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 informationFirst 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';
@handy-common-utils/oclif-utils
@handy-common-utils/oclif-utils / cli-console / CliConsole
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. |
• debug: DEBUG_FUNC
• error: ERROR_FUNC
• info: INFO_FUNC
• isDebug: boolean = false
• isQuiet: boolean = false
• warn: WARN_FUNC
▪ Static Protected NO_OP_FUNC: () => void
▸ (): void
####### Returns
void
▸ Static default<FLAGS>(flags, debugFlagName?, quietFlagName?): CliConsole<fn, fn, fn, fn>
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<fn, fn, fn, fn>
An instance that uses console.log/info/warn/error.
▸ 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.
| 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<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
oclif-utils.OclifUtils
• new OclifUtils()
▸ Static generateHelpText(commandInstance, options?): string
Generate formatted text content of help to a command
| Name | Type | Description |
|---|---|---|
commandInstance | default | instance of the Command |
options? | Partial<HelpOptions> | format options |
string
help content
▸ Static getCommandConfig(commandInstance): Command
| Name | Type |
|---|---|
commandInstance | default |
Command
▸ Static injectHelpTextIntoReadmeMd(commandInstance, options?): Promise<void>
| Name | Type |
|---|---|
commandInstance | default |
options? | Partial<HelpOptions> |
Promise<void>
▸ Static parseCommandLine<T>(commandInstance): CommandOptions<T>
| Name | Type |
|---|---|
T | extends Object |
| Name | Type |
|---|---|
commandInstance | InstanceType<T> |
▸ 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.
| 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 |
string
the command line string corresponding to the parsed options
@handy-common-utils/oclif-utils / oclif-utils / OclifHelpContent
oclif-utils.OclifHelpContent
• Optional aliases: string
• Optional args: string
• Optional description: string
• Optional examples: string
• Optional flags: string
• Optional usage: string
@handy-common-utils/oclif-utils / cli-console
Ƭ DefaultCliConsole: ReturnType<typeof default>
@handy-common-utils/oclif-utils / oclif-utils
Ƭ CommandArgNames<T>: T extends { name: infer A }[] ? A : never
| Name |
|---|
T |
Ƭ CommandArgs<T>: { [x in CommandArgNames<T["args"]>]: string}
| Name | Type |
|---|---|
T | extends Object |
Ƭ CommandFlags<T>: T extends Parser.Input<infer F> ? F : never
| Name |
|---|
T |
Ƭ CommandOptions<T>: Parser.Output<CommandFlags<T>, CommandArgs<T>>
| Name | Type |
|---|---|
T | extends Object |
▸ Const cliConsole<FLAGS>(flags, debugFlagName?, quietFlagName?): CliConsole<fn, fn, fn, fn>
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<fn, fn, fn, fn>
An CliConsole instance that uses console.log/info/warn/error.
▸ 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.
| 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<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.
▸ Const generateHelpText(commandInstance, options?): string
| Name | Type |
|---|---|
commandInstance | default |
options? | Partial<HelpOptions> |
string
▸ getCommandConfig(commandInstance): Config.Command
| Name | Type |
|---|---|
commandInstance | Command |
Config.Command
▸ Const injectHelpTextIntoReadmeMd(commandInstance, options?): Promise<void>
| Name | Type |
|---|---|
commandInstance | default |
options? | Partial<HelpOptions> |
Promise<void>
▸ Const parseCommandLine<T>(commandInstance): CommandOptions<T>
| Name | Type |
|---|---|
T | extends Object |
| Name | Type |
|---|---|
commandInstance | InstanceType<T> |
▸ Const prependCliToExamples(commandInstance): void
| Name | Type |
|---|---|
commandInstance | default |
void
▸ Const reconstructCommandLine<T>(commandInstance, options?): string
| Name | Type |
|---|---|
T | extends Object |
| Name | Type |
|---|---|
commandInstance | InstanceType<T> |
options? | CommandOptions<T> |
string
FAQs
oclif related utilities
The npm package @handy-common-utils/oclif-utils receives a total of 16 weekly downloads. As such, @handy-common-utils/oclif-utils popularity was classified as not popular.
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.