@decaf-ts/utils/lib/writers/StandardOutputWriter.d.ts

module management utils for decaf-ts

import { OutputWriter } from "./OutputWriter";
import { PromiseExecutor } from "../utils/types";
import { OutputType } from "./types";
import { Logger } from "@decaf-ts/logging";
/**
 * @description A standard output writer for handling command execution output.
 * @summary This class implements the OutputWriter interface and provides methods for
 * handling various types of output from command execution, including standard output,
 * error output, and exit codes. It also includes utility methods for parsing commands
 * and resolving or rejecting promises based on execution results.
 *
 * @template R - The type of the resolved value, defaulting to string.
 *
 * @param cmd - The command string to be executed.
 * @param lock - A PromiseExecutor to control the asynchronous flow.
 * @param args - Additional arguments (unused in the current implementation).
 *
 * @class
 * @example
 * ```typescript
 * import { StandardOutputWriter } from '@decaf-ts/utils';
 * import { PromiseExecutor } from '@decaf-ts/utils';
 *
 * // Create a promise executor
 * const executor: PromiseExecutor<string> = {
 *   resolve: (value) => console.log(`Resolved: ${value}`),
 *   reject: (error) => console.error(`Rejected: ${error.message}`)
 * };
 *
 * // Create a standard output writer
 * const writer = new StandardOutputWriter('ls -la', executor);
 *
 * // Use the writer to handle command output
 * writer.data('File list output...');
 * writer.exit(0, ['Command executed successfully']);
 * ```
 *
 * @mermaid
 * sequenceDiagram
 *   participant Client
 *   participant StandardOutputWriter
 *   participant Logger
 *   participant PromiseExecutor
 *
 *   Client->>StandardOutputWriter: new StandardOutputWriter(cmd, lock)
 *   StandardOutputWriter->>Logger: Logging.for(cmd)
 *
 *   Client->>StandardOutputWriter: data(chunk)
 *   StandardOutputWriter->>StandardOutputWriter: log("stdout", chunk)
 *   StandardOutputWriter->>Logger: logger.info(log)
 *
 *   Client->>StandardOutputWriter: error(chunk)
 *   StandardOutputWriter->>StandardOutputWriter: log("stderr", chunk)
 *   StandardOutputWriter->>Logger: logger.info(log)
 *
 *   Client->>StandardOutputWriter: exit(code, logs)
 *   StandardOutputWriter->>StandardOutputWriter: log("stdout", exitMessage)
 *   alt code === 0
 *     StandardOutputWriter->>StandardOutputWriter: resolve(logs)
 *     StandardOutputWriter->>PromiseExecutor: lock.resolve(reason)
 *   else code !== 0
 *     StandardOutputWriter->>StandardOutputWriter: reject(error)
 *     StandardOutputWriter->>PromiseExecutor: lock.reject(reason)
 *   end
 */
export declare class StandardOutputWriter<R = string> implements OutputWriter {
    protected cmd: string;
    protected lock: PromiseExecutor<R>;
    protected logger: Logger;
    constructor(cmd: string, lock: PromiseExecutor<R>, ...args: unknown[]);
    /**
     * @description Logs output to the console.
     * @summary Formats and logs the given data with a timestamp and type indicator.
     *
     * @param type - The type of output (stdout or stderr).
     * @param data - The data to be logged.
     */
    protected log(type: OutputType, data: string | Buffer): void;
    /**
     * @description Handles standard output data.
     * @summary Logs the given chunk as standard output.
     *
     * @param chunk - The data chunk to be logged.
     */
    data(chunk: any): void;
    /**
     * @description Handles error output data.
     * @summary Logs the given chunk as error output.
     *
     * @param chunk - The error data chunk to be logged.
     */
    error(chunk: any): void;
    /**
     * @description Handles error objects.
     * @summary Logs the error message from the given Error object.
     *
     * @param err - The Error object to be logged.
     */
    errors(err: Error): void;
    /**
     * @description Handles the exit of a command.
     * @summary Logs the exit code and resolves or rejects the promise based on the code.
     *
     * @param code - The exit code of the command.
     * @param logs - Array of log messages to be processed before exiting.
     */
    exit(code: number | string, logs: string[]): void;
    /**
     * @description Parses a command string or array into components.
     * @summary Converts the command into a consistent format and stores it, then returns it split into command and arguments.
     *
     * @param command - The command as a string or array of strings.
     * @return A tuple containing the command and its arguments as separate elements.
     */
    parseCommand(command: string | string[]): [string, string[]];
    /**
     * @description Resolves the promise with a success message.
     * @summary Logs a success message and resolves the promise with the given reason.
     *
     * @param reason - The reason for resolving the promise.
     */
    protected resolve(reason: R): void;
    /**
     * @description Rejects the promise with an error message.
     * @summary Logs an error message and rejects the promise with the given reason.
     *
     * @param reason - The reason for rejecting the promise, either a number (exit code) or a string.
     */
    protected reject(reason: number | string | Error): void;
}