@ts-common/azure-js-dev-tools/dist/lib/run.d.ts

Developer dependencies for TypeScript related projects

/**
 * Copyright (c) Microsoft Corporation. All rights reserved.
 * Licensed under the MIT License. See License.txt in the project root for
 * license information.
 */
/// <reference types="node" />
import { StdioOptions } from "child_process";
import { StringMap } from "./common";
export interface Command {
    /**
     * The executable file/command to run.
     */
    executable: string;
    /**
     * The arguments to pass to the executable.
     */
    args?: string[];
    /**
     * The options to use when running the command.
     */
    options?: RunOptions;
}
/**
 * Get the string representation of the provided command.
 */
export declare function commandToString(command: Command): string;
export interface CommandToken {
    text: string;
    startIndex: number;
    endIndex: number;
    isWhitespace?: boolean;
}
export declare function parseCommandToken(commandString: string, startIndex: number): CommandToken | undefined;
export declare function parseCommandTokens(commandString: string, startIndex?: number): CommandToken[];
export declare function createCommand(commandTokens: CommandToken[] | undefined): Command | undefined;
/**
 * Parse a command object from the provided command string.
 */
export declare function parseCommand(commandString: string, startIndex?: number): Command | undefined;
export declare function parseCommands(commandString: string, startIndex?: number): Command[];
/**
 * Quote the provided value if it is needed.
 */
export declare function quoteIfNeeded(value: string, quote?: string): string;
/**
 * Determine whether or not the provided value should be quoted.
 */
export declare function shouldQuote(value: string, quote?: string): boolean;
/**
 * Ensure that the provided value is surrounded by the provided quote string.
 */
export declare function ensureQuoted(value: string, quote?: string): string;
/**
 * An object that runs a provided command.
 */
export interface Runner {
    /**
     * Run the provided command asynchronously.
     * @param command The command to run.
     * @param options The options to use when running the command.
     */
    run(command: Command, options: RunOptions | undefined): Promise<RunResult>;
}
export declare function chunkToString(chunk: any): string;
/**
 * A command runner that runs commands using a spawned process.
 */
export declare class RealRunner implements Runner {
    run(command: Command, options?: RunOptions): Promise<RunResult>;
}
export interface FakeCommand {
    executable: string;
    args?: string[];
    executionFolderPath?: string;
    result?: RunResult | Promise<RunResult> | (() => RunResult | Promise<RunResult>);
}
/**
 * A fake command runner.
 */
export declare class FakeRunner implements Runner {
    private readonly innerRunner;
    private readonly fakeCommands;
    private unrecognizedCommand;
    constructor(innerRunner?: Runner);
    /**
     * Set the function to invoke when an unrecognized command is run.
     * @param unrecognizedCommandHandler The function to call when an unrecognized command is run.
     */
    onUnrecognizedCommand(unrecognizedCommandHandler: ((command: Command, options?: RunOptions) => (RunResult | Promise<RunResult>))): void;
    /**
     * Configure this FakeRunner so that all unrecognized commands will be passed through to its
     * inner runner.
     */
    passthroughUnrecognized(): void;
    /**
     * Set the fake result to return when the provided command is run.
     * @param command The command to fake.
     */
    set(command: FakeCommand): void;
    /**
     * Indicate that when this Runner attempts to run the provided commandString it should just pass
     * the commandString through to the inner runner.
     * @param commandString The commandString to pass through to the inner runner.
     */
    passthrough(command: Command, executionFolderPath?: string): void;
    run(command: Command, options?: RunOptions): Promise<RunResult>;
}
/**
 * The result of running a command.
 */
export interface RunResult {
    /**
     * The code that the process exited with.
     */
    exitCode?: number;
    /**
     * The text that the process wrote to its stdout stream.
     */
    stdout?: string;
    /**
     * The text that the process wrote to its stderr stream.
     */
    stderr?: string;
    /**
     * An error that occurred when trying to run the process.
     */
    error?: Error;
    /**
     * The id of the process.
     */
    processId?: number;
}
export interface RunOptions {
    /**
     * A function that will be used to write logs.
     */
    log?: (text: string) => Promise<any> | any;
    /**
     * The folder/directory where the command will be executed from.
     */
    executionFolderPath?: string;
    /**
     * Whether or not to write the command that will be executed to the console. Defaults to true.
     */
    showCommand?: boolean;
    /**
     * Whether or not to show the environment variables that have been passed to this command.
     */
    showEnvironmentVariables?: boolean;
    /**
     * Whether or not to write the command result to the console. Defaults to only show if the exit
     * code was non-zero.
     */
    showResult?: boolean | ((result: RunResult) => boolean);
    /**
     * Prefix added to log
     */
    capturePrefix?: string;
    /**
     * Whether or not to capture the command's output stream. If true or undefined, then the output
     * stream will be captured and returned in the RunResult's stdout property. If a function, then
     * the function will be called on each line of output text written by the process. If false, then
     * the command's output stream will be written to the parent process's output stream.
     */
    captureOutput?: boolean | ((outputLine: string) => void);
    /**
     * Whether or not to capture the command's error stream. If true or undefined, then the error
     * stream will be captured and returned in the RunResult's stderr property. If a function, then
     * the function will be called on each line of error text written by the process. If false, then
     * the command's error stream will be written to the parent process's error stream.
     */
    captureError?: boolean | ((errorLine: string) => void);
    /**
     * The runner that will be used to execute this command.
     */
    runner?: Runner;
    /**
     * The environment variables that will be added when the command is run.
     */
    environmentVariables?: StringMap<string>;
    /**
     * Throw on non-zero exit code
     */
    throwOnError?: boolean;
}
/**
 * Get an array of string arguments from the provided args.
 * @param args The args string or array of strings.
 */
export declare function getArgsArray(args: undefined | string | string[]): string[];
/**
 * Get the showResult function that will determine whether the command's result will be logged.
 * @param showResult The showResult property from the command's RunOptions.
 */
export declare function getShowResultFunction(showResult: undefined | boolean | ((result: RunResult) => boolean)): (result: RunResult) => boolean;
export declare function logCommand(command: Command, options: RunOptions): Promise<void>;
export declare function logEnvironmentVariables(options: RunOptions): Promise<void>;
export declare function logResult(result: RunResult, options: RunOptions | undefined): Promise<void>;
export declare function getChildProcessStdio(options: RunOptions): StdioOptions;
/**
 * Run the provided command asynchronously.
 * @param command The command to run.
 * @param args The arguments to provide to the command.
 */
export declare function run(command: string | Command, args?: string[], options?: RunOptions): Promise<RunResult>;
//# sourceMappingURL=run.d.ts.map