@gkalpak/cli-utils NPM

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:

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.