@villedemontreal/scripting
Version:
Scripting core utilities
177 lines • 7.09 kB
TypeScript
import { ActionParameters, Command, CommandConfig, Logger, ParsedArgumentsObject, Program } from '@villedemontreal/caporal';
import { StdioOptions } from 'child_process';
import { IGlobalOptions } from './globalOptions';
/**
* A script with a name starting with this prefix
* will only be registered on Caporal when tests
* are running (ie: when the NODE_APP_INSTANCE env
* var is "tests").
*/
export declare const TESTING_SCRIPT_NAME_PREFIX = "testing:";
/**
* Constructor definition of a Script class
*/
export type IScriptConstructor<O = {}, GO extends IGlobalOptions = IGlobalOptions, A extends ParsedArgumentsObject = {}> = new (actionParams: ActionParameters) => ScriptBase<O, GO, A>;
/**
* Base class for a Script.
*
* You can parametrize it so `this.options` and `this.args`
* are typed.
*/
export declare abstract class ScriptBase<O = {}, GO extends IGlobalOptions = IGlobalOptions, A extends ParsedArgumentsObject = {}> {
private _actionParams;
constructor(actionParams: ActionParameters);
protected get actionParams(): ActionParameters;
/**
* Dependencies required for the script to run properly.
*/
protected get requiredDependencies(): string[];
/**
* The script's arguments.
*/
protected get args(): A;
/**
* The script's options.
*/
protected get options(): O & GO;
/**
* The script's logger. Will respect any specified log
* level (for example if the script was called with `--silent`).
*/
protected get logger(): Logger;
/**
* Register the script on Caporal
*/
registerScript(caporal: Program): Promise<void>;
protected addAction(command: Command): Promise<void>;
protected addHelpBody(command: Command): Promise<void>;
/**
* WARNING: The code in this method only makes sense *when launching
* a new process*! Using this to run code in the current process
* will not result in the proper configs to be used since configs
* are already loaded.
*
* Instead of using this method, you should probably use `invokeShellCommand()`
* with the `useTestsNodeAppInstance` param set to `true`.
*/
protected withTestsNodeAppInstance<T = void>(runner: () => Promise<T>): Promise<T>;
/**
* Invokes the specified script.
*
* @param scriptType the class of a Script to invoke
* @param options specify the target options for the script to invoke. Those options
* will be *merged* to the current global options, if any.
* @param args specify the target args for the script to invoke
*/
protected invokeScript<TOptions, TArgs extends ParsedArgumentsObject>(scriptType: IScriptConstructor<TOptions, GO, TArgs>, options: TOptions, args: TArgs): Promise<void>;
/**
* Execute a shell command.
*
* This function is a promisified version of Node's `spawn()`
* with extra options added
* ( https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options ).
*
* Will fail if the process returns a code different than
* `options.successExitCode` ("0" by default). The exit
* code would then be available in the generated Error:
* `err.exitCode`.
*
* @param bin The executable program to call.
*
* @param args The arguments for the program.
*
* @param options.successExitCodes The acceptable codes the
* process must exit with to be considered as a success.
* Defaults to [0].
*
* @param options.outputHandler A function that will receive
* the output of the process (stdOut and stdErr).
* This allows you to capture this output and manipulate it.
* No handler by default.
*
* @param options.disableConsoleOutputs Set to `true` in order
* to disable outputs in the current parent process
* (you can still capture them using a `options.dataHandler`).
* Defaults to `false`.
*
* @param options.stdio See https://nodejs.org/api/child_process.html#child_process_options_stdio
* Defaults to `['inherit', 'pipe', 'pipe']`.
*
* @param options.useShellOption See the "shell" option:
* https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options
* Defaults to `true`.
*
* @param options.escapeArgs will automatically escape the submitted args.
* Defaults to `false`.
*
* @param options.useTestsNodeAppInstance Execute the specified command with the
* "NODE_APP_INSTANCE" env var set to "tests". This makes the testing configurations
* be used in the launched process.
*
* @returns The exit code *when the execution is a success*. This may be useful when more
* than one exit codes can be considered as a success (those specified using
* `options.successExitCodes`). Note that if an error occures, an `ExecError` is thrown
* so nothing is returned (see below).
*
* @throws Will fail with a `ExecError` error if the process returns a code different than
* `options.successExitCodes` ("0" by default). The exit code would then be available in the
* generated Error: `err.exitCode.`
*/
protected invokeShellCommand(bin: string, args: string[], options?: {
successExitCodes?: number | number[];
outputHandler?: (stdoutOutput: string, stderrOutput: string) => void;
disableConsoleOutputs?: boolean;
stdio?: StdioOptions;
useShellOption?: boolean;
escapeArgs?: boolean;
useTestsNodeAppInstance?: boolean;
}): Promise<number>;
protected getCommand(): Command;
protected getCommandOptionsNames(): Set<string>;
private addGlobalOptions;
/**
* The name of the script.
*/
abstract get name(): string;
/**
* Will be used to identify the script
* when outputing console messages.
*/
get outputName(): string;
/**
* The description of the script.
*/
abstract get description(): string;
get commandConfig(): Partial<CommandConfig>;
/**
* Override this method in order to add
* options or to configure a script that
* requires more information than a name and
* description.
*/
protected configure(command: Command): Promise<void>;
/**
* Get the project direct dependencies (those
* explicitly listed in its `package.json`).
*/
protected getProjectDirectDependencies(): Promise<string[]>;
/**
* Returns `true` if the specified dependency is a
* direct dependency in the project.
*/
protected isProjectDirectDependency(dependencyName: string): Promise<boolean>;
/**
* Validate the required dependencies.
*/
protected validateRequiredDependencies(): Promise<void>;
/**
* Runs the script.
*/
run(): Promise<void>;
/**
* The main code to execute when the
* script is called.
*/
protected abstract main(): Promise<void>;
}
//# sourceMappingURL=scriptBase.d.ts.map