@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

Classes

• OclifUtils

Interfaces

• OclifHelpContent

Type aliases

• CommandArgNames
• CommandArgs
• CommandFlags
• CommandOptions

Functions

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

Type aliases

CommandArgNames

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

Type parameters

CommandArgs

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

Type parameters

CommandFlags

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

Type parameters

CommandOptions

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

Type parameters

Functions

generateHelpText

▸ Const generateHelpText(commandInstance, options?): string

Parameters

Returns

string

getCommandConfig

▸ getCommandConfig(commandInstance): Config.Command

Parameters

Returns

Config.Command

injectHelpTextIntoReadmeMd

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

Parameters

Returns

Promise<void>

parseCommandLine

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

Type parameters

Parameters

Returns

CommandOptions<T>

prependCliToExamples

▸ Const prependCliToExamples(commandInstance): void

Parameters

Returns

void

reconstructCommandLine

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

Type parameters

Parameters

Returns

string

Classes

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

Class: 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

Returns

string

help content

getCommandConfig

▸ Static getCommandConfig(commandInstance): Command

Parameters

Returns

Command

injectHelpTextIntoReadmeMd

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

Parameters

Returns

Promise<void>

parseCommandLine

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

Type parameters

Parameters

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

Returns

void

void

reconstructCommandLine

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

Reconstruct the command line from already parsed options.

Type parameters

Parameters

Returns

string

the command line string corresponding to the parsed options

Interfaces

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

Interface: 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