cli-utils

Description

A private collection of utilities for developing cli tools.

Usage

You should generally not use it. You would use tools built or developed with it, for example:

• @gkalpak/aliases
• gkalpak.aio-docs-utils

I may use it for building or developing other tools (see above). Below is a brief overview of what's in the box.

Programmatic usage

This package exposes the following utilities (see the respective source files for API docs):

• commandUtils:

  • expandCmd(cmd: string, runtimeArgs: string[], config: IRunConfig): Promise<string>:
    Expand a command string, by substituting argument identifiers with the specified arguments. It also supports default/fallback arguments (specified either as static values or as commands to execute and use the output).

  • preprocessArgs(rawArgs: string[]): {args: string[], config: IRunConfig}:
    Preprocess a list of input arguments into a list of arguments that can be used for substituting into commands. Also, derive a configuration object to modify the behavior of commandUtils.run().

  • run(cmd: string, runtimeArgs?: string[], config?: IRunConfig): Promise<string>:
    Run a command. Could be a complex command with |, && and ||. It also supports argument substitution with commandUtils.expandCmd().

  • spawnAsPromised(cmd: string, config?: IRunConfig): Promise<string>:
    Spawn a complex command (or series of piped commands) and return a promise that resolves or rejects based on the command's outcome. It provides some extras on top of child_process.spawn().

• processUtils:

  • doOnExit(proc: Process, action: Function): Function:
    Run the specified action, when exit or SIGINT are fired on the specified process.

  • suppressTerminateBatchJobConfirmation(proc: Process): Function:
    Suppress the "Terminate batch job (Y/N)?" confirmation on Windows for the specified process. Calling it with a non-Windows process is a no-op.

    NOTE: This is still an experimental feature and not guaranteed to work as expected. It is known to not work with certain types of commands (e.g. vim).

• testingUtils:

  • testCmd(cmd: string, config?: IRunConfig): Promise<string>:
    Run the specified command using commandUtils.spawnAsPromised(), capture the output and return it (after normalizing newlines and trimming it).

  • testScriptFactory(scriptPath: string, config?: IRunConfig): Function:
    Create a function that can be used for testing a Node.js script with testingUtils.testCmd(). Different arguments can be passed per call of the returned function.

  • withJasmineTimeout(newTimeout: number, testSuite: Function): void:
    Run a test suite (i.e. describe() block) with a different DEFAULT_TIMEOUT_INTERVAL. The previous timeout interval is restored after all tests of the suite have completed.

Command-line usage

This package exposes the following commands (see the respective source files for API docs):

• gkcu-expand-cmd "<cmd>" <arg1> <arg2> --gkcu-<arg3> ...:
  Expand a command string by substituting argument identifiers with the specified arguments. It also supports default/fallback arguments (specified either as static values or as commands to execute and use the output).

  Examples:

  gkcu-expand-cmd "echo \$1 \${2:bar} \$1" foo
  #--> echo foo bar foo
  
  gkcu-expand-cmd "echo \${1:Hello}, \${0:::whoami}!" Hey
  #--> echo Hey, gkalpak!

• gkcu-run "<cmd>" <arg1> <arg2> --gkcu-<arg3> ...:
  Run a command with support for argument substitution. Could be a complex command with |, && and || (but not guaranteed to work if too complex :P).

  Examples:

  gkcu-run "echo \$1 \${2:bar} \$1" foo
  #--> foo bar foo
  
  gkcu-run "echo \${1:Hello}, \${0:::whoami}!" Hey
  #--> Hey, gkalpak!

Testing

The following test-types/modes are available:

• Code-linting: npm run lint Lint TypeScript files using TSLint.

• Unit tests: npm run test-unit Run all the unit tests once. These tests are quick and suitable to be run on every change.

• E2E tests: npm run test-e2e Run all the end-to-end tests once. These test may hit actual API endpoints or perform expensive I/O operations and are considerably slower than unit tests.

• All tests: npm test / npm run test Run all of the above tests (code-linting, unit tests, e2e tests). This command is automatically run before every release (via npm run release).

• "Dev" mode: npm run dev Watch all files and rerun the unit tests whenever something changes. For performance reasons, code-linting and e2e tests are omitted.

TODO

Things I want to (but won't necessarily) do:

• Add more unit tests for commandUtils.spawnAsPromised().